Realms and Delegation

Realms and Credentials

A realm is defined by its root key, the key that signs its credentials. A realm needs no other configuration, and no secret is shared anywhere.

Realms form a tree, and every member pins the identifier of the root of the tree. Members derive everything they must agree on from that one identifier, such as the address space and the tags that stand for taints.

A credential grants membership. It is a statement, signed by a realm's root key, that names a subject and an expiry date. There are two kinds of credential:

An anchor belongs to the realm that issued its anchor credential. Credentials have no name field, and there is no registry of realms.

An anchor presents its whole credential chain to every peer. The peer checks each link from the pinned root down, and refuses the chain at the first link that fails. See Checking a Chain.

Unlike a blockchain, the tree has no ledger, consensus or history. Every link is an ML-DSA signature. A peer verifies each link once, and remembers it until it expires.

Credentials expire and are renewed as follows:

• Every credential has an expiry date, which its signer chooses. A credential with no expiry is refused.
• To renew a credential, the issuer signs a new one. If it arrives before the old one lapses, a running anchor adopts it without dropping a session.
• A renewal keeps the anchor in the same realm, with the same taints, the labels that set its compartments. To move an anchor to another realm, restart it in that realm. To change its compartments, send a Taints order. See Taints.

Delegation

Delegation lets a realm hand part of the tree to another key. The realm signs a delegation for that key with its root key. The new realm then admits its own anchors and, if its delegation allows it, delegates again.

On a sovereign network, your organisation's realm delegates a sub-realm for each site or team in this way. Every sub-realm your guardian creates sits directly beneath your organisation's realm.

The depth limit

Every delegation carries a signed depth limit:

• At 0, the realm may admit anchors but may not delegate further.
• At 1, it may create sub-realms that cannot delegate further themselves.

The limit defaults to 0, so a delegation never allows more levels unless you choose it. Whatever the limits, a chain can have at most eight links.

The depth limit is the only signed limit on how far a branch can grow, so choose it with care. Expiry does not limit a branch, as Lapsed Delegations explains.

On a sovereign network, the depth limit in your realm credential decides whether sub-realms can exist at all. At 0, every machine is a member of your organisation's realm itself.

Narrowing powers

Powers are rights over the other members of a realm, such as the right to block one. A delegation grants every power unless it names fewer. A chain grants only the powers that every link on it grants. A power left out of a delegation is therefore withheld from the whole subtree beneath it.

Every sub-realm delegation that your guardian signs carries all four powers. See Powers and Boundaries.

Lapsed Delegations

A lapsed delegation revokes nothing. It cuts the tree at that edge, and the realm beneath carries on as a tree of its own:

• Its anchors keep connecting, relaying for each other and exchanging data within each realm.
• Its root key keeps admitting anchors, and can still delegate within its own depth limit.
• It keeps its addresses and tags, because they come from the root of the tree.

The realm beneath the cut loses contact with everything above it, in both directions. As soon as the delegation expires, each anchor below the cut closes every connection across it.

Multiple cuts

When two delegations on one line of descent lapse, the tree splits into three groups. No traffic crosses a cut. Whether two anchors can connect depends only on the delegations between their two realms.

Two anchors in one realm are therefore never refused, whatever happens above them. An anchor that has adopted a renewed delegation also stays connected to neighbours that have not adopted it yet. A renewal therefore never splits a subtree while it spreads.

A realm above cannot shut down a realm it delegated. Withholding a renewal separates the branch, but its anchors keep working until their own credentials expire.

Renewing Delegations

A renewal replaces one link in the chain and reissues nothing beneath it. It therefore costs one signature, however many anchors the branch holds.

Renewed delegations spread between peers on traffic that is already flowing. Each anchor checks a renewal against what it already holds, so it can accept one from any peer.

• An anchor adopts a delegation only for an edge above its own realm, and only if the delegation was issued later than the one it holds. Because the issue time decides, a root can move an expiry date earlier as well as later.
• Renew a delegation before it lapses. A renewal that arrives later rejoins the tree, but the connections across the cut have already closed.

On a sovereign network, your guardian renews every delegation beneath your organisation's realm, and every machine's credential, on its own schedule. If your organisation's own realm credential lapses, the cut falls above your realm, and nothing inside your tree stops.

Renewal and Cut Events

Every anchor that a renewal, a cut or a rejoin affects records an event. To watch for these events, run:

$ sudo conflux anchorctl events
11:07:10  realm-cred-changed             realm credential renewed with 719h58m0s still to run, valid until 2026-10-19T11:07:02Z

sudo conflux status shows the machine's own credential and its expiry. A cut above the machine leaves that credential valid and the machine working, so the credential alone does not show a cut. Watch for the events instead.