summaryrefslogtreecommitdiffstats
path: root/docs/federation.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-18 12:48:29 +0000
committertv <tv@krebsco.de>2026-11-18 13:59:42 +0100
commitd130c0612b4c63f2d30da65ebcc231018c1f2606 (patch)
tree8700f2d53351cbbecbe772ea7701bf6240d5210c /docs/federation.md
parent0bfe07af92a775b0e896e0fc5a989a1d9b65f7b3 (diff)
docs: references to another document's section linked to it
Where a document names a section of another after linking to it ("([`store.md`](store.md), Pinned checkpoints)"), the name links to that section too, by the id both GitHub and cgit's about filter give its heading; paragraphs that grew past the width are wrapped anew, links and code kept on one line each.
Diffstat (limited to 'docs/federation.md')
-rw-r--r--docs/federation.md131
1 files changed, 67 insertions, 64 deletions
diff --git a/docs/federation.md b/docs/federation.md
index 2b76fdf..190f2b4 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -88,8 +88,9 @@ Not promised:
* that a node joining from the root, in a federation that never passed a checkpoint,
isn't shown a chain old keys grew: of two versions changing one it takes neither, but
where its seeds are all the adversary's it is shown one ([Checkpoints](#checkpoints));
-* that a checkpoint, or a fork's root, that a node takes on its operator's word is the
- one the others built ([`store.md`](store.md), Pinned checkpoints).
+* that a checkpoint, or a fork's root, that a node takes on its operator's word is the one
+ the others built ([`store.md`](store.md),
+ [Pinned checkpoints](store.md#pinned-checkpoints)).
## The design
@@ -173,8 +174,8 @@ another event of what a party signed. Of an event, federation 1 allows:
It names no swarm, no version and no ID of its own: its history says the first two. An
event signed in a federation, or in a fork once it forked, has that store's root in its
-history, and no other store takes it ([`store.md`](store.md), Forks). An event is
-**written under** the version current at its history
+history, and no other store takes it ([`store.md`](store.md), [Forks](store.md#forks)). An
+event is **written under** the version current at its history
([Changing the policy](#changing-the-policy)).
### The policy
@@ -249,7 +250,7 @@ client backs none that isn't: two thirds backing one that can never be written b
federation to its version, as a yes binds ([Changing the policy](#changing-the-policy)).
What the swarm's document holds beyond the events, and what a node takes at its API, is
-the store's ([`store.md`](store.md), On Automerge).
+the store's ([`store.md`](store.md), [On Automerge](store.md#on-automerge)).
### Changing the policy
@@ -301,25 +302,25 @@ written: it is current at every history that holds it and no version after it.
**A node takes a version only where it changes the version the node reads**, or is one
it took, written again. A version event of any other, valid at its history or not, it
refuses, with everything built on it, reports, and leaves to its operator
-([`store.md`](store.md), A node's own); another node's refusal doesn't make it drop what
-it took. One valid at its history breaks no rule: the node reports it apart from events
-against the rules, and holds nothing against the node that put it. Of two that change
-the one it reads, it takes the first it judges; a node still joining takes neither, and
-reports, until its operator names one. A node is still joining, for this, from its start
-or a rejoin until it has synced with every seed its operator named: continuum's
-lifecycle has it `Joining` only until its first sync, with one peer, which could be the
-adversary's alone. Without keys voting twice, every version written changes the one
-every node reads, or is one it took, and none is refused.
+([`store.md`](store.md), [A node's own](store.md#a-nodes-own)); another node's refusal
+doesn't make it drop what it took. One valid at its history breaks no rule: the node
+reports it apart from events against the rules, and holds nothing against the node that
+put it. Of two that change the one it reads, it takes the first it judges; a node still
+joining takes neither, and reports, until its operator names one. A node is still joining,
+for this, from its start or a rejoin until it has synced with every seed its operator
+named: continuum's lifecycle has it `Joining` only until its first sync, with one peer,
+which could be the adversary's alone. Without keys voting twice, every version written
+changes the one every node reads, or is one it took, and none is refused.
**An operator may have its node drop what it took** after its checkpoint: a version the
-others refused, or any event, with everything built on it ([`store.md`](store.md), A
-node's own), and then take what the others hold. A version that moved the node to a
-checkpoint it undoes only by taking a checkpoint its operator pins, as the node forgot
-what the other side's version needs. No peer's word moves a node; its operator's does.
-The node refuses what it dropped, from whoever brings it, and any version event naming a
-version among it, whoever wrote it anew, and writes none itself, though it holds the
-votes that passed it, until its operator says otherwise. So either side of keys that
-voted twice may join the other without what parts them, and without a fork.
+others refused, or any event, with everything built on it ([`store.md`](store.md),
+[A node's own](store.md#a-nodes-own)), and then take what the others hold. A version that
+moved the node to a checkpoint it undoes only by taking a checkpoint its operator pins, as
+the node forgot what the other side's version needs. No peer's word moves a node; its
+operator's does. The node refuses what it dropped, from whoever brings it, and any version
+event naming a version among it, whoever wrote it anew, and writes none itself, though it
+holds the votes that passed it, until its operator says otherwise. So either side of keys
+that voted twice may join the other without what parts them, and without a fork.
**The current version** is the written version with the highest number: the end of the
chain the node took.
@@ -425,9 +426,9 @@ version current, version events aside, as it holds the version itself
([What counts](#what-counts)), as the JCS encoding of
`{"at": [<IDs>], "keeps": [<IDs>], "version": <version>}`, its IDs ascending and its
version the version itself, the object, named by its SHA-256 ([`store.md`](store.md),
-Checkpoints). Every node holding the history up to those heads builds the same one, and
-its version counts as written: a version event of it that comes later is one the node
-took.
+[Checkpoints](store.md#checkpoints)). Every node holding the history up to those heads
+builds the same one, and its version counts as written: a version event of it that comes
+later is one the node took.
A version names a checkpoint by its heads (`checkpoint`): events after the current
checkpoint, at which it is current too, none in another's history, their IDs ascending,
@@ -445,23 +446,24 @@ among it. A node shows, for a proposed checkpoint, what it holds that its heads
for a fork ([Forks](#forks)). This is the voter's rule, by its own clock: nothing more is
judged. It is a version only where its proposal is above those heads, and a version event
writing it is taken only where it is above them too, and so is every vote it is written on
-([`store.md`](store.md), Events): so moving to the checkpoint refuses nothing that decided
-it. A party's client, and a node voting by itself, vote on the events proposing what they
-vote on, and a node proposes a checkpoint on its heads: so their votes are above those
-heads wherever the proposal is. A vote beside them binds its party as any yes does, until
-the move refuses it. A node that takes the version moves to the checkpoint: it builds it,
-forgets everything before those heads that it doesn't keep, and every event not above
-them, and refuses such events from then on. Judging an event after them needs nothing it
-forgot: the version, every party's keys and node list, and the proposals on the current
-version with their votes all count, and are kept. A node starting from a checkpoint reads
-what it keeps as written under its version, as it holds none of their histories: each was
-written under that one or an earlier, counting there, a kept proposal is on it, and a
-later `since` that leaves one out is past it. A node that can't build a checkpoint, as it
-was away across a move and a remake after it, or as it joins, takes it only where its
-operator pins it ([`store.md`](store.md), Pinned checkpoints). What it can't check of its
-heads it takes on its operator's word: that they are after the checkpoint current at the
-version naming them, at which that one is current too; so it judges that version as every
-node does.
+([`store.md`](store.md), [Events](store.md#events)): so moving to the checkpoint refuses
+nothing that decided it. A party's client, and a node voting by itself, vote on the events
+proposing what they vote on, and a node proposes a checkpoint on its heads: so their votes
+are above those heads wherever the proposal is. A vote beside them binds its party as any
+yes does, until the move refuses it. A node that takes the version moves to the
+checkpoint: it builds it, forgets everything before those heads that it doesn't keep, and
+every event not above them, and refuses such events from then on. Judging an event after
+them needs nothing it forgot: the version, every party's keys and node list, and the
+proposals on the current version with their votes all count, and are kept. A node starting
+from a checkpoint reads what it keeps as written under its version, as it holds none of
+their histories: each was written under that one or an earlier, counting there, a kept
+proposal is on it, and a later `since` that leaves one out is past it. A node that can't
+build a checkpoint, as it was away across a move and a remake after it, or as it joins,
+takes it only where its operator pins it ([`store.md`](store.md),
+[Pinned checkpoints](store.md#pinned-checkpoints)). What it can't check of its heads it
+takes on its operator's word: that they are after the checkpoint current at the version
+naming them, at which that one is current too; so it judges that version as every node
+does.
What a checkpoint loses: what counted no more before it, so that a key added back, or a
place given back, brings back nothing signed before it, and a party that voted twice on
@@ -472,12 +474,13 @@ while the vote takes its course, a client writing once a checkpoint is proposed
only on what is above its heads, and a party's client signs again what a move refused.
**Joining.** Once a checkpoint passed, a node joins from a checkpoint its operator pins,
-not from the root ([`store.md`](store.md), Pinned checkpoints). Whether one passed is
-its operator's to know, not the node's: a chain old keys grew need name none. From the
-root, keys a version named before it, revoked since or thrown away, could grow another
-chain, at histories before the version that followed, and node lists naming only their
-own nodes would seal a node joining in it, never shown the other. So a checkpoint bounds
-what old keys can do to the versions after it.
+not from the root ([`store.md`](store.md),
+[Pinned checkpoints](store.md#pinned-checkpoints)). Whether one passed is its operator's
+to know, not the node's: a chain old keys grew need name none. From the root, keys a
+version named before it, revoked since or thrown away, could grow another chain, at
+histories before the version that followed, and node lists naming only their own nodes
+would seal a node joining in it, never shown the other. So a checkpoint bounds what old
+keys can do to the versions after it.
A version that changes nothing but its number, what it changes and its checkpoint only
moves the store on. Like any version, it lapses the proposals on the version before, so
@@ -533,20 +536,20 @@ written under names for the party. A party's list is that one
([What counts](#what-counts), 5) where it is written under a version numbered at least the
`since` its version gives the party's list, otherwise the list its version gives, if any,
as with keys ([Keys](#keys)). The store's members are the nodes each party's list names,
-each as its party's ([`store.md`](store.md), Members); another party's list does nothing
-for a node. A party's list counts until the party writes another or a version names one
-anew, whatever keys its version names since, so that no change of keys leaves a swarm
-without members; a list a stolen key wrote stays until the party writes one under the
-version that replaced that key, which it can at once, through any member. A node puts
-whatever events it is given, its party's and others' alike: what counts is who signed an
-event, not which node put it. So a party without nodes of its own writes through any node
-that takes its events.
+each as its party's ([`store.md`](store.md), [Members](store.md#members)); another party's
+list does nothing for a node. A party's list counts until the party writes another or a
+version names one anew, whatever keys its version names since, so that no change of keys
+leaves a swarm without members; a list a stolen key wrote stays until the party writes one
+under the version that replaced that key, which it can at once, through any member. A node
+puts whatever events it is given, its party's and others' alike: what counts is who signed
+an event, not which node put it. So a party without nodes of its own writes through any
+node that takes its events.
### Forks
Any group can carry on without the rest: too many parties are away for good, a version
the group won't follow passed, or the parties can't agree. It **forks**: it starts a
-store of its own from the federation's ([`store.md`](store.md), Forks).
+store of its own from the federation's ([`store.md`](store.md), [Forks](store.md#forks)).
1. One of the group makes the fork's root, a checkpoint at the heads it forks at, which
no party signs, so that one version and one set of heads make one fork
@@ -605,10 +608,10 @@ so one first version makes one federation, named by the root's ID. Among the nod
the version gives, one names a node of its founders', so the federation starts with
members, and other nodes come in as their parties list them. Its swarm's genesis change
holds the root, built byte for byte from it, its policy naming the fold `federation`
-(`{"version": 2, "store": "federation"}`, [`store.md`](store.md), On Automerge). So
-nothing is from before the federation: it changes by versions, and any group carries on by
-a fork. A running swarm doesn't become federated; its parties start one, and sign into it
-what they keep.
+(`{"version": 2, "store": "federation"}`, [`store.md`](store.md),
+[On Automerge](store.md#on-automerge)). So nothing is from before the federation: it
+changes by versions, and any group carries on by a fork. A running swarm doesn't become
+federated; its parties start one, and sign into it what they keep.
## Why it holds
@@ -643,8 +646,8 @@ what they keep.
## Attacks
What an attacker does, and what happens; what it does to the store, its document and its
-remakes, is the store's ([`store.md`](store.md), Attacks). *Unit*: the fold, with
-crafted events. *Sim*: a simulation. *Bench*: measured, not judged.
+remakes, is the store's ([`store.md`](store.md), [Attacks](store.md#attacks)). *Unit*: the
+fold, with crafted events. *Sim*: a simulation. *Bench*: measured, not judged.
| # | Attack | What happens | Test |
|---|---|---|---|
@@ -848,7 +851,7 @@ continuum builds and behaves as it does, and its tests pass untouched.
1. **The store**, generic and in memory, with a fold made for its tests: events,
histories, judging at a history, the state, checkpoints and moving to them, a node's
- own refusals and drops, forks ([`store.md`](store.md), Tests).
+ own refusals and drops, forks ([`store.md`](store.md), [Tests](store.md#tests)).
2. **The federation's fold**, as pure code: events and what makes one, versions and what
makes one valid, rules and paths, places, keys, votes, passing and dead, version
events, which version a node takes and the current one, what counts, node lists and