From c5dd5c4b04da76753e351b8ea1e5a1a7e64f3659 Mon Sep 17 00:00:00 2001 From: tv Date: Tue, 17 Nov 2026 13:09:06 +0000 Subject: guides: checkpoints in a federation What a move to a checkpoint keeps and loses, a version only moving the store on and the heads to name, a node proposing checkpoints by its operator's rules, backing only heads that leave out nothing held for a while (which a node voting by itself checks and a party's client doesn't), signing again after a move, and nodes that weren't there. --- docs/guides/federation/README.md | 2 + docs/guides/federation/checkpoints.md | 78 +++++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+) create mode 100644 docs/guides/federation/checkpoints.md (limited to 'docs') 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). -- cgit v1.3.1