aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/common-changes.md
blob: 8a31080a02a24436843931c1f0877488d0f348b6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
# Common changes

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)).

## How

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 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
```

The other parties vote as on any proposal (`continuum-party vote 8d02 yes`).

## Letting a party in

`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

`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. `propose give PATH PARTY` adds that rule first, and drops one of the same
path that came before:

```sh
continuum-party propose give names/r/wiki lass
```

`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 for the name and one for what lies under it:

```sh
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
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)). 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 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
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
  at the node with nodes added (`--add`) or taken off (`--remove`), or set whole
  (`--set`); `nodes` alone shows it:

  ```sh
  continuum-party --node http://tv:secret@localhost:3000 --key tv.key \
    --record tv.record nodes --add continuum:77d0…
  # tv's node list: continuum:5be1… continuum:77d0…
  # 9b2c… taken
  ```

  A list left empty, taking all of the party's nodes out of the swarm, is written with
  `--force` only. The client checks first that the current version names the key it
  signs with for the party, and says otherwise: then only a version naming the party's keys or its list
  anew changes it, which a party proposes and the parties pass. 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

`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)).