aboutsummaryrefslogtreecommitdiffstats
path: root/docs/federation.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 03:52:49 +0000
committertv <tv@krebsco.de>2026-11-19 05:11:45 +0100
commit6c6f978189eafa15add0df865f713dc946dfc5cb (patch)
tree2b4c556ba96820aa6fd13c22d96cd5fe5af9e091 /docs/federation.md
parent54bcc0e4ee8e1e6a29e0e01369c2ba95b27abce8 (diff)
federation: merge events, the first revision
What builds on many heads merges them, but only an event a party writes: in a quiet federation, heads beside each other stay so, and past 64 no event is above them all. Revision 1 (`merge-events`) adds merge events: `{"merge": true}`, signed with a node's own key, the `key` its Ed25519 key, for the party whose node list names it. One counts for nothing, and only gathers what it builds on into the history of what builds on it. Under the base revision, signed by a node its party doesn't list, or by a party's key, it is refused; the model alike. Generated federations begin at either revision, and their nodes merge. A node voting by itself backs no version changing the revision, on any version neither: its party's operators vote on that one, once their nodes run a continuum that knows it. `federation.md` lists the revisions, says what a merge event is, and row 71 is tested (`federation_attack_71`).
Diffstat (limited to 'docs/federation.md')
-rw-r--r--docs/federation.md34
1 files changed, 26 insertions, 8 deletions
diff --git a/docs/federation.md b/docs/federation.md
index 766c9a6..ecc3f21 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -145,7 +145,12 @@ Spread out:
* `proposal`, a version, the object ([Changing the policy](#changing-the-policy));
* `vote`, `{"on": "<hash>", "proposal": "<hash>", "yes": true}`, `"yes"` `true` or
`false` ([Changing the policy](#changing-the-policy)): a version's hash, the SHA-256
- of its JCS bytes, written as an ID is.
+ of its JCS bytes, written as an ID is;
+ * `merge`, `true`: nothing but building on its dependencies, under a revision with
+ merge events ([Changing the federation](#changing-the-federation)), signed by a node
+ its party's node list names, its `key` the node's Ed25519 key: a **merge event**,
+ which counts for nothing, so that what builds on it has its dependencies in its
+ history ([Nodes](#nodes)).
* **`sig`**: an SSH signature (`ssh-keygen -Y sign`, namespace `continuum-federation`)
over the event's bytes without `sig`: the SSHSIG blob of version 1, hashed with
`sha512`, its key the event's `key`, its reserved field empty, as `ssh-keygen` writes
@@ -532,7 +537,10 @@ as it judges any vote or proposal. The design has two in mind:
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.
+ the parties, its key kept on a node, passes what it backs. On a version changing the
+ revision it follows never: its party's operators vote on that one by hand, once their
+ nodes run a continuum that knows it
+ ([Changing the federation](#changing-the-federation)).
* **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
@@ -585,7 +593,9 @@ which a list the stolen key writes at a history from before that version, whatev
ID, doesn't replace ([What counts](#what-counts), 5). 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.
+node that takes its events. Under a revision with merge events, a node its party lists
+signs merge events with its own key ([Events](#events)): they count for nothing, and only
+gather what they build on into the history of what builds on them.
### Forks
@@ -763,6 +773,7 @@ fold, with crafted events. *Sim*: a simulation. *Bench*: measured, not judged.
| 68 | A checkpoint proposed at heads that leave out what was written since: a key set dropping a stolen key, say | Not backed: clients and nodes back a checkpoint only where what they held for a while is among its heads, in their history, or above them; a node shows what they lack | unit |
| 69 | A key a version names, stolen, writes its party's node list at a history from before the version naming the party's keys anew, beside the list the party writes under that version, several, for the lowest ID | The party's counts: of a party's lists, those written under the latest version come first | unit |
| 70 | A checkpoint's version proposed again, by an event beside its heads | Voters back it all the same, as a proposal lapses with the move, and vote on the events proposing it above its heads, as a node shows them; a version event on votes beside them is refused | unit |
+| 71 | Merge events under the base revision, signed by a node its party doesn't list, by a party's key, or spelled otherwise | Refused, or none: a merge event is taken only under a revision with merge events, signed by a node its party's node list names, its `merge` `true`; it counts for nothing | unit |
## Roads not taken
@@ -851,10 +862,15 @@ which a version names by its ID (`"revision": "<ID>"`); one naming none follows
**base revision**, which federation 1 began with, keys of type `ecdsa-sha2-nistp256`
among it. A revision adds a feature to those of the one before, and its ID is the SHA-256
of the JCS list of its features' names, so that a continuum that doesn't know a revision,
-another build's among them, can't read a version naming it. There are none yet but the
-base revision. What no history judges, the document, a change, the snapshot and the
-Automerge version, no version names: a change there splits the swarm until every node
-runs it ([`guides/federation/upgrades.md`](guides/federation/upgrades.md)).
+another build's among them, can't read a version naming it:
+
+| Revision | Its feature | What it adds |
+| --- | --- | --- |
+| 1 | `merge-events` | Merge events, which a node its party lists signs with its own key, building on events it holds and writing nothing ([Events](#events)) |
+
+What no history judges, the document, a change, the snapshot and the Automerge version, no
+version names: a change there splits the swarm until every node runs it
+([`guides/federation/upgrades.md`](guides/federation/upgrades.md)).
A version leaves `revision` out for the base revision, and names a revision no earlier
than that of the version it changes. What a revision adds counts at a history only where
@@ -862,7 +878,9 @@ the version current there names that revision or a later one: before, every node
as before, so that what a party uses early, every node refuses alike. A version is read by
the revision it names, so one moving to a revision may already hold what that revision
adds to a version; its proposal, the votes on it and its version event are judged under
-the version before.
+the version before. A node voting by itself backs no version changing the revision
+([Votes a node casts by itself](#votes-a-node-casts-by-itself)): its party's operators
+vote on it.
A node that doesn't read a version that passed on the version it reads, of a revision or
a federation it doesn't know or none at all, stops at the version event writing it, and