aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/federation-tests.md5
-rw-r--r--docs/federation.md34
-rw-r--r--docs/guides/federation/voting-by-itself.md3
3 files changed, 31 insertions, 11 deletions
diff --git a/docs/federation-tests.md b/docs/federation-tests.md
index d902c36..3aa1996 100644
--- a/docs/federation-tests.md
+++ b/docs/federation-tests.md
@@ -61,8 +61,9 @@ to: a stage is done when its tests are.
## Properties, over generated histories
Histories are generated: a few parties (3 to 7), their keys, versions passing, honest
-writes and votes, and an adversary that signs anything its own keys or stolen ones can,
-on any dependencies, and puts out events no party signs. Each property is checked for
+writes and votes, nodes merging under a revision with merge events or not, and an
+adversary that signs anything its own keys or stolen ones can, on any dependencies, and
+puts out events no party signs. Each property is checked for
every order of every history small enough (up to some 8 events, every order that puts
each after its dependencies), and for seeded histories and orders beyond that.
diff --git a/docs/federation.md b/docs/federation.md
index 766c9a6..ecc3f21 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -145,7 +145,12 @@ Spread out:
* `proposal`, a version, the object ([Changing the policy](#changing-the-policy));
* `vote`, `{"on": "<hash>", "proposal": "<hash>", "yes": true}`, `"yes"` `true` or
`false` ([Changing the policy](#changing-the-policy)): a version's hash, the SHA-256
- of its JCS bytes, written as an ID is.
+ of its JCS bytes, written as an ID is;
+ * `merge`, `true`: nothing but building on its dependencies, under a revision with
+ merge events ([Changing the federation](#changing-the-federation)), signed by a node
+ its party's node list names, its `key` the node's Ed25519 key: a **merge event**,
+ which counts for nothing, so that what builds on it has its dependencies in its
+ history ([Nodes](#nodes)).
* **`sig`**: an SSH signature (`ssh-keygen -Y sign`, namespace `continuum-federation`)
over the event's bytes without `sig`: the SSHSIG blob of version 1, hashed with
`sha512`, its key the event's `key`, its reserved field empty, as `ssh-keygen` writes
@@ -532,7 +537,10 @@ as it judges any vote or proposal. The design has two in mind:
following one hand it their votes on checkpoints: with them, it passes one at heads of
its choosing, by the voters' rule (below). Its operator may have it follow on any
version, which hands that party the node's `true`: a party followed so by two thirds of
- the parties, its key kept on a node, passes what it backs.
+ the parties, its key kept on a node, passes what it backs. On a version changing the
+ revision it follows never: its party's operators vote on that one by hand, once their
+ nodes run a continuum that knows it
+ ([Changing the federation](#changing-the-federation)).
* **Proposing a checkpoint**: propose a version that only moves to a checkpoint, at
heads the node has held for a while, once conditions its operator sets are met: so
many events or bytes held beyond its checkpoint, so many versions since it, or so long
@@ -585,7 +593,9 @@ which a list the stolen key writes at a history from before that version, whatev
ID, doesn't replace ([What counts](#what-counts), 5). A node
puts whatever events it is given, its party's and others' alike: what counts is who signed
an event, not which node put it. So a party without nodes of its own writes through any
-node that takes its events.
+node that takes its events. Under a revision with merge events, a node its party lists
+signs merge events with its own key ([Events](#events)): they count for nothing, and only
+gather what they build on into the history of what builds on them.
### Forks
@@ -763,6 +773,7 @@ fold, with crafted events. *Sim*: a simulation. *Bench*: measured, not judged.
| 68 | A checkpoint proposed at heads that leave out what was written since: a key set dropping a stolen key, say | Not backed: clients and nodes back a checkpoint only where what they held for a while is among its heads, in their history, or above them; a node shows what they lack | unit |
| 69 | A key a version names, stolen, writes its party's node list at a history from before the version naming the party's keys anew, beside the list the party writes under that version, several, for the lowest ID | The party's counts: of a party's lists, those written under the latest version come first | unit |
| 70 | A checkpoint's version proposed again, by an event beside its heads | Voters back it all the same, as a proposal lapses with the move, and vote on the events proposing it above its heads, as a node shows them; a version event on votes beside them is refused | unit |
+| 71 | Merge events under the base revision, signed by a node its party doesn't list, by a party's key, or spelled otherwise | Refused, or none: a merge event is taken only under a revision with merge events, signed by a node its party's node list names, its `merge` `true`; it counts for nothing | unit |
## Roads not taken
@@ -851,10 +862,15 @@ which a version names by its ID (`"revision": "<ID>"`); one naming none follows
**base revision**, which federation 1 began with, keys of type `ecdsa-sha2-nistp256`
among it. A revision adds a feature to those of the one before, and its ID is the SHA-256
of the JCS list of its features' names, so that a continuum that doesn't know a revision,
-another build's among them, can't read a version naming it. There are none yet but the
-base revision. What no history judges, the document, a change, the snapshot and the
-Automerge version, no version names: a change there splits the swarm until every node
-runs it ([`guides/federation/upgrades.md`](guides/federation/upgrades.md)).
+another build's among them, can't read a version naming it:
+
+| Revision | Its feature | What it adds |
+| --- | --- | --- |
+| 1 | `merge-events` | Merge events, which a node its party lists signs with its own key, building on events it holds and writing nothing ([Events](#events)) |
+
+What no history judges, the document, a change, the snapshot and the Automerge version, no
+version names: a change there splits the swarm until every node runs it
+([`guides/federation/upgrades.md`](guides/federation/upgrades.md)).
A version leaves `revision` out for the base revision, and names a revision no earlier
than that of the version it changes. What a revision adds counts at a history only where
@@ -862,7 +878,9 @@ the version current there names that revision or a later one: before, every node
as before, so that what a party uses early, every node refuses alike. A version is read by
the revision it names, so one moving to a revision may already hold what that revision
adds to a version; its proposal, the votes on it and its version event are judged under
-the version before.
+the version before. A node voting by itself backs no version changing the revision
+([Votes a node casts by itself](#votes-a-node-casts-by-itself)): its party's operators
+vote on it.
A node that doesn't read a version that passed on the version it reads, of a revision or
a federation it doesn't know or none at all, stops at the version event writing it, and
diff --git a/docs/guides/federation/voting-by-itself.md b/docs/guides/federation/voting-by-itself.md
index a31595f..0390cfd 100644
--- a/docs/guides/federation/voting-by-itself.md
+++ b/docs/guides/federation/voting-by-itself.md
@@ -42,7 +42,8 @@ or `POST /admin/events/vote` with `{"proposal": "8d02…", "yes": true}`.
checkpoint lapses it. Even so, the parties following one hand
it their votes on checkpoints. With `--store-follow-any`, on any version: that hands
those parties the node's `true`. A party followed so by two thirds of the parties, with
- its key kept on a node, passes what it backs.
+ its key kept on a node, passes what it backs. On a version changing the revision it
+ follows never: vote on that one by hand ([`upgrades.md`](upgrades.md)).
* **After a move** (`--store-back-after`, ten minutes unless set): it backs, and proposes,
no checkpoint until its store held its checkpoint, or ran, that long by its own clock,
by itself or by hand: the parties it follows move the store once that long at most, and