aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/guides/federation/common-changes.md119
-rw-r--r--docs/guides/federation/proposing-and-voting.md23
2 files changed, 95 insertions, 47 deletions
diff --git a/docs/guides/federation/common-changes.md b/docs/guides/federation/common-changes.md
index a18d863..8a31080 100644
--- a/docs/guides/federation/common-changes.md
+++ b/docs/guides/federation/common-changes.md
@@ -1,91 +1,121 @@
# Common changes
-Recipes for the changes a federation makes most, each a version to propose and vote on
-([`proposing-and-voting.md`](proposing-and-voting.md)), and a few a party makes by itself.
+The changes a federation makes most, each a version proposed by a command of its own and
+voted on ([`proposing-and-voting.md`](proposing-and-voting.md)), and a few a party makes
+by itself.
The rules are the design's ([`federation.md`](../../federation.md),
[The policy](../../federation.md#the-policy), [Keys](../../federation.md#keys),
[Nodes](../../federation.md#nodes)).
-## The next version
+## How
-Every change below begins from the current version: the next number, the current one's
-hash as `changes`, and no `checkpoint` (a version names one only to move the store
-on, and the current version's heads are behind):
+Each change below is a subcommand of `propose`: the client writes the next version, the
+current one with the next number, its hash as `changes`, no `checkpoint`, and the change;
+says what it does; asks on a terminal; and proposes it. `--yes` votes `true` on it too.
+The client's options are as everywhere (`--node`, `--key`, `--record`, or a federation's
+directory, [`configuration.md`](../../configuration.md),
+[The party's client](../../configuration.md#the-partys-client)), left out below:
```sh
-continuum-party --node http://tv:secret@localhost:3000 next > next.json
+continuum-party propose admit makefu --keys makefu.key.pub --nodes continuum:e2a8… --yes
+# version 2 on 1:
+# 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
```
-Each recipe is a `jq` filter on that file; then propose the result, and vote.
+The other parties vote as on any proposal (`continuum-party vote 8d02 yes`).
## Letting a party in
-Name its keys and its node list anew, `since` the new version's number:
-
-```sh
-jq --arg key "$(cut -d' ' -f1,2 makefu.key.pub)" --arg node continuum:e2a8… '
- .keys.makefu = {since: .number, keys: [$key]}
- | .nodes.makefu = {since: .number, nodes: [$node]}' next.json
-```
-
-A party let in without nodes has an empty list (`nodes: []`) and writes through any node
-that takes its events. It begins its record before it votes: from the root, as it never
-voted ([`proposing-and-voting.md`](proposing-and-voting.md),
+`propose admit PARTY --keys KEY… [--nodes NODE…]`: its keys, each an `authorized_keys`
+line as one argument or a file of them (`makefu.key.pub`), and its node list, by node ID,
+named anew, `since` the new version's number. A party let in without nodes has an empty
+list and writes through any node that takes its events. It begins its record before it
+votes: from the root, as it never voted
+([`proposing-and-voting.md`](proposing-and-voting.md),
[Voting](proposing-and-voting.md#voting)).
## Taking a party out
-Leave out its keys and its node list, and the rules giving it places:
-
-```sh
-jq 'del(.keys.lass, .nodes.lass) | .rules |= map(select(.writer != "lass"))' next.json
-```
-
+`propose remove PARTY`: its keys and node list left out, and the rules giving it places.
What it wrote counts no more, nor its key set and node list: its nodes are members no
more. To come back, the parties let it in anew.
## Giving a place, taking it back
A place goes to a party by a rule before any other that matches its path; the first
-match decides:
+match decides. `propose give PATH PARTY` adds that rule first, and drops one of the same
+path that came before:
```sh
-jq '.rules = [{path: "names/r/wiki", writer: "lass"}] + .rules' next.json
+continuum-party propose give names/r/wiki lass
```
-To give it to another, change the rule's writer; to take it back, remove the rule or
-make its writer `false`. What the former writer signed there counts no more; given back
-later, it shows again, unless something replaced it or a checkpoint left it out.
+`propose take PATH` gives the places the path matches to nobody: it drops the rule of
+that path, and where another rule still gives one of them, adds a rule giving them to
+nobody (`"writer": false`) first. What the former writer signed there counts no more;
+given back later, it shows again, unless something replaced it or a checkpoint left it
+out.
## Zones and blocks
-A rule a party holds by its name gives it a zone without a vote for each name in it:
+A rule a party holds by its name gives it a zone without a vote for each name in it, a
+rule for the name and one for what lies under it:
```sh
-jq '.rules += [{path: "names/r/{party}", writer: "{party}"},
- {path: "names/r/{party}/**", writer: "{party}"}]' next.json
+continuum-party propose give 'names/r/{party}' '{party}'
+continuum-party propose give 'names/r/{party}/**' '{party}'
```
and a block of addresses by its parts, to one party:
```sh
-jq '.rules += [{path: "ip4/10/243/7/*", writer: "tv"}]' next.json
+continuum-party propose give 'ip4/10/243/7/*' tv
```
Then a new host in the zone or the block is a write, no vote
-([`designing-rules.md`](designing-rules.md)).
+([`designing-rules.md`](designing-rules.md)). Each `propose` is a version of its own:
+the second of two proposed at once lapses when the first passes, so propose the next once
+one passed, or write both rules in one version by hand ([By hand](#by-hand)).
-## Keys named anew
+## Keys and node lists named anew
A party that lost a key its version names, or had one stolen, gets its keys named anew
(`since` the new number); every key set it wrote before counts no more, and it writes its
set again ([`keys.md`](keys.md)):
```sh
-jq --arg key "$(cut -d' ' -f1,2 tv-new.key.pub)" '
- .keys.tv = {since: .number, keys: [$key]}' next.json
+continuum-party propose keys tv tv-new.key.pub
```
+`propose nodes PARTY NODE…` names a party's node list anew, likewise: where it can't
+write its own.
+
+## By hand
+
+Anything else, or several changes in one version, is written by hand from the next
+version, the current one with the next number, its hash as `changes`, and no
+`checkpoint`:
+
+```sh
+continuum-party next > next.json
+```
+
+or from what a command above would propose, `--print` writing it instead:
+
+```sh
+continuum-party propose give 'names/r/{party}' '{party}' --print > next.json
+jq '.rules = [{path: "names/r/{party}/**", writer: "{party}"}] + .rules' next.json \
+ > both.json
+continuum-party propose both.json
+```
+
+What each field holds is in [`proposing-and-voting.md`](proposing-and-voting.md),
+[Writing a version](proposing-and-voting.md#writing-a-version).
+
## What a party does by itself
* **Its node list**, signed with a key its version names, no vote: the list as it counts
@@ -111,7 +141,12 @@ jq --arg key "$(cut -d' ' -f1,2 tv-new.key.pub)" '
## Moving to a checkpoint
-A version that only moves the store on changes nothing else: the next version, with
-`checkpoint` set to the heads ([`checkpoints.md`](checkpoints.md)). Keep other changes
-out of it: a node voting by itself backs no version naming a checkpoint that changes
-more.
+`propose checkpoint`: a version that only moves the store on, to a checkpoint at the
+heads the node shows ([`checkpoints.md`](checkpoints.md)). Keep other changes out of it:
+a node voting by itself backs no version naming a checkpoint that changes more.
+
+## Moving to a revision
+
+`propose revision FEATURE`: the next version, following the revision that adds the
+feature, once every party's nodes run a continuum that knows it
+([`upgrades.md`](upgrades.md), [Moving to a revision](upgrades.md#moving-to-a-revision)).
diff --git a/docs/guides/federation/proposing-and-voting.md b/docs/guides/federation/proposing-and-voting.md
index d8410f6..b58a926 100644
--- a/docs/guides/federation/proposing-and-voting.md
+++ b/docs/guides/federation/proposing-and-voting.md
@@ -10,8 +10,15 @@ its key set are its own to write, without a vote
## Writing a version
-A version is the whole policy, not a change to it. Begin from the current one, as a node
-shows it, with `number` and `changes` set and its `checkpoint` left out, as below:
+The changes made most have a command each, which writes the version from the current
+one and proposes it: `propose admit`, `remove`, `give`, `take`, `keys`, `nodes`,
+`checkpoint` and `revision` ([`common-changes.md`](common-changes.md)). With `--print`,
+each writes the version to standard output instead, to change further and propose as a
+file.
+
+A version is the whole policy, not a change to it. To write one by hand, begin from the
+current one, as a node shows it, with `number` and `changes` set and its `checkpoint`
+left out, as below:
```sh
continuum-party --node http://tv:secret@localhost:3000 next > next.json
@@ -55,13 +62,19 @@ drop it ([`when-things-go-wrong.md`](when-things-go-wrong.md),
```sh
continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
propose next.json
+# version 4 on 3:
+# adds rule 1: names/r/wiki -> lass
+# Propose it? [y/N] y
# c41e… taken
# proposal 8d02…
```
-With `--yes`, the client votes `true` on it too, as `vote 8d02… yes` does
-([Voting](#voting), below): a party whose node votes for it by itself votes through that
-node instead.
+The client says what the version does to the current one, as `show` says it of a
+proposal ([Following a vote](#following-a-vote)), and asks before it signs, where its
+input and its errors are a terminal; asked nothing, as in a script, it goes on. It
+proposes nothing that changes the current version only by its number. With `--yes`, it
+votes `true` on it too, as `vote 8d02… yes` does ([Voting](#voting), below), asking once
+for both: a party whose node votes for it by itself votes through that node instead.
The client proposes only a version it would back: one changing the current one as a
version must (its `number`, `changes`, and each `since`), whose checkpoint, where it names