aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 01:48:57 +0000
committertv <tv@krebsco.de>2026-11-19 03:19:19 +0100
commit101080b8a62709cd2606dece086f959781bdf38f (patch)
tree618e9acdd6e5d311ece2cf5b213432257c31bc39
parente0075264e9efdd4c8a32290c0d5643e7f48bfb14 (diff)
vote: a follower copies no false, lapses nothing others back, waits after a move
A node following a party (`--store-follow`) handed it more than the text said: * it copied the party's `false`: one party's nay freed bound followers, and its `true` shown to some and its `false` to the rest passed a checkpoint at one history and made it dead at another. It copies the `true` alone now, on any version too; * a checkpoint lapses every other proposal: the followed party ended any proposal it disliked by passing one. A node follows a checkpoint only where no proposal that changes more can still pass that someone but its proposer backs; * nothing bounded how often the store moved, so fresh events could be left out of every checkpoint; and a node just started held nothing for a while, so the voters' rule kept nothing. A node backs, and proposes, a checkpoint only once its store held its checkpoint, or ran, for a while (`--store-back-after`, ten minutes unless set), by itself or by hand. `federation.md` says what following hands over, and row 58 what a follower on any version copies; the guides and the example say the rest.
-rw-r--r--docs/example.toml8
-rw-r--r--docs/federation.md27
-rw-r--r--docs/guides/federation/checkpoints.md7
-rw-r--r--docs/guides/federation/voting-by-itself.md15
-rw-r--r--src/config/mod.rs14
-rw-r--r--src/federation/vote.rs176
-rw-r--r--src/lib.rs1
7 files changed, 194 insertions, 54 deletions
diff --git a/docs/example.toml b/docs/example.toml
index 7f01df7..4bb5c98 100644
--- a/docs/example.toml
+++ b/docs/example.toml
@@ -151,10 +151,11 @@ htpasswd = "/etc/continuum/htpasswd"
# Behind the `federation` feature: this node votes and proposes for its party by itself
# (docs/federation.md, Votes a node casts by itself), with a key its party's version
# names, kept here, and its party's one record of its votes; its party then votes by
-# hand only through it (POST /admin/events/vote). It follows the parties named (by
-# default only on versions that only move to a checkpoint), votes `false` on a
+# 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.
+# 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.
# 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-propose-events = 10000
# store-propose-every = "7d"
# store-held-for = "10m"
+# store-back-after = "10m"
# SSH keys, as authorized_keys lines (ssh-ed25519 <base64> [comment]), whose signature
# on a strict remake's manifest this node takes: the values kept when the swarm turns
diff --git a/docs/federation.md b/docs/federation.md
index ade27a9..784915a 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -505,14 +505,18 @@ A party may have one of its nodes vote and propose for it, by rules its operator
the rules are written nowhere in the swarm, and every node judges what such a node signs
as it judges any vote or proposal. The design has two in mind:
-* **Following**: back a proposal where a party the rule names backed it, and vote
- `false` where that party did; a proposal binds its proposer to nothing, so following
- one would bind the node where that party is free. By default it follows only on a
- version that only moves to a checkpoint ([Checkpoints](#checkpoints)), a `true` as a
- `false`; its operator may have it follow on any version, which hands that party the
- node's vote, its `false` among it: a party followed so by more than a third of the
- parties, its key kept on a node, ends every proposal, the one naming that key anew among
- them.
+* **Following**: back a proposal where a party the rule names backed it; a proposal
+ binds its proposer to nothing, so following one would bind the node where that party is
+ free. A `false` it copies not: copied, one party's `false` would free bound followers,
+ and its `true` shown to some and its `false` to the rest would pass a proposal at one
+ history and make it dead at another. By default it follows only on a version that only
+ moves to a checkpoint ([Checkpoints](#checkpoints)), and only where no proposal that
+ changes more can still pass, but one nobody backs but its proposer: such a version
+ lapses every other proposal, and the party it follows would end any it disliked by
+ passing one. Even so, the parties following one hand it their votes on checkpoints: with
+ them, it passes one at heads of its choosing, by the voters' rule (below). Its operator
+ may have it follow on any version, which hands that party the node's `true`: a party
+ followed so by two thirds of the parties, its key kept on a node, passes what it backs.
* **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
@@ -529,7 +533,10 @@ rule for checkpoints, none for a version that changes more than its number, what
changes and its checkpoint, which it checks against the current one, nor for one whose
heads leave out what it held for a while ([Checkpoints](#checkpoints)). Where two
checkpoints are proposed at once, the votes split, as any do; a rule may vote `false` on
-the one it doesn't back, so that one dies and its backers are free. A node that stopped
+the one it doesn't back, so that one dies and its backers are free. It backs, and
+proposes, a checkpoint only once its store held its checkpoint, or ran, for a while, by
+its own clock: so the parties it follows move the store at most once that long, and a
+node just started, which holds nothing for a while yet, backs none. A node that stopped
at a version it doesn't read casts nothing, by itself or by hand, as what it reads is
behind ([Changing the federation](#changing-the-federation)).
@@ -722,7 +729,7 @@ fold, with crafted events. *Sim*: a simulation. *Bench*: measured, not judged.
| 55 | A checkpoint a node can't build, handed to it by peers, or a fork's root it can't check | Taken only where its operator pinned it, or named the fork | unit |
| 56 | Two versions changing one, naming different checkpoints | As 12: each node keeps the one it took, and moves to its checkpoint | unit |
| 57 | A key added back, or a place given back, after a checkpoint | Brings back nothing signed before the checkpoint that counted no more there | unit |
-| 58 | A party a node follows backs, or votes `false` on, a version that changes more than its checkpoint | By default the node follows neither; one following on any version does, as its operator chose | unit |
+| 58 | A party a node follows backs, or votes `false` on, a version that changes more than its checkpoint | By default the node follows neither; one following on any version backs the one, as its operator chose, and copies no `false` | unit |
| 59 | Two checkpoints proposed at once, by nodes voting by themselves | The votes split; nays from the nodes backing one make the other dead, and its backers are free | sim |
| 60 | Two nodes of one party, each voting by itself | They can vote twice, answered as any party voting twice: a party has one node vote by itself | — |
| 61 | A key a version names, kept on a node that votes by itself, stolen with it | As 23: it counts while that version is current | unit |
diff --git a/docs/guides/federation/checkpoints.md b/docs/guides/federation/checkpoints.md
index 69debaf..345bc98 100644
--- a/docs/guides/federation/checkpoints.md
+++ b/docs/guides/federation/checkpoints.md
@@ -50,8 +50,11 @@ only so, and so does a vote by hand through it (`continuum-party vote … --thro
party's client voting on its own (`continuum-party vote`) checks no heads: check them
yourself, or vote through such a node.
-* `--store-follow PARTY,…` has a node voting by itself follow those parties' votes, by
- default on versions that only move to a checkpoint, and still by that rule.
+* `--store-follow PARTY,…` has a node voting by itself follow those parties' `true`,
+ by default on versions that only move to a checkpoint, and still by that rule, but not
+ where a proposal changing more can still pass that someone but its proposer backs.
+* `--store-back-after` (ten minutes unless set) has it back none before its store held its
+ checkpoint, or ran, that long.
* `--store-nay-beside` has it vote `false` on every other version only moving to a
checkpoint, where it backs one that can still pass: of two checkpoints proposed at once,
the other dies, and its backers are free.
diff --git a/docs/guides/federation/voting-by-itself.md b/docs/guides/federation/voting-by-itself.md
index b88947a..97f4eff 100644
--- a/docs/guides/federation/voting-by-itself.md
+++ b/docs/guides/federation/voting-by-itself.md
@@ -37,11 +37,16 @@ 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.
+ it follows voted `true`, never `false`; by default only on a version that only moves to
+ a checkpoint, and only where no proposal changing more can still pass that someone but
+ its proposer backs, as a checkpoint lapses it. Even so, the parties following one hand
+ it their votes on checkpoints. With `--store-follow-any`, on any version: that hands
+ those parties the node's `true`. A party followed so by two thirds of the parties, with
+ its key kept on a node, passes what it backs.
+* **After a move** (`--store-back-after`, ten minutes unless set): it backs, and proposes,
+ 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
diff --git a/src/config/mod.rs b/src/config/mod.rs
index 8196db6..412753e 100644
--- a/src/config/mod.rs
+++ b/src/config/mod.rs
@@ -312,6 +312,14 @@ pub(crate) const OPTIONS: &[OptionSpec] = &[
Some("10m"),
"With store-vote-key: how long it holds an event before it holds it for a while: it proposes a checkpoint at the heads of such, and backs none whose heads leave out one it held for a while before it was proposed.",
),
+ #[cfg(feature = "federation")]
+ option(
+ "store-back-after",
+ Kind::Duration,
+ "DURATION",
+ Some("10m"),
+ "With store-vote-key: how long its store holds its checkpoint, or runs, by its own clock, before it backs or proposes a later one, by itself or by hand: a party it follows moves the store once that long at most, and just started it backs none, as it holds nothing for a while yet.",
+ ),
option(
"strict-keys",
Kind::List,
@@ -832,6 +840,12 @@ pub(crate) struct Settings {
with = "crate::units::duration_option"
)]
pub(crate) store_held_for: Duration,
+ #[cfg(feature = "federation")]
+ #[serde(
+ default = "default_store_held_for",
+ with = "crate::units::duration_option"
+ )]
+ pub(crate) store_back_after: Duration,
#[serde(default)]
pub(crate) strict_keys: Vec<String>,
diff --git a/src/federation/vote.rs b/src/federation/vote.rs
index 693339e..bf866e7 100644
--- a/src/federation/vote.rs
+++ b/src/federation/vote.rs
@@ -3,9 +3,10 @@
//! any vote or proposal.
//!
//! * **Following**: it votes `true` on a proposal on the current version 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 (`Version::only_moves_on`), a `true` as a
-//! `false`.
+//! 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 can still pass, but one nobody backs but its proposer (`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 nothing that can still
@@ -20,7 +21,9 @@
//! one record of its votes kept on it; and, by the voters' rule, backs a version naming a
//! checkpoint only where it changes nothing of the current one but its number, what it
//! changes and its checkpoint, and its heads leave out nothing it held for a while before
-//! it was proposed (`Store::left_out`).
+//! it was proposed (`Store::left_out`), and only once its store held its checkpoint, or
+//! ran, for a while (`Rules::back_after`): a party it follows moves the store once that
+//! long at most, and a node just started backs none, as it holds nothing for a while yet.
use std::collections::BTreeSet;
use std::time::Duration;
@@ -48,6 +51,9 @@ pub(crate) struct Rules {
pub(crate) held_for: Duration,
/// Voting `false` on a checkpoint proposed beside one it backs.
pub(crate) nay_beside: bool,
+ /// How long its store holds its checkpoint, or runs, before it backs or proposes a
+ /// later one.
+ pub(crate) back_after: Duration,
}
/// What the node sees: its store, how long it has held each event it took, and how long
@@ -144,7 +150,8 @@ fn proposed(seen: &Seen<'_>, current: &Version) -> Vec<Proposed> {
/// Whether the node backs `version`, proposed `proposed_held` ago, by the voters' rule: one
/// naming a checkpoint only where it changes nothing of `current` but its number, what it
/// changes and its checkpoint, and its heads leave out nothing the node held for a while
-/// before it was proposed, proposals and votes aside, which lapse with the move.
+/// before it was proposed, proposals and votes aside, which lapse with the move; and only
+/// once its store held its checkpoint, or ran, for a while (`Rules::back_after`).
pub(crate) fn backs_checkpoint(
seen: &Seen<'_>,
rules: &Rules,
@@ -160,6 +167,13 @@ pub(crate) fn backs_checkpoint(
"a checkpoint that changes more than its number and what it changes".to_owned(),
);
}
+ if seen.since_move < rules.back_after {
+ return Err(format!(
+ "its store held its checkpoint, or ran, {}s: it backs a later one after {}s",
+ seen.since_move.as_secs(),
+ rules.back_after.as_secs()
+ ));
+ }
let before = proposed_held + rules.held_for;
// Proposals and votes lapse with the move: they count no more on the version after.
let lapsing = |id: &Id| {
@@ -194,6 +208,12 @@ fn alive(current: &Version, proposed: &Proposed) -> bool {
3 * (parties - proposed.no.len().min(parties)) >= 2 * parties
}
+/// Whether `proposed` holds back a version that only moves to a checkpoint, which would
+/// lapse it: it can still pass, and someone but its proposer backs it.
+fn holds_back(current: &Version, proposed: &Proposed) -> bool {
+ alive(current, proposed) && !proposed.yes.is_subset(&proposed.proposers)
+}
+
/// What a node voting by itself by `rules` signs now, as it sees its store, by
/// its party's `record`: its votes, at most one `true`, and a proposal of a checkpoint.
pub(crate) fn decide(seen: &Seen<'_>, rules: &Rules, record: &Record) -> Vec<Act> {
@@ -218,36 +238,48 @@ pub(crate) fn decide(seen: &Seen<'_>, rules: &Rules, record: &Record) -> Vec<Act
.flat_map(|proposed| proposed.votes.iter().cloned())
.collect();
for proposed in &all {
- let follows =
- |votes: &BTreeSet<String>| rules.follow.iter().any(|party| votes.contains(party));
- let yes = if own.contains(&proposed.hash) || follows(&proposed.yes) {
- true
- } else if follows(&proposed.no) {
- false
- } else {
+ let own_one = own.contains(&proposed.hash);
+ // A `false` it copies not: one party's would free bound followers.
+ let follows = rules
+ .follow
+ .iter()
+ .any(|party| proposed.yes.contains(party));
+ if !own_one && !follows {
continue;
- };
+ }
let moves_on = proposed
.version
.as_ref()
.is_some_and(|version| version.only_moves_on(&current));
- if !own.contains(&proposed.hash) && !rules.follow_any && !moves_on {
+ if !own_one && !rules.follow_any && !moves_on {
+ continue;
+ }
+ // A checkpoint lapses what else is proposed: the party it follows may not end so
+ // a proposal that changes more.
+ let lapses = all.iter().any(|other| {
+ other.hash != proposed.hash
+ && !other
+ .version
+ .as_ref()
+ .is_some_and(|version| version.only_moves_on(&current))
+ && holds_back(&current, other)
+ });
+ if !own_one && moves_on && lapses {
continue;
}
// One `true` at a time, for a version, by the voters' rule.
- if yes
- && (backed
- || proposed.version.as_ref().is_none_or(|version| {
- backs_checkpoint(seen, rules, &current, version, proposed.held).is_err()
- }))
+ if backed
+ || proposed.version.as_ref().is_none_or(|version| {
+ backs_checkpoint(seen, rules, &current, version, proposed.held).is_err()
+ })
{
continue;
}
- if let Ok(kept) = record.may_vote(&current, proposed.hash, &proposed.json, yes, &nays) {
- backed |= yes;
+ if let Ok(kept) = record.may_vote(&current, proposed.hash, &proposed.json, true, &nays) {
+ backed = true;
acts.push(Act::Vote {
proposal: proposed.hash,
- yes,
+ yes: true,
nays: kept,
});
}
@@ -369,7 +401,7 @@ fn checkpoint(seen: &Seen<'_>, rules: &Rules, current: &Version, all: &[Proposed
|| rules
.propose_every
.is_some_and(|every| seen.since_move >= every);
- if !due {
+ if !due || seen.since_move < rules.back_after {
return None;
}
let blocked = all.iter().any(|proposed| {
@@ -377,7 +409,7 @@ fn checkpoint(seen: &Seen<'_>, rules: &Rules, current: &Version, all: &[Proposed
version.only_moves_on(current)
&& backs_checkpoint(seen, rules, current, version, proposed.held).is_ok()
});
- alive(current, proposed) && (backs || !proposed.yes.is_subset(&proposed.proposers))
+ (alive(current, proposed) && backs) || holds_back(current, proposed)
});
if blocked {
return None;
@@ -506,11 +538,12 @@ mod tests {
&acts[0],
Act::Vote { proposal, yes: true, .. } if *proposal == checkpoint.hash()
));
+ // On any version, the checkpoint still; the other's `false` it copies not.
let any = Rules {
follow_any: true,
..rules.clone()
};
- assert_eq!(decide(&seen(&store, &long), &any, &record).len(), 2);
+ assert_eq!(decide(&seen(&store, &long), &any, &record).len(), 1);
// Heads leaving out what it held for a while before it was proposed: not backed.
let later = taken(
&mut store,
@@ -528,7 +561,8 @@ mod tests {
/// Row 58 (`docs/federation.md`): a party the node follows backs, or votes `false` on,
/// a version that changes more than moving to a checkpoint: by default the node follows
- /// neither; one following on any version, as its operator chose, follows both.
+ /// neither; one following on any version, as its operator chose, backs the one, and
+ /// copies the `false` not.
#[test]
fn federation_attack_58() {
let (tv, _, _, first, mut store) = three();
@@ -563,15 +597,89 @@ mod tests {
..rules
};
let acts = decide(&seen(&store, &long), &any, &record);
- assert_eq!(acts.len(), 2);
- assert!(acts.iter().any(|act| matches!(
- act,
+ assert_eq!(acts.len(), 1);
+ assert!(matches!(
+ &acts[0],
Act::Vote { proposal, yes: true, .. } if *proposal == backed.hash()
- )));
- assert!(acts.iter().any(|act| matches!(
- act,
- Act::Vote { proposal, yes: false, .. } if *proposal == opposed.hash()
- )));
+ ));
+ }
+
+ /// A party the node follows backs a checkpoint while a proposal that changes more,
+ /// which another party backs, can still pass: the node backs it not, as it would lapse
+ /// that one; while nobody but its proposer backs that one, it does.
+ #[test]
+ fn a_follower_lets_no_checkpoint_lapse_what_others_back() {
+ let (tv, lass, _, first, mut store) = three();
+ let root = store.id();
+ let on = first.hash();
+ let write = taken(
+ &mut store,
+ tv.write(&[root], "home/tv/a", harness::str("1")),
+ );
+ let mut checkpoint = first.after(on);
+ checkpoint.checkpoint = Some(vec![write]);
+ let mut other = first.after(on);
+ other
+ .rules
+ .push(("names/x".to_owned(), harness::str("lass")));
+ let proposal = taken(&mut store, tv.propose(&[write], &checkpoint.json()));
+ let elsewhere = taken(&mut store, lass.propose(&[root], &other.json()));
+ taken(
+ &mut store,
+ tv.vote(&[proposal], on, checkpoint.hash(), true),
+ );
+ let rules = Rules {
+ follow: vec!["tv".to_owned()],
+ ..Rules::default()
+ };
+ let long = |_: &Id| Some(Duration::from_secs(3600));
+ let record = record(&store, "makefu");
+ // lass proposed the other, and backs it alone: the checkpoint, followed.
+ taken(&mut store, lass.vote(&[elsewhere], on, other.hash(), true));
+ assert_eq!(decide(&seen(&store, &long), &rules, &record).len(), 1);
+ // Backed by another too: not.
+ taken(&mut store, tv.vote(&[elsewhere], on, other.hash(), true));
+ assert!(decide(&seen(&store, &long), &rules, &record).is_empty());
+ }
+
+ /// A node backs no checkpoint, and proposes none, before its store held its checkpoint,
+ /// or ran, for a while: a party it follows moves the store once that long at most, and
+ /// just started it holds nothing for a while yet.
+ #[test]
+ fn a_node_backs_no_checkpoint_soon_after_a_move_or_its_start() {
+ let (tv, _, _, first, mut store) = three();
+ let root = store.id();
+ let on = first.hash();
+ let write = taken(
+ &mut store,
+ tv.write(&[root], "home/tv/a", harness::str("1")),
+ );
+ let mut checkpoint = first.after(on);
+ checkpoint.checkpoint = Some(vec![write]);
+ let proposal = taken(&mut store, tv.propose(&[write], &checkpoint.json()));
+ taken(
+ &mut store,
+ tv.vote(&[proposal], on, checkpoint.hash(), true),
+ );
+ let rules = Rules {
+ follow: vec!["tv".to_owned()],
+ propose_events: Some(1),
+ back_after: Duration::from_secs(600),
+ ..Rules::default()
+ };
+ let long = |_: &Id| Some(Duration::from_secs(3600));
+ let record = record(&store, "makefu");
+ let soon = Seen {
+ store: &store,
+ held: &long,
+ since_move: Duration::from_secs(60),
+ };
+ assert!(decide(&soon, &rules, &record).is_empty());
+ let later = Seen {
+ since_move: Duration::from_secs(700),
+ ..soon
+ };
+ assert_eq!(decide(&later, &rules, &record).len(), 1);
}
#[test]
diff --git a/src/lib.rs b/src/lib.rs
index 739f712..66d54bc 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -70,6 +70,7 @@ fn voter(args: &config::Settings) -> Result<Option<federation::held::Voter>> {
propose_events: args.store_propose_events,
propose_every: args.store_propose_every,
held_for: args.store_held_for,
+ back_after: args.store_back_after,
},
}))
}