aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-17 13:50:04 +0000
committertv <tv@krebsco.de>2026-11-17 15:04:15 +0100
commit5972eb84ebea9944fe6a7f1d23a90e52269c69a6 (patch)
treee2a734f3fb4def052da83e11a9deccb314e525f7 /docs
parent4bc653a9f81e2b22fd45eb8481ca4b3e122db28a (diff)
guides: a node voting by itself
Setting up a node to vote for its party, its key and the party's one record, voting by hand through it, its rules for following, proposing checkpoints and voting `false` beside, what it keeps to, and what its log says.
Diffstat (limited to 'docs')
-rw-r--r--docs/guides/federation/README.md2
-rw-r--r--docs/guides/federation/voting-by-itself.md75
2 files changed, 77 insertions, 0 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md
index 6a0cd1e..cc415cd 100644
--- a/docs/guides/federation/README.md
+++ b/docs/guides/federation/README.md
@@ -24,3 +24,5 @@ by them, in its words.
what that asks of a party, an operator and an application.
* [`common-changes.md`](common-changes.md): the next version, and recipes for letting a
party in, taking one out, giving places, zones and blocks, and keys named anew.
+* [`voting-by-itself.md`](voting-by-itself.md): a node voting and proposing for its party
+ by its operator's rules: its key, its record, following, proposing checkpoints.
diff --git a/docs/guides/federation/voting-by-itself.md b/docs/guides/federation/voting-by-itself.md
new file mode 100644
index 0000000..bf7a01e
--- /dev/null
+++ b/docs/guides/federation/voting-by-itself.md
@@ -0,0 +1,75 @@
+# A node voting by itself
+
+A party may have one of its nodes vote and propose for it, by rules its operator sets,
+written nowhere in the swarm: every node judges what such a node signs as any vote or
+proposal. The rules are the design's ([`federation.md`](../../federation.md), Votes a
+node casts by itself).
+
+## Setting it up
+
+```sh
+continuum --store-id 6d1e… --store-party tv … \
+ --store-vote-key tv.key --store-vote-record tv.record \
+ --store-follow lass,makefu --store-nay-beside --store-propose-events 1000
+```
+
+* `--store-vote-key`: a key the party's version names, an OpenSSH private key file
+ without a passphrase, kept on the node. One stolen there votes, and writes the party's
+ key set and node list, as the party, until a version names its keys anew
+ ([`keys.md`](keys.md)).
+* `--store-vote-record`: the party's one record of its votes, which the node votes by
+ and writes before each vote. Where there is none, the node begins one on the version
+ current then, and casts nothing on that version; a party that never voted gives it one
+ begun from the root instead (`continuum-party --record tv.record init tv --root
+ root`), which casts on every version. A record of another store or party, the node
+ doesn't take, and votes none (`Voting by itself, without its party's record: votes
+ none`).
+
+A party has one node vote by itself: two of its nodes, each voting so, can vote twice.
+And it 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
+```
+
+or `POST /admin/events/vote` with `{"proposal": "8d02…", "yes": true}`.
+
+## Its rules
+
+* **Following** (`--store-follow PARTY,…`): it votes `true` on a proposal where a party
+ it follows voted `true`, and `false` where one voted `false`; by default only on a
+ version that only moves to a checkpoint. With `--store-follow-any`, on any version:
+ that hands those parties the node's vote, its `false` among it. A party followed so by
+ more than a third of the parties, with its key kept on a node, can end every proposal,
+ the one naming that key anew among them.
+* **Proposing checkpoints** (`--store-propose-events COUNT`, `--store-propose-every
+ DURATION`): once it holds so many events beyond its checkpoint, or so long after its
+ store moved there by its own clock, it proposes a version that only moves to a
+ checkpoint, at the heads of what it held for a while (`--store-held-for`, ten minutes
+ unless set), where nothing that can still pass is proposed on the current version,
+ but a proposal it wouldn't back that nobody backs but its proposer. It backs what it
+ proposes, so that the nodes following its party back it too.
+* **`false` beside** (`--store-nay-beside`): where it backs a proposal that can still
+ pass, it votes `false` on every other version only moving to a checkpoint, so that of
+ two checkpoints proposed at once the other dies, and its backers are free.
+
+## What it keeps to
+
+What a party's client keeps to: one `true` at a time, never `true` and `false` on one
+proposal, nothing on the version its record began on, and no `true` for a proposal that
+is no version ([`proposing-and-voting.md`](proposing-and-voting.md), Voting). And, for a
+version naming a checkpoint, the voters' rule: it backs one only where it changes nothing
+of the current version but its number, what it changes and its checkpoint, and its heads
+leave out nothing it held for a while before it was proposed
+([`checkpoints.md`](checkpoints.md), Backing one). A vote by hand through it keeps to the
+same.
+
+It signs its votes on the events proposing what it votes on, and its checkpoint
+proposals on its heads, so that a version event may be written on them.
+
+## Watching it
+
+Its log says what it signs and why it signs nothing: `Voting for its party` (with the
+proposal, the vote, and whether by hand), `Proposing a checkpoint for its party`,
+`Couldn't vote by itself` (with why). What it cast is in its record, and at its node
+(`votes` of each proposal in `GET /events/counts`).