aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/proposing-and-voting.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/guides/federation/proposing-and-voting.md')
-rw-r--r--docs/guides/federation/proposing-and-voting.md90
1 files changed, 69 insertions, 21 deletions
diff --git a/docs/guides/federation/proposing-and-voting.md b/docs/guides/federation/proposing-and-voting.md
index ee9a46a..e656083 100644
--- a/docs/guides/federation/proposing-and-voting.md
+++ b/docs/guides/federation/proposing-and-voting.md
@@ -1,21 +1,24 @@
# 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).
+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 ([`common-changes.md`](common-changes.md) does the first steps below in one):
+shows it, with `number` and `changes` set and its `checkpoint` left out, as below:
```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
+continuum-party --node http://tv:secret@localhost:3000 next > next.json
```
-Then change it:
+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.
@@ -24,9 +27,13 @@ Then change it:
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.
+ 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`](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.
@@ -42,12 +49,23 @@ is none: it can't pass, and a party's client backs none.
```sh
continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
propose next.json
+# c41e… taken
+# proposal 8d02…
```
-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.
+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 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.
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.
+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.
@@ -65,15 +83,16 @@ record before it sends the vote. It casts no vote that would make its party vote
* 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;
+* `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, 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:
+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
@@ -113,6 +132,35 @@ 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.
+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:
+
+```sh
+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:
+
+```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.