Gossip Controls
Gossip controls let the members of a realm manage it themselves, with no central server.
Orders and Knowledge
Gossip controls are the realm's control plane. You use them to block a machine, move it between taints, change what a router serves or read a machine's telemetry. They come in two forms:
- An order goes from one member to one other member, encrypted end to end, and ends when it is answered. There are three orders: Telemetry, Subnets and Taints.
- The realm's knowledge is a set of signed advertisements that every member stores and passes on for as long as each one lasts. A block is part of the realm's knowledge, not an order.
| Control | Form | What it does | Power |
|---|---|---|---|
| Telemetry | Order | Asks one member for its status, routes and counters. Never its peers or its traffic | telemetry |
| Subnets | Order | Reads or changes the networks that one router serves. The router keeps the new list across restarts | subnets |
| Taints | Order, then knowledge | Moves one member to other taints. The member then publishes a record of the move | taint |
| Block and unblock | Knowledge | Makes every member refuse an anchor, or lifts the block | block |
- A member whose credential carries block signs a block that names the anchor.
- It hands the block to one member of each group, over connections it already has.
- Each of those members passes it on to the rest of its group, until every member has it.
- Every member now refuses the blocked anchor. Nothing is sent to it.
Choose a control to follow it. A block passes from member to member through the realm, and is never sent to the anchor it blocks. The three orders go end to end to one anchor, through members that relay them but cannot read them. The steps are paced for reading, not in real time.
Issuing Controls
To use a control, a member's credential must carry the matching power. An ordinary credential carries none.
Credentials from the instance VeilNet hosts carry no powers. On that instance, only you can act on your machine.
On a sovereign network, the guardian runs its own anchor in each realm, inside the guardian stack. This anchor is the root node, which the console calls the admin node. It issues the realm's controls: blocks with a reason and an optional end, taint moves, changes to a router's networks, and telemetry orders.
The admin node's standing credential carries only telemetry. For a block, a taint move or a change of networks, it is lent the one power it needs, for ten minutes and for that one action. Controls stop at the realm boundary, so there is one admin node in every realm.
When console control is turned off, an operator runs the commands below from a conflux machine, with a short-lived control credential. For the guardian's side, see Realm Control.
Orders
An order is an instruction from one member to one other member. The sender signs it and attaches its credential chain. The target checks the order itself, and trusts nothing about the members that carried it.
An order travels encrypted end to end, over an existing connection or along the relayed route that traffic would take. Relays of any realm can carry it but cannot read it. No new connection is opened for an order.
The target carries out the order only if the sender is in the same realm and holds the needed power, and the order names this target and has not expired. If the same order arrives again, the target returns the first result and does not carry it out twice.
An order expires when its sender stops waiting for an answer. A telemetry order waits 30 seconds by default. No order lives longer than ten minutes, or beyond the expiry of the sender's own credential.
Subnets and Taints orders work only on a member with a state directory, because the member saves the change there. A member without one refuses them.
| Ends in | Means | What to do |
|---|---|---|
| Refused: does not hold the capability | The sender's credential does not grant the power | Use a credential that carries it |
| Refused: not in the issuer's realm | The target is in another realm, including a realm above | Send it from a member of the target's own realm |
| No path to the order's target | There is no connection and no relayed route | Open a connection first with connect, or wait for a route |
| Went unanswered in its lifetime | No answer came in time, and the target will not carry the order out later | Try again, with a longer timeout if the route is slow |
The Realm's Knowledge
The realm's knowledge is a set of signed advertisements, each about one subject, usually an anchor. A block is one example. Every member stores each advertisement and passes it on, so no central server is needed.
Each member checks every advertisement itself, and trusts nothing about the member that passed it on. It accepts an advertisement only if the issuer is in the same realm and holds the needed power.
- An advertisement outlives its issuer's credential. It counts if the issuer's credential was valid when it was signed.
- A member refuses an advertisement signed more than ten minutes ahead of its own clock.
- Only the latest advertisement from each issuer about each subject counts. There is no history and no consensus round.
- An advertisement ends on every member at the time it states. A block with an end disappears everywhere at that moment.
- A deleted advertisement stays deleted. A member that was away cannot bring an old one back.
- A member with a state directory saves every advertisement and checks them again when it starts, so a block holds before any peer can reach it. Without a state directory, the member keeps them in memory only, and the anchor reports this when it starts.
Spreading Knowledge
A new advertisement spreads through the realm as a tree. The issuer splits the members it knows into up to eight groups and hands the advertisement to one member of each group. Each of those members does the same with its share, so every member receives it once, in a few rounds.
- Answers come back up the tree, so the issuer learns how many members it reached. The block command reports this count.
- A member that cannot be reached is still owed the advertisement, and receives it as soon as it is heard from again.
- Each hand-over takes the same route as an order, so relays from another realm can carry it but cannot read it.
Catching Up
Two members compare what they hold whenever they link up: on a new connection, a new relayed session, or when an anchor starts or reconnects. A member that missed an advertisement gets it this way. Members do not compare on a schedule.
Control Scope
Taints do not apply to control traffic. Orders and the realm's knowledge only need the two members to share a realm. A member stays reachable by its realm whatever its taints, including by the order that moves it.
Controls stop at the realm boundary. A realm above may carry a sub-realm's traffic, but it cannot send orders to its members, block them or ask them for telemetry. Each realm is run by its own members that hold its powers.
Inspecting Controls
On a conflux machine, run these commands as sudo conflux followed by the command. Give the full anchor… ID that sudo conflux status prints. Reading needs no power, and changing anything needs the matching power.
$ sudo conflux blocks ANCHOR BY SINCE UNTIL REASON ao6zcnoeaa cyhgl55pie 2026-09-12T09:03:38Z unblocked decommissioned $ sudo conflux events 14:02:11 blocked ao6zcnoeaa decommissioned
| Command | Does | Power |
|---|---|---|
telemetry -from ID [-timeout D] | Asks another member for its status | telemetry |
subnets -peer ID [-set A,B | -clear] | Reads, or replaces, the networks another member routes | subnets |
taints -peer ID [-set A,B] | Reads, or changes, another member's taints | taint |
block -target ID [-days N] [-reason TEXT] | Makes every member refuse an anchor | block |
unblock -target ID | Lifts a block | block |
blocks | Lists the blocks in force on this member | None |
| Metric | What it tells you |
|---|---|
anchor_orders_carried_out_total | Orders this anchor received and carried out, by kind |
anchor_orders_refused_total | Orders it refused, by reason, such as capability, realm, expired or no_dir. Alert on it, because a member sending orders it may not give appears here |
anchor_knowledge_published_total | Advertisements this anchor issued |
anchor_knowledge_learned_total | New advertisements it learned, by how: pushed or compared |
anchor_knowledge_refused_total | Advertisements it refused, by rule: capability, realm, skew, signature and others |
anchor_knowledge_held | Advertisements held, including the records that stop deleted ones from coming back |