aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-17 13:48:36 +0000
committertv <tv@krebsco.de>2026-11-17 15:04:05 +0100
commitae0e570322f1b485da76c39da8218aef475f8a15 (patch)
treeb9fd42e20e4d09a8e29ef4cd7b448e84c2c8f7cc /docs/guides
parentcf223ca8139e2652edb5c2cd976d97f5868b243f (diff)
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.
Diffstat (limited to 'docs/guides')
-rw-r--r--docs/guides/federation/README.md2
-rw-r--r--docs/guides/federation/promises.md61
2 files changed, 63 insertions, 0 deletions
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).