diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/example.toml | 6 | ||||
| -rw-r--r-- | docs/federation.md | 16 | ||||
| -rw-r--r-- | docs/guides/federation/checkpoints.md | 11 | ||||
| -rw-r--r-- | docs/guides/federation/voting-by-itself.md | 22 |
4 files changed, 34 insertions, 21 deletions
diff --git a/docs/example.toml b/docs/example.toml index 4bb5c98..4078017 100644 --- a/docs/example.toml +++ b/docs/example.toml @@ -154,8 +154,9 @@ htpasswd = "/etc/continuum/htpasswd" # hand only through it (POST /admin/events/vote). It follows the `true` of the parties # named (by default only on versions that only move to a checkpoint), votes `false` on a # checkpoint proposed beside one it backs, if told, and proposes a checkpoint once it -# holds so many events beyond its checkpoint, or so long after it moved there; it backs -# and proposes none sooner than store-back-after after a move or its start. +# holds so many events beyond its checkpoint, so many versions were written since, or so +# long after it moved there; it backs and proposes none sooner than store-back-after +# after a move or its start. # store-vote-key = "/var/lib/continuum/party.key" # store-vote-record = "/var/lib/continuum/party-record.json" # store-follow = ["lass"] @@ -163,6 +164,7 @@ htpasswd = "/etc/continuum/htpasswd" # store-nay-beside = false # store-propose-events = 10000 # store-propose-every = "7d" +# store-propose-versions = 1 # store-held-for = "10m" # store-back-after = "10m" diff --git a/docs/federation.md b/docs/federation.md index 1d77e4f..ceb1064 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -336,9 +336,13 @@ chain the node took. won't wait fork. * **Two versions changing one** are written only where keys voted twice: a party voting `true` and `false` on one proposal, each shown to some, or `true` on two; or the keys - an earlier version named, for two thirds of its parties, passing another proposal on - it at a history from before the version that followed: some party among them backed - that one too (two shares of two thirds share a party). Each node keeps the version it + an earlier version named passing another proposal on it at a history from before the + version that followed: some party among them backed that one too (two shares of two + thirds share a party). The votes cast before count at such a history too, so it takes + only the votes a proposal lacked there: after a close vote, one key voting twice, its + `true` on a proposal that died where its `false` isn't in the history, can be enough, + at any time until a checkpoint above the version that followed, as the votes it builds + on are all before that version. Each node keeps the version it took and refuses the other, so nodes holding the same events still read the same policy, and an event whose history holds both is refused, as no version is current there; the sides are apart, and a node that lagged behind, or joins, may be shown @@ -520,7 +524,9 @@ as it judges any vote or proposal. The design has two in mind: * **Proposing a checkpoint**: propose a version that only moves to a checkpoint, at heads the node has held for a while, once conditions its operator sets are met: so many events or bytes held beyond its checkpoint, so many versions since it, or so long - by its own clock, by which nothing anyone judges goes. It proposes only where no + by its own clock, by which nothing anyone judges goes. One after every version ends, + at the checkpoint, what keys voting twice could grow beside that version at a history + from before it. It proposes only where no proposal on the current version holds it back, as such a version lapses what is: one it would back that can still pass; one that can still pass that a third of the parties back, someone but its proposer among them; or one new, held for less than a while, whose @@ -694,7 +700,7 @@ fold, with crafted events. *Sim*: a simulation. *Bench*: measured, not judged. | 17 | Votes split, honestly or not | Nothing passes; nays make the proposals dead, and another passes | unit | | 18 | The parties beyond two thirds never vote, or vote `false` on everything | Nothing passes; the others fork | unit | | 19 | A node of the party a version takes out writes that version | Taken: a version counts by its votes, not by who wrote it | unit | -| 20 | The keys an earlier version named, for two thirds of its parties, pass another proposal on it at a history from before, and raise its number | Refused by every node that took the version after it, and reported; a node that lagged may take it: keys voted twice | unit | +| 20 | The keys an earlier version named pass another proposal on it, or one that died, at a history from before, the votes cast before counting with theirs, so that after a close vote one key voting twice is enough, and raise its number | Refused by every node that took the version after it, and reported; a node that lagged, or joins from the root, may take it: keys voted twice. Refused by every node once a checkpoint above that version passed: nodes may propose one after every version (`--store-propose-versions 1`) | unit | | 21 | Two versions changing the one a node reads, coming together | It takes the first it judges, and refuses the other | unit | | 22 | Values signed with a key a party's set holds, stolen | Count until the party drops the key | unit | | 23 | A key a version names, stolen, votes, or writes its party's set or list | Counts while that version is current; the party's own vote beside it is voting twice, answered by a fork | unit | diff --git a/docs/guides/federation/checkpoints.md b/docs/guides/federation/checkpoints.md index f935421..cd77e28 100644 --- a/docs/guides/federation/checkpoints.md +++ b/docs/guides/federation/checkpoints.md @@ -35,11 +35,12 @@ Like any version, it lapses the proposals on the version before: propose one whe nothing that can still pass is proposed on the current version. A node voting for its party by itself proposes checkpoints by its operator's rules: once -it holds so many events beyond its checkpoint (`--store-propose-events`), or so long -after its store moved there (`--store-propose-every`), at the heads of what it held for -a while (`--store-held-for`, ten minutes unless set), where no proposal holds it back -([`voting-by-itself.md`](voting-by-itself.md), [Its rules](voting-by-itself.md#its-rules)); -and it backs what it proposes. +it holds so many events beyond its checkpoint (`--store-propose-events`), so many +versions were written since it (`--store-propose-versions`, after every version with 1), +or so long after its store moved there (`--store-propose-every`), at the heads of what it +held for a while (`--store-held-for`, ten minutes unless set), where no proposal holds it +back ([`voting-by-itself.md`](voting-by-itself.md), +[Its rules](voting-by-itself.md#its-rules)); and it backs what it proposes. ## Backing one diff --git a/docs/guides/federation/voting-by-itself.md b/docs/guides/federation/voting-by-itself.md index cfcdcf3..a31595f 100644 --- a/docs/guides/federation/voting-by-itself.md +++ b/docs/guides/federation/voting-by-itself.md @@ -47,15 +47,19 @@ or `POST /admin/events/vote` with `{"proposal": "8d02…", "yes": true}`. no checkpoint until its store held its checkpoint, or ran, that long by its own clock, by itself or by hand: the parties it follows move the store once that long at most, and just started, it holds nothing for a while yet. -* **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 no proposal on the current version holds it back: one it would back - that can still pass; one that can still pass that a third of the parties back, someone - but its proposer among them; or one held for less than a while whose proposer has none - older on the version. It backs what it proposes, so that the nodes following its party - back it too. +* **Proposing checkpoints** (`--store-propose-events COUNT`, `--store-propose-versions + COUNT`, `--store-propose-every DURATION`): once it holds so many events beyond its + checkpoint, so many versions were written since it, 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 no + proposal on the current version holds it back: one it would back that can still pass; + one that can still pass that a third of the parties back, someone but its proposer among + them; or one held for less than a while whose proposer has none older on the version. It + backs what it proposes, so that the nodes following its party back it too. With + `--store-propose-versions 1`, it proposes one after every version: after a close vote, + one key voting twice can pass a rival version at a history from before it, any time + later, which nodes lagging behind or joining from the root may take; a checkpoint above + that version ends that. * **`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. |
