# Running a node of a federation A node of a federated swarm runs as any continuum node: its node key, its state and document files, its transports, a supervisor ([`operations.md`](../../operations.md)). This guide says what is otherwise: the options of a swarm holding a store, who syncs, what its API lets in, and joining. ## Its options * `--store-root FILE` starts the swarm from its root, or goes on with it: the file the founders made (`continuum-party root`), the root on its first line and, for a fork, the events the root keeps, a line each. The node builds the changes founding the swarm from it, as every node given the file builds them, and is ready at once. * `--store-id ID` joins the swarm by its ID, the root's SHA-256, through `--seeds`. Joining with an empty document, the node takes as its root that store's genesis change only. * `--store-party NAME`, which both need: the party the node is of, named in its entry and its handshakes. It is a member once that party's node list names it. * `--store-file PATH`: what is the node's own, written whenever it changes: the events it refused by what it took before (of two versions changing one, the second it judged) and those its operator had it drop. A node reads its store anew from its document whenever it starts: without the file, it may then take what it refused. Keep it beside the document file; one that doesn't read stops the node from starting. * `--store-checkpoint ID`: a checkpoint the node reads its store from whenever it starts, instead of from the document's checkpoint, by its ID (Joining, below). * `--store-neighbour-parties NAME,…`: parties among whose members, with its own party's, the node keeps some of its neighbours. * `--store-vote-key PATH` and the options with it: the node votes and proposes for its party by itself; its party then votes by hand only through it. What makes a new swarm's first change (`--genesis`, `--bootstrap-users`, `--bootstrap-keys`, `--bootstrap-policy`, `--remake`, `--genesis-root`) doesn't apply, nor a swarm key (`--swarm-key-file`, `--swarm-key-create`) nor `--protocol-writers`: the node refuses to start with them. ## Its files Beside those of every node ([`lifecycle.md`](../../lifecycle.md), What the files are for), the store file. Back up the node key, as every node's: its node ID is what its party lists, and a new key is a new node, which the party lists anew. The document file and the store file go together: the store file says what the node refuses of what the document holds. ## Who syncs The members are the nodes the parties' node lists name, as the current version reads them, each as its party's; nodes sync with members only. There is no swarm key: the parties say who syncs. A node its party doesn't list syncs with nobody, and says so in its log (`This node isn't a member of its store`); once it is listed, the others sync with it (`This node is a member of its store`). A party that takes a node off its list takes it out of the swarm. Of a node's neighbours (`--neighbours`), some are kept among the members of its own party and of the parties in `--store-neighbour-parties`, by the graph among those alone, so that a party listing many nodes can't be all of a node's neighbours. ## Its API * **Who it lets in** is its own (`--htpasswd`, or a reverse proxy naming the user): there is no user registry, and every user it lets in may do everything at it: put events, read, have it drop what it took and take it back, vote through it, make a fork's root. A token is taken by the node that issued it only. Let in those who act for the node, and give a party without nodes of its own a user to put its events. * **The events** (`docs/openapi.yaml`, Events): `GET /events` (the store's ID, its checkpoint, its heads, how many events it took), `POST /events` (an event, whoever signed it), `GET /events/{id}`, `GET /events/counts` (what counts), `GET /events/refused` (what the store refused, and why), `POST /events/fork` (what the node finds of a fork's root); and its operator's: `POST /admin/events/drop`, `/admin/events/allow`, `/admin/events/vote`, `/admin/events/fork`. Each answers `404` while the node holds no store. * **The store API** (`/store`) reads the document, where events are bytes at `_continuum/events/`; what counts is read at `GET /events/counts`. A write through it is refused (`403`): the document takes events and each node's own protocol data only. ## Joining A node with an empty document joins by the store's ID (`--store-id`) through a member (`--seeds`), and holds its store once it has read the document: `GET /events` answers then. Once the store moved to a checkpoint, a node joining starts from that checkpoint, which its operator pins by its ID (`--store-checkpoint`): ask a node you trust for it (`checkpoint` in `GET /events`). The node finds it in its document, built from what the document holds as any node builds it, and holds no store until then (`The pinned checkpoint isn't in the document (yet)`). It takes no epoch whose snapshot holds a checkpoint it neither builds nor has pinned: from the root, it would take what was grown anew from it since, by keys of versions long replaced. A node that was away across a move to a checkpoint builds that checkpoint from its document, which holds what came before until a remake leaves it out; after such a remake, it takes the checkpoint only where its operator pins it. Pin it, and restart the node. ## What it writes by itself * **A version that passed**, as soon as it holds the votes passing it (`Writing a version that passed`): any node may write it, and the same version written by several is one. * **Events its document lacks**, that its store would take and that it has: after a remake, a rejoin, or a change of another node it refused (`Put again events the document lacked`). * **Its own protocol data**: its entry, its acks of remakes, and the remakes it coordinates. Remakes are compactions only, acked by the members ([`remakes.md`](../../remakes.md)). It refuses events as every node does, and some by what it took before: of two versions changing the one it reads, the second it judged (`Refused an event its history takes, by what this node took before: kept so`). `GET /events/refused` lists them apart (`own`): tell its party, which decides what the node keeps.