aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-17 13:52:13 +0000
committertv <tv@krebsco.de>2026-11-17 15:04:41 +0100
commitb4bc2251891677b471e34d72d1cb8ed32350fc48 (patch)
treed727f106abbd0003cd3d20833a9bf9abb0f0564e /docs/guides/federation
parent7b7c09b818a94be3d1493817d38404a1b208aa9e (diff)
guides: building on a federated swarm's API
Reading what counts and when to read again, writing through the party's client or as events of its own spelled and signed as the federation does, when a write counts, one writer at a place, keeping a namespace in step, and the store API refusing writes.
Diffstat (limited to 'docs/guides/federation')
-rw-r--r--docs/guides/federation/README.md2
-rw-r--r--docs/guides/federation/building-on-the-api.md89
2 files changed, 91 insertions, 0 deletions
diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md
index a4af7f7..1c8e049 100644
--- a/docs/guides/federation/README.md
+++ b/docs/guides/federation/README.md
@@ -34,3 +34,5 @@ by them, in its words.
federation's number says.
* [`watching.md`](watching.md): what a node's API and its log say that needs an operator
or a party.
+* [`building-on-the-api.md`](building-on-the-api.md): an application reading what
+ counts and writing as a party, through the client or with code of its own.
diff --git a/docs/guides/federation/building-on-the-api.md b/docs/guides/federation/building-on-the-api.md
new file mode 100644
index 0000000..9f144be
--- /dev/null
+++ b/docs/guides/federation/building-on-the-api.md
@@ -0,0 +1,89 @@
+# Building on the API
+
+An application on a federated swarm reads what counts at a node and writes as a party.
+This guide says how, through the client or with code of its own. The formats are the
+design's ([`federation.md`](../../federation.md), Events, The policy, What counts).
+
+## Reading
+
+`GET /events/counts` is what counts, as the node reads it now: the values at places
+(`values`), the current version and its rules, each party's keys and nodes, the members
+([`writing-and-reading.md`](writing-and-reading.md), Reading). There is no stream of what
+counts: read it again when the store's heads change (`heads` in `GET /events`).
+
+What a node answers is its word: it may be behind, and an application that must not take
+it on trust reads the events themselves (`GET /events/{id}`) and checks their signatures,
+or asks nodes of several parties.
+
+## Writing through the client
+
+The simplest is the party's client, a command per write:
+
+```sh
+continuum-party --node http://tv:secret@localhost:3000 --key laptop.key \
+ --record tv.record write home/tv/hosts/laptop '{"ip6": "42:0:a46e::1"}'
+```
+
+It signs on the heads the node shows, records what it signed, and puts it; `again` signs
+anew what a move to a checkpoint refused ([`writing-and-reading.md`](writing-and-reading.md),
+After a move).
+
+## Writing with code of its own
+
+An event is the JCS encoding (RFC 8785) of an object, its member names sorted as JCS
+sorts them:
+
+```json
+{ "deps": ["<ID>"], "key": "ssh-ed25519 AAAA…",
+ "party": "tv", "sig": "<signature>",
+ "write": { "path": "home/tv/hosts/laptop", "value": {"ip6": "42:0:a46e::1"} } }
+```
+
+* `deps`: the heads it read (`heads` in `GET /events`), each as 64 lower-case hex digits,
+ ascending, one at least.
+* `key`: the key it signs with, `ssh-ed25519`, a space, the base64 of its blob, no
+ comment; one of the party's keys.
+* `sig`: an SSH signature (`ssh-keygen -Y sign`, namespace `continuum-federation`, hashed
+ with `sha512`) over the JCS bytes of the object without `sig`: the SSHSIG blob, its
+ reserved field empty, in base64, unarmored.
+* The value is any JSON with integers only, from −2⁵³ to 2⁵³; the event up to 256 KiB.
+
+Put its bytes as they are:
+
+```sh
+curl -u tv:secret -X POST -H 'Content-Type: application/json' \
+ --data-binary @event.json localhost:3000/events
+# {"event":"taken","id":"0c7e…"}
+```
+
+Its ID is the SHA-256 of its bytes. A node takes no event that isn't byte for byte as
+the federation spells it; the vectors (`federation::vectors`) give events and their IDs
+to check code against.
+
+Keep what it signed: once the store moves to a checkpoint, a write signed on heads from
+before is refused (`it isn't above the checkpoint's heads`), and is to be signed again on
+the heads a node shows then.
+
+## When a write counts
+
+At the node it was put through, at once where it is `taken` and the latest its party
+signed at that place: `GET /events/counts` shows it. At another node, once that node holds
+it (`GET /events/{id}` answers `200` there), as both read the same from the same events.
+
+## One writer at a place
+
+Two writes of one party at one place, neither in the other's history, leave the one with
+the lower ID, whichever came last. Write each place from one client, on heads read just
+before; where two did, write again, after both.
+
+## Keeping a namespace in step
+
+To have a party's namespace hold what an application keeps elsewhere: read `values`,
+write each place whose value differs, and `null` at each place of the namespace that the
+application holds no value for any more. Write nothing where a place holds the value
+already: a write is an event every node keeps until a checkpoint leaves it out.
+
+## Not through the store API
+
+A node of a federated swarm refuses writes through the store API (`/store`): the document
+takes events and each node's own protocol data only.