aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 21:24:09 +0000
committertv <tv@krebsco.de>2026-11-19 22:30:41 +0100
commit237c79efc5d25f438d024522fd89ea7fc600cbd1 (patch)
tree4f36801570db29d495b655f66da9901baa149abf /docs/guides
parent5e93c28c963224ce89901b813c06598bcc84f8c7 (diff)
continuum-party: a record held against the node's votes, a wait, restore
A party votes from one record; a second record voting beside it, or one begun anew after a loss, can make the party vote twice. The client votes by its record, never by what a node shows, and still should look. Before a vote (`consistent`, `unrecorded`), the party's votes on the current version that the node shows (each proposal's yes and no) are held against the record's (Record::votes_cast): one the node shows that the record lacks refuses the vote, naming it and `restore`; one the record holds that the node doesn't show is said, as on its way or held back. Where they agree, nothing is said. What may keep a vote from the node is said too (`cut_off`, from counts' `heard`): the party's own nodes the node hasn't heard from in five minutes, through which another vote of it may have gone; and the parties none of whose nodes it heard from lately, where they are a third of those with nodes or more: a part of the swarm cut off. Then it waits (--wait SECONDS, 5 unless given, on vote and propose) and asks the node again: a vote cast elsewhere just before arrives first. A version passing meanwhile ends it, as the proposal lapsed. `restore` takes the party's votes on the current version, as the node holds them, into its record, or a new one of --party (Record::restore, checking each vote's signature, its party and version, none twice); a record begun on the current version casts on it then. Best effort: a vote on its way from elsewhere isn't among them, and what `again` signs anew, and the nays that freed an earlier `true`, it doesn't learn.
Diffstat (limited to 'docs/guides')
-rw-r--r--docs/guides/federation/proposing-and-voting.md38
1 files changed, 34 insertions, 4 deletions
diff --git a/docs/guides/federation/proposing-and-voting.md b/docs/guides/federation/proposing-and-voting.md
index b58a926..48ec03c 100644
--- a/docs/guides/federation/proposing-and-voting.md
+++ b/docs/guides/federation/proposing-and-voting.md
@@ -127,7 +127,24 @@ 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
+[Changing the policy](../../federation.md#changing-the-policy)). Before it casts, the
+client holds the record against the votes of its party the node shows on the current
+version, and says nothing where they agree:
+
+* a vote the node shows that the record lacks refuses the vote: another record votes for
+ the party, or this one was begun anew, and casting beside it may be voting twice;
+ `restore` (below) takes it into the record;
+* a vote the record holds that the node doesn't show yet is said: on its way, or held
+ back where it was put;
+* the party's nodes the node hasn't heard from in five minutes are said, as a vote put
+ through one of them may not have reached it, and so are the parties none of whose nodes
+ it heard from lately, where they are a third of those with nodes or more: a part of the
+ swarm may be cut off, its votes not here (`heard` in `GET /events/counts`).
+
+It then waits five seconds (`--wait SECONDS`, 0 not at all), asks the node again, and
+casts only where nothing came meanwhile: a vote cast elsewhere just before arrives first.
+A vote cast elsewhere at the same moment, or held back by a cut, it can't see: one place
+votes for a party. A party whose node votes
for it by itself votes by hand only through that node, which keeps its one record:
```sh
@@ -135,9 +152,22 @@ continuum-party --node http://tv:secret@localhost:3000 vote 8d02… yes --throug
```
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.
+casts nothing on the current version, and votes again from the next one. Or it restores
+one, best effort: `restore` takes the party's votes on the current version, as the node
+holds them, into the record, a new one where there is none (with `--party`), which then
+casts on the current version by them:
+
+```sh
+continuum-party --party tv --record tv.record restore
+# took 1 vote of tv on version 3 into tv.record, as the node holds them; one on its way
+# from elsewhere isn't among them
+```
+
+A vote held back somewhere, or still on its way, isn't among them: restore where the node
+hears from every party's nodes, and give a vote cast before the loss time to arrive. What
+the party signs again after a move (`again`) a restored record doesn't know, nor the nays
+that freed its earlier `true`, which its old record kept. A party that never voted may
+begin its record from the root (`init --root`), and casts on every version.
## Counting support first