aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation/promises.md
blob: 3c9a257b64d62a14115ed054184d1010b6d40e51 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
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).