From b7771be595b76cfa26540acda5234bdefa0c4e54 Mon Sep 17 00:00:00 2001 From: tv Date: Tue, 17 Nov 2026 13:04:22 +0000 Subject: guides: getting started with a federation `docs/guides/federation/` holds the guides to a federated swarm, the design saying what the rules are and they how to live by them. The first: two parties start a federation, a node each, write, read, and let a third party in by their votes. The README points to them. --- docs/guides/federation/README.md | 8 ++ docs/guides/federation/getting-started.md | 189 ++++++++++++++++++++++++++++++ 2 files changed, 197 insertions(+) create mode 100644 docs/guides/federation/README.md create mode 100644 docs/guides/federation/getting-started.md (limited to 'docs/guides') diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md new file mode 100644 index 0000000..5a6b227 --- /dev/null +++ b/docs/guides/federation/README.md @@ -0,0 +1,8 @@ +# Guides to a federated swarm + +How to start, run and use a swarm kept by parties that don't trust each other. The design +([`federation.md`](../../federation.md)) says what the rules are; these say how to live +by them, in its words. + +* [`getting-started.md`](getting-started.md): two parties start a federation, write, + read, and let a third one in. diff --git a/docs/guides/federation/getting-started.md b/docs/guides/federation/getting-started.md new file mode 100644 index 0000000..8ce4c19 --- /dev/null +++ b/docs/guides/federation/getting-started.md @@ -0,0 +1,189 @@ +# 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. The client reads an +OpenSSH Ed25519 key without a passphrase: + +```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…"],"store":"6d1e…","taken":0} +``` + +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. 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. -- cgit v1.3.1