aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-17 13:07:36 +0000
committertv <tv@krebsco.de>2026-11-17 14:23:17 +0100
commitc3b5bd694333d69b6cc88f229c0e80833ab64cf9 (patch)
tree8a9f4c59978f96a2c174a53202d06cc786527976 /docs/guides/federation
parentdf2b1579cb7525badd041ff7f98b1f6fd2763ceb (diff)
guides: proposing and voting in a federation
Writing a version from the current one, its `since`s and what makes one none, proposing it, voting through the party's client by its record and what the client refuses to cast, voting through a node that votes for its party, a lost record, and when a proposal passes or dies, with the counts for some numbers of parties.
Diffstat (limited to 'docs/guides/federation')
-rw-r--r--docs/guides/federation/README.md2
-rw-r--r--docs/guides/federation/proposing-and-voting.md116
2 files changed, 118 insertions, 0 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md
index 8efae2b..690d0ad 100644
--- a/docs/guides/federation/README.md
+++ b/docs/guides/federation/README.md
@@ -10,3 +10,5 @@ by them, in its words.
its API lets in, and joining.
* [`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.
diff --git a/docs/guides/federation/proposing-and-voting.md b/docs/guides/federation/proposing-and-voting.md
new file mode 100644
index 0000000..926955f
--- /dev/null
+++ b/docs/guides/federation/proposing-and-voting.md
@@ -0,0 +1,116 @@
+# Proposing and voting
+
+Everything a federation decides is a change of its policy: who the parties are, their
+keys and node lists, who writes where, a checkpoint. A party proposes a version, the
+parties vote, and once two thirds of them back it, it is written. The rules are the
+design's ([`federation.md`](../../federation.md), The policy, Changing the policy).
+
+## Writing a version
+
+A version is the whole policy, not a change to it. Begin from the current one, as a node
+shows it:
+
+```sh
+curl -s -u tv:secret localhost:3000/events/counts | jq .version.version > next.json
+curl -s -u tv:secret localhost:3000/events/counts | jq -r .version.hash
+```
+
+Then change it:
+
+* **`number`**: one more than the current version's.
+* **`changes`**: the current version's hash.
+* **`keys`**: every party's keys, with their `since`. A party let in, or whose keys the
+ version names anew (replaced, or the same named anew), has this version's number as
+ its `since`; every other keeps the `since` it had, and its keys unchanged. A party left
+ out is no party any more.
+* **`nodes`**: every party's node list, with its `since`, likewise. The version letting a
+ party in names its list anew, empty where it gives it no nodes.
+* **`rules`**: in order, the first matching a path deciding who writes there
+ ([`writing-and-reading.md`](writing-and-reading.md), Places).
+* **`checkpoint`**, only where the version moves the store to a checkpoint: the heads.
+
+Party names are 1 to 64 of `A-Z a-z 0-9 . _ @ -`; a party has up to 16 keys and 64
+nodes; a rule's path is a path as a write's is, its first segment literal and not
+`_continuum`, `**` last only, `{party}` once at most, and its writer a party of the
+version, `"{party}"` where the path holds it, or `false`. A version breaking any of that
+is none: it can't pass, and a party's client backs none.
+
+## Proposing
+
+```sh
+continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
+ propose next.json
+```
+
+The proposal is on the current version, and its hash is the version's: the node shows it
+under that hash (`proposals` in `GET /events/counts`), with the events proposing it.
+Several parties proposing the same version make one proposal. The key a party proposes
+and votes with is one the current version names for it, not one of its key set.
+
+A proposal lapses, with the votes on it, once its version isn't current any more: when
+another proposal on it passed.
+
+## Voting
+
+```sh
+continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
+ vote 8d02… yes
+```
+
+The client votes by the party's record, never by what a node shows, and writes the
+record before it sends the vote. It casts no vote that would make its party vote twice:
+
+* never `true` and `false` on one proposal, nor the same vote twice;
+* nothing on the version current when the record began, as a vote sent before may be
+ held back somewhere;
+* `true` only for a version changing the current one;
+* one `true` at a time: another `true` on the same version only once the proposal the
+ party backed is dead. The client fetches the votes that made it so from the node, and
+ keeps them in the record beside the new `true`.
+
+A party votes from one client, with one record: two clients backing two proposals at
+once is voting twice, and shows ([`federation.md`](../../federation.md), Changing the
+policy). A party whose node votes for it by itself votes by hand only through that
+node, which keeps its one record:
+
+```sh
+continuum-party --node http://tv:secret@localhost:3000 vote 8d02… yes --through
+```
+
+A party that lost its record begins a new one at a node (`continuum-party init`); it
+casts nothing on the current version, and votes again from the next one. A party that
+never voted may begin its record from the root (`init --root`), and casts on every
+version.
+
+## Passing and dying
+
+A proposal **passes** once at least two thirds of its version's parties voted `true`
+(3·yes ≥ 2·parties), and is **dead** once so many voted `false` that the rest can't
+pass it (3·(parties − no) < 2·parties):
+
+| parties | `true` to pass | `false` to kill |
+|---|---|---|
+| 2 | 2 | 1 |
+| 3 | 2 | 2 |
+| 4 | 3 | 2 |
+| 5 | 4 | 2 |
+| 6 | 4 | 3 |
+| 7 | 5 | 3 |
+| 9 | 6 | 4 |
+
+Every party counts, quiet ones too: a version naming parties that never vote makes every
+decision harder. Once a node holds a proposal passed, it writes the version, and every
+node takes it: `.version.number` in `GET /events/counts` is its number then.
+
+A `true` binds its party while its proposal can still pass. Of nine parties, five back X,
+two prefer Y and two never vote: X needs one more, and can't die, as that takes four
+nays; the five back nothing else on this version. Votes that split pass nothing, three
+for one proposal and three for another of six: a `false` on the proposal you won't back
+kills it the sooner, and frees its backers for another.
+
+## Following a vote
+
+`GET /events/counts` names each proposal on the current version with the events
+proposing it (`proposals`) and the votes on it (`votes`), each by its ID; `GET
+/events/{id}` shows a vote, signed by its party. A node writes nothing more than the
+version once it passed; the parties' records keep their votes.