aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-17 16:10:34 +0000
committertv <tv@krebsco.de>2026-11-17 17:14:22 +0100
commit1ed4ccdb0cd3a9407b6101b1bc595df2a451a18d (patch)
treed75459a0844e3be3d9f646af66fe0ab60586b526 /docs/guides
parent2f78f51a4cd779e0ab989057727995f7bccf75ab (diff)
events: counts names who voted what, and whether a proposal passed or is dead
`GET /events/counts` gives each proposal on the current version the parties voting `true` and `false` (`yes`, `no`), whether it passed and whether it is dead (`passed`, `dead`), as the node reads its votes (`State::tally`, which the fold judges by too), so that reading where a vote stands takes no fetch of every vote. A party's client still decides its votes by the votes it checks itself.
Diffstat (limited to 'docs/guides')
-rw-r--r--docs/guides/federation/proposing-and-voting.md20
-rw-r--r--docs/guides/federation/watching.md3
-rw-r--r--docs/guides/federation/writing-and-reading.md3
3 files changed, 21 insertions, 5 deletions
diff --git a/docs/guides/federation/proposing-and-voting.md b/docs/guides/federation/proposing-and-voting.md
index ee9a46a..3f4aa0f 100644
--- a/docs/guides/federation/proposing-and-voting.md
+++ b/docs/guides/federation/proposing-and-voting.md
@@ -113,6 +113,20 @@ 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"]}}
+```
+
+`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.
diff --git a/docs/guides/federation/watching.md b/docs/guides/federation/watching.md
index e83408f..b66d5b4 100644
--- a/docs/guides/federation/watching.md
+++ b/docs/guides/federation/watching.md
@@ -13,7 +13,8 @@ besides it, the node's store, through its API and its log.
read its store ([`when-things-go-wrong.md`](when-things-go-wrong.md), A node doing less
than it should).
* **Proposals on the current version** (`proposals` in `GET /events/counts`): each with
- the votes on it; the party's record says what it voted.
+ who voted what, and whether it passed or is dead; the party's record says what it
+ voted.
* **The version** (`.version.number` in `GET /events/counts`): a change nobody expected
is worth a look at what passed and who voted for it.
* **The members** (`members` in `GET /events/counts`): a node of your party missing
diff --git a/docs/guides/federation/writing-and-reading.md b/docs/guides/federation/writing-and-reading.md
index 0e6865c..a9e0c5a 100644
--- a/docs/guides/federation/writing-and-reading.md
+++ b/docs/guides/federation/writing-and-reading.md
@@ -97,7 +97,8 @@ Votes and proposals aren't signed again: their version is behind.
* `values`: each place holding a value, with it;
* `members`: each node of the swarm, with its party, `[node, party]`;
* `proposals`: the proposals on the current version, by hash, each with the events
- proposing it and the votes on it ([`proposing-and-voting.md`](proposing-and-voting.md)).
+ proposing it, the votes on it, the parties voting `true` and `false`, and whether it
+ passed and whether it is dead ([`proposing-and-voting.md`](proposing-and-voting.md)).
`GET /events/{id}` is an event's bytes, as its party signed them: anyone can check its
signature, an SSH signature over its bytes without `sig` (namespace