From c0b1835d226db63a1504b3c751b30d0f6369e4ad Mon Sep 17 00:00:00 2001 From: tv Date: Tue, 17 Nov 2026 13:49:12 +0000 Subject: guides: common changes to a federation's version The next version begun from the current one, and recipes as jq filters for letting a party in, taking one out, giving and taking back a place, zones and blocks, and keys named anew; what a party changes by itself; and a version that only moves the store on. --- docs/guides/federation/README.md | 2 + docs/guides/federation/common-changes.md | 109 +++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 docs/guides/federation/common-changes.md (limited to 'docs/guides/federation') 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. -- cgit v1.3.1