From 6c6f978189eafa15add0df865f713dc946dfc5cb Mon Sep 17 00:00:00 2001 From: tv Date: Thu, 19 Nov 2026 03:52:49 +0000 Subject: 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`). --- docs/federation-tests.md | 5 +++-- docs/federation.md | 34 +++++++++++++++++++++++------- docs/guides/federation/voting-by-itself.md | 3 ++- 3 files changed, 31 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/federation-tests.md b/docs/federation-tests.md index d902c36..3aa1996 100644 --- a/docs/federation-tests.md +++ b/docs/federation-tests.md @@ -61,8 +61,9 @@ to: a stage is done when its tests are. ## Properties, over generated histories Histories are generated: a few parties (3 to 7), their keys, versions passing, honest -writes and votes, and an adversary that signs anything its own keys or stolen ones can, -on any dependencies, and puts out events no party signs. Each property is checked for +writes and votes, nodes merging under a revision with merge events or not, and an +adversary that signs anything its own keys or stolen ones can, on any dependencies, and +puts out events no party signs. Each property is checked for every order of every history small enough (up to some 8 events, every order that puts each after its dependencies), and for seeded histories and orders beyond that. 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": "", "proposal": "", "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": ""`); 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 diff --git a/docs/guides/federation/voting-by-itself.md b/docs/guides/federation/voting-by-itself.md index a31595f..0390cfd 100644 --- a/docs/guides/federation/voting-by-itself.md +++ b/docs/guides/federation/voting-by-itself.md @@ -42,7 +42,8 @@ or `POST /admin/events/vote` with `{"proposal": "8d02…", "yes": true}`. checkpoint lapses it. Even so, the parties following one hand it their votes on checkpoints. With `--store-follow-any`, on any version: that hands those parties the node's `true`. A party followed so by two thirds of the parties, with - its key kept on a node, passes what it backs. + its key kept on a node, passes what it backs. On a version changing the revision it + follows never: vote on that one by hand ([`upgrades.md`](upgrades.md)). * **After a move** (`--store-back-after`, ten minutes unless set): it backs, and proposes, no checkpoint until its store held its checkpoint, or ran, that long by its own clock, by itself or by hand: the parties it follows move the store once that long at most, and -- cgit v1.3.1