From ae0e570322f1b485da76c39da8218aef475f8a15 Mon Sep 17 00:00:00 2001 From: tv Date: Tue, 17 Nov 2026 13:48:36 +0000 Subject: guides: what a federation promises Who a party and the adversary are, the three promises in plain words, what isn't promised, and what that asks of a party, an operator and an application. --- docs/guides/federation/README.md | 2 ++ docs/guides/federation/promises.md | 61 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+) create mode 100644 docs/guides/federation/promises.md (limited to 'docs/guides') diff --git a/docs/guides/federation/README.md b/docs/guides/federation/README.md index eda5c4c..ccc0647 100644 --- a/docs/guides/federation/README.md +++ b/docs/guides/federation/README.md @@ -20,3 +20,5 @@ by them, in its words. that voted twice, choosing a side, and a node doing less than it should. * [`forking-and-following.md`](forking-and-following.md): when to fork, making and checking a fork, and following one. +* [`promises.md`](promises.md): what holds whatever the parties do, what doesn't, and + what that asks of a party, an operator and an application. diff --git a/docs/guides/federation/promises.md b/docs/guides/federation/promises.md new file mode 100644 index 0000000..3c9a257 --- /dev/null +++ b/docs/guides/federation/promises.md @@ -0,0 +1,61 @@ +# What a federation promises + +A federated swarm is kept by parties that don't trust each other. This guide says, in +plain words, what holds whatever any of them does, what doesn't, and what that asks of +a party, an operator and an application. The design says it precisely +([`federation.md`](../../federation.md), Parties and the adversary, What is promised). + +## Who is who + +A **party** is a name in the version, with its keys: whoever holds the keys is the +party, several people keeping one together or one person in several. Only parties +write and vote; others come in by the votes of those who are in. Any party may be +malicious, alone or with others. + +An adversary may run nodes (once a party lists them), craft any event on any +dependencies, show different events to different nodes, withhold events, delay or drop +messages, and steal a party's key. It can't forge a signature, nor make two events with +one ID. + +Nothing is kept from being read: every party reads all of it. Nor is it hidden who talks +to whom. A party whose machine is taken over whole is the adversary from then on. + +## What holds + +1. **What counts is what a party signed, with a key it holds, where the version lets it + write.** Every honest node refuses anything else, whoever brings it, judged at the + event's history; a node checks every event back to its checkpoint, which it built or + its operator pinned. +2. **The version changes only by two thirds of its parties' votes**, as one history saw + them, and nodes holding the same events read the same version. Without a party + voting twice, a version that passed stays, on every node. +3. **Any group carries on as it chooses**, by a fork, and whoever wants follows. Nobody + is held by parties it doesn't follow. + +## What doesn't + +* **Progress**: if the parties don't cooperate, nothing passes; those who do, fork. +* **Good votes**: a party may vote badly; a `true` binds it while its proposal can + pass. +* **Delivery**: what a party's nodes withhold reaches nobody through them. +* **Speed and uptime**: a party that floods the store, or keeps remakes from committing, + makes nodes slow or runs them out of memory, never wrong. The others fork away from it. +* **One swarm where keys voted twice**: each node keeps the version it took, and nodes + part, until their operators choose ([`when-things-go-wrong.md`](when-things-go-wrong.md)). +* **Writes from before a move**: what isn't above a checkpoint's heads is refused once + nodes moved there; its party signs it again ([`checkpoints.md`](checkpoints.md)). +* **A joining node's view**: a node joining from the root of a federation that never + passed a checkpoint, whose seeds are all the adversary's, may be shown a chain that + old keys grew; a checkpoint or a fork's root a node takes on its operator's word is + only as good as that word. + +## What it asks of you + +* **A party**: keep the keys a version names apart, and keep its record + ([`keys.md`](keys.md), [`proposing-and-voting.md`](proposing-and-voting.md)); vote + from one client; back only what you mean to, as a `true` binds. +* **An operator**: give your node seeds you trust, pin checkpoints you got from nodes you + trust, and keep its store file ([`running-a-node.md`](running-a-node.md)). +* **An application**: read from a node you trust, as what it answers is its word; check + the events yourself where that matters + ([`writing-and-reading.md`](writing-and-reading.md), Reading). -- cgit v1.3.1