aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides
diff options
context:
space:
mode:
Diffstat (limited to 'docs/guides')
-rw-r--r--docs/guides/federation/README.md2
-rw-r--r--docs/guides/federation/common-changes.md109
2 files changed, 111 insertions, 0 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md
index ccc0647..6a0cd1e 100644
--- a/docs/guides/federation/README.md
+++ b/docs/guides/federation/README.md
@@ -22,3 +22,5 @@ by them, in its words.
checking a fork, and following one.
* [`promises.md`](promises.md): what holds whatever the parties do, what doesn't, and
what that asks of a party, an operator and an application.
+* [`common-changes.md`](common-changes.md): the next version, and recipes for letting a
+ party in, taking one out, giving places, zones and blocks, and keys named anew.
diff --git a/docs/guides/federation/common-changes.md b/docs/guides/federation/common-changes.md
new file mode 100644
index 0000000..2e5861e
--- /dev/null
+++ b/docs/guides/federation/common-changes.md
@@ -0,0 +1,109 @@
+# 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 rules are the design's ([`federation.md`](../../federation.md), The policy,
+Keys, Nodes).
+
+## The next version
+
+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):
+
+```sh
+curl -s -u tv:secret localhost:3000/events/counts |
+ jq '.version as $v | $v.version | .number += 1 | .changes = $v.hash | del(.checkpoint)' \
+ > next.json
+```
+
+Each recipe is a `jq` filter on that file; then propose the result, and vote.
+
+## 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), 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
+```
+
+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:
+
+```sh
+jq '.rules = [{path: "names/r/wiki", writer: "lass"}] + .rules' next.json
+```
+
+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.
+
+## Zones and blocks
+
+A rule a party holds by its name gives it a zone without a vote for each name in it:
+
+```sh
+jq '.rules += [{path: "names/r/{party}", writer: "{party}"},
+ {path: "names/r/{party}/**", writer: "{party}"}]' next.json
+```
+
+and a block of addresses by its parts, to one party:
+
+```sh
+jq '.rules += [{path: "ip4/10/243/7/*", writer: "tv"}]' next.json
+```
+
+Then a new host in the zone or the block is a write, no vote
+([`designing-rules.md`](designing-rules.md)).
+
+## Keys 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
+```
+
+## What a party does by itself
+
+* **Its node list**, signed with a key its version names, no vote:
+
+ ```sh
+ continuum-party --node http://tv:secret@localhost:3000 --key tv.key \
+ --record tv.record nodes continuum:5be1… continuum:77d0…
+ ```
+
+ A version names a party's list anew only where it must: when the party is let in, or
+ when it can't write its own.
+* **Its key set**, likewise ([`keys.md`](keys.md)).
+* **Its writes**, wherever the rules give it places
+ ([`writing-and-reading.md`](writing-and-reading.md)).
+
+## 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.