Powers and Boundaries
Powers let a credential act on the other members of its realm, and the realm tree decides what may pass between realms.
Available Powers
A power lets the holder of a credential act on other members of its realm, for example to block a machine or read its telemetry. A credential grants only the powers it names.
| Power | Lets its holder | Used through |
|---|---|---|
telemetry | Ask another member for its status, routes and counters | A Telemetry order |
subnets | Read or change the networks that another member routes for the realm | A Subnets order |
block | Block a member of its realm so that every member refuses it, and lift a block | A block in the realm's knowledge |
taint | Read or change another member's taints while it runs | A Taints order |
all | Every power, including any that a later release adds | — |
Every power stays inside one realm. An order goes only to a member of the same realm, and the realm's knowledge never leaves the realm.
Narrowing Down a Chain
A credential chain grants only the powers that every link on it grants. If a realm was delegated without a power, nothing in that realm or beneath it can grant that power.
A realm delegated all also holds any power that a later release adds.
The middle delegation withholds block, so nothing beneath it can hold block, however its credential is signed. The anchor's credential names telemetry and block, but the anchor holds only telemetry. Every sub-realm delegation that a guardian signs carries all four powers. A delegation that withholds a power can only be made without a guardian.
The two kinds of credential have different defaults:
- An anchor credential grants nothing unless it names powers. Most machines should hold no power, so that an ordinary member cannot act on any other.
- A delegation grants every power unless it names fewer. A delegation gives a realm the right to run itself.
Holding Powers
On a sovereign network, machines never hold a power. The powers belong to the guardian's root node, the guardian's own anchor in each realm. The console calls it the admin node.
Every sub-realm delegation carries all four powers. Controls stop at the realm boundary, so the guardian runs one root node in every realm.
- The root node always holds
telemetry, so the guardian can collect telemetry from any machine in the realm. - For each block, taint move or change to a router's networks, the root node is lent
block,taintorsubnetsfor ten minutes. - The root node holds no key of its own. The guardian's signer signs every credential with the realm's key. That key stays sealed in the guardian, and is unsealed only for one signature.
On the instance VeilNet hosts, no machine's credential carries a power.
Permissions Between Realms
Five permissions apply between realms: connecting, carrying traffic, collecting telemetry, blocking and exchanging data. Each has its own rule. A realm here means its whole line of descent from the root. If one key is delegated realms on two branches, those are two realms.
| Permission | Same realm | Above, to a realm below | Below, to a realm above | Another branch |
|---|---|---|---|---|
| Connect | Yes | Yes | Yes | No |
| Serve: carry a circuit | Yes | Yes | No | No |
| Collect telemetry | With telemetry | No | No | No |
| Block | With block | No | No | No |
| Exchange data | Yes | No | No | No |
A realm above may connect to every realm beneath it, at any depth, and carry its traffic. That traffic is encrypted end to end, so the realm above cannot read it or send data of its own. Data, blocks and telemetry stay inside one realm, and sibling realms never meet.
The table follows from these rules:
- A realm serves the realms beneath it. It carries traffic for realms below it at any depth, but none of them carries traffic for it.
- Connecting works in both directions. A realm above can only carry traffic for a realm below if the two can connect, and the realm below dials.
- Data stays in one realm. A realm above carries its descendants' traffic, but cannot read it or send them data. This also lets two realms reuse one address range.
- Blocking and telemetry stay in one realm too. A realm above cannot block a realm below or collect its telemetry.
- Sibling realms never meet. Realms on different branches cannot connect, carry traffic for each other or exchange data, at any depth.
- Telemetry describes only the anchor itself. A report gives its uptime, the number of peers it knows, its connections, reachability, MTU, counters and route table. It never includes the anchor's peers, its events or the traffic it carries.
Enforcing the Rules
Each rule is checked at a different point:
| Rule | Checked |
|---|---|
| Connect | Right after the handshake, and for as long as the connection lasts. If a delegation between the two anchors lapses, the connection closes |
| Exchange data | At both ends, before sending and on receipt |
| Block | Where the block is issued, and again on every member that receives it |
| Collect | At the anchor that receives the telemetry order |
| Serve | At the relay, against the anchor that opened the relayed route |
A relay may carry traffic that its destination then refuses. The result is the same as if the relay had refused it.
A peer's realm counts only once it is proved, by a direct connection or by the peer's credential chain. Gossip alone proves nothing. An anchor whose realm is not yet known is refused data.
Checking Permissions
In sudo conflux peers, the DATA column combines the data rule and the taint rule. A peer in a realm above or below this one may connect and relay, but it shows DATA no.
A refusal under these rules is a deliberate answer, not a fault. For example, ask a member for its telemetry from a machine whose credential carries no power:
$ sudo conflux anchorctl telemetry -from anchor6btpa3gn6w4stipba4hekzho7caw6srfyy5puvbz7mfanaiept5a
You should see PERMISSION_DENIED. The message names the rule that refused the request and the end that applied it. A retry gets the same answer.
Commands that name a member take its full 58-character AnchorID, as sudo conflux status prints it on that machine. The ten-character form that peers shows does not work.