From cf223ca8139e2652edb5c2cd976d97f5868b243f Mon Sep 17 00:00:00 2001 From: tv Date: Tue, 17 Nov 2026 13:10:29 +0000 Subject: guides: forking and following in a federation When a group forks, choosing the heads, the fork's version, its root as a node builds it, starting the fork's nodes and beginning a record there; what a node holding the history finds of a fork's root; and following a fork, coming back, and groups that parted coming together. --- docs/guides/federation/README.md | 2 + docs/guides/federation/forking-and-following.md | 78 +++++++++++++++++++++++++ 2 files changed, 80 insertions(+) create mode 100644 docs/guides/federation/forking-and-following.md (limited to 'docs') diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md index 021e8e4..eda5c4c 100644 --- a/docs/guides/federation/README.md +++ b/docs/guides/federation/README.md @@ -18,3 +18,5 @@ by them, in its words. signing again after a move, and nodes that weren't there. * [`when-things-go-wrong.md`](when-things-go-wrong.md): a version a node refused, a party that voted twice, choosing a side, and a node doing less than it should. +* [`forking-and-following.md`](forking-and-following.md): when to fork, making and + checking a fork, and following one. diff --git a/docs/guides/federation/forking-and-following.md b/docs/guides/federation/forking-and-following.md new file mode 100644 index 0000000..51d56ab --- /dev/null +++ b/docs/guides/federation/forking-and-following.md @@ -0,0 +1,78 @@ +# Forking and following + +Any group can carry on without the rest, by a fork: a store of its own, whose root is a +checkpoint at heads of the federation's. It needs nobody's vote and binds only those who +go. The rules are the design's ([`federation.md`](../../federation.md), Forks; +[`store.md`](../../store.md), Forks). + +## When + +* Keys voted twice, and nodes are apart ([`when-things-go-wrong.md`](when-things-go-wrong.md)): + fork without the party that voted twice, or with its keys named anew. +* Too many parties are away for good: every party counts, quiet ones too, and nothing + passes. +* A version the group won't follow passed, or the parties can't agree: every proposal is + a chance to fork, and the fork's version is usually one that didn't pass. + +## Making a fork + +1. **Choose the heads** it forks at: heads a node of yours showed (`heads` in `GET + /events`) and has held for a while. The fork keeps what counts there; what was + written after them stays behind. +2. **Write the fork's version**: it changes the version current at those heads (that + version's hash as `changes`), numbered one past it. It names anew (`since` its + number) the keys of any party whose keys it changes, and the founders' own node lists, + so that their nodes are members there. It leaves out the parties that don't go, and + may name those that weren't among the first to go, with their keys as they were, so + that they can follow whenever they like. +3. **Make its root**, as a node holding that history builds it, with the events it + keeps: + + ```sh + continuum-party --node http://tv:secret@localhost:3000 fork fork.json 4a1d… 9e30… \ + > fork-root + ``` + + The fork is named by its root's ID, the SHA-256 of its root (the file's first line), + which nobody can steer. +4. **Start it**: a node carries one swarm, so the founders start the fork's nodes with + files of their own (state, document, store file), from the root + (`--store-root fork-root`), or by its ID through one of them (`--store-id`), each + with its party (`--store-party`). +5. **Begin a record there**: a fork is a store of its own, and a party that never voted + in it begins its record from its root. + + ```sh + continuum-party --record tv-fork.record init tv --root fork-root + ``` + +## Checking a fork + +A node holding the history up to the fork's heads builds its root and checks it: + +```sh +continuum-party --node http://lass:secret@localhost:3000 check fork-root +# 7c55…: built here, byte for byte +# its heads lack 0c7e… +# makefu's keys: ["ssh-ed25519 AAAA…"] here, ["ssh-ed25519 AAAA…"] in the fork +``` + +Whether it builds that root at those heads; what it took that the heads lack (neither +among them, in their history, nor above them), which the fork doesn't hold; and, party by +party, the keys the fork's version gives otherwise than the party had at those heads. A +node that doesn't hold that history takes the root on its operator's word, who names the +fork by its ID. + +## Following + +Which fork a node follows is its operator's choice: no peer's word moves it, and a node +voting by itself follows parties' votes, never their forks. A party following a fork +moves its nodes there or starts new ones, listed in its node list there, and signs again +there what it keeps of what was written after the fork's heads: the fork takes only +events with its root in their history. + +A party the fork's version leaves out writes nothing there, and what it had counts no +more there; to come back, the fork's parties let it in by a version, as anyone new. +Groups that parted come together the same way: one side lets the other side's parties in, +by a version or by a fork naming them, and they sign again there what they keep. There +are no merges. -- cgit v1.3.1