From dd720b2556fa64bd07dc1d087b502ac4ab0f7899 Mon Sep 17 00:00:00 2001 From: tv Date: Thu, 19 Nov 2026 01:48:58 +0000 Subject: vote: propose a checkpoint after so many versions The votes cast before count at a history from before too: a proposal that died, or a rival, needs there only the votes it lacked, and after a close vote one key voting twice is enough, at any time until a checkpoint above the version that followed. Nodes that took that version refuse it; one lagging behind, or joining from the root, may take it. `federation.md` said it took the keys of two thirds of the parties. A node voting by itself proposes a checkpoint once so many versions were written since its store's (`--store-propose-versions`), as the design lists: with 1, after every version, so that what keys voting twice grow beside a version ends at a checkpoint above it. `federation.md` says how little a rival version takes, row 20 too, and the guides the option. --- docs/example.toml | 6 ++-- docs/federation.md | 16 ++++++--- docs/guides/federation/checkpoints.md | 11 ++++--- docs/guides/federation/voting-by-itself.md | 22 +++++++------ src/config/mod.rs | 14 ++++++++ src/federation/fold.rs | 5 +++ src/federation/vote.rs | 52 ++++++++++++++++++++++++------ src/lib.rs | 1 + 8 files changed, 97 insertions(+), 30 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. diff --git a/src/config/mod.rs b/src/config/mod.rs index feb16e3..0e6e1b9 100644 --- a/src/config/mod.rs +++ b/src/config/mod.rs @@ -305,6 +305,14 @@ pub(crate) const OPTIONS: &[OptionSpec] = &[ "With store-vote-key: propose a checkpoint, as store-propose-events, once this long passed by its own clock since its store moved to its checkpoint, or started there.", ), #[cfg(feature = "federation")] + option( + "store-propose-versions", + Kind::Integer, + "COUNT", + None, + "With store-vote-key: propose a checkpoint, as store-propose-events, once this many versions were written since its store's checkpoint: with 1, after every version, so that what keys voting twice could grow beside it at a history from before ends there.", + ), + #[cfg(feature = "federation")] option( "store-held-for", Kind::Duration, @@ -835,6 +843,8 @@ pub(crate) struct Settings { )] pub(crate) store_propose_every: Option, #[cfg(feature = "federation")] + pub(crate) store_propose_versions: Option, + #[cfg(feature = "federation")] #[serde( default = "default_store_held_for", with = "crate::units::duration_option" @@ -1370,6 +1380,10 @@ impl Settings { ("store-nay-beside", self.store_nay_beside), ("store-propose-events", self.store_propose_events.is_some()), ("store-propose-every", self.store_propose_every.is_some()), + ( + "store-propose-versions", + self.store_propose_versions.is_some(), + ), ]; match (&self.store_vote_key, &self.store_vote_record) { (Some(_), None) => { diff --git a/src/federation/fold.rs b/src/federation/fold.rs index 46f56e1..3670051 100644 --- a/src/federation/fold.rs +++ b/src/federation/fold.rs @@ -348,6 +348,11 @@ impl State { ballots } + /// The checkpoint's version: the one current where the store moved there, or started. + pub(crate) fn checkpoint_version(&self) -> &Version { + &self.versions[&self.checkpoint] + } + /// The version the proposal of hash `proposal` proposes, as JSON, where it holds one: /// whether it is a version is asked apart (`Version::read`). pub(crate) fn proposal(&self, proposal: &Id) -> Option<&Json> { diff --git a/src/federation/vote.rs b/src/federation/vote.rs index 4c4cdfa..2e5ce15 100644 --- a/src/federation/vote.rs +++ b/src/federation/vote.rs @@ -6,13 +6,13 @@ //! follows voted `true`, never `false`; by default only on a version that only moves to a //! checkpoint (`Version::only_moves_on`), and then only where no proposal that changes //! more holds it back (`holds_back`), as such a version lapses it. -//! * **Proposing a checkpoint**: once so many events are held beyond its checkpoint, or so -//! long after it 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, 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 new, held less than a while, whose proposer has no older one on the version -//! (`holds_back`). It backs what it proposes. +//! * **Proposing a checkpoint**: once so many events are held beyond its checkpoint, so +//! many versions were written since, or so long after it 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, 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 new, held less than a while, whose proposer has no +//! older one on the version (`holds_back`). It backs what it proposes. //! * **Voting `false` beside**: where it backs a proposal that can still pass, it votes //! `false` on every other proposal on the current version that only moves to a //! checkpoint, so that, of two checkpoints proposed at once, the one it doesn't back @@ -46,8 +46,10 @@ pub(crate) struct Rules { pub(crate) follow_any: bool, /// Proposing a checkpoint once so many events are held beyond the checkpoint... pub(crate) propose_events: Option, - /// ...or so long after the store moved to it, by its own clock. + /// ...or so long after the store moved to it, by its own clock... pub(crate) propose_every: Option, + /// ...or once so many versions were written since the one it holds. + pub(crate) propose_versions: Option, /// How long it holds an event before it holds it for a while. pub(crate) held_for: Duration, /// Voting `false` on a checkpoint proposed beside one it backs. @@ -407,12 +409,16 @@ pub(crate) fn by_hand( /// that nobody backs but its proposer. fn checkpoint(seen: &Seen<'_>, rules: &Rules, current: &Version, all: &[Proposed]) -> Option { let store = seen.store; + let since = current.number - store.state().checkpoint_version().number; let due = rules .propose_events .is_some_and(|events| store.taken().len() >= events) || rules .propose_every - .is_some_and(|every| seen.since_move >= every); + .is_some_and(|every| seen.since_move >= every) + || rules + .propose_versions + .is_some_and(|versions| since >= versions); if !due || seen.since_move < rules.back_after { return None; } @@ -779,6 +785,34 @@ mod tests { assert!(by_hand(&seen(&store, &long), &rules, &record, next.hash(), false).is_err()); } + /// A node proposes a checkpoint once so many versions were written since its store's: + /// with one, after every version, at heads above it. + #[test] + fn a_node_proposes_a_checkpoint_after_a_version() { + let (tv, lass, _, first, mut store) = three(); + let root = store.id(); + let on = first.hash(); + let next = first.after(on); + let proposal = taken(&mut store, tv.propose(&[root], &next.json())); + let votes = [&tv, &lass] + .map(|party| taken(&mut store, party.vote(&[proposal], on, next.hash(), true))); + let rules = Rules { + propose_versions: Some(1), + ..Rules::default() + }; + let long = |_: &Id| Some(Duration::from_secs(3600)); + let record = record(&store, "makefu"); + assert!(decide(&seen(&store, &long), &rules, &record).is_empty()); + let written = taken(&mut store, harness::version_event(&votes, next.hash())); + let acts = decide(&seen(&store, &long), &rules, &record); + let [Act::Propose(json)] = acts.as_slice() else { + panic!("not one proposal: {acts:?}"); + }; + let version = Version::read(json).unwrap(); + assert_eq!(version.checkpoint, Some(vec![written])); + assert_eq!(version.changes, Some(next.hash())); + } + #[test] fn a_node_proposes_a_checkpoint_at_what_it_held_for_a_while() { let (tv, _, _, first, mut store) = three(); diff --git a/src/lib.rs b/src/lib.rs index 66d54bc..5873a89 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -69,6 +69,7 @@ fn voter(args: &config::Settings) -> Result> { nay_beside: args.store_nay_beside, propose_events: args.store_propose_events, propose_every: args.store_propose_every, + propose_versions: args.store_propose_versions, held_for: args.store_held_for, back_after: args.store_back_after, }, -- cgit v1.3.1