aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation
diff options
context:
space:
mode:
Diffstat (limited to 'docs/guides/federation')
-rw-r--r--docs/guides/federation/checkpoints.md22
-rw-r--r--docs/guides/federation/getting-started.md47
-rw-r--r--docs/guides/federation/keys.md7
-rw-r--r--docs/guides/federation/upgrades.md16
-rw-r--r--docs/guides/federation/when-things-go-wrong.md7
5 files changed, 49 insertions, 50 deletions
diff --git a/docs/guides/federation/checkpoints.md b/docs/guides/federation/checkpoints.md
index eb9fec2..f6340b0 100644
--- a/docs/guides/federation/checkpoints.md
+++ b/docs/guides/federation/checkpoints.md
@@ -22,14 +22,20 @@ isn't above the heads, which its party signs again ([After a move](#after-a-move
## Proposing one
A version that only moves the store on is the current one with the next `number`, the
-current version's hash as `changes`, and the heads as `checkpoint`
-([`proposing-and-voting.md`](proposing-and-voting.md),
-[Writing a version](proposing-and-voting.md#writing-a-version)). The heads are events
-after the current checkpoint, at which the current version is current too, none in
-another's history, their IDs ascending: the heads a node shows (`heads` in `GET /events`)
-as late as you can, so that what was written before is in their history. Propose it
-then: the client signs the proposal on the heads its node
-shows then, above the ones it names, as it must be.
+current version's hash as `changes`, and the heads as `checkpoint`: `propose checkpoint`
+writes and proposes it, at the heads the node shows then, as late as you can, so that
+what was written before is in their history:
+
+```sh
+continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
+ propose checkpoint --yes
+```
+
+The heads are events after the current checkpoint, at which the current version is
+current too, none in another's history, their IDs ascending; by hand, `heads` in `GET
+/events` ([`proposing-and-voting.md`](proposing-and-voting.md),
+[Writing a version](proposing-and-voting.md#writing-a-version)). The client signs the
+proposal on the heads its node shows then, above the ones it names, as it must be.
Like any version, it lapses the proposals on the version before: propose one where
nothing that can still pass is proposed on the current version.
diff --git a/docs/guides/federation/getting-started.md b/docs/guides/federation/getting-started.md
index 6a0aec8..483a991 100644
--- a/docs/guides/federation/getting-started.md
+++ b/docs/guides/federation/getting-started.md
@@ -141,8 +141,8 @@ names them once, when it begins its record (`init --federation NAME`), and never
lass reads it on its node, with everything else that counts:
```sh
-curl -s -u lass:secret localhost:3000/events/counts | jq .values
-# {"home/tv/motd": "hello"}
+continuum-party --node http://lass:secret@localhost:3000 values
+# home/tv/motd "hello" (tv)
```
lass can't write there: its node refuses it, as every node does.
@@ -165,48 +165,35 @@ root, as it never voted:
continuum-party --record makefu.record init makefu --root root
```
-The founders write the version letting makefu in: the next number, the hash of the
-version it changes, makefu's keys and node list named anew in it (`since` its number),
-and the founders' as they were. `continuum-party next` gives the current version with
-the first two changed:
-
-```sh
-continuum-party --node http://tv:secret@localhost:3000 next > second.json
-```
-
-and makefu goes in:
-
-```json
-{ "federation": 1, "number": 1, "changes": "1f4c…",
- "keys": { "tv": { "since": 0, "keys": ["ssh-ed25519 AAAA…"] },
- "lass": { "since": 0, "keys": ["ssh-ed25519 AAAA…"] },
- "makefu": { "since": 1, "keys": ["ssh-ed25519 AAAA…"] } },
- "nodes": { "tv": { "since": 0, "nodes": ["continuum:5be1…"] },
- "lass": { "since": 0, "nodes": ["continuum:9c07…"] },
- "makefu": { "since": 1, "nodes": ["continuum:e2a8…"] } },
- "rules": [ { "path": "home/{party}/**", "writer": "{party}" } ] }
-```
-
-One of them proposes it, and votes `true` on it (`--yes`); the client says the
-proposal's hash, the version's:
+One of the founders proposes the version letting makefu in, with makefu's key and node,
+and votes `true` on it (`--yes`). The client writes it from the current one, says what it
+does and asks, and says the proposal's hash, the version's:
```sh
continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
- propose second.json --yes
+ propose admit makefu --keys makefu.key.pub --nodes continuum:e2a8… --yes
+# version 1 on 0:
+# lets makefu in: 1 key (ssh-ed25519 SHA256:2kq…); 1 node (continuum:e2a8…)
+# Propose it, and vote `true` on it? [y/N] y
# c41e… taken
# proposal 8d02…
# 5a77… taken
```
-The other votes `true` too, through its own node:
+The other looks at it, and votes `true` too, through its own node, naming the proposal by
+a prefix of its hash:
```sh
continuum-party --node http://lass:secret@localhost:3000 --key lass.key \
- --record lass.record vote 8d02… yes
+ --record lass.record vote 8d02 yes
+# 8d02…: can still pass, 1 more `true` passing it (2 of 2); true: tv; false: nobody
+# proposed by tv: version 1 on 0
+# lets makefu in: 1 key (ssh-ed25519 SHA256:2kq…); 1 node (continuum:e2a8…)
+# Vote `true` on 8d02…? [y/N] y
```
Once a node holds both votes, it writes the version, and every node takes it:
-`.version.number` in `GET /events/counts` is 1. makefu's node, started with
+`continuum-party status` says version 1. makefu's node, started with
`--store-id 6d1e… --store-party makefu` and a seed, is a member now: the others sync
with it, and makefu writes in its namespace as tv did.
diff --git a/docs/guides/federation/keys.md b/docs/guides/federation/keys.md
index dcac7a2..e6bf1e0 100644
--- a/docs/guides/federation/keys.md
+++ b/docs/guides/federation/keys.md
@@ -76,8 +76,8 @@ before dropping a key, sign again with a new one what should stay:
set (the client signs on the heads its node shows). For a namespace:
```sh
- curl -s -u tv:secret localhost:3000/events/counts |
- jq -c '.values | to_entries[] | select(.key | startswith("home/tv/"))' |
+ continuum-party --node http://tv:secret@localhost:3000 values home/tv --json |
+ jq -c 'to_entries[]' |
while read -r entry; do
continuum-party --node http://tv:secret@localhost:3000 --key desk.key \
--record tv.record write "$(jq -r .key <<<"$entry")" "$(jq -c .value <<<"$entry")"
@@ -92,7 +92,8 @@ signed since replaced it and no checkpoint left it out.
## Changing the keys a version names
A party proposes a version naming its keys anew (`since` that version's number), and the
-parties vote ([`proposing-and-voting.md`](proposing-and-voting.md)). Its votes and
+parties vote ([`proposing-and-voting.md`](proposing-and-voting.md)): `continuum-party
+propose keys tv tv-new.key.pub`, by another party where tv's version keys are lost. Its votes and
proposals use the new keys from that version on; its set written before counts no more,
so it writes its set again, with the new version keys.
diff --git a/docs/guides/federation/upgrades.md b/docs/guides/federation/upgrades.md
index 9025164..cb82382 100644
--- a/docs/guides/federation/upgrades.md
+++ b/docs/guides/federation/upgrades.md
@@ -83,19 +83,21 @@ adds is refused everywhere until a version names it.
A node says nothing on a build from before it said this, or where this node didn't
hear from it since it started: each says it with each handshake.
-2. **Propose.** A party begins the next version following it, by the feature it adds;
- `next` says so where its node knows a later revision than the current version's:
+2. **Propose.** A party proposes the next version following it, by the feature it adds
+ (`next` says which, where its node knows a later revision than the current
+ version's):
```sh
- continuum-party --node http://tv:secret@localhost:3000 next --revision merge-events \
- > next.json
continuum-party --node http://tv:secret@localhost:3000 --key tv.key \
- --record tv.record propose next.json
+ --record tv.record propose revision merge-events
+ # version 5 on 4:
+ # moves to revision 1 (merge-events)
+ # Propose it? [y/N] y
# proposal 5e81…
```
- Where nodes the parties list aren't known to know the revision, `next` warns, and
- names them. It may already hold what the revision adds to a version: a version is read
+ Where nodes the parties list aren't known to know the revision, the client names
+ them before it asks. It may already hold what the revision adds to a version: a version is read
by the revision it names. Its proposal and the votes on it are judged under the current
version, and what the revision adds to events counts from the version after.
diff --git a/docs/guides/federation/when-things-go-wrong.md b/docs/guides/federation/when-things-go-wrong.md
index 8171201..8326f72 100644
--- a/docs/guides/federation/when-things-go-wrong.md
+++ b/docs/guides/federation/when-things-go-wrong.md
@@ -12,7 +12,8 @@ Two versions changing one are written only where keys voted twice: a party's `tr
`false` on one proposal, each shown to some, or its `true` on two. Each node takes the
first it judges and refuses the other, with everything built on it, and keeps so across
restarts (`--store-file`); its log says so (`Refused an event its history takes, by what
-this node took before: kept so`), and `GET /events/refused` lists it under `own`:
+this node took before: kept so`), `continuum-party status` says so, and `GET
+/events/refused` lists it under `own`:
```sh
curl -s -u tv:secret localhost:3000/events/refused | jq .own
@@ -63,7 +64,9 @@ took after its checkpoint: a version that moved it to a checkpoint it undoes onl
taking a checkpoint its operator pins (`--store-checkpoint`).
The parties answer keys that voted twice by forking, without the party that voted twice
-or with its keys named anew ([`forking-and-following.md`](forking-and-following.md)).
+(`continuum-party fork remove lass`) or with its keys named anew (`fork keys lass
+KEY…`), at the heads of the side they keep
+([`forking-and-following.md`](forking-and-following.md)).
Tell the other parties what your node took and what it refused, and send them your
record.