aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/proposing-and-voting.md
blob: e91806cfec85cbf467dfdbb271b7313968b951fa (plain)
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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
# Proposing and voting

Everything a federation decides is a change of its policy: who the parties are, the keys
they vote with, 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](../../federation.md#the-policy),
[Changing the policy](../../federation.md#changing-the-policy)). A party's node list and
its key set are its own to write, without a vote
([`common-changes.md`](common-changes.md#what-a-party-does-by-itself)).

## Writing a version

A version is the whole policy, not a change to it. Begin from the current one, as a node
shows it, with `number` and `changes` set and its `checkpoint` left out, as below:

```sh
continuum-party --node http://tv:secret@localhost:3000 next > next.json
```

What each field holds, to change ([`common-changes.md`](common-changes.md) has recipes
for the changes made most):

* **`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. Otherwise a version
  names a list anew only where its party can't write its own, with a key the current
  version names for it: a party adds and takes off its nodes by itself
  ([`common-changes.md`](common-changes.md#what-a-party-does-by-itself)).
* **`rules`**: in order, the first matching a path deciding who writes there
  ([`writing-and-reading.md`](writing-and-reading.md),
  [Places](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.
* **`revision`**, the revision of the federation the version follows, by its ID, left
  out for the base revision: the current version's, or a later one (`next --revision`,
  [`upgrades.md`](upgrades.md), [Moving to a revision](upgrades.md#moving-to-a-revision)).

Party names are 1 to 64 of `A-Z a-z 0-9 . _ @ -`; a version names up to 96 parties; 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, and a party's client backs none; where two thirds pass it
all the same, nodes stop at the version event writing it, until their operators have them
drop it ([`when-things-go-wrong.md`](when-things-go-wrong.md),
[A node stopped](when-things-go-wrong.md#a-node-stopped)).

## Proposing

```sh
continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
  propose next.json
# c41e… taken
# proposal 8d02…
```

With `--yes`, the client votes `true` on it too, as `vote 8d02… yes` does
([Voting](#voting), below): a party whose node votes for it by itself votes through that
node instead.

The client proposes only a version it would back: one changing the current one as a
version must (its `number`, `changes`, and each `since`), whose checkpoint, where it names
one, names no more than 64 heads and none of the heads of the current version's
checkpoint, as such a version is never written. It says why it doesn't propose one
otherwise. 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 that a vote may build on: of a checkpoint, those above its heads. 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: the client checks that
before it signs, and records nothing otherwise.

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, whose checkpoint names none of the
  current checkpoint's heads;
* 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, keeps
  them in the record beside the new `true`, and builds the `true` on them, so that the
  first is dead at its history too: the proposal it backs next may have been proposed at
  a history holding its first `true`. A checkpoint's `true` it builds on the proposal
  alone, and says when it may be refused so: where the nays came after the heads the
  checkpoint names, back the one proposed after.

A `true` holds the party until its proposal passes or is dead, and only other parties'
nays make it dead. Where ending it would take every party yet to vote, or more, and those
are a third of the parties or fewer, the client says so before it casts the `true`
(``Warning: this `true` binds tv until the proposal passes, …``): one of them staying
quiet binds the party on this version for good, unless the proposal passes.

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](../../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.

## 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`
(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`); whether it passed (`passed`) and whether it is
dead (`dead`), as the node reads its votes; and why no party's client backs it (`none`),
where it is no version this node reads, none changing the current one, or one naming the
heads of the current one's checkpoint, else `null`:

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

The client shows the same, why it backs one not, by the federation it knows, what each
proposal's version changes of the current one, field by field and party by party, and
the places holding a value whose writer it changes (`who writes names/wiki/a: tv ->
wiki`): admitting a party named as a segment of a place is, or changing the rules or
their order, moves who writes there, rules unchanged in the first case, and what was
written there counts no more once it passes:

```sh
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`](../../dashboard.md),
[Federation](../../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.