aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-14 03:16:56 +0000
committertv <tv@krebsco.de>2026-11-14 03:16:56 +0000
commit2b13313ad0ea46c0dd211a54120c294beb4501fa (patch)
tree88b20897c68cc016cd5207453635b9226b3be6c2 /docs
parent86e5a91fd0c014cd1642f95f87e37117d40af784 (diff)
federation: operator actions, writers past cuts, caught up, fork bases, relays
- What an operator says, listed with each action named where it is used: rejoin, choose (two remakes decided, or a walk through the archives that ends elsewhere), follow (a node that waits past `remakeAge`), back (refusing the remake), fork, refusing and bounds, dropping what the others refuse, accepting a check of itself that differed, taking what was put off. Tokens from the nodes `--token-nodes` names. - Where a cut takes a thief's node's writers off a user's count, below the limit again, every node takes what it put off for that user, nobody acting. A writer counts for the user it was counted for until such a cut. - Caught up: the heads each peer kept had when the node reached it, as its first STATUS says, or `witness` passed; a peer that keeps sending keeps it silent no longer. - A fork's base: rule 4 takes its proposer's node's record, without votes; it refused it unless two thirds voted for the fork. - Relays: each node's configuration in a federated swarm; nobody may write `_continuum/relays` plain. - In the open: `GET /registry/users/<name>` shows which root's node keeps a user in past an unvouch or a cut, and which roots' creations contest a moved-in user's first keys. - A carry record names what counts through a cut, as through an unvouch. Two rows move to the stage of policies changing: a limit lowered and raised again, a stamp between.
Diffstat (limited to 'docs')
-rw-r--r--docs/federation.md141
1 files changed, 87 insertions, 54 deletions
diff --git a/docs/federation.md b/docs/federation.md
index 9c39a22..2576b57 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -253,9 +253,10 @@ value:
| `fractions.seen` | 1/3 | the share of the voters whose nodes must have seen a thing for long: a user out, a claim holding, a thing uncovered |
What today's genesis change sets for the swarm as a whole (how many neighbours, the
-topology, the dissemination *(checked: `swarm::bootstrap`)*) are numbers of the
-policy too. The relays aren't: they are addresses an operator lists, which come and
-go, and they stay what they are today.
+topology, the dissemination *(checked: `swarm::bootstrap`)*) are numbers of the policy
+too. The relays aren't: in a federated swarm they are each node's configuration
+(`--libp2p-relays`), addresses its operator lists, which come and go, nothing in the
+document, which nobody may write plain.
Nothing constrains them, and a number that makes no sense has the result it has. A
time of nothing is "at once"; a limit of nothing lets nothing more in; a `baseAge` of
@@ -355,19 +356,22 @@ grows. A statement is signed by one user and says one thing:
change that starts another is put off by every node that would take it from that
user's nodes, until a remake. A node's writers count for one user: the one its
member entry names, of those it carries for, where each writer starts (a writer
- counted stays so), its own word, carried over a remake with the entry; naming none
- of them, the user of the `node` statement naming it with the lowest digest, of those
- that count there, so that its operator names one to choose. So a user past its limit
- puts off the nodes whose writers count for it, and no other that carries for it too.
- It is never refused: put off is each node's doing, its operator may take what it
- puts off, and a change that reaches a node within another's history is taken.
- Writers a node started outside a cut it was stopped with count for nobody: a thief's
- node costs its victim nothing once cut off. A writer is a run, not a write: with a
- thousand, three nodes each crash or rejoin daily for most of a year. A node whose
- writers count for a user past it is put off as a whole, with what it carries for
- others and its records of proposals, until a remake or its operator takes what is
- put off; how many a user's nodes started shows (`GET /registry/users`), for a remake
- to come first.
+ counts for the user it was counted for, until a cut leaves it out), its own word,
+ carried over a remake with the entry; naming none of them, the user of the `node`
+ statement naming it with the lowest digest, of those that count there, so that its
+ operator names one to choose. So a user past its limit puts off the nodes whose
+ writers count for it, and no other that carries for it too. It is never refused: put
+ off is each node's doing, its operator may take what it puts off
+ (`POST /admin/put-off/take`, naming the user), and a change that reaches a node
+ within another's history is taken. Writers a node started outside a cut it was
+ stopped with count for nobody: a thief's node costs its victim nothing once cut off,
+ and where the count falls back below the limit so, every node takes what it put off
+ for that user, read again from the changes, nobody acting: late, with what was built
+ on it. A writer is a run, not a write: with a thousand, three nodes each crash or
+ rejoin daily for most of a year. A node whose writers count for a user past it is
+ put off as a whole, with what it carries for others and its records of proposals,
+ until a remake or its operator takes what is put off; how many a user's nodes
+ started shows (`GET /registry/users`), for a remake to come first.
* **A party's budget.** A node takes changes from a party's nodes no faster than a
budget, its own setting: what is over waits, and nothing is refused for it. For a
budget a party is a user with the users below it that no line reaches but through
@@ -708,8 +712,11 @@ What this gives:
"contested", and one releases. While no root's node is up, a claim isn't settled,
and whichever of two reaches one first when it is back holds.
* **A node that comes back** (started, or cut off for a while) writes nothing before
- it caught up with the peers it keeps (its user's other nodes, its seeds). So it is
- the harder to hand a node a rival before the claim it would have seen first.
+ it caught up with the peers it keeps (its user's other nodes, its seeds): until it
+ holds the heads each of them had when it reached it, as the first STATUS says,
+ whatever they write after, or `witness` passed. A peer that keeps sending keeps it
+ silent no longer. So it is the harder to hand a node a rival before the claim it
+ would have seen first.
* **Final.** A claim is **final** once it has been seen holding the name for `final`
(Lengths of time). From then on no other claim of the name holds it or contests
it, whatever a witness says and whatever is cut off: not a rival that a root says
@@ -1052,7 +1059,7 @@ which every node works out itself.
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.
+ operator says which (`POST /admin/epochs/choose`).
* **Every node builds the snapshot** itself once the remake is decided, from the base
as it holds it, and switches after the switch delay its proposal names. The snapshot
holds the registry as it resolves at the base:
@@ -1095,12 +1102,13 @@ which every node works out itself.
lacks, whoever signed them (statements, values, proposals, votes and their
releases), and what it held of them, as the snapshot states it for the base: which
claim it held as late against which, or as giving way to which; which statements of
- a user since unvouched count through the unvouch; which users it held as gone, which
- claims as final and what as dropped, beyond the snapshot. One record a node and
- epoch, of digests and of what the node held. Nothing tells it from a later change of
- the node, and nothing has to: it witnesses by what it names, not by when it was
- committed. A node that came to carry after the base commits, with its record, the
- `node` statement that named it (rule 2).
+ a user since unvouched, or whose creation or vouch was cut off, count through the
+ unvouch or the cut; which users it held as gone, which claims as final and what as
+ dropped, beyond the snapshot. One record a node and epoch, of digests and of what
+ the node held. Nothing tells it from a later change of the node, and nothing has to:
+ it witnesses by what it names, not by when it was committed. A node that came to
+ carry after the base commits, with its record, the `node` statement that named it
+ (rule 2).
* **Then the envelopes, once.** After its record the node takes from its peers, and
writes again, as they are, the envelopes its record names that the epoch doesn't
hold yet. Any node commits such an envelope (a `node` statement only the node it
@@ -1175,14 +1183,14 @@ in one of two ways:
as it keeps that epoch's document: `archiveRetention` at least, longer if its
operator says, and every epoch on a node kept as an archive. Peers say in the
handshake which epochs they keep. From such a peer the node syncs the rest of the
- epoch it is in, judging every change; sees the remake decided; builds the
- snapshot itself; and is in the next epoch, whose ID is the snapshot's hash.
- So on, epoch by epoch, as far as peers keep them: with an archive within reach,
- from any epoch to the swarm's, and for a node that joins, from the genesis change.
- Where the walk ends in another epoch than the node's peers are in, the node
- stops and shows it, for its operator to say which: an archive can keep changes
- back, and a decision of long ago can be made up with keys stolen since. Keeping
- an archive is an application's; continuum answers for what a node keeps.
+ epoch it is in, judging every change; sees the remake decided; builds the snapshot
+ itself; and is in the next epoch, whose ID is the snapshot's hash. So on, epoch by
+ epoch, as far as peers keep them: with an archive within reach, from any epoch to
+ the swarm's, and for a node that joins, from the genesis change. Where the walk
+ ends in another epoch than the node's peers are in, the node stops and shows it,
+ for its operator to say which (`POST /admin/epochs/choose`): an archive can keep
+ changes back, and a decision of long ago can be made up with keys stolen since.
+ Keeping an archive is an application's; continuum answers for what a node keeps.
2. **By an ID, on its operator's word.** Where no peer keeps the epoch any more, the
node can't check how the swarm got from there to here. Its operator gives it the
ID of the epoch to go to (`POST /admin/epochs/rejoin`), from a party it trusts:
@@ -1206,8 +1214,9 @@ Either way, what follows:
* **As a voter or a root** the user is what the epoch it arrives in names it.
* **Its old document** goes to the archive, as today.
-A node moves to an older epoch, or to another of the same age that doesn't hold by
-the rule above, only by its operator's word.
+A node moves to an older epoch, or to another of the same age that doesn't hold by the
+rule above, only by its operator's word (`POST /admin/epochs/back`,
+`POST /admin/epochs/choose`).
### The policy changes by a decision
@@ -1367,10 +1376,11 @@ A change is valid if, in the document at its dependencies:
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 remake, the base its
coordinator's record names (the coordinator's own names it) and the ID built from
- it; of any other, with votes for it in the change's history by more than
- `fractions.decide` of the voters, none released there. Under `_continuum/carried`:
- only the node's own carry record, once an epoch. Nothing replaced, nothing deleted,
- nor anything that holds a register.
+ it; of a fork, its proposer's node's own, naming the base, without votes; of any
+ other, with votes for it in the change's history by more than `fractions.decide` of
+ the voters, none released there. Under `_continuum/carried`: only the node's own
+ carry record, once an epoch. Nothing replaced, nothing deleted, nor anything that
+ holds a register.
5. A `create`: its name is one the kind `user` takes, and neither a creation of it nor
a user's claim of it as its own name stands there, a rule of the kind lets the
signer, and the signer isn't past its limit there; or it is a root's, for a user
@@ -1491,7 +1501,10 @@ name), and answers from it:
* `GET /registry/users/<name>`: the user that has the name, its keys and nodes, who
created it and who vouches for it; or that it is contested, between whom; or out,
- since where, and how long its names still wait; or gone.
+ since where, and how long its names still wait; or gone. Also what is in the open:
+ which root's node keeps it in past an unvouch or a cut by a witness the signer's own
+ nodes didn't make, and, for a user the root change holds, which roots' creations
+ contest its first keys.
* `GET /registry/claims/<kind>/<name>`: the holder, and whether the claim is settled,
and final; held "while a release, a cut, or statements past a limit stand" where it
was made in sight of a claim that one could bring back, and isn't final; or
@@ -1624,13 +1637,32 @@ takes along those of the nodes that carry for a user it holds.
in the registry gives a user nothing on anyone's node by itself. (Today a user
with keys in the registry logs in on any node *(docs)*.) What a user may write is
in its signature, whatever node it reaches.
-* **Tokens** are taken only from the node itself and from the nodes its operator
- names: its party's others. (Today every node takes a token any member signed
- *(docs)*: a party's node could let itself in anywhere.) Ended sessions are each
- node's, as in a swarm without a registry.
+* **Tokens** are taken only from the node itself and from the nodes its operator names
+ (`--token-nodes`, their node IDs): its party's others. (Today every node takes a
+ token any member signed *(docs)*: a party's node could let itself in anywhere.)
+ Ended sessions are each node's, as in a swarm without a registry.
* **Reading**: every party reads everything. The registry holds public keys, names
and addresses, nothing secret; a value only some should read is sealed for them, as
today.
+* **What an operator says**, on its own node and nowhere else, each shown where the
+ node waits on it (`GET /admin/epochs`, the dashboard):
+ * `POST /admin/epochs/rejoin`, naming an epoch's ID: go there, where no peer keeps
+ the epochs between (Coming back after remakes).
+ * `POST /admin/epochs/choose`, naming an epoch's ID: which, where two remakes of the
+ epoch it left are both decided, or its walk through the archives ends elsewhere
+ than its peers are.
+ * `POST /admin/epochs/follow`, naming a decided remake's proposal: follow it now, for
+ a node that waits past `remakeAge` (Partitions).
+ * `POST /admin/epochs/back`, naming the epoch: go back to it, refusing the remake
+ that left it; what its users signed since goes to the quarantine (Partitions).
+ * `POST /admin/fork`, naming a fork's proposal and its base (Going apart).
+ * `POST /admin/decisions/refuse`, naming a proposal; `GET` and `PUT /admin/bounds`
+ (Refusing a decision).
+ * `POST /admin/refused/drop`, naming the peer whose word it takes (Partitions).
+ * `POST /admin/check/accept`: write again after a check of itself that differed
+ (Continuum changing under a swarm).
+ * `POST /admin/put-off/take`, naming a user: take what was put off for the writers
+ past its limit (Users).
* **Who may connect** is outside this design. Today it is the swarm key, a secret all
nodes share: it keeps those who aren't parties from connecting and reading, as far
as every party keeps it, and is no boundary between the parties. Nothing here
@@ -2044,10 +2076,10 @@ author remembered to say. So the design goes by what nodes compute:
policies disagree does so today)*, and compares with the stamps it holds of the
voters' nodes. Where it differs from the nodes of more than two thirds of the other
voters (`fractions.decide`; a voter counted once, however many nodes it has), it
- writes nothing, and shows it, until its operator says to go on. Where it differs
- from fewer it shows that and goes on. So fewer than a third stamping nonsense stop
- nobody, with three voters too, and a version that computes otherwise than the honest
- ones stops.
+ writes nothing, and shows it, until its operator says to go on
+ (`POST /admin/check/accept`). Where it differs from fewer it shows that and goes on.
+ So fewer than a third stamping nonsense stop nobody, with three voters too, and a
+ version that computes otherwise than the honest ones stops.
* **A change of the rules is a change of policy.** What a version judges or resolves
differently on purpose, it does under a policy of its own (a part of the policy
that versions before don't know), which the swarm decides. A change is judged by
@@ -2219,7 +2251,7 @@ Decisions and remakes:
| 99 | Creates a user, lets it settle names, then cuts the creation's key off from before it with a retirement that says it saw little, its own nodes silent, so that nothing the user signed counts through the creation, and an accomplice claims its names | The roots' nodes witness past a cut, as against an unvouch: what the user signed that a root's node had in its history counts, its settled names hold, and it is out from the retirement, its names waiting | 5 | unit: `a_cut_keeps_the_roots_witnesses` |
| 100 | Cuts the creation's key off from before it on old dependencies, then claims the user's settled names, or creates a user of its name, in a change whose history holds the user's claims and the cut and nothing else | Where the user's claim didn't stand there only by the cut, the two are ordered as claims out of each other's sight, over all the changes: the roots' nodes had the user's claim count first, so the new claim is late, for good, and the user keeps its names | 5 | unit: `a_claim_in_sight_past_a_cut_is_ordered_by_lateness` |
| 101 | A root cuts off the key it created users with, from before the creations, to take their names, final ones too, where only the roots create users; or a thief of a root's key gives a moved-in user first keys | A root's creation another root's node had seen stays the claim of the name, and its first keys: a turned root takes back only what the other roots hadn't seen, never a settled or final name. A thief's creation made out of their sight falls; one made in it the voters undo | 5; not promised | unit: `a_roots_creation_outlasts_its_cut_where_another_root_saw_it` |
-| 102 | A root's node, beside a thief, commits with a fresh writer on heads without the retirement a change holding what the thief's sock signed, to keep it in past the cut | A root's node witnesses past a cut, as against an unvouch: the sock stays in by it, in the open, the root marked. An accomplice's vouch keeps it in too | not promised | unit: `a_cut_has_its_signers_witnesses` |
+| 102 | A root's node, beside a thief, commits with a fresh writer on heads without the retirement a change holding what the thief's sock signed, to keep it in past the cut | A root's node witnesses past a cut, as against an unvouch: the sock stays in by it, in the open, shown with the root (`GET /registry/users/<name>`). An accomplice's vouch keeps it in too | not promised | unit: `a_cut_has_its_signers_witnesses` |
| 103 | A node that held only the older of two values its user wrote since the base carries it beside the newer one | Of several carried over to one place, one that another replaces is left out | 3 | unit: `a_replaced_value_is_left_out` |
| 104 | Signs a claim "in the epoch before" of a name the snapshot holds | It gives way to what the snapshot holds | 5 | unit: `the_snapshot_comes_first` |
| 105 | Hands in again what a remake left out: a stolen laptop's `node` and `key` statements, retired since | Refuse: the root change lists the digests of the statements the base held | 3 | unit: `what_a_remake_dropped_stays_out` |
@@ -2363,8 +2395,8 @@ their vectors. At every stage the existing tests pass untouched (149).
read from the stamps; final. `GET /registry/claims` with what makes a claim late;
values marked in `GET /store`. A node keeps its seeds and its user's other nodes as
neighbours, leaves out members that name another epoch, and shows a claim long
- unsettled. Tests: 7, 9, 10, 13, 15, 16, 30, 36, 38, 39, 43 to 46, 49, 52, 53, 127,
- 129, 130.
+ unsettled. Tests: 7, 9, 10, 13, 15, 16, 36, 38, 39, 43 to 46, 49, 52, 53, 127, 129,
+ 130.
6. **Cuts.** `retire` and the keys above, a node that stops, a cut never reaching its
own statement, what a cut takes back, what doesn't count left out, the value before
read again, the client listing what stopped counting. Tests: 14, 20, 47, 48, 51, 54
@@ -2389,7 +2421,7 @@ their vectors. At every stage the existing tests pass untouched (149).
holds, what hangs; `GET /registry/decisions`. What is decided: a number, a user's
first keys, the names of a user that is out, whose a contested name is, a name the
rules leave to the voters. The simulations start from a root change naming several
- voters, as a remake's does. Tests: 23, 50, 63, 67, 70 to 86, 148.
+ voters, as a remake's does. Tests: 23, 63, 67, 70 to 86, 148.
11. **Versions.** The digest with every stamp, a node checking itself before it
writes; for every swarm, a node that speaks the wire version before its own, and a
handshake that says which epochs its node keeps. Tests: 145, 146.
@@ -2407,7 +2439,7 @@ their vectors. At every stage the existing tests pass untouched (149).
95, 103 to 110, 116 to 120.
13. **The policy by a decision.** The policy as a matter, a node that doesn't know it,
what it no longer covers: shown aside, taken away by its user only, dropped after
- a time, moved at a remake. Tests: 87, 88, 147.
+ a time, moved at a remake. Tests: 30, 50, 87, 88, 147.
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 at once (`remakeAge`) and how the split heals, a waiting
@@ -2456,7 +2488,8 @@ Checked in the code:
(`remake::delta`). A quarantine on disk that holds envelopes, anyone's, and every
node writing again the envelopes it holds after a remake, are new.
* The relays are read from `_continuum/relays`, which an operator lists
- (`document::meta`, `swarm::members`); the genesis change doesn't set them.
+ (`document::meta`, `swarm::members`); the genesis change doesn't set them. A
+ federated node reads them from its configuration alone (`--libp2p-relays` exists).
* A snapshot records the highest number per actor in its base, by which a node tells
what it holds beyond it (`remake::snapshot`, `remake::delta`). The digests of the
base's statements do that for a federated one.