aboutsummaryrefslogtreecommitdiffstats

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