diff options
| author | tv <tv@krebsco.de> | 2026-11-15 02:50:18 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-15 02:50:18 +0000 |
| commit | 58efa560c03da03a6c10eaa7efc212fab28ebab2 (patch) | |
| tree | cf6033c1935f0949586d0c4fb50705f94bfce41c | |
| parent | 22940ca24fb736f43ddc6d6fb9a4b8b0ee638ee8 (diff) | |
federation: parties vote, rules say who writes, remakes only carry
The design asks less of continuum and of remakes:
- Parties vote; there are no voters apart from them.
- The policy's rules say who writes where: paths with `*`, `**` and
`{party}` (`names/{party}.r`), each naming its writer, the first
that matches deciding; shared identifiers are rules, given by
versions. The federation's own paths are fixed by its number.
- A swarm says which federation it follows (this design is 1); a
change to the federation is a design of its own with the next number.
- A passed proposal is written as the chain's current version by any
party; what lapsed, or doesn't count, any party may delete.
- A value counts only while the key that signed it is its party's: a
removed key takes back all it signed, the party signs again what was
its own. Deletions stay until the key of what they deleted goes.
- Agreement holds while fewer than a third of the parties vote twice,
as the design now says.
- A party without nodes writes through any node; node lists say who
is a member and whom a node syncs with.
- Remakes are continuum's, when and with whom it likes, of any kind
that loses and adds nothing; writes after the base are each judged
again, with no replay window.
- A fork is a chain of its own within the same document; nodes follow
one chain and sync with its parties' nodes only.
- What Automerge limits are recommendations; denial of service breaks
no promise.
| -rw-r--r-- | docs/federation.md | 479 |
1 files changed, 231 insertions, 248 deletions
diff --git a/docs/federation.md b/docs/federation.md index 3798560..22bdecf 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -7,24 +7,24 @@ repository that one maintainer merges into. What it is for is narrow: to hand ou identifiers (names, addresses, keys), and to give every party a namespace of its own that everyone reads. -It aims to be simple, and promises little beyond that. A federation that cooperates -settles fast; one that doesn't comes apart, and whoever wants to carry on with whom -does so. Claims about the code are marked *(checked)* where they were read in it. +It asks as little as it can of continuum and promises the least that makes a +federation possible. A federation that cooperates settles fast; one that doesn't +comes apart, and whoever wants to carry on with whom does so. Claims about the code +are marked *(checked)* where they were read in it. ## Optional -A swarm is federated if its genesis change says so (The policy, below). Nothing else -changes: a swarm started as today stays as it is, its registry, rules, remakes and -replay included. The code is apart where it would cost: judging reads the federated -rules under the federated policy only. The wire's version goes up for every swarm, as -with every change to it. +A swarm is federated if its genesis change says so, and which federation it follows: +this design is federation 1. Nothing else changes: a swarm started as today stays as +it is, its registry, rules, remakes and replay included. Continuum's wire version +says only whether a node can take part in a federation at all; which federation a +swarm follows is its own number (Changing the federation). ## Parties and the adversary -A **party** is a name in the policy, its keys, and the nodes it lists. Every party is -a voter, and only a voter is a party: who isn't in the policy writes nothing, and comes -in by a decision of those who are. Nobody owns the swarm, and any party may be -malicious, alone or with others. +A **party** is a name in the policy, with its keys. Parties write, and parties vote: +who isn't in the policy writes nothing, and comes in by a decision of those who are. +Nobody owns the swarm, and any party may be malicious, alone or with others. What an adversary can do: @@ -43,20 +43,20 @@ that nothing coming from any node breaks a promise for the others. ## What is promised -1. **What is written is what the policy lets be written, as its party signed it.** - Every honest node refuses anything else, whoever sends it. -2. **The policy changes only by the votes of two thirds of its voters**, and two nodes - that hold the same votes have the same policy. Nobody can make a node take back a - change of the policy it took. -3. **A remake changes nothing that counts.** It only starts the document anew, for - Automerge's sake (Where Automerge sets limits). -4. **Any group carries on as it chooses.** Its parties fork with the policy they want, +1. **What counts is what a party signed, with a key it holds, where the policy lets it + write.** Every honest node refuses what no policy would let be written, whoever + sends it, and reads nothing else as counting. +2. **The policy changes only by the votes of a share of its parties**, two thirds + unless the parties decide otherwise, and nodes that hold the same changes read the + same policy. That holds as long as fewer than a third of the parties vote twice + (Changing the policy). +3. **Any group carries on as it chooses.** Its parties fork with the policy they want, and whoever wants to follow does. Nobody is held by parties it doesn't follow. -Not promised: progress without the cooperation of two thirds of the voters (those who -cooperate fork, and carry on); that a party votes well; that a party whose key was -stolen keeps what the thief did before the key was replaced; that what a party's nodes -withhold reaches anyone. +Not promised: progress without the parties' cooperation (those who cooperate fork, +and carry on); that a party votes well; that what a party's nodes withhold reaches +anyone; that the swarm stays fast. A party that floods the document makes nodes slow, +not wrong: denial of service breaks no promise here. ## The design @@ -66,103 +66,110 @@ may write there, as the document stood when they were written. ### What it asks of the document -The design reads one thing: a set of changes, each naming the changes before it by -their hashes, committed and signed by a node, and writing to paths in one tree of -maps. Of it, the design asks: - -* **A change's history**, fixed by its hash: what its writer had seen. A change is - judged at its history and nothing else. +* **A change's history**, fixed by the change's hash: what its writer had seen. A + change is judged at its history and nothing else. * **The document at a set of changes**: the tree its writes make, the same on every - node for the same set; where two changes wrote one place at once, both writes held. -* **A remake** that starts the document anew from a set of changes, every node - building the same. + node for the same set. Where two changes wrote one place at once, one is shown, the + same on every node, and all are held. A deletion removes what its writer saw, and + nothing written at the same time. +* **Remakes that lose nothing and add nothing**: whatever continuum does to start the + document anew, a node follows it only where the new document holds what the old one + held at the base (Remakes). Every head of an epoch commits to the epoch's root change, and that root to the epoch before and the base it was made from, back to the genesis change *(checked: `access::rules`, one root an epoch; `remake::snapshot`, the previous epoch and the base heads in the snapshot)*. Continuum's document is an Automerge document, which gives -all of this and sets limits the design works around (Where Automerge sets limits). +all of this and has limits worth knowing (Where Automerge sets limits). ### The policy The genesis change writes `_continuum/access/policy` as `{"version": 2, "values": -"signed", "federated": true}`, and the policy's first version. From then on, the -policy is a chain of **versions**, each one JSON value, named by the SHA-256 of its -canonical form, naming the version it changes (none for the first): +"signed", "federation": 1}`, and the policy's first version. From then on, the policy +is a chain of **versions**, each one JSON value, named by the SHA-256 of its canonical +form, naming the version it changes (none for the first): ```json { "changes": "<hash of the version it changes>", - "voters": { "alice": ["ssh-ed25519 AAAA… alice"], - "bob": ["ssh-ed25519 AAAA… bob"] }, - "kinds": { "domain": { "chars": "a-z0-9.-", "length": 253 }, - "ip4": { "chars": "0-9.", "length": 15 } }, - "holders": { "domain": { "wiki.r": "alice" }, "ip4": { "10.243.0.5": "bob" } }, - "numbers": { "share": "2/3", "remakeChanges": 10000, "remakeWriters": 1000, - "replayWindow": 2, "limits": { "nodes": 64, "writers": 64, - "proposals": 8, "value": 65536 } } } + "parties": ["tv", "lass", "makefu"], + "keys": { "makefu": ["ssh-ed25519 AAAA… makefu"] }, + "rules": [ + { "path": "{party}/**", "writer": "{party}" }, + { "path": "names/{party}.r", "writer": "{party}" }, + { "path": "names/{party}.w", "writer": "{party}" }, + { "path": "names/wiki.r", "writer": "lass" }, + { "path": "ip4/10.243.0.5", "writer": "tv", "value": { "type": "string" } } ], + "numbers": { "share": "2/3", "limits": { "proposals": 8, "nodes": 64 } } } ``` -* **The voters**: each party's name and the keys the version gives it. A name is a - path segment no kind uses. -* **The kinds** of shared identifiers, each with the characters and length its - identifiers may have. -* **The holders**: for each kind, which party holds which identifier. An identifier - nobody holds is free. -* **The numbers**, which nothing constrains but `share`: a version whose `share` isn't - more than a half is no version. +* **The parties**, by name. +* **The keys it sets**: those of a party new in it, or of one whose keys it replaces; + they are written when the version becomes current (Keys). +* **The rules**, in order: the first whose path matches a path says who writes there. + A path is segments separated by `/`; a segment of a rule is literal, `*` (any one + segment), `**` (any number of them, last only), or holds `{party}` (the segment with + a party's name in its place: `{party}.r` matches `tv.r`). The writer is `{party}` + (the party the path names), a party's name, `any` (every party) or `nobody`. A rule + may constrain the value (its type; for a string, its characters and length). A path + no rule matches, nobody writes. +* **The numbers**: `share`, more than a half, and the limits. -What may be written follows from the version that is current: +The federation's own paths are its number's, not the rules': they are what this +design says below, the same in every version. | Where | Who writes it | |---|---| -| `<party>/…` | that party, its namespace | -| `<kind>/<identifier>` | the identifier's holder | -| `_continuum/federation/proposals/<hash>` | any voter | -| `_continuum/federation/votes/<voter>/<hash>` | that voter, once | -| `_continuum/federation/keys/<party>` | that party | +| `_continuum/federation/proposals/<hash>` | any party | +| `_continuum/federation/votes/<party>/<hash>` | that party | +| `_continuum/federation/current/<chain>` | any party, once a proposal passed | +| `_continuum/federation/keys/<party>/<name>` | that party; a version that becomes current | | `_continuum/federation/nodes/<party>` | that party | -| `_continuum/federation/forks/<ID>` | any voter | +| `_continuum/federation/forks/<hash>` | any party | | `_continuum/federation/went/<party>` | that party | | protocol data of nodes (member entries, remakes, acks) | as in every swarm, by members | -| anything else | nobody | -Every value at the first eight is an envelope, signed by a key of its party, replacing -the one there (its `prev`), as under the strict policy. A federated swarm has no other +Every value a party writes is an envelope, signed by one of its keys, replacing the +one there (its `prev`), as under the strict policy. A federated swarm has no other registry: `_continuum/users` and the users API are closed under it, and a party logs in to its own nodes as its operator sets up. ### Changing the policy -A **proposal** is a version not yet current, written by any voter at -`_continuum/federation/proposals/<hash>`, its hash the version's. A voter has at most +A **proposal** is a version not yet current, written by any party at +`_continuum/federation/proposals/<hash>`, its hash the version's. A party has at most `limits.proposals` proposals on one version. -A voter **votes** by writing, at `_continuum/federation/votes/<voter>/<hash of the -version it changes>`, the hash of the proposal it votes for. A vote is never replaced: -a change writing where a vote is, as the change saw it, is refused. Two written at -once by one voter's nodes are both held, and the voter then counts for neither. +A party **votes** by writing, at `_continuum/federation/votes/<party>/<hash of the +version it changes>`, the hash of the proposal it votes for. A vote never changes: +a change writing there another choice than the one it saw is refused (the same +choice, signed again, is fine). Two different ones written at once are both held, +and the party then counts for neither. -**The current version** at a set of changes: start from the version the epoch's root -names; while a proposal that changes it has the votes of at least `share` of its -voters, counting each voter's single vote, that proposal is current. So: +A proposal on the current version **passes** once at least `share` of that version's +parties voted for it, each counting once. Then any party writes it at +`_continuum/federation/current/<chain>` (Forks: the chain is that of the genesis +version, unless the swarm forked), together with the keys it sets, in one change; +every node judges that change by the votes in its history. **The current version** at +a set of changes is the one written there, or a proposal that passed on it there and +isn't written yet. -* **There is never a choice between two.** Two proposals that change one version can't - both have more than half of its voters, as no voter counts for two. In whatever - order a node gets the votes, it ends at the same version; a node that holds more - votes is further along the same chain. -* **Nothing else needs to happen.** No record of the decision, no remake: once the - votes are in the document, every node reads the new version, and judges by it every - change written in sight of them. -* **A proposal on a version that was replaced lapses**, with its votes. Its proposer - proposes it again on the current one; a client does that by itself for one that - touches nothing the version that passed changed. Proposals that don't conflict - pass in turn. +* **Two proposals on one version both pass only if at least a third of the parties + voted for both.** Each needs two thirds, so their voters share a third; a party that + voted twice counts for neither once both votes are seen, but a node that has seen + only one counts it. Honest parties vote once: a party's votes come from one place. + With fewer than a third voting twice, there is never a choice between two, and in + whatever order a node gets the votes, it ends at the same version. +* **Nothing else needs to happen.** No remake: once the votes are there, every node + reads the new version, and judges by it every change written in sight of them. +* **What lapsed goes.** A proposal on a version that isn't current any more, and the + votes on it, may be deleted by any party. Who wrote a proposal doesn't matter once + it is written: it passes or lapses whether its author is still a party or not. * **A split vote passes nothing.** Forty, forty and twenty on three proposals is - resolved by a new proposal two thirds agree on, or by going apart (Forks). + resolved by a new proposal enough parties agree on, or by going apart (Forks). -Everything the federation decides is a change of the policy: who votes, with which -keys; who holds an identifier, which is giving one, taking it back and giving it to -another; the kinds; the numbers. A party's namespace is its name in the policy. +Everything the federation decides is a change of the policy: who the parties are, +and their keys where they lost them; who writes which identifier, which is giving +one, taking it back and giving it to another; the rules; the numbers. ### What counts @@ -172,180 +179,149 @@ party wrote while it could still write there is taken, even where a version that passed at the same time says otherwise. What **counts** is read by the version current in the document as a whole: -* a value at `<kind>/<identifier>` counts if its holder signed it; -* a value in a namespace, a party's keys and its nodes count if the party is a voter; +* a value counts if the key that signed it is still its party's, and the current + version lets that party write there; where two were written at once, the one shown; * a proposal and its votes count while the version it changes is current. -What doesn't count is still held, and shown as such, until a remake leaves it out. -Where two values were written at once in one party's namespace, both count, and -readers show both until the party writes one replacing them: that is the party's -own matter. +What doesn't count may be deleted by any party. That is the federation's own +housekeeping; remakes carry whatever is there. ### Keys -A party's keys are the ones the latest version that set them anew gave it (a version -whose keys for it differ from those of the version it changes), unless the party -replaced them since: an envelope at `_continuum/federation/keys/<party>`, signed with -one of its keys, naming its new keys; the first names the version whose keys it -replaces, the latest that set them anew, and each next one replaces the one before -(its `prev`). +A party's keys are at `_continuum/federation/keys/<party>/<name>`, one line each, as +an `authorized_keys` line has it. The party adds and removes them itself, with a key +it holds; a version that becomes current writes those it sets. -* **A stolen key.** The party replaces its keys, and the thief's key signs nothing - from there on. If the thief replaced them first, or both did at once (two envelopes - replacing the same keys: the party then has none), two thirds of the voters give - the party new keys by a version. That version can also undo, by naming it, what the - thief did that the voters don't want kept: an identifier given away, a proposal. - What the party's own namespace holds, the party writes again itself. A vote the - thief cast stays the party's. -* **Rotation** is the same, without a thief. +* **A value counts only while the key that signed it is its party's.** So rotating a + key is: add the new one, sign again what should stay (a client does that), remove + the old one. A removed key isn't kept, and what it signed counts no more and may be + deleted. +* **A stolen key.** The party removes it at once: what the thief signed with it + stops counting, and so does what the party signed with it, until signed again. If + the thief removed the party's other keys first, or both removed each other's at + once (the party then has none), the parties give it new keys by a version. A vote + the thief cast on a version that passed stays passed. +* **Deleting a value** is writing an envelope with `null` in its place. It stays + until the key that signed the value it deleted is removed; then anyone may delete + it. Until then, whoever holds the old envelope could put it back where nothing is. + A party that deletes much rotates its keys now and then, and the deletions go. ### Nodes A party lists the nodes that carry for it, by node ID, at `_continuum/federation/nodes/<party>`, at most `limits.nodes`. Only a listed node is a -member: it may register itself, and commit changes. A node commits whatever its -party's operators send it, its party's envelopes and others' alike: what counts is -who signed a value, not which node committed it. - -### Remakes - -The document grows with every write, by the time it exists, not by what it holds. -A remake starts it anew. It is continuum's remake, of the kind that keeps the content -(`compact`), with two differences under the federated policy: - -* **When**: once the epoch holds `remakeChanges` changes beyond its root, or its - changes started `remakeWriters` writers. Every node reads that from the document. -* **Who agrees**: acks count by voter, not by node. A voter acks a remake when any of - its listed nodes does; a voter whose nodes ack two remakes of one epoch counts for - neither. A remake commits with acks of more than half of the current version's - voters. With too many voters away, no remake commits; those who are there fork - (Forks), and the document grows meanwhile. - -**The snapshot** holds what counts at the base: the current version and nothing of -the chain before it; the proposals on it and their votes; the values that count; the -parties' keys and node lists; the member entries; and, for `replayWindow` epochs, the -envelopes that deleted a value. It names the epochs of the last `replayWindow` -remakes. - -**Writes after the base** are replayed as the policy shapes it: every envelope beyond -the base, in the order of their `prev`, each judged again in the new epoch. One -signed in an epoch more than `replayWindow` remakes back, or that the new epoch -refuses (its party no longer holds the identifier, its key was replaced), goes to the -quarantine of the node that holds it, and its party signs it again if it still may. -An envelope names the epoch it was signed in. - -So a remake decides nothing: the snapshot is what counted already, every node builds -the same, and a write after the base is judged as any write is. +member: it registers, commits changes and syncs, and a node syncs with no other +(Stages). 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. ### Forks -Any party, or group of parties, can carry on without the rest: two thirds of the -voters are away for good, a decision the group won't follow passed, or a vote is -split. It **forks**: +Any group can carry on without the rest: too many parties are away for good, a +decision the group won't follow passed, or a vote is split. It **forks**: it writes, +at `_continuum/federation/forks/<hash>`, a version of its choosing on the version it +leaves, without any votes: the parties it wants to carry on with, and whatever else +it wants changed. That version begins a **chain** of its own, named by its hash, with +its own `current/<chain>`. + +A node follows one chain. It judges by that chain, reads what counts by it, and syncs +only with the nodes that its chain's parties list. So both sides keep the history up +to the fork, in the same document, and go apart from there: nothing is copied, and no +remake is needed. A party a fork leaves out has no member there; to come back, the +fork's parties add it by a version, as they would anyone new. A fork may list parties +that weren't among its founders (every party it considers honest, say), so that they +can follow without asking. -1. It names an epoch, heads in it, and a version of its choosing: the voters it wants - to carry on with, and whatever else it wants changed. -2. Every node builds the fork's root alike: a snapshot of what counts at those heads, - with that version as its first. The root names the epoch it came from and the - heads, so anyone can check what it carries. Its ID is its hash. -3. The founder writes the fork into the epoch it leaves - (`_continuum/federation/forks/<ID>`, its heads and its version), and each party - that goes writes where it went (`_continuum/federation/went/<party>`), before its - nodes switch. -4. Envelopes after the heads, of parties that are voters of the fork, are replayed and - judged there, as after a remake. +### Following -A fork needs nobody's ack: it binds only those who go. Only its voters' nodes are -members of it. A party it leaves out writes nothing there; to come back, the fork's -voters give it a place by a version, as they would to anyone new. The epoch it left -goes on for those who stay. A fork may list parties as voters that weren't among its -founders (every party it considers honest, say), so that they can follow without -asking. +Each node has a follow rule, its operator's setting: by default, the chain it is on, +until its operator chooses another. Or a list of parties to follow: the node goes to +a fork once more than half of the parties it follows went there and none went to +another, and asks its operator only when they went different ways. A party that +goes says where at `_continuum/federation/went/<party>`, on the chain it leaves, +before its nodes switch. -Nodes on different epochs don't sync, so the two go apart as far as the document is -concerned; each party chooses where its nodes are. +A party may vote the same way: once more than half of the parties it follows voted +for a proposal, and none for another on the same version. Only one of its nodes +votes, so that it never votes twice. -### Following +So a federation that cooperates can have a group that leads without being named: the +active parties the others follow. Those who follow need to act only when the parties +they follow disagree, and a party that won't cooperate is left behind by everyone who +doesn't follow it. -Each node has a follow rule, its operator's setting: +### Shared identifiers -* **Remakes**: by acks, as above. -* **Forks**: by default, none: its operator chooses. Or a list of parties to follow: - the node goes to a fork once more than half of the parties it follows went there and - none went elsewhere, and asks its operator only when they went different ways. +Anything that isn't a party's namespace is shared: names under `.r`, IPv4 and IPv6 +addresses, anything a rule names. Who writes one is what a rule says: by its own name +(`names/{party}.r`: a party writes the name that is its own), or given to one party by +a version, which takes `share`, and taken back and given to another the same way. +Nothing is first come, first served. The value is what its writer signs there +(`names/wiki.r`: where the name points); a value a former writer signed stops counting +once a version gives the place to another. -The same list may vote: a node holding a key of its party for that votes for a -proposal once more than half of the parties it follows voted for it, and none for -another proposal on the same version. +In a federation that cooperates this settles at once: a party proposes what it wants, +those who follow vote with those they follow. A group that gives an identifier to +another against the rest can't, short of `share`; with it, the rest fork with the +policy they want. -So a federation that cooperates has a leading group without naming one: the active -parties the others follow. Those who follow need to act only when their leaders -disagree, and a party that won't cooperate is left behind by everyone who doesn't -follow it. +### Remakes -### Shared identifiers +A remake starts the document anew, for Automerge's sake only (Where Automerge sets +limits); the federation needs none and asks for none. When to remake, and who acks, +is continuum's as in every swarm. What a federated node asks of a remake, whatever its +kind: -Anything that isn't in a party's namespace is a shared identifier of a kind the policy -lists: a name under `.r`, an IPv4 or IPv6 address, anything else a version adds as a -kind. An identifier is given by a version, which needs two thirds; taken back and -given to another the same way. Nothing is first come, first served. Its holder writes -its value (`domain/wiki.r`: where the name points); a value its former holder wrote -stops counting once a version gives the identifier to another. +* **It loses nothing and adds nothing.** The new document holds every envelope and + every record of the federation that the old one held at the base, byte for byte, + and nothing else of the parties'. A node checks that before it switches, and stays + where it is otherwise. +* **Writes after the base** are replayed as the policy shapes it: every envelope beyond + the base, in the order of their `prev`, each judged again in the new epoch. One the + new epoch refuses (its key was removed, its place given to another) goes to the + quarantine of the node that holds it, and its party signs it again if it still may. -In a federation that cooperates this settles at once: a party proposes the addresses -it wants, the parties that follow the leaders vote with them. A group that gives an -identifier to another against the rest of the voters can't, short of two thirds; with -two thirds, the rest fork with the policy they want. +So a remake decides nothing, and a swarm that never remakes stays as correct as one +that remakes all the time; it only grows slower. ### Where Automerge sets limits +Recommendations, not rules: none of these breaks a promise, only how fast a node is. + * **Writers.** Every writer costs every node memory while the epoch lasts, in - proportion to the document's history *(measured upstream: about 4 bytes per change)*. - A node writes under a fresh writer each time it starts. So a party's nodes start at - most `limits.writers` writers in an epoch; changes past that wait for the next - remake, which `remakeWriters` brings. Without that cost, neither limit would be - needed. + proportion to the document's history *(measured: about 4 bytes per change)*. A node + writes under a fresh writer each time it starts, or rejoins. A federated swarm + remakes before its writers and history make that felt, and a node keeps its writer + over a clean restart where it can. * **One change a number.** A node that commits two changes under one writer and number splits the nodes that took one from those that took the other: a node holding one can't take the other. Continuum refuses the second as forged, by whoever brings it - *(checked: `Signatures::forks`)*; the next remake heals the split, as the snapshot - holds only what counts. + *(checked: `Signatures::forks`)*; a remake heals the split. * **Changes it shouldn't apply.** A change is first of all one Automerge itself writes, or it is refused before Automerge sees it, in every swarm *(checked: `document::changes::Written`)*. -* **Values written at once.** Where two changes wrote one place at once, reading shows - one, in an order a writer can steer. Votes and keys are read with all the values a - place holds, never the one shown. -* **History.** The document keeps all of it; remakes keep it bounded. -* **Bytes.** Every node builds the same snapshot only with the same Automerge - version: a federated swarm moves to another one at a remake, all its nodes together - (Continuum changing under a swarm). - -### What it costs - -The document holds what counts and what was written since the last remake: -`remakeChanges` changes at most, of `limits.value` bytes each at most, plus open -proposals and their votes. A version is held once, the current one. Judging a change -reads the current version at its history: the votes on the proposals there. +* **Values written at once.** Where two changes wrote one place at once, the one shown + is chosen by an order a writer can steer. Within a party's namespace that is the + party's own matter; votes are read with all the values a place holds. +* **History.** The document keeps all of it, which remakes bound. +* **Bytes.** Every node builds the same snapshot only with the same Automerge version: + a federated swarm moves to another one at a remake, all its nodes together. ## Why it holds -1. **What is written.** A change is judged at its history, which its hash fixes, by - the version current there, which the votes in that history fix. Every node judges - alike, and refuses the change and everything built on it. What counts is read by - the version current in the document as a whole, the same on every node that holds - the same changes. -2. **The policy.** A proposal becomes current only with at least `share` of the - voters of the version it changes, and `share` is more than a half; a voter's vote - counts only alone. So at most one proposal changes a version, and the chain is the - same on every node, however the votes arrived. Votes are never replaced, so a node - that holds more is only further along. -3. **A remake.** Its snapshot is what counted at the base, built alike by every node, - checked against the ID committed. What comes after the base is judged again, so a - remake from any base commits nothing that wouldn't count anyway; at worst it makes - parties sign again what they wrote more than `replayWindow` remakes back. -4. **Carrying on.** A fork's root is what counted at the heads it names, with the - founders' version. Nodes follow it only by their own rule. A party nobody follows +1. **What counts.** A change is judged at its history, which its hash fixes, by the + version current there, which the records and votes in that history fix. Every node + following one chain judges alike, and refuses the change and everything built on + it. What counts is read by the version current in the document as a whole and the + keys the parties hold there, the same on every such node that holds the same + changes. +2. **The policy.** A proposal passes only with `share` of the parties of the version + it changes, more than a half; a party counts once, and for neither once its two + votes are seen. Two proposals on one version both pass only if their voters share + at least 2·`share` − 1 of the parties, all of whom voted twice: a third, at two + thirds. Votes never change, so a node that holds more is only further along. +3. **Carrying on.** A fork is a version its founders write; nodes follow it by their + own rule only, and sync only with its parties' nodes. A party nobody follows carries on alone. ## Roads not taken @@ -354,47 +330,54 @@ reads the current version at its history: the votes on the proposals there. at once can't be read from the document without trusting someone's clock or someone's witness. Votes need neither. * **Anything waiting on time** (final after so many days). Clocks are each node's own. - Everything here waits on votes, or on how much the document holds. -* **Taking back what a stolen key signed.** Telling from the document which signatures - came after a theft needs its history kept and read. Voters decide what to undo, by - naming it. -* **Acks by node.** Nodes cost nothing to run; a party with many would decide remakes. + Everything here waits on votes. +* **Taking back what a stolen key signed, from history.** Telling which signatures + came after a theft needs history kept and read. Removing the key takes all of them + back, and the party signs again what was its own. +* **Forks as new documents.** A fork could start a document of its own, as a remake + does. Following a chain and syncing with its parties' nodes only does the same + within one document, and keeps remakes for Automerge alone. * **Users below the parties.** A party's people and keys within it are its own matter: it may hand out its keys as it likes. The federation sees parties. -## Continuum changing under a swarm +## Changing the federation Every node of a swarm runs the same version of continuum today. A federated swarm's parties can't be made to upgrade together, so what all its nodes must agree on is -small: the hash of a change and how it is encoded (Automerge's version); the snapshot -a remake builds, to its byte; the federated rules. A rule changes only with a version -of the policy that names it (`"rules": 2`), which the voters pass once their nodes run -a continuum that knows it; the Automerge version moves only at a remake. +small: the hash of a change and how it is encoded (Automerge's version), and the +federation's rules, which its number names. + +A change to the federation is a design like this one, with the next number. A swarm +moves to it by a version of its policy that names it (`"federation": 2`), which the +parties pass once their nodes run a continuum that knows it. A node that doesn't know +a federation its chain moved to stops taking changes and says so. Continuum's wire +version only says whether a node can take part in a federation at all. ## The registry on it The krebs registry today: users, their hosts, the hosts' names, addresses and keys. On a federated swarm: -* each krebs user is a party, its hosts in its namespace (`alice/hosts/laptop`: its - keys, its addresses as it uses them); -* names under `.r`, and the retiolum and wiregrill addresses, are kinds; the policy - says who holds each; +* each krebs user is a party, its hosts in its namespace (`tv/hosts/laptop`: its keys, + its addresses as it uses them); +* its own names under `.r` and `.w` by the rules `names/{party}.r`, `names/{party}.w`; + other names, and the retiolum and wiregrill addresses, given by versions; * a tool reads what counts and writes what kartei's consumers read today. ## Stages -1. **The federated policy**: versions, the current one read from votes, judging by - it: namespaces, identifiers, proposals, votes. Tests: two proposals on one version - with every order of votes; a vote replaced; two votes at once. -2. **Keys and nodes**: a party's keys and their replacement, two replacements at once, - a version setting keys anew; membership by the node lists. -3. **What counts**, read by the current version; shown in the API. -4. **Remakes**: acks by voter, the snapshot of what counts, replay of envelopes, the - window in epochs. -5. **Forks and following**: the fork's root, `went`, the follow rule, voting with the - parties followed. -6. **The registry**: the kinds, the tool. +1. **The federated policy**: versions, rules and their paths, the current version from + votes and records, judging by it. Tests: two proposals on one version with every + order of votes; a vote changed; two votes at once. +2. **Keys**: what counts by the keys held, removing a key, two removing each other's, + a version setting keys, deletions kept until their key goes. +3. **Nodes**: membership by the node lists, and a node syncing with members only, as + a swarm key does today: a wire change. +4. **Housekeeping**: deleting what lapsed or doesn't count. +5. **Remakes**: the check that a remake lost and added nothing; replay of envelopes, + each judged again. +6. **Forks and following**: chains, the follow rule, voting with the parties followed. +7. **The registry**: the rules for krebs, the tool. Each stage keeps every swarm that isn't federated as it is, its tests passing untouched. |
