aboutsummaryrefslogtreecommitdiffstats
path: root/docs/federation.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/federation.md')
-rw-r--r--docs/federation.md92
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