aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/forking-and-following.md
blob: 51d56abd1357bd9fe283f91684b6c6228495054e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
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.