Swarm Authority

Source

This page reflects spec/schemas/chio-swarm/v1/authority-verifier-report.schema.json and spec/PROTOCOL.md section 6.4.2 in the chio repository. The Swarm Protocol reference carries the full set of artifacts and the verification order.

One entry point, no state

chio-swarm-authority exports one verification function. It holds no state, performs no I/O, and reads no clock: every fact it checks comes from the bundle it was handed or from the key slice the caller passed, and the current time arrives as the bundle field now_unix_ms.

pub fn verify_swarm_authority_bundle(
    bundle: &SwarmAuthorityBundle,
    trusted_witness_issuer_keys: &[PublicKey],
) -> Result<SwarmAuthorityVerifierReport, SwarmAuthorityError> {

Verification is all or nothing. Either the whole bundle verifies and the function returns a report whose verdict is the literal string verified, or it returns SwarmAuthorityError and there is no report at all. There is no partial verdict, no per-artifact error list, and no warning state. The rest of the crate’s public API is constructors: mint_*, sign_*, and the budget fan-out and fan-in helpers. Their only callers in the workspace are tests, in chio-swarm-authority, chio-runtime-core, and the CLI proof contract suite. This crate specifies verification; issuance stays with whoever operates the planner.

The bundle

SwarmAuthorityBundle is nine fields. Every type in the crate that crosses the wire carries deny_unknown_fields, down to the nested AttenuationWitness it borrows from chio-core-types, so a bundle with an extra key fails deserialization before the verifier sees it. The *MintRequest structs are plain Rust and are never deserialized.

Issuers are strings. An issuer prefixed did:chio: must be self-certifying: exactly 64 lowercase hex characters after the prefix, parsed as the Ed25519 public key that signed the artifact. A bare hex key is also accepted. Either way the key that comes out must appear in trusted_witness_issuer_keys, which is what makes the DID a pin rather than a name.

Closed vocabularies and one gate

Several fields accept a fixed set of values rather than free strings. These are the limits most likely to surprise someone minting a bundle from the schemas alone.

• A route-plan receipt’s egress_constraints must be non-empty, and every entry must be the literal deny-private-network. Any other value is unsupported swarm route-plan egress constraint. Its attenuation_decision must be the literal accepted.
• A route-plan receipt’s selected_route and egress_contract_id must each start with its own bridge_id followed by :, and protocol_target must start with the same id followed by ://.
• join_predicate must be all_success, any_success, or quorum:N with N between one and the expected parent count. A graph join needs at least two parents.
• A witness chain of more than one hop is rejected unless the signed graph sets multiHopWitnessChains. Multi-hop delegation is a per-graph gate carried inside the signed artifact, not a verifier default.
• The allocation a continuation names must be in state active, and the pool’s summed max_units may not exceed its total_units.

The order of checks

The entry point is a straight sequence of fallible calls. Order is load bearing, so it is worth reading literally. This is the whole body up to the point where the claim list is assembled:

require_trusted_witness_issuer_keys(trusted_witness_issuer_keys)?;
validate_task_graph(&bundle.task_graph, bundle.now_unix_ms)?;
verify_task_graph_signature(&bundle.task_graph, trusted_witness_issuer_keys)?;
require_signed_swarm_delegation_evidence(bundle)?;
let graph_sha256 = canonical_sha256(&bundle.task_graph)?;
let task_by_id = task_index(&bundle.task_graph)?;
let edge_set = edge_set(&bundle.task_graph.edges);
let route_by_id =
    validate_route_plan_receipts(bundle, &task_by_id, trusted_witness_issuer_keys)?;
let join_by_id = validate_join_receipts(bundle, &task_by_id, trusted_witness_issuer_keys)?;
let allocation_by_id = validate_budget_pool(bundle, &task_by_id)?;
validate_revocation_epoch(bundle, &task_by_id, trusted_witness_issuer_keys)?;
validate_terminal_graph_receipts(
    bundle,
    &task_by_id,
    &route_by_id,
    &join_by_id,
    &allocation_by_id,
    trusted_witness_issuer_keys,
)?;
validate_continuation_tokens(&ContinuationValidationContext {
    bundle,
    graph_sha256: &graph_sha256,
    task_by_id: &task_by_id,
    edge_set: &edge_set,
    route_by_id: &route_by_id,
    join_by_id: &join_by_id,
    allocation_by_id: &allocation_by_id,
    trusted_witness_issuer_keys,
})?;
validate_witness_chains(bundle, &task_by_id, &edge_set, trusted_witness_issuer_keys)?;

Trust comes first, so an unconfigured verifier stops before reading a single artifact. Graph structure and the graph signature come next, because every later check indexes into a graph that has already been proved acyclic, single-rooted, depth-consistent, and signed by a pinned issuer. Routes, joins, allocations, and the epoch are validated and indexed before continuations, because a continuation token names all four and its checks are lookups into those indexes. Witness chains run last, over the edge set, as a cover check.

Totality, not spot checks

Routes, joins, witness chains, and terminal receipts are checked in both directions: no declared reference may be unbacked, and no supplied artifact may be undeclared. That symmetry is what makes the bundle atomic. Continuation tokens are the one asymmetric family, noted below.

• Every route_plan_refs entry must have a receipt, and every receipt must match a ref. Duplicates are rejected on sight.
• Every graph join must have a receipt whose next_task_id equals the join’s, and whose expected-parent count equals the join’s parent count.
• Every edge must be covered by exactly one witness chain. A second chain over the same edge is a duplicate; an uncovered edge is missing swarm delegation witness chain.
• Every task with a parent must name a continuation token, and that token’s child_task_id must be the naming task. Token ids and nonces must be unique within the bundle. Each token binds either a parent_task_id or a join_receipt_id, never both and never neither.
• The reverse does not hold for continuations. validate_continuation_tokens walks tasks to find missing tokens, but never walks tokens to find unreferenced ones. A second, fully valid token for a child that already has one is accepted; it only inflates continuation_count in the report. Deciding which token a child may present is the caller’s job, and the runtime does it by naming one token id in the request.
• The terminal receipt’s completed-task set must equal the graph’s entire task set, its join set every join, its route set every route. A terminal receipt cannot close part of a graph.

Digests are recomputed, never trusted

Five digest fields are recomputed from the bundle’s own contents and compared, rather than accepted as declared.

The first row closes an obvious attack. A tampered graph invalidates both the graph signature and every token digest, and the two are computed over different bytes: the signature body drops the signature field, the token digest keeps it. Repairing one does not repair the other. swarm_authority_stage0_rejects_task_graph_tampering_after_continuations_are_resealed widens max_fanout, reseals every continuation against the new digest, and still lands on swarm task graph signature invalid.

Two refusals worth stating exactly

Claim: an unconfigured verifier verifies nothing

Claim: a root-only bundle is denied, not partially verified

A graph with one task and no edges is structurally valid. It is still rejected, and the reason is the shape of the report rather than the shape of the graph:

fn require_signed_swarm_delegation_evidence(
    bundle: &SwarmAuthorityBundle,
) -> Result<(), SwarmAuthorityError> {
    if bundle.continuation_tokens.is_empty() || bundle.witness_chains.is_empty() {
        return Err(rejected(
            "signed swarm delegation evidence missing: continuation tokens and witness chains are required",
        ));
    }
    Ok(())
}

The verified-claim list is assembled conditionally. Four of the eight claims are pushed only when their collection is non-empty, so a bundle with no continuations and no witness chains would otherwise return a report reading verified while silently carrying fewer claims than a reader expects. Denying the root-only case is what keeps verified from meaning two different things. swarm_authority_stage0_rejects_root_only_bundle_without_signed_swarm_evidence pins it. Downstream, both proof paths compare the report’s verified_claims against the required_claims in the verifier policy shipped with the bundle and fail when a required claim is missing, so a claim that quietly stopped being emitted fails there too. That list is per policy, not per crate: the recursive-delegation fixture requires seven of the eight swarm claims and omits claim.swarm.terminal_graph_receipt_bound. spec/registries/proof-manifest.v1.json registers all eight against test, fixture, and schema references; it is a registry checked for liveness, not the enforcement path.

Three consumers, one definition

The runtime path is pre-dispatch and trusted-input. It engages only for a request whose governed intent carries a chioSwarm context naming seven evidence references. chio-runtime-core loads the bundle from its own admission store by task-graph evidence id, overwrites now_unix_ms with the request clock, checks that each referenced evidence id and its canonical SHA-256 match the stored artifact, compares live route metadata against the route-plan receipt, calls the verifier, and only then consumes the continuation id. A verifier rejection becomes the denial code chio_swarm_authority_rejected, carrying the verifier’s own message as detail; an evidence id or hash that does not match the stored artifact becomes chio_swarm_authority_ref_mismatch instead. Consumption is conditional on the token’s mode: only single_use tokens are consumed, and a resumable token is presented again without replay accounting.

The proof paths are after the fact and untrusted-input. chio proof verify runs the swarm arm of its local family dispatch, and chio-proof-room calls the same function on an embedded bundle reconstructed from an evidence graph. Both resolve their key slice from CHIO_SWARM_TRUSTED_WITNESS_KEYS and neither adds a check the runtime has and the crate lacks: the reference hashing, the route-metadata comparison, and continuation consumption are all runtime-side. A fourth caller, chio-conformance’s r_t03_recursive_swarm_conformance, is a test. What the call sites share is that the definition of a valid delegation is one function, not three.

Run the verifier

The shipped fixture bundle exercises the whole order of checks: a four-task graph, three witness chains, three route plans, one join, one pool, one epoch. chio proof verify writes its report to stdout as one JSON object, so jq is the readable way to take the verdict and the claims out of it.

$ source scripts/proof-room-quickstart-env.sh
$ chio proof verify \
  fixtures/proof-room/swarm-authority/valid-recursive-delegation/transaction-passport.json \
  | jq '{verdict, passport_id, verified_claims}'

{
  "verdict": "verified",
  "passport_id": "passport-swarm-valid",
  "verified_claims": [
    "claim.swarm.task_graph_bound",
    "claim.swarm.continuation_fresh",
    "claim.swarm.attenuation_witness_chain_bound",
    "claim.swarm.route_plan_bound",
    "claim.swarm.join_receipt_bound",
    "claim.swarm.budget_pool_bound",
    "claim.swarm.revocation_epoch_bound",
    "claim.swarm.terminal_graph_receipt_bound"
  ]
}

Eight claims, one per artifact family the bundle carries. The full report also carries a per-hop hopReports array under family_reports, with attenuationVerified, routeVerified, budgetVerified, and lineageVerified per child task, plus the SHA-256 of the claim set, the evidence graph, and the verifier policy.

Point the same command at a sibling directory and the verifier refuses. The bundle at fixtures/proof-room/swarm-authority/revoked-task/ is signed and internally consistent; its epoch carries "revokedTaskIds":["task-child-a"] where the valid epoch carries an empty list. Its paired descriptor at negatives/revoked-task.json names the claim it targets, claim.swarm.revocation_epoch_bound.

$ source scripts/proof-room-quickstart-env.sh
$ chio proof verify \
  fixtures/proof-room/swarm-authority/revoked-task/transaction-passport.json

error [urn:chio:error:cli:other]: proof verify: swarm task is revoked: task-child-a
context: {"domain":"cli","severity":"error","stability":"deprecated","string_code":"CHIO-CLI-OTHER"}
suggested fix: Preserve the original message and migrate the call site to a specific registry code when touched.

No report is written. The verifier returns on the first failing check, so the seven claims that would have verified are not reported either, and the refusal names the task rather than the epoch. This is the shape every refusal on this rung takes; the Denial Codes page prints all 11 from one loop.

Guarantees and limits

Next Steps

• Task Graphs · the first artifact in the bundle: one root, depth arithmetic, and the ceilings
• Continuation Tokens · the artifact a child runs against, and the id the runtime burns before dispatch
• Delegation Witnesses · the per-hop attenuation proof the verifier recomputes for every edge
• Sub-Agent Budgets · the pool split at fan-out, reclaimed at fan-in, and reconciled by the terminal receipt
• Swarm Overview · the rung, the nine schemas, and the admission sequence this verifier sits inside
• Capabilities · the scope and attenuation model a witness hop proves a subset of
• Authority & Rotation · the rung below, where authority is one keypair you hold rather than a chain you verify
• Proof Room · where the recursive-delegation fixtures and the negative cases live
• 3-Vendor Walkthrough · one delegated scenario carried end to end