aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides
diff options
context:
space:
mode:
Diffstat (limited to 'docs/guides')
-rw-r--r--docs/guides/federation/README.md2
-rw-r--r--docs/guides/federation/checkpoints.md78
2 files changed, 80 insertions, 0 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md
index 369ac62..e4c52f4 100644
--- a/docs/guides/federation/README.md
+++ b/docs/guides/federation/README.md
@@ -14,3 +14,5 @@ by them, in its words.
voting by a record, and when a proposal passes or dies.
* [`keys.md`](keys.md): the keys a version names and those of a key set, changing them,
and a stolen key.
+* [`checkpoints.md`](checkpoints.md): what a checkpoint does, proposing and backing one,
+ signing again after a move, and nodes that weren't there.
diff --git a/docs/guides/federation/checkpoints.md b/docs/guides/federation/checkpoints.md
new file mode 100644
index 0000000..0ff26fe
--- /dev/null
+++ b/docs/guides/federation/checkpoints.md
@@ -0,0 +1,78 @@
+# Checkpoints
+
+A checkpoint writes down what counts at some heads, so that nodes forget the rest and hold
+what is relevant. The parties pass it as any version. The rules are the design's
+([`federation.md`](../../federation.md), Checkpoints; [`store.md`](../../store.md),
+Checkpoints).
+
+## What one does
+
+A version may name heads for a checkpoint (`checkpoint`). A node taking it **moves**:
+it builds the checkpoint, the version current at those heads and the events that count
+there, forgets everything else before them and every event not above them, and refuses
+such events from then on. What it keeps is what judging needs: the version, every party's
+keys and node list, the values that count, the proposals on the current version and
+their votes.
+
+What it loses: what counted no more before the heads, so a key added back or a place
+given back brings back nothing signed before them; votes on versions behind it, so a
+party that voted twice there shows only in the votes the parties' clients kept; and what
+isn't above the heads, which its party signs again (After a move, below).
+
+## Proposing one
+
+A version that only moves the store on is the current one with the next `number`, the
+current version's hash as `changes`, and the heads as `checkpoint`
+([`proposing-and-voting.md`](proposing-and-voting.md), Writing a version). The heads are
+events after the current checkpoint, at which the current version is current too, none in
+another's history, their IDs ascending: heads a node showed (`heads` in `GET /events`)
+once the version was written, and that it has held for a while since, so that every
+node holds them. Propose it afterwards: the client signs the proposal on the heads its
+node shows then, above the ones it names, as it must be.
+
+Like any version, it lapses the proposals on the version before: propose one where
+nothing that can still pass is proposed on the current version.
+
+A node voting for its party by itself proposes checkpoints by its operator's rules: once
+it holds so many events beyond its checkpoint (`--store-propose-events`), or so long
+after its store moved there (`--store-propose-every`), at the heads of what it held for
+a while (`--store-held-for`, ten minutes unless set), where nothing that can still pass
+is proposed; and it backs what it proposes.
+
+## Backing one
+
+Back a checkpoint only where everything you held for a while before it was proposed is
+among its heads, in their history, or above them: heads a proposer made up, built on
+little, would take back what was written since, a key set dropping a stolen key among
+it. A node voting by itself backs one only so, and so does a vote by hand through it
+(`continuum-party vote … --through`). A party's client voting on its own
+(`continuum-party vote`) checks no heads: check them yourself, or vote through such a
+node.
+
+* `--store-follow PARTY,…` has a node voting by itself follow those parties' votes, by
+ default on versions that only move to a checkpoint, and still by that rule.
+* `--store-nay-beside` has it vote `false` on every other version only moving to a
+ checkpoint, where it backs one that can still pass: of two checkpoints proposed at once,
+ the other dies, and its backers are free.
+
+## After a move
+
+A write signed on heads from before the move, still on its way, is refused (`it isn't
+above the checkpoint's heads`). The client signs it again, on the heads its node shows:
+
+```sh
+continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
+ again
+```
+
+Votes and proposals aren't signed again: their version is behind.
+
+## Nodes that weren't there
+
+A node reads its store at every start from its document's checkpoint, or from the one
+its operator pins (`--store-checkpoint`), which it finds in its document. Until a remake
+leaves out what a checkpoint forgot, the document holds what came before, and a node
+that was away builds the checkpoint from it as any. After such a remake, a node away
+across it, or joining, takes the checkpoint only where its operator pins it: ask a node
+you trust for it (`checkpoint` in `GET /events`)
+([`running-a-node.md`](running-a-node.md), Joining).