Getting started
Two parties, tv and lass, start a federation, a node each; they write, read, and let a
third party, makefu, in by their votes. What a party signs goes through its client,
continuum-party; what a node does, through its options
(running-a-node.md). The words are the design's
(federation.md).
Building
cargo build --release --features mycelium,federation
That builds the node, continuum, and the party's client, continuum-party, in
target/release/. Any transport does (transports.md).
A key for each party
The version names each party's keys, and the party signs with them. A key is
ssh-ed25519 or ecdsa-sha2-nistp256. The client reads an OpenSSH private key file
without a passphrase, of an Ed25519 key, or signs through an ssh-agent holding the key
(keys.md, Keys in an ssh-agent):
ssh-keygen -t ed25519 -N '' -f tv.key
cut -d' ' -f1,2 tv.key.pub # ssh-ed25519 AAAA…: the key as a version names it
Here one key does everything a party signs.
A node for each party
Each node needs its node key, a user of its API, and its node ID, which the first
version names before the federation starts. A node makes its key with
--node-key-create and logs its ID before anything else (Node identity): start it so
once, with nothing of a swarm, and stop it.
printf '%s' 'secret' | argon2 "$(openssl rand -hex 16)" -id -e | sed 's/^/tv:/' > htpasswd
continuum --node-key-file node.key --node-key-create --htpasswd htpasswd --mycelium-enable
# INFO Created a new node key: this is a new node node_id=continuum:5be1…
The first version
The founders write the first version together, as a file:
{ "federation": 1, "number": 0, "changes": null,
"keys": { "tv": { "since": 0, "keys": ["ssh-ed25519 AAAA…"] },
"lass": { "since": 0, "keys": ["ssh-ed25519 AAAA…"] } },
"nodes": { "tv": { "since": 0, "nodes": ["continuum:5be1…"] },
"lass": { "since": 0, "nodes": ["continuum:9c07…"] } },
"rules": [ { "path": "home/{party}/**", "writer": "{party}" } ] }
Each party writes in its namespace (home/tv/…), and nowhere else: no other rule gives
a place. Every change of the version takes two thirds of its parties: of two, both.
The root
continuum-party root first.json > root
The federation's root, built byte for byte from the first version, and the file its
nodes start from. Each founder makes it from the same version and finds the same bytes.
The federation's ID is the root's SHA-256 (store in GET /events).
Records
A party's client keeps a record of its party's votes, and votes by it (--record). A
record begun at a node casts nothing on the version current then, as a vote sent before
may be held back somewhere; one begun from the root, by a party that never voted, casts
on every version, the first too:
continuum-party --record tv.record init tv --root root
Keep it: a party that loses its record casts nothing on the current version
(proposing-and-voting.md).
Starting
tv's node starts the federation from the root:
continuum --store-root root --store-party tv --store-file store.json \
--state-file state.json --document-file document --node-key-file node.key \
--htpasswd htpasswd --mycelium-enable
curl -s -u tv:secret localhost:3000/events
# {"checkpoint":"6d1e…","heads":["6d1e…"],"party":"tv","store":"6d1e…","taken":0,
# "votesByItself":false}
lass's node joins it by its ID, through tv's node, one of whose addresses it is given
(addresses in GET /admin/stats there):
continuum --store-id 6d1e… --store-party lass --store-file store.json \
--seeds mycelium:… --state-file state.json --document-file document \
--node-key-file node.key --htpasswd htpasswd --mycelium-enable
Nodes sync with the nodes the parties list, and with no others: both are in the first version.
Writing and reading
tv writes in its namespace, through its node:
continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
write home/tv/motd '"hello"'
# 3a9f… taken
The value is JSON. The client's options can go in a configuration file instead, as the
node's do (configuration.md, The party's client):
continuum-party --config tv.toml write ….
lass reads it on its node, with everything else that counts:
curl -s -u lass:secret localhost:3000/events/counts | jq .values
# {"home/tv/motd": "hello"}
lass can't write there: its node refuses it, as every node does.
continuum-party --node http://lass:secret@localhost:3000 --key lass.key \
--record lass.record write home/tv/motd '"mine"'
# Error: the node answers 422 Unprocessable Entity: {"error":"the store refuses it",
# "id":"…","why":"lass may not write at home/tv/motd"}
writing-and-reading.md has the rest.
Letting a party in
makefu makes its key and its node as the founders did, and begins its record from the 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 (.version.hash in GET /events/counts), makefu's keys and node
list named anew in it (since its number), and the founders' as they were:
{ "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; the node shows the proposal by its hash, the version's:
continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
propose second.json
curl -s -u tv:secret localhost:3000/events/counts | jq '.proposals | keys'
# ["8d02…"]
Both vote true, each through its own node:
continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
vote 8d02… yes
continuum-party --node http://lass:secret@localhost:3000 --key lass.key \
--record lass.record vote 8d02… yes
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
--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.
What next
running-a-node.md: a node's options and files, and what it does otherwise than in a swarm that isn't federated.writing-and-reading.md: places, values, and why a write counts or doesn't.proposing-and-voting.md: writing a version, proposing it, and voting.
