diff options
| -rw-r--r-- | docs/guides/federation/README.md | 2 | ||||
| -rw-r--r-- | docs/guides/federation/proposing-and-voting.md | 116 |
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. |
