diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/federation.md | 82 |
1 files changed, 49 insertions, 33 deletions
diff --git a/docs/federation.md b/docs/federation.md index 0544371..7a7b93a 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -133,12 +133,13 @@ What is not promised: * **A name against the voters.** Two thirds of them give a user's first keys anew. Meant for a user that lost them, it hands a name to whoever they say: in the open, over the days a vote takes. The same two thirds free the names of a user that is - out, or give them to another, say who has a contested name, and decide a policy - that covers a name no more. And a third of them, stamping as they like, make a - user that is out gone, a claim final, and what a policy uncovered dropped, at - once. A third is one where there are up to three voters: a few maintainers at the - start are each that third. And a limit lowered for a day gives the names claimed - meanwhile, in sight of what fell past it, to their claimants for good. + out, or give them to another, say who has a contested name, and decide a policy that + covers a name no more. And a third of them, stamping as they like, make a user that + is out gone, a claim or a decision final, what a policy uncovered dropped, and what + was given up stop counting for good, at once. A third is one where there are up to + three voters: a few maintainers at the start are each that third. And a limit + lowered for a day gives the names claimed meanwhile, in sight of what fell past it, + to their claimants for good. * **A name through a long partition.** A user unvouched on one side of a partition that outlasts `gone` is gone, though someone vouched for it in time on the other. Two claims that each became final on a side of one that outlasts `final` are @@ -156,9 +157,9 @@ What is not promised: * **When a proposal is decided.** One that had the votes and lacks records of nodes hangs over its matter: whoever holds the last record chooses the day. The voters end that by deciding a later proposal of the matter (Decisions). -* **Decisions without the voters.** With a third of an epoch's voters not taking part - (gone, silent, without a node that carries for them), nothing more is decided there, - and no remake passes; what users write goes on. Those left go apart (Going apart). +* **Decisions without the voters.** With a third of the voters not taking part (gone, + silent, without a node that carries for them), nothing more is decided there, and no + remake passes; what users write goes on. Those left go apart (Going apart). * **Anything of 7 with one voter.** A swarm that one user starts has that user as its only root and voter until it decides on others: it decides alone, and what a third of the voters see, it sees alone. And as the only root, its cut takes back a name @@ -170,11 +171,12 @@ What is not promised: nothing bounds how many reach a node as part of others' histories: a limit and a party's budget bound how fast a node takes them from the party itself. Who did it shows, under its nodes' signatures. -* **How often the swarm remakes, and from what.** The alive peers commit a remake as - in every swarm, and a party that runs most of the alive nodes has them. It changes - nothing that counts, and comes no sooner than `remakeAfter`, then as `remakeChanges` - and `remakeWriters` allow; but each remake of an epoch a node is offered costs it a - snapshot, the lowest ID first, until one comes out to the ID it was committed for. +* **How often the swarm remakes, and from what.** A node follows a committed remake + whatever acks it gathered, as in every swarm a coordinator's decision is taken from + it: one node commits a remake alone. It changes nothing that counts, and comes no + sooner than `remakeAfter`, then as `remakeChanges` and `remakeWriters` allow; but + each remake of an epoch a node is offered costs it a snapshot, the lowest ID first, + until one comes out to the ID it was committed for. * **A swarm that never splits.** A node that forks its own writer (two changes with one number) splits the honest nodes that took one from those that took the other, until one side drops its own (Partitions; Automerge: one change a number). It is @@ -1125,7 +1127,8 @@ envelopes are brought along as they were signed (below). lacks the base syncs it from a peer that keeps the epoch. * **By its result.** Every node builds the snapshot itself from the base, and follows only where it gets the epoch ID the remake was committed for (Continuum changing - under a swarm). + under a swarm). It builds at most one snapshot a coordinator and epoch: a + coordinator that commits several has the others left, and shows. * **A remake that expires**, its coordinator silent or gone, any node aborts, once a grace has passed since it expired by its own clock, as an operator does in every swarm: the abort frees the acks for another. A remake committed is followed @@ -1160,6 +1163,7 @@ envelopes are brought along as they were signed (below). time, from which it has held the thing so without a break; * what is uncovered and not dropped; * the proposals that are open, with their votes; + * for each user it holds without keys, the root that gives them; * the member entries of the nodes that carry for a user it holds, and the epochs' metadata, as today; * the floors (below). @@ -1251,8 +1255,8 @@ envelopes are brought along as they were signed (below). a statement a floor refuses comes no more; what only a node witnessed after the base, and named in no switch record because it never switched and doesn't come back, is lost with it; a decision decided after the base waits for the switch records that hold its -records. Who remakes, when, and from what base changes none of it: that is why the -alive peers decide it, of whom a party running many nodes can be most. +records. Who remakes, when, and from what base that passes changes none of it: that is +why any node may commit one. What a remake bounds, and what everything costs, is said below (What it costs). @@ -1447,6 +1451,11 @@ all the rest. Beside those, by kind: | `propose` | `matter`, `holds` (below), `matterNumber` (its number among its matter's proposals: Decisions) | | `vote` | `proposal`, its digest; `ends`, when it runs out | +**The genesis change** holds the policy with its numbers, the roots and the voters by +their IDs, and the users it starts with: each with its ID and name, its keys or, +without, the root that gives them (`keysBy`), and what it holds in its name. A +snapshot holds what Remakes lists. + **A value's envelope**: `swarm`, `branch`, `path` (its place), `userId`, `signingKey`, `prev` (the digest of a value that counts at its place where it is signed, or none), the value (or `null`, putting nothing there), and the signature. It says nothing of @@ -1509,14 +1518,15 @@ A change is valid if, in the document at its dependencies: out there. 3. Apart from the node's own member entry (of the shape the policy's version gives it, within `limits.entry`), its own records of proposals, its switch record, and what - it writes of a remake as in every swarm (its ack; a coordinator's proposal and - decision, of the kind `compact`; any node's abort of one that expired, a grace - after), it writes only envelopes, each naming the swarm, its branch (this one, or - one this one came from), its path and its user's ID, and for a statement what its - signer saw (`seen`: changes in this change's history, or, for one brought along, - none of this epoch's) and the number that gives it, signed with a key that is that - user's there and not retired there. Any node commits it, but a `node` statement, - which the node it names does. + it writes of a remake as in every swarm (its ack; a coordinator's records of a + remake, its proposal and its decision, of the kind `compact`, which are no proposal + or decision of the voters; any node's abort of one that expired, a grace after), it + writes only envelopes, each naming the swarm, its branch (this one, or one this one + came from), its path and its user's ID, and for a statement what its signer saw + (`seen`: changes in this change's history, or, for one brought along, none of this + epoch's) and the number that gives it, signed with a key that is that user's there + and not retired there. Any node commits it, but a `node` statement, which the node + it names does. 4. In a register (`_continuum/users/<name>`, `_continuum/claims/<kind>/<name>`): only a new entry under its own digest. Under `_continuum/decisions/<proposal>`: only the node's own record, once, of a proposal that is there: of a fork, its proposer's @@ -1848,7 +1858,11 @@ the design recommends; who acts, and how. A node shows each where it waits on it | a claim of a user the node carries for, not settled (`GET /registry/claims`) | ten times `witness` | its neighbours and seeds; the roots' nodes' last change | | the age of the last change of the roots' nodes the node holds | twice `stamp` | its seeds; tell the roots | | peers in another epoch (`GET /peers`) | longer than a switch delay and `catchUp` | a peer that keeps the epoch, or the ID (`POST /admin/epochs/rejoin`) | -| a committed remake whose ID the node doesn't get | at once | versions differ: upgrade, or report it | +| a committed remake whose ID the node doesn't get | at once | versions differ: upgrade, or report it; or its coordinator lied, which shows | +| remakes committed within `remakeAfter` of each other, or several by one coordinator | more than one | the coordinator: a node that commits remakes for nothing | +| a remake expired and not aborted | past its grace | nothing: any node aborts it | +| a second remake of an epoch the swarm left | at once | nothing: it moves nobody; its coordinator shows | +| envelopes a switch refused by a floor (`GET /admin/quarantine`) | anything | their users sign them again | | a refused peer, a forked writer proven (`GET /peers`, `sync.refusedPeers`) | at once | drop (`POST /admin/refused/drop`), or not | | two digests for the same changes; a check of itself that differed | at once | upgrade, or write on (`POST /admin/check/accept`) | | a policy the node doesn't know | at once | upgrade, or refuse the decision | @@ -2024,7 +2038,7 @@ voters are malicious, and the honest ones' nodes keep time. **Promise 6.** No rule for what users write reads a vote or waits for another party; a write is refused only by what its own history holds, and counts from the start. -**Promise 7.** Let V be the epoch's voters, n of them, fewer than a third malicious. +**Promise 7.** Let V be the voters, n of them, fewer than a third malicious. * *None that honest voters didn't vote for.* A record is valid only with votes for its proposal in its history by more than 2n/3 of V, none released there: more than n/3 @@ -2076,10 +2090,11 @@ counted again (For good, under Cuts). What a node holds beyond the base comes al with what it held of it, by its switch record, whatever base the coordinator chose of those that pass: an honest node witnesses there as its changes would have, and a base holds what a third of the voters' nodes had seen once the epoch was due. Lengths of -time go on from the stamps the snapshot lists. So a remake from any base, by any node, -at any time, moves nothing that counts; and of two, every node goes to the one the -switch records of nodes of a third of the voters chose, else the lower ID: a remake -committed late moves nobody. +time go on from the stamps the snapshot and the switch records list. An envelope comes +along from however many remakes back, and what a remake left out stays out by the +floors. So a remake from any base that passes, by any node, at any time, moves nothing +that counts; and of two, every node goes to the one the switch records of nodes of a +third of the voters chose, else the lower ID: a remake committed late moves nobody. **Unvouching** takes away no more than its signer could have kept from seeing: what the unvouched user signed stays if a node of the unvoucher or of a root committed a @@ -2410,7 +2425,7 @@ Unvouching: | # | The adversary | Honest nodes | Promise | Shown by | |---|---|---|---|---| | 24 | Unvouches a user it didn't vouch for; a root unvouches the users the root change holds, or those a root before it created | Refuse the first. What is the seats' is taken back once every root unvouched it: one root puts nobody out, where there are several | 3 | unit: `only_the_voucher_unvouches`, `the_seats_take_back_together` | -| 25 | The roots unvouch the voters, and wait for them to be gone, to keep them from deciding | A voter votes for its epoch, in, out or gone, and the nodes of one that is out go on committing their records and switch records, and nothing else: who votes is the voters' word, not its vouchers' | 7 | unit: `a_voter_votes_for_its_epoch`, `an_out_voters_node_records` | +| 25 | The roots unvouch the voters, and wait for them to be gone, to keep them from deciding | A voter votes while a decision lists it, in, out or gone, and the nodes of one that is out go on committing their records and switch records, and nothing else: who votes is the voters' word, not its vouchers' | 7 | unit: `a_voter_votes_while_listed`, `an_out_voters_node_records` | | 26 | Unvouches saying it saw little, to undo what the user did since | What its own nodes or a root's had seen of the user stays | as said under Unvouching | unit: `an_unvouch_undoes_nothing_seen` | | 27 | The unvouched user signs on, saying it saw nothing of the unvouch, or across a partition | Hold it as part of another's history only; it doesn't count; once the partition is over every node finds the same | 2, 3 | unit: `past_an_unvouch`; sim: `an_unvouch_across_a_partition` | | 28 | A user is unvouched: what of those it brought in, and its names? | One that another vouched for stays in, without doing anything. The others are out from the same point; a vouch after brings them back whole. Their names wait | 4 | unit: `a_second_line_keeps_it`, `those_it_brought_in`, `a_vouch_brings_back` | @@ -2497,7 +2512,7 @@ Decisions and remakes: | 89 | Keeps the voters' nodes apart for longer than `final`, each side deciding the same matter | Both decisions are final on their sides; together, the higher number holds, then the lower digest, and for who votes first the one the roots' nodes saw decided first | 7 | unit: `two_final_decisions` | | 90 | The voters decide a policy that covers a user's names no more; another user writes over what is uncovered; a third of the voters stamp to drop it at once | It doesn't count where the policy holds, and shows aside. Only its user takes it away, nobody changes it; it is dropped once seen there for `uncovered` | not promised | unit: `what_a_policy_no_longer_covers`, `uncovered_is_only_taken_away` | | 91 | The voters decide a policy that stops keeping names for their users | A kept name its user claimed stays its claim. One it didn't is the first comer's | not promised | unit: `a_kept_name_claimed` | -| 92 | Runs most of the alive nodes: commits remakes from bases of its choosing, as often as it may; serves a snapshot of its own | Nothing that counts changes: every node builds the snapshot itself, brings along what it holds beyond the base, and follows a remake only once its base holds `remakeChanges` changes or `remakeWriters` writers, and the epoch was seen for `remakeAfter`. Each costs every node a snapshot | 2; not promised (how often) | sim: `every_node_builds_the_snapshot`, `remakes_no_sooner_than_the_changes` | +| 92 | Runs a node, or most of the alive ones: commits remakes alone, from bases of its choosing, as often as it may; serves a snapshot of its own | Nothing that counts changes: every node builds the snapshot itself, brings along what it holds beyond the base, and follows a remake only once its base holds `remakeChanges` changes or `remakeWriters` writers, and the epoch was seen for `remakeAfter`. Each costs every node a snapshot | 2; not promised (how often) | sim: `every_node_builds_the_snapshot`, `remakes_no_sooner_than_the_changes` | | 93 | Starts writers under many users of its own, and writes at its budget's pace, to have the swarm remake every two hours | Writers count per party, and its users are of its party; and no remake comes before the epoch was seen for `remakeAfter` | 6 | unit: `writers_count_per_party`, `no_remake_before_its_time` | | 94 | Proposes a remake the moment the epoch is due, gathers the acks, and never decides; or its coordinator dies | It expires, and any node aborts it a grace after, which frees the acks: the next remake comes. One committed is followed whatever abort came beside it | 6 | sim: `an_expired_remake_is_aborted_by_any_node` | | 95 | Commits remake after remake on bases of its own changes, the epoch's root and a chain of its own, so that nothing honest enters a snapshot | No node follows: a base must hold stamps of nodes of more than a third of the voters written once the epoch was due, and with them what those nodes had seen. What a base that passes leaves out is brought along | 2 | unit: `a_base_holds_a_third_of_the_voters_stamps` | @@ -2575,6 +2590,7 @@ Rules, and the swarm as it is: | 157 | A policy version a node doesn't know: in the root, or decided | It doesn't sync, and takes no such proposal up: a policy is decided only with two thirds of the voters' nodes knowing it | 1 | unit: `no_sync_under_an_unknown_policy`, `an_unknown_policy_isnt_taken_up` | | 158 | A partition, for any length of time | A side decides only with nodes of two thirds of all the voters on it. Where a third of them have nodes and votes on both sides, both may: every node then acts on the higher number | 7 | sim: `one_side_decides`; unit: `the_last_holds` | | 159 | None: a swarm that isn't federated | Everything as today | Optional | the existing tests, untouched; `bench_screening` | + ## The registry on it ``` |
