diff options
| author | tv <tv@krebsco.de> | 2026-11-15 23:37:52 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-15 23:37:52 +0000 |
| commit | f2861e1ff33e335f4fd49b94a75a1a7442854b30 (patch) | |
| tree | 6c73784a94c6f237fa67c14b3dae1ae656eb278d /docs/federation.md | |
| parent | acb8d25d510f3c04e8beb03ad5cd26556adfa8b1 (diff) | |
federation: the first member in the genesis, node lists by party
Nothing made a federation's first node a member, so nothing after its
genesis change was ever taken. The genesis change holds its node's
party's node list, naming that node, and the other parties' lists come
in through it. A list counts as its party's, whichever of its keys
signed it, until the party writes another: no change of keys leaves a
swarm or a fork without members, and signing the list again with the
keys goes.
A fork's genesis is said to be a function of its first version and the
heads alone. Closed is at, within and above, a member's entry too, and
the swarm's topology is closed with the rest. Smaller: keys differ by
keys; a party changing keys adds the new ones, signs again with one,
then drops the old; the keys a version sets name the version being
written; rule 6 is read at the deleting change's history; a party may
keep the keys its version names offline. Rows for the genesis list,
stranded lists and a stolen voting key.
Diffstat (limited to 'docs/federation.md')
| -rw-r--r-- | docs/federation.md | 92 |
1 files changed, 57 insertions, 35 deletions
diff --git a/docs/federation.md b/docs/federation.md index 5ada122..3bdbe34 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -87,7 +87,8 @@ path, who signed, when, the envelope it replaces (`prev`) and its number there ( one more than that one's). Under the federation it names also the **version** of the policy current where it was written, by number (`version`, The policy): a change writing one that names another is refused, but for an epoch's first change (a remake's snapshot, -a fork's genesis), which is judged by none. Of the envelopes a place holds, written at +a fork's genesis), which is judged by none, and for the keys a version sets, which name +the version being written (Keys). Of the envelopes a place holds, written at once, the one with the highest version number is its value, then the highest `seq`, then the lower SHA-256. So what a place holds is its party's to say, never the order of operations, which whoever writes a change steers; and what was signed under a later @@ -139,9 +140,9 @@ the first, number 0, which only the genesis change writes; a fork's first, Forks 2·a > b: with `[2, 3]`, the votes of two of every three (3·votes ≥ 2·parties). * **The parties and their keys**: each party by name, as continuum's user names, 1 to 64 of `A-Z a-z 0-9 . _ @ -`, with the keys its votes and proposals on this version - are signed with. Where a party's keys differ from those the version it changes names - (a party new in it, or one whose keys the parties replace), the version **sets** - them (Keys). + are signed with. Where a party's keys, as keys, differ from those the version it + changes names (a party new in it, or one whose keys the parties replace), the version + **sets** them (Keys). * **The rules**, in order: the first whose path matches a path says who writes there. A path is segments separated by `/`. A rule's first segment is literal, and not `_continuum`; any other is literal, `{party}` (a party's name), `*` (any one @@ -180,9 +181,12 @@ place takes only the proposal. Of continuum's own data, a federated swarm keeps nodes write for the protocol (member entries, remakes and their acks, epochs), written by members as in every swarm, but a member's entry by that member only; a member's change carries its node's signature, as signatures are required in a strict swarm. It -has no user registry: `_continuum/users`, bans, logouts, sessions, forgotten nodes, and -every entry of `_continuum/access`, the policy's place included, are closed: a write -there is refused, and nothing reads them. A party logs in to its own nodes as its +has no user registry: `_continuum/users`, bans, logouts, sessions, forgotten nodes, +`_continuum/access` with the policy's place, and the swarm's topology (`neighbours`, +`relays`, `topology`, `dissemination`) are closed: a write at, within or above any of +them is refused, a member's entry by any other node too. The topology stays as the +genesis change set it, and each node picks its own relays; nothing but the policy is +read of the rest. A party logs in to its own nodes as its operator sets up, and a node takes tokens only from the nodes of its own party (Nodes). ### Changing the policy @@ -256,7 +260,8 @@ naming another (Changing the federation). ### Keys A party votes and proposes with the keys its version names for it; everything else it -writes, with its keys at `_continuum/federation/keys/<party>`: one envelope, the set, +writes, its node list among it, with its keys at +`_continuum/federation/keys/<party>`: one envelope, the set, signed with a key of the set it replaces, numbered as any envelope. The change that writes a version setting a party's keys writes them there too, and only that change, or it is refused: an envelope without a signature (`cv2.<value>.<meta>.`), the keys the @@ -266,11 +271,13 @@ ahead of every set written under an earlier version, and the party's next set na as the one it replaces. * **A value counts only while the key that signed it is among its party's keys**, - votes and proposals excepted, which go by their version's. Changing keys is: write - the new set, and sign again, in the same change, what should stay, its node list - among it (a client does that, its deletions too). A key added back, from a backup - say, can bring back what it signed, and what a `null` of its party covered once that - `null` went (What counts). + votes and proposals excepted, which go by their version's, and its node list, which + counts until its party writes another (Nodes). Changing keys is: add the new keys to + the set, sign again with one of them what should stay (a change is judged at its + history, where only the set it replaces is the party's), then drop the old ones (a + client does that, its deletions too). A key added back, from a backup say, can bring + back what it signed, and what a `null` of its party covered once that `null` went + (What counts). * **Only a version revokes a key.** A party changing its keys by itself adds keys and tidies; but a key it drops can still sign, at a history from before the drop, a set of its own numbered past the party's, and nothing in the document tells which of two @@ -280,8 +287,8 @@ as the one it replaces. anything the old key writes at a history from before it. * **A party's own key change reaches its votes and proposals** once a version names its new keys; until then its version's keep voting, as only a version revokes a key. - After a version replaces a party's keys, the party signs its node list again, through - any node that takes its envelopes. + A party can keep the keys its version names apart, offline, and sign its values with + a set of its own. ### What counts @@ -295,12 +302,13 @@ whole. These count no more, and nothing else is stale: longer one, the place went to another, a rule changed; and of a party that is no longer one, its keys and its node list; 2. a value signed by a key that isn't among its party's, votes and proposals - excepted, which go by the keys their version names; + excepted, which go by the keys their version names, and its node list; 3. a proposal on a version that isn't current, and the votes on that version; 4. a version behind the current one: of a lower number, or of its number with the higher hash; 5. an envelope behind another at its place; -6. the member entry of a node its own party doesn't list (Nodes); +6. the member entry of a node its own party doesn't list (Nodes), read at the deleting + change's history; 7. a party's `null` where the deleting change's history holds everything its place held before it or beside it in this epoch, from empty, all signed by keys its party no longer holds. A `null` the epoch's first change holds goes only at a remake @@ -330,7 +338,11 @@ A party lists the nodes that carry for it, by node ID, at configuration, and its own member entry names it. A node is a member while that party lists it: it registers, commits changes and syncs, and nodes sync with members only (Stages); it takes tokens only from the nodes that party lists. Another party's list -does nothing. A node commits whatever envelopes it is given, its party's and others' +does nothing. A party's list counts as its party's, whichever of the party's keys +signed it, until the party writes another, so that no change of keys leaves a swarm, +or a fork, without members; a list a stolen key wrote stays until its party writes one +under the version that replaced that key, which it can at once, through any member. A +node commits whatever envelopes it is given, its party's and others' alike: what counts is who signed a value, not which node committed it. So a party without nodes of its own writes through any node that takes its envelopes. @@ -340,15 +352,18 @@ Any group can carry on without the rest: too many parties are away for good, a v the group won't follow passed, the parties can't agree, or it leaves the federation. It **forks**: it starts a swarm of its own from the document. -1. One of the group starts the new swarm. Its genesis change holds what the old - document read as at heads it names, built byte for byte as a remake's snapshot is, - so that one version and one set of heads make one swarm, but for the - federation's versions, the keys they set, continuum's member entries and the swarm's - name: of versions, only the group's own, the fork's first. It names the highest - version at those heads as the one it changes, is numbered one past it, and sets - every party's keys; judged by none, as an epoch's first change is. Every proposal is - a chance to fork: the version is usually one that didn't pass. To leave the - federation, the genesis holds another policy instead, and what it needs. +1. One of the group starts the new swarm. Its genesis change holds what the old document + read as at heads it names, built byte for byte from the fork's first version and + those heads alone, with the old epoch's Automerge version: its writer from the fork's + name, time 0, no message, nothing of a remake's metadata but what the heads fix; so + one version and one set of heads make one swarm, and a node that doesn't hold the + heads' history takes it on its peers' word, as a joiner takes a remake. It holds all + of it but for the federation's versions, the keys they set, continuum's member + entries and the swarm's name: of versions, only the group's own, the fork's first. It + names the highest version at those heads as the one it changes, is numbered one past + it, and sets every party's keys; judged by none, as an epoch's first change is. Every + proposal is a chance to fork: the version is usually one that didn't pass. To leave + the federation, the genesis holds another policy instead, and what it needs. 2. A fork is named by the hash of its first version together with the heads it names, which nobody can steer to a given name, the old swarm's least of all: its genesis change writes it at `_continuum/swarm`, as every node checks, and an envelope's meta @@ -392,7 +407,10 @@ for parties, zones, blocks and names that are nobody's by their spelling. ### Starting a federation A federation starts with a swarm of its own: its genesis change, the swarm's first, -writes the federated policy and the first version, with the keys it sets, as a swarm +writes the federated policy and the first version, with the keys it sets, and the node +list of its own node's party, naming that node, signed by that party for the swarm the +change names (its operator holds a key of that party): so the federation starts with +one member, and the other parties' lists come in through it. It records them as a swarm strict from its start records its policy (`--bootstrap-policy`) *(checked: `swarm::bootstrap`)*, which starts it empty: content before it would be a change from before the federation, judged by none. So nothing is from before the federation, and @@ -557,10 +575,13 @@ What an attacker does, and what happens. *Unit*: the judging, with crafted chang | 51 | A party's node writing another node's member entry | Refused: an entry is its member's | unit | | 52 | A `null` and an envelope of its party at once, the `null` read | Rule 7 waits for both: the `null` stays while the envelope could count | unit | | 53 | Two founders forking one version at one set of heads | One swarm: the genesis change is built byte for byte | sim | -| 54 | A party's node writing logouts, sessions or forgotten nodes | Refused: closed | unit | -| 55 | A coordinator records an old base | Everything after it is replayed, each as every node judges it | sim | -| 56 | A write after a base on a `null` the snapshot left out | Quarantined; its party writes again | unit | -| 57 | A version written without the keys it sets, or keys written by another change | Refused | unit | +| 54 | A party's node writing logouts, sessions, forgotten nodes, the topology, or at, within or above `_continuum/access` | Refused: closed | unit | +| 55 | A federation's genesis change without its node's party's list | Nothing after it is taken: no node is a member. The genesis holds that list | unit | +| 56 | A version replacing every listed party's keys, or a fork naming keys the lists weren't signed with | The lists still count, each its party's until it writes another | unit | +| 57 | A key a version names, stolen, votes as its party | Counts until a version replaces it; the party's own vote beside it is a double vote, answered by a fork | unit | +| 58 | A coordinator records an old base | Everything after it is replayed, each as every node judges it | sim | +| 59 | A write after a base on a `null` the snapshot left out | Quarantined; its party writes again | unit | +| 60 | A version written without the keys it sets, or keys written by another change | Refused | unit | ## Roads not taken @@ -583,8 +604,8 @@ What an attacker does, and what happens. *Unit*: the judging, with crafted chang * **The longest chain from the first version.** It reads the same as the highest number, but needs every version kept, and a tie decided where two chains part, long behind both. -* **Becoming federated in a running swarm.** It needs the time before closed, as - continuum closes it for a swarm turned strict, values from before counting only +* **Becoming federated in a running swarm.** It needs the time before closed, which + continuum doesn't do for a swarm turned strict either, values from before counting only where a party signed them, and of two federating changes at once neither preferred, as a tie broken by hash would let a change made later to look as old take the place of the one every node took. A federation started by its genesis change needs @@ -636,7 +657,8 @@ On a federated swarm: ## Stages -1. **The federated policy**: a swarm started federated by its genesis change; versions +1. **The federated policy**: a swarm started federated by its genesis change, with its + node's party's list; versions and what makes one valid, rules and paths, keys, votes, passing and dead, the current version, judging by it; votes and proposals by their version's keys; the protocol data closed but for member entries, each its member's, remakes, acks and epochs; the |
