1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
# 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 ([`common-changes.md`](common-changes.md) does the first steps below in one):
```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.
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
```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.
|