aboutsummaryrefslogtreecommitdiffstats
path: root/docs/federation.md
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-15 03:53:39 +0000
committertv <tv@krebsco.de>2026-11-15 03:53:39 +0000
commit4667fbf86fac9693753608d6cfc7ed0bee5ef9af (patch)
treea43ce506d7fd995980e0c2b1d6b38c5ae74785c3 /docs/federation.md
parent58efa560c03da03a6c10eaa7efc212fab28ebab2 (diff)
federation: forks are proposals, following is private, housekeeping by any member
- A swarm becomes federated by writing the federated policy with its first version, at genesis or later; what was written before counts only where a party signed it as the first version allows. - A rule's writer is `true` or `false` for every party or none, and `share` two whole numbers ([2, 3]), so nothing needs parsing or rounding. - At most `limits.proposals` of one party's proposals on one version are held at a time; it deletes one to make room. - The keys a version sets are written as the party's keys by the change that makes the version current; the version holds them for nothing else. - What doesn't count may be deleted by any member, judged by what counted at the deleting change's history; the writer that made it stale deletes it, others only what they find stale. An envelope signed with a key still held can be put back where nothing is. - Every proposal is a chance to fork: a group follows one by writing it as the current version of a chain named by its hash. No forks path. - What a party's nodes do of themselves (following others, voting by bounds) is their operators' business and written nowhere.
Diffstat (limited to 'docs/federation.md')
-rw-r--r--docs/federation.md157
1 files changed, 88 insertions, 69 deletions
diff --git a/docs/federation.md b/docs/federation.md
index 22bdecf..bb17467 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -14,11 +14,12 @@ are marked *(checked)* where they were read in it.
## Optional
-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).
+A swarm is federated once its policy says so, and which federation it follows: this design
+is federation 1. It can say so from the genesis change, or later, written by one who may
+write the policy (The policy). Nothing else changes: a swarm that doesn't say so 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
@@ -84,10 +85,13 @@ 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", "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):
+A swarm becomes federated by `_continuum/access/policy` being `{"version": 2, "values":
+"signed", "federation": 1}`, written together with the policy's first version: in the
+genesis change, or later by one who may write the policy. What was written before then
+counts only as anything does, where a key of a party signed it and the first version lets
+that party write there; the rest doesn't count. 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>",
@@ -98,21 +102,25 @@ form, naming the version it changes (none for the first):
{ "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 } } }
+ { "path": "ip4/10.243.0.5", "writer": "tv", "value": { "type": "string" } },
+ { "path": "names/*", "writer": false } ],
+ "numbers": { "share": [2, 3], "limits": { "proposals": 8, "nodes": 64 } } }
```
* **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.
+* **The keys it sets**: those of a party new in it, or of one whose keys it replaces.
+ The version holds them only to set them: the change that writes it as current writes
+ them as the party's keys, in place of any it had (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, `true` (every party) or `false` (none). 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`, two whole numbers: a proposal passes with votes of
+ `share[0]` of every `share[1]` parties (3·votes ≥ 2·parties, for `[2, 3]`), which
+ must be more than a half; and the limits.
The federation's own paths are its number's, not the rules': they are what this
design says below, the same in every version.
@@ -121,10 +129,9 @@ design says below, the same in every version.
|---|---|
| `_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/current/<chain>` | any party, once a proposal passed, or to fork |
| `_continuum/federation/keys/<party>/<name>` | that party; a version that becomes current |
| `_continuum/federation/nodes/<party>` | that party |
-| `_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 |
@@ -136,8 +143,10 @@ in to its own nodes as its operator sets up.
### Changing the policy
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.
+`_continuum/federation/proposals/<hash>`, its hash the version's. The document holds at
+most `limits.proposals` of one party's proposals on one version at a time; it deletes
+one to make room. A proposal is its content, named by its hash, so whoever holds it
+may write it again.
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:
@@ -147,11 +156,11 @@ and the party then counts for neither.
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.
+`_continuum/federation/current/<chain>` (the chain named by the first version's hash, or
+by the proposal a fork followed: Forks), 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.
* **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
@@ -161,9 +170,9 @@ isn't written yet.
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.
+* **What lapsed goes.** A proposal on a version that isn't current any more, and the votes
+ on it, may be deleted by any member (What counts). 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 enough parties agree on, or by going apart (Forks).
@@ -183,8 +192,18 @@ in the document as a whole:
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 may be deleted by any party. That is the federation's own
-housekeeping; remakes carry whatever is there.
+**What doesn't count may be deleted by any member**, in a change that every node judges by
+whether what it deletes counted at its history: a lapsed proposal and its votes, a value
+whose key was removed or whose place went to another, a deletion once the key of what it
+deleted went (Keys). That is the federation's own housekeeping; remakes carry whatever is
+there. So that deletions don't flood the document, the party whose write made something
+stop counting deletes it in the same change, or soon after; others delete only what they
+find stale, as in a swarm where parties went quiet. What is deleted doesn't come back
+where it would count again: its party writes it again.
+
+An envelope signed with a key its party still holds can be put back where nothing is,
+by whoever holds it, and counts: a party that wants its old values gone for good
+removes the key that signed them.
### Keys
@@ -194,17 +213,16 @@ it holds; a version that becomes current writes those it sets.
* **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.
+ the old one. A removed key isn't kept, and what it signed counts no more.
* **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.
+ until the key that signed the value it deleted is removed, and counts no more from
+ then: until then, the old envelope could be put back where nothing is. A party that
+ deletes much rotates its keys now and then, and the deletions go.
### Nodes
@@ -217,33 +235,32 @@ without nodes of its own writes through any node that takes its envelopes.
### 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>`.
+Every proposal is a chance to fork. A group that wants one, on whatever version and
+whoever voted for it, follows it: one of the group writes it at
+`_continuum/federation/current/<chain>`, without any votes, where the chain is named by
+the proposal's hash. That begins a **chain** of its own, with the parties the proposal
+names, and versions on it pass by votes of its parties, as on any chain. The group might
+be all but a few who won't cooperate, a few trying something the others may follow later
+or never, or anyone who won't follow a version that passed.
-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.
+A node follows one chain: its operator's choice, by default the one it is on. It
+judges by that chain, reads what counts by it, and syncs only with the nodes that its
+chain's parties list. So the 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 chain leaves out has no member there; to come back, its parties add it by a
+version, as they would anyone new. A proposal may name parties that won't be among
+the first to go (every party its proposer considers honest, say), so that they can go
+whenever they like, without asking. A party that goes may say where, at
+`_continuum/federation/went/<party>` on the chain it leaves, so that others can
+follow.
### Following
-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.
-
-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.
+What a party's nodes do of themselves is their operators' business, and nothing of it
+is written into the document. A node may go where the parties its operator follows
+went, by their `went`, and ask only when they went different ways; vote as they voted;
+vote by bounds its operator set on the numbers; or do nothing without its operator. A
+party votes from one node only, so that it never votes twice.
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
@@ -318,10 +335,10 @@ Recommendations, not rules: none of these breaks a promise, only how fast a node
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
+ at least twice `share` less one 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 proposal a group follows; nodes go there by their
+ operators' choice only, and sync only with its parties' nodes. A party nobody follows
carries on alone.
## Roads not taken
@@ -337,6 +354,7 @@ Recommendations, not rules: none of these breaks a promise, only how fast a node
* **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.
+* **Forks apart from proposals.** Every proposal is one already.
* **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.
@@ -373,10 +391,11 @@ On a federated swarm:
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.
+4. **Housekeeping**: deleting what doesn't count, judged by what counted at the
+ deleting change's history.
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.
+6. **Forks**: chains, a node following one, syncing with its parties' nodes.
7. **The registry**: the rules for krebs, the tool.
Each stage keeps every swarm that isn't federated as it is, its tests passing