aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/federation.md76
1 files changed, 49 insertions, 27 deletions
diff --git a/docs/federation.md b/docs/federation.md
index 01c9388..aadaca1 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -153,16 +153,18 @@ What is not promised:
* **A remake the voters changed their minds on.** A vote for a remake isn't released,
and a voter has one an epoch. So a remake that hangs comes on the day its last
record does, for the rest of the epoch, and those who voted for it vote for no
- other. A node follows a remake only within `remakeAge` of taking its base up, and
- refuses one decided later by staying (Refusing a decision): every node holds that
- number, but each took the base up when it reached it, and gets the decision when it
- does. So whoever holds the last record can show it when some honest nodes are past
- that and some aren't, and splits them between two epochs; those that stayed have
- their remake votes spent, and go apart. And voters who split their votes between two
- remakes, neither getting more than two thirds, end the epoch's remakes: those left
- go apart (Going apart). One voter can split them: clients keep honest votes on one
- remake, but a twin proposal made while honest voters vote, within the same minutes,
- splits those.
+ other. A node follows a remake at once only within `remakeAge` of taking its base
+ up; past that, it waits in the epoch until the new epoch's carry records count for
+ more than a third of the voters (Partitions). Every node holds that number, but each
+ took the base up when it reached it, and gets the decision when it does: whoever
+ holds the last record can show it when some honest nodes are past that and some
+ aren't, and splits them for a while. The split shows, and heals: every node follows
+ once those carry records count for more than a third, or those that followed go
+ back, `remakeAge` later, and their users sign again what they wrote there. And
+ voters who split their votes between two remakes, neither getting more than two
+ thirds, end the epoch's remakes: those left go apart (Going apart). One voter can
+ split them: clients keep honest votes on one remake, but a twin proposal made while
+ honest voters vote, within the same minutes, splits those.
* **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; what users write goes on. Those left go apart (Going apart).
@@ -1021,13 +1023,13 @@ which every node works out itself.
* **A remake that hangs**, short of votes or records, is decided once they come: every
node takes up a base a third took up. Nothing else ends it: its votes aren't
released, so whoever holds its last record chooses its day for the rest of the
- epoch, and those who voted for it vote for no other. A node follows it only within
- `remakeAge` of taking its base up, and refuses it later by staying (Refusing a
- decision): shown when some nodes are past that and some aren't, it splits them (what
- is not promised). Voters who split between two remakes, neither getting more than
- two thirds, end the epoch's remakes: those left go apart (Going apart). No node,
- having switched, moves again by itself: where it finds another remake of the epoch
- it left decided, it shows it, and its operator says.
+ epoch, and those who voted for it vote for no other. A node follows it at once only
+ within `remakeAge` of taking its base up; past that, once the new epoch's carry
+ records count for more than a third of the voters (Partitions). Voters who split
+ between two remakes, neither getting more than two thirds, end the epoch's remakes:
+ those left go apart (Going apart). No node, having switched, moves again by itself,
+ but back from a remake its carry records didn't bear (Partitions): where it finds
+ another remake of the epoch it left decided, it shows it, and its operator says.
* **Every node builds the snapshot** itself once the remake is decided, from the base
as it holds it, and switches after the switch delay, as today. The snapshot holds
the registry as it resolves at the base:
@@ -1262,8 +1264,9 @@ follows every decision. Its operator has it refuse:
* **By hand** (`POST /admin/decisions/refuse`, naming the proposal): any decision of
the epoch the node is in.
* **By how late a remake comes** (`remakeAge`, the policy's): how long after it took a
- base up, by its own clock, a node still follows a remake decided on it. One decided
- later it refuses, as any remake is refused: by staying.
+ base up, by its own clock, a node follows a remake decided on it at once. One
+ decided later it doesn't, until the new epoch's carry records count for more than a
+ third of the voters (Partitions).
What refusing does:
@@ -1484,9 +1487,28 @@ same holder, or contested. The users see it and one releases; nobody drops anyth
**Two epochs**, after a fork or a decision some refuse, are apart for good: each node
is where its operator put it (by word or by bounds), and moves to the other side by
-being told to (it builds that side's snapshot from the base it holds, and carries
-over what it holds). The same where two remakes of one epoch were both decided,
-which takes more than a third of the voters voting for both (Remakes).
+being told to (it builds that side's snapshot from the base it holds, and carries over
+what it holds). The same where two remakes of one epoch were both decided, which takes
+more than a third of the voters voting for both (Remakes).
+
+**A remake past `remakeAge`** splits the honest nodes for a while: those that got the
+decision within it follow, those past it wait in the epoch. It shows on both sides:
+those that wait hold the decision and see peers in the new epoch; those that followed
+see peers in the old one, the decision in their history (`GET /peers`, the dashboard).
+It heals by the new epoch's carry records, which count for the voters each node
+carries for, read alike by every node, and only grow:
+
+* Once they count for more than a third of the voters, every node in the old epoch
+ follows, past `remakeAge` or not: a node of an honest voter got the decision in
+ time, and the malicious alone count for less.
+* While they count for no more than a third, `remakeAge` after a node followed, it
+ goes back: it drops the new epoch, as a node comes back from changes the others
+ refuse (below), and what its users signed there goes to the quarantine, to be signed
+ again in the epoch it is back in.
+* A node that went back follows again should they count for more than a third later.
+ So every honest node ends in one epoch, whichever it is. A remake shown long after
+ its time gets no honest node's carry record, and nobody but the malicious follows
+ it.
**Changes one side refuses** are a partition nobody chose. A node is cut off from the
others when it holds a change they refuse, as everything it writes after builds on
@@ -2150,8 +2172,8 @@ Decisions and remakes:
| 102 | A partition at the base: the nodes of a third of the voters take it up, the rest see it after they held more than it has | Every node takes up a base whose records count for a third of the voters, however old, and the remake is decided | 7 | sim: `a_base_seen_late` |
| 103 | Proposes a remake beside another voter's; or hands its base first to nodes back from away, or one an hour old that such a node takes up, so that the nodes take up one base and no other | A node takes up every base that passes, one record a proposal. A client offers a vote only for a base whose records count for more than two thirds of the voters, which every node takes up, and shows the other remakes under way: a vote goes to a base every voter's node can take up. Only the votes keep two bases from both being decided | 7 | sim: `two_remakes_proposed_at_once` |
| 104 | Proposes a twin of a remake under way, or as its coordinator names two bases to two nodes of each voter, so that honest votes split and the epoch's remakes end | Clients offer a vote for one of the remakes that name the same voters and roots (most votes, then the lowest digest), and none for a proposal whose coordinator named two bases. Honest voters signing within the same minutes can still be split | 7; not promised | sim: `a_twin_remake_gets_no_votes` |
-| 105 | Votes for a remake with the others, keeps its node's record back once they changed their minds, and shows it when it likes | Those who voted for the remake vote for no other in the epoch: it comes on the day its last record does. A node follows a remake only within `remakeAge` of taking its base up, and refuses a later one by staying. Voters who split between two remakes end the epoch's remakes, and those left go apart | not promised | sim: `a_remake_held_by_its_last_record` |
-| 106 | Holds its node's record of a remake back, and shows it when some honest nodes are past `remakeAge` from taking the base up and some aren't | Those within it follow, those past it stay: the honest nodes split between two epochs, and those that stayed have their remake votes spent and go apart. Not prevented | not promised | sim: `a_remake_between_the_bounds` |
+| 105 | Votes for a remake with the others, keeps its node's record back once they changed their minds, and shows it when it likes | Those who voted for the remake vote for no other in the epoch: it comes on the day its last record does. A node follows a remake at once only within `remakeAge` of taking its base up; past it, once the new epoch's carry records count for more than a third of the voters. Voters who split between two remakes end the epoch's remakes, and those left go apart | not promised | sim: `a_remake_held_by_its_last_record` |
+| 106 | Holds its node's record of a remake back, and shows it when some honest nodes are past `remakeAge` from taking the base up and some aren't | Those within it follow, those past it wait, and both sides see it. Once the new epoch's carry records count for more than a third of the voters every node follows; while they count for no more, `remakeAge` later, those that followed go back, their users' writes there quarantined to be signed again. Every honest node ends in one epoch; a remake shown long after its time is followed by the malicious alone | not promised; healed | sim: `a_remake_between_the_bounds_heals`, `a_remake_long_past_its_time` |
| 107 | A thief's statements are in the base of a remake | They stand: a remake makes final. The vote's days are the time to cut the key off | not promised | unit: `a_cut_reaches_to_the_snapshot` |
| 108 | Tells a node that was away of an epoch that isn't the swarm's | The node rejoins no epoch that peers advertise: it finishes the old one from archives and builds the next itself, or takes the ID its operator gave | 1 | sim: `away_over_a_remake`, `back_by_an_id` |
| 109 | A node back after several remakes offers what its user signed epochs ago | Refuse: an envelope is taken in its epoch and the next. Quarantined, for the user to sign again | 3 | unit: `carried_over_one_epoch_only` |
@@ -2328,9 +2350,9 @@ their vectors. At every stage the existing tests pass untouched (140).
a time, moved at a remake. Tests: 84, 85, 138.
14. **Going apart, and refusing.** A fork followed by an operator's word, with who
votes and who the roots are on its side. Refusing a decision: a node's bounds, how
- late a remake it follows (`remakeAge`), the epoch without the decision, what a
- node takes along. Tests: 105, 106, 112 to 117. From here it can be relied on: the
- rules change by decisions.
+ late a remake it follows at once (`remakeAge`) and how the split heals, the epoch
+ without the decision, what a node takes along. Tests: 105, 106, 112 to 117. From
+ here it can be relied on: the rules change by decisions.
## What was checked, and what is assumed