aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-17 13:10:29 +0000
committertv <tv@krebsco.de>2026-11-17 14:23:22 +0100
commitcf223ca8139e2652edb5c2cd976d97f5868b243f (patch)
treeee8664da90a0b6aaf133af73406887e21c8b0dfc
parentd054476f7dc71b84c4ee5b707806032d567226e6 (diff)
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.
-rw-r--r--docs/guides/federation/README.md2
-rw-r--r--docs/guides/federation/forking-and-following.md78
2 files changed, 80 insertions, 0 deletions
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.