# 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`](running-a-node.md)). The words are the design's ([`federation.md`](../../federation.md)). ## Building ```sh 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`](../../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.md), Keys in an ssh-agent): ```sh 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. ```sh 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: ```json { "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 ```sh 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: ```sh 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`](proposing-and-voting.md)). ## Starting tv's node starts the federation from the root: ```sh 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): ```sh 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: ```sh 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`](../../configuration.md), The party's client): `continuum-party --config tv.toml write …`. lass reads it on its node, with everything else that counts: ```sh 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. ```sh 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`](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: ```sh 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: ```json { "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: ```sh 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: ```sh 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`](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`](writing-and-reading.md): places, values, and why a write counts or doesn't. * [`proposing-and-voting.md`](proposing-and-voting.md): writing a version, proposing it, and voting.