aboutsummaryrefslogtreecommitdiffstats

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, 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 (common-changes.md does the first steps below in one):

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, Places).
  • checkpoint, only where the version moves the store to a checkpoint: the heads. Otherwise leave it out, though the current version names one: its heads are behind, and a version naming them again is never written.

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

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

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, Changing the policy). A party whose node votes for it by itself votes by hand only through that node, which keeps its one record:

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; the parties voting true (yes) and false (no); and whether it passed (passed) and whether it is dead (dead), as the node reads its votes:

curl -s -u tv:secret localhost:3000/events/counts | jq .proposals
# {"8d02…":{"dead":true,"no":["lass"],"passed":false,"proposals":["c41e…"],
#   "votes":["5a77…","e019…"],"yes":["tv"]}}

The client shows the same, and what each proposal's version changes of the current one, field by field and party by party:

continuum-party --node http://tv:secret@localhost:3000 proposals
# 8d02…: dead; true: tv; false: lass
#   changes: null -> "1f4c…"
#   checkpoint: - -> ["4a1d…","9e30…"]
#   number: 0 -> 1

A node's dashboard shows them so too, and where the node votes for its party by itself, votes through it (dashboard.md, Federation).

GET /events/{id} shows a proposing event, the version it proposes in proposal, and a vote, signed by its party. A node lacking some votes reads a proposal as neither passed nor dead where another reads it dead; no vote takes either back. A dead proposal stays listed until a version passes on the current one, and a passed one is written at once; then every proposal on the version before lapses. A party's client decides its votes by the votes it checks itself, never by what a node says of them; the parties' records keep their votes.