# 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)). Bash completes the client's commands, proposals and parties with `share/bash-completion/completions/continuum-party` ([`configuration.md`](../../configuration.md), [The party's client](../../configuration.md#the-partys-client)). ## 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](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. `continuum node-id` makes the key and says the ID, without starting the node: ```sh continuum node-id --create node.key # a new node key in node.key: a new node # continuum:5be1… printf '%s' 'secret' | argon2 "$(openssl rand -hex 16)" -id -e | sed 's/^/tv:/' > htpasswd ``` ## The first version The founders agree on the first version, as a file. `continuum-party found` writes it from each party's keys (`PARTY=` an `authorized_keys` line, or a file of them), its node list, and the rules in order (`--rule PATH=WRITER`), each party writing in its namespace where no rule is given: ```sh continuum-party found tv=tv.key.pub lass=lass.key.pub \ --nodes tv=continuum:5be1… --nodes lass=continuum:9c07… > first.json ``` ```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. `--revision FEATURE` starts it on a later revision of the federation ([`upgrades.md`](upgrades.md)). ## 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. A party lists another node of its own by itself, without a vote ([`common-changes.md`](common-changes.md#what-a-party-does-by-itself)). ## 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, and a federation's directory keeps them, with the record, so that a party names them once, when it begins its record (`init --federation NAME`), and never again ([`configuration.md`](../../configuration.md), [The party's client](../../configuration.md#the-partys-client)). lass reads it on its node, with everything else that counts: ```sh continuum-party --node http://lass:secret@localhost:3000 get home/tv/motd -r # hello continuum-party --node http://lass:secret@localhost:3000 get 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 ``` One of the founders proposes the version letting makefu in, with makefu's key and node, and votes `true` on it (`--yes`). The client writes it from the current one, says what it does and asks, and says the proposal's hash, the version's: ```sh continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \ propose admit makefu --keys makefu.key.pub --nodes continuum:e2a8… --yes # version 1 on 0: # 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 looks at it, and votes `true` too, through its own node, naming the proposal by a prefix of its hash: ```sh continuum-party --node http://lass:secret@localhost:3000 --key lass.key \ --record lass.record vote 8d02 yes # 8d02…: can still pass, 1 more `true` passing it (2 of 2); true: tv; false: nobody # proposed by tv: version 1 on 0 # lets makefu in: 1 key (ssh-ed25519 SHA256:2kq…); 1 node (continuum:e2a8…) # Vote `true` on 8d02…? [y/N] y ``` Once a node holds both votes, it writes the version, and every node takes it: `continuum-party status` says version 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.