From 5d8259ce576fce47b921c0bfbd6821f255be504a Mon Sep 17 00:00:00 2001 From: tv Date: Thu, 19 Nov 2026 14:25:53 +0000 Subject: docs: how large checkpoints grow, joining before the first, counting support What the docs left unsaid: * A checkpoint names every event that counts, 32 bytes each, and has no size limit, unlike an event; nothing bounds what a party writes where its rules let it, so every node, snapshot and fork's root holds as much as it writes. A party writing more than the others will hold is taken out by a version, or the others fork. Row 73 says so, and the rules guide. * Before the first checkpoint passed, a node joins from the root and nobody pins anything: a chain of old keys needs keys a version replaced, and a node voting by itself proposes a checkpoint after every version that changes more; until that passes, a joining node takes the first of two versions it judges, as row 63 has it. * A `true` binds; what binds nobody is said outside the votes. The voting guide shows how parties count their support first by plain writes, at a place a rule gives each (`intents/{party}/**`), read at `values` in GET /events/counts. --- docs/federation.md | 22 ++++++++++++++++++- docs/guides/federation/README.md | 3 ++- docs/guides/federation/designing-rules.md | 6 ++++++ docs/guides/federation/proposing-and-voting.md | 29 ++++++++++++++++++++++++++ 4 files changed, 58 insertions(+), 2 deletions(-) diff --git a/docs/federation.md b/docs/federation.md index f0099ef..2cdd4d9 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -309,7 +309,11 @@ five backing X, who can't back a compromise the seven others would all pass unti or dies, and silence never ends. With q parties quiet, a proposal short by q votes or fewer can neither pass nor die. A party gone quiet for good is taken out by a version while two thirds still answer, and a party's client says when a `true` would bind its -party unless every party yet to vote votes `false`. +party unless every party yet to vote votes `false`. What binds nobody is said outside +the votes: parties may count their support first by plain writes, where the rules give +each a place for it +([`guides/federation/proposing-and-voting.md`](guides/federation/proposing-and-voting.md), +[Counting support first](guides/federation/proposing-and-voting.md#counting-support-first)). Once a proposal passed on the current version, a node writes it as soon as it holds it passed, by a **version** event, `{"deps": […], "version": }`, which no party @@ -515,6 +519,21 @@ histories before the version that followed, and node lists naming only their own 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. +Before the first checkpoint passed, a node joins from the root, and nobody pins anything: +such a chain needs keys a version replaced, so it can grow only after a version, and a +node voting by itself proposes a checkpoint after every version that changes more +([Votes a node casts by itself](#votes-a-node-casts-by-itself)). Until it passes, a node +joining may be shown that chain, and takes the first of the two versions it judges, as +any node, reporting the other (row 63 of [Attacks](#attacks)). + +**How large.** A checkpoint names every event that counts at its heads, 32 bytes each, +beside the version, and has no size limit, unlike an event. It grows with what the +parties write, and nothing bounds that: a party writes as many places as its rules give +it, each event up to 256 KiB, and every node holds the events that count. A checkpoint is +written into the document with a remake's snapshot only, and as a fork's root. A party +writing more than the others will hold is answered as any party misbehaving: the others +take it out by a version, or fork. + 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 that can still pass is proposed on the current @@ -785,6 +804,7 @@ fold, with crafted events. *Sim*: a simulation. *Bench*: measured, not judged. | 70 | A checkpoint's version proposed again, by an event beside its heads | Voters back it all the same, as a proposal lapses with the move, and vote on the events proposing it above its heads, as a node shows them; a version event on votes beside them is refused | unit | | 71 | Merge events under the base revision, signed by a node its party doesn't list, by a party's key, or spelled otherwise | Refused, or none: a merge event is taken only under a revision with merge events, signed by a node its party's node list names, its `merge` `true`; it counts for nothing | unit | | 72 | A version, or a fork's, admitting a party named as a segment of places others write, or changing the rules or their order, so that who writes those places moves, rules unchanged in the first case | Taken, as any version two thirds pass, or any fork: a party's client names each place holding a value whose writer a proposal changes before it is voted on, and a fork's check does for the fork's version | unit | +| 73 | A party writes a great many places, so that every node holds them, and every checkpoint, snapshot and fork's root names them | Taken where its rules let it write: nothing bounds what a party writes but the rules' places and an event's size; the others take it out by a version, or fork | — | ## Roads not taken diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md index 4c5b33b..104a04c 100644 --- a/docs/guides/federation/README.md +++ b/docs/guides/federation/README.md @@ -11,7 +11,8 @@ by them, in its words. * [`writing-and-reading.md`](writing-and-reading.md): places, values, what counts, why a write is refused, and signing again after a move. * [`proposing-and-voting.md`](proposing-and-voting.md): writing a version, proposing it, - voting by a record, and when a proposal passes or dies. + voting by a record, counting support before anyone is bound, 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, diff --git a/docs/guides/federation/designing-rules.md b/docs/guides/federation/designing-rules.md index db61f62..bd577cd 100644 --- a/docs/guides/federation/designing-rules.md +++ b/docs/guides/federation/designing-rules.md @@ -69,6 +69,12 @@ parties' votes. A rule per shared name is a vote per name, and makes every versi much larger: give zones and blocks by rules where the spelling allows, and leave literal rules to what is shared. +Nor does a rule bound how many places below it a party writes, or how large a value is +but by an event's size (256 KiB): every node holds what counts, and every checkpoint +names it, 32 bytes an event. A party writing more than the others will hold is taken out +by a version, or the others fork ([`federation.md`](../../federation.md), +[Checkpoints](../../federation.md#checkpoints)). + ## An example: the krebs registry The krebs users who will vote are parties, each with its hosts in its namespace diff --git a/docs/guides/federation/proposing-and-voting.md b/docs/guides/federation/proposing-and-voting.md index f052276..9b50e09 100644 --- a/docs/guides/federation/proposing-and-voting.md +++ b/docs/guides/federation/proposing-and-voting.md @@ -116,6 +116,35 @@ casts nothing on the current version, and votes again from the next one. A party never voted may begin its record from the root (`init --root`), and casts on every version. +## Counting support first + +A `true` isn't taken back, and binds while its proposal can pass. Parties that want to +know who would back a proposal before anyone is bound can say so by plain writes, which +bind nobody and count for nothing in the votes. The version gives each party a place for +it, by a rule: + +```json +{"path": "intents/{party}/**", "writer": "{party}"} +``` + +and each party writes there, by the proposal's hash, whether it would back it: + +```sh +continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \ + write intents/tv/8d02… true +``` + +Anyone reads them at `values` in `GET /events/counts`: + +```sh +curl -s -u tv:secret localhost:3000/events/counts \ + | jq '.values | with_entries(select(.key | test("^intents/[^/]+/8d02")))' +``` + +Once two thirds of the parties wrote `true`, each backs it. A party's write there is its +word, not its vote: it may write `false` later, or vote otherwise. It doesn't help with +parties that stay quiet: they write nothing either. + ## Passing and dying A proposal **passes** once at least two thirds of its version's parties voted `true` -- cgit v1.3.1