From 694b18329c72643c6f4a2919c6dde5118e20836b Mon Sep 17 00:00:00 2001 From: tv Date: Mon, 16 Nov 2026 15:18:27 +0000 Subject: docs/federation: what a checkpoint keeps, its heads, and joining from one A checkpoint keeps the events that count at its heads but version events, as it holds the version itself, and a version event of it that comes later is one a node took. Its heads are events after the current checkpoint, none in another's history, ascending, one at least, and a proposer names heads it has held for a while. Once a checkpoint passed, a node joins from a pinned one: from the root, keys long replaced could grow another chain, and node lists naming only their own nodes would seal a joining node in it; a node still joining that is shown two versions changing one takes neither. A node drops only what it took after its checkpoint, and undoes a move only by a pin; a version named again where it isn't above its checkpoint's heads isn't taken. --- docs/federation.md | 90 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 55 insertions(+), 35 deletions(-) diff --git a/docs/federation.md b/docs/federation.md index 6021dea..5b4046a 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -75,6 +75,9 @@ Not promised: taken neither of two (it lagged behind, or joins) may be shown either first; * that what isn't above a checkpoint's heads is taken once nodes moved to it: its party signs it again (Checkpoints); +* that a node joining from the root, in a federation that never passed a checkpoint, + isn't shown a chain old keys grew: of two versions changing one it takes neither, but + where its peers are all the adversary's it is shown one (Checkpoints); * that a checkpoint, or a fork's root, that a node takes on its operator's word is the one the others built ([`store.md`](store.md), Pinned checkpoints). @@ -267,16 +270,19 @@ refuses, with everything built on it, reports, and leaves to its operator ([`store.md`](store.md), A node's own); another node's refusal doesn't make it drop what it took. One valid at its history breaks no rule: the node reports it apart from events against the rules, and holds nothing against the node that put it. Of two that change -the one it reads, it takes the first it judges. Without keys voting twice, every version -written changes the one every node reads, or is one it took, and none is refused. - -**An operator may have its node drop what it took**: a version the others refused, or -any event, with everything built on it ([`store.md`](store.md), A node's own), and then -take what the others hold. No peer's word moves a node; its operator's does. The node -refuses what it dropped, from whoever brings it, and any version event naming a version -among it, whoever wrote it anew, and writes none itself, though it holds the votes that -passed it, until its operator says otherwise. So either side of keys that voted twice -may join the other without what parts them, and without a fork. +the one it reads, it takes the first it judges; a node still joining takes neither, and +reports, until its operator names one. Without keys voting twice, every version written +changes the one every node reads, or is one it took, and none is refused. + +**An operator may have its node drop what it took** after its checkpoint: a version the +others refused, or any event, with everything built on it ([`store.md`](store.md), A +node's own), and then take what the others hold. A version that moved the node to a +checkpoint it undoes only by taking a checkpoint its operator pins, as the node forgot +what the other side's version needs. No peer's word moves a node; its operator's does. +The node refuses what it dropped, from whoever brings it, and any version event naming a +version among it, whoever wrote it anew, and writes none itself, though it holds the +votes that passed it, until its operator says otherwise. So either side of keys that +voted twice may join the other without what parts them, and without a fork. **The current version** is the written version with the highest number: the end of the chain the node took. @@ -376,36 +382,48 @@ with the lower ID; the party writes again, after both, to choose. A **checkpoint** writes down what counts at some heads: those heads, a version (the one current there, or a fork's), and the IDs of the events that count there with that -version current (What counts; a merge's root keeps otherwise, Forks), as the JCS -encoding of `{"at": [], "keeps": [], "version": }`, its IDs -ascending, named by its SHA-256 ([`store.md`](store.md), Checkpoints). Every node -holding the history up to those heads builds the same one, and its version counts as -written. - -A version names a checkpoint by its heads (`checkpoint`). It is a version only where its -proposal is above those heads, and a vote on it, or a version event writing it, is taken -only where it is above them too ([`store.md`](store.md), Events): so moving to the -checkpoint refuses nothing that decided it. A node that takes the version moves to the -checkpoint: it builds it, forgets everything before those heads that it doesn't keep, -and every event not above them, and refuses such events from then on. Judging an event -after them needs nothing it forgot: the version, every party's keys and node list, and -the proposals on the current version with their votes all count, and are kept. A node -that can't build a checkpoint, as it was away longer than its peers kept what they -forgot, or as it joins, takes it only where its operator pins it -([`store.md`](store.md), Pinned checkpoints). +version current, version events aside, as it holds the version itself (What counts; a +merge's root keeps otherwise, Forks), as the JCS encoding of +`{"at": [], "keeps": [], "version": }`, its IDs ascending, named by +its SHA-256 ([`store.md`](store.md), Checkpoints). Every node holding the history up to +those heads builds the same one, and its version counts as written: a version event of +it that comes later is one the node took. + +A version names a checkpoint by its heads (`checkpoint`): events after the current +checkpoint, none in another's history, their IDs ascending, one at least. A proposer +names heads it has held for a while, by its own clock, which judges nothing, so that +every node holds them. It is a version only where its proposal is above those heads, and +a vote on it, or a version event writing it, is taken only where it is above them too +([`store.md`](store.md), Events): so moving to the checkpoint refuses nothing that +decided it. A node that takes the version moves to the checkpoint: it builds it, forgets +everything before those heads that it doesn't keep, and every event not above them, and +refuses such events from then on. Judging an event after them needs nothing it forgot: +the version, every party's keys and node list, and the proposals on the current version +with their votes all count, and are kept. A node that can't build a checkpoint, as it +was away across a move and a remake after it, or as it joins, takes it only where its +operator pins it ([`store.md`](store.md), Pinned checkpoints). What a checkpoint loses: what counted no more before it, so that a key added back, or a place given back, brings back nothing signed before it, and a party that voted twice on a version behind it shows only in the votes its clients kept; and what isn't above its -heads, which its party signs again. That is rare: the heads are in the proposal's -history, nodes build on them while the vote takes its course, and a client writing once -a checkpoint is proposed builds only on what is above its heads. +heads, which its party signs again. Few are: the heads are ones its proposer held for a +while, nodes build on them while the vote takes its course, a client writing once a +checkpoint is proposed builds only on what is above its heads, and a party's client +signs again what a move refused. + +**Joining.** Once a checkpoint passed, a node joins from a checkpoint its operator pins, +not from the root ([`store.md`](store.md), Pinned checkpoints). From the root, keys a +version named before it, revoked since or thrown away, could grow another chain, at +histories before the version that followed, and node lists naming only their own nodes +would seal a node joining in it, never shown the other. So a checkpoint bounds what old +keys can do to the versions after it. A version that changes nothing but its number, what it changes and its checkpoint only moves the store on. Like any version, it lapses the proposals on the version before, so -a party proposes one where nothing else is proposed on the current version. A -federation's root is its first checkpoint, without heads (Starting a federation), and a -fork's root a checkpoint at the heads it forks at, of one store or of several (Forks). +a party proposes one where nothing that can still pass is proposed on the current +version. A federation's root is its first checkpoint, without heads (Starting a +federation), and a fork's root a checkpoint at the heads it forks at, of one store or of +several (Forks). ### Votes a node casts by itself @@ -615,12 +633,12 @@ crafted events. *Sim*: a simulation. *Bench*: measured, not judged. | 41 | A federation's root with heads or events kept, or whose version lists no node | None; or nothing after it is taken, as no node is a member | unit | | 42 | A version replacing every listed party's keys | The lists still count, each its party's until it writes another | unit | | 43 | A version whose `since` for a party is neither its own number nor the `since` the version it changes gives the party, or that changes a party's keys or list without naming them anew | No version: a version event naming it is refused | unit | -| 44 | A version written again late, at a history from before the next, by a node that was away | Taken: it is one every node took | unit | +| 44 | A version written again late, at a history from before the next, by a node that was away | Taken: it is one every node took; but one naming a checkpoint, written again where it isn't above the checkpoint's heads, is not (54) | unit | | 45 | An honest node writes a version valid where it is written, on the side a node doesn't read | Refused, and reported apart; nothing is held against the node that put it | unit | | 46 | A party's `true` and `false` on one proposal, both in a history | Both count there: a history holding more votes takes back no pass and no death | unit | | 47 | A path whose `{party}` segment names no party (`names/r/foo`) | The `{party}` rule doesn't match; a later rule decides | unit | | 48 | Two thirds back a proposal that is no version | It can't be written, nor die; the federation is bound to its version. A node shows that it is none, and clients don't back it | unit | -| 49 | Keys voting twice part honest nodes | An operator has its node drop what it took and take the other side's; no fork | sim | +| 49 | Keys voting twice part honest nodes | An operator has its node drop what it took and take the other side's; no fork. Where the version it took named a checkpoint, by a checkpoint its operator pins | sim | | 50 | An honest party backs a second proposal once its first is dead; another party later signs `true` on the first too | It isn't named: its first proposal is dead by all the votes; the party with `true` and `false` on one is | unit | | 51 | A node whose operator had it drop a version is sent it again, written anew by another node, or holds the votes that passed it | It refuses any event writing that version and writes it no more, until its operator says otherwise | unit | | 52 | A party taken out and let in again | The list it wrote before counts no more: its list's `since` is the version that let it in | unit | @@ -640,6 +658,8 @@ crafted events. *Sim*: a simulation. *Bench*: measured, not judged. | 66 | A merge's root keeping a value that didn't count on its side, or at a place its version gives another | Nodes holding that side build the root, find it differs, and don't join; others take it on their operator's word | sim | | 67 | Events a side writes after a merge's heads, brought to the merge | Never taken: their history lacks its root; their party signs them again | unit | | 68 | A party's event spelled anew by another: its `sig` or `key` encoded otherwise, its signature's S not canonical, its blob naming another key | None: `key` and `sig` read back to themselves, the signature is checked strictly, and the blob's key is `key` | unit | +| 69 | A node joining from the root is shown a chain old keys grew, beside the one the others took | It takes neither, and reports; once a checkpoint passed, it joins from a pinned one, where that chain is refused | unit | +| 70 | Checkpoint heads before the current checkpoint, or one in another's history | No version: a version event naming it is refused | unit | ## Roads not taken -- cgit v1.3.1