Revocation Epochs

Source

This page reflects spec/schemas/chio-swarm/v1/revocation-epoch.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.

A signed block list with a clock

A revocation epoch is one artifact in a swarm delegation bundle. It carries two lists, a validity window, a digest over the lists, and a signature from a pinned witness key. The verifier reads it on every bundle it is handed, checks the window against the caller-supplied instant, recomputes the digest from the lists, and then tests the bundle’s own subjects and task ids against it. Nothing about it is stateful: it is data inside the bundle, not a service the verifier calls.

Three things are shipped and unconditional in crates/kernel/chio-swarm-authority: the type, the validation, and the binding into every continuation token.

The name is reused elsewhere in the tree and the mechanisms are not the same one. crates/trust/chio-revocation-oracle is a Merkle accumulator over (subject, epoch_nonce) keys that produces inclusion and non-inclusion proofs and ticks a signed root on a schedule; its one shipped implementation is sparse_merkle::InMemoryRevocationOracle, and it is documented in Revocation Oracle. The Kernel-rung RevocationView holds a snapshot of revoked capability ids and denies a delegated dispatch when any link in the chain appears in it. Read that one carefully: the delegation cargo feature it sits behind is in chio-kernel’s default set rather than an opt-in, and consult_revocation_view returns Ok(()) when no view is installed, falling back to the per-row revocation store. The swarm epoch borrows neither. chio-swarm-authority declares exactly four dependencies: chio-core-types, serde, serde_json, thiserror. The only others in its manifest are chio-test-support and proptest, both dev-dependencies.

Nine fields

pub struct SwarmRevocationEpoch {
    pub schema: String,
    pub epoch_id: String,
    pub root_hash: String,
    pub issued_at_unix_ms: u64,
    pub valid_until_unix_ms: u64,
    pub revoked_subjects: Vec<String>,
    pub revoked_task_ids: Vec<String>,
    pub issuer: String,
    pub signature: String,
}

The wire form is pinned separately in spec/schemas/chio-swarm/v1/revocation-epoch.schema.json, which sets additionalProperties: false, requires all nine fields, holds rootHash to ^[0-9a-f]{64}$ and signature to ^[0-9a-f]{128}$, and gives both list item types minLength: 1. The Rust side carries deny_unknown_fields, so the closed-object rule holds in both. The two disagree in the same two directions they disagree everywhere else in this family, and Continuation Tokens works that asymmetry through once for the whole bundle. Two instances are local to this artifact. revokedTaskIds entries get no emptiness check from the verifier at all, so a blank entry is schema-invalid and verifier-acceptable, where a blank revokedSubjects entry is refused by both. And neither list is checked for uniqueness on either side: the schema sets no uniqueItems and the verifier calls require_unique_strings on neither list, so a repeated entry is accepted everywhere and still changes the root, because the digest sorts without deduplicating.

The root hash is a digest, not a tree

struct RevocationEpochListRoot<'a> {
    revoked_subjects: Vec<&'a str>,
    revoked_task_ids: Vec<&'a str>,
}

fn revocation_epoch_list_root_hash(
    epoch: &SwarmRevocationEpoch,
) -> Result<String, SwarmAuthorityError> {
    canonical_sha256(&RevocationEpochListRoot {
        revoked_subjects: sorted_strings(&epoch.revoked_subjects),
        revoked_task_ids: sorted_strings(&epoch.revoked_task_ids),
    })
}

The preimage type carries #[serde(rename_all = "camelCase")], so the hashed object holds revokedSubjects and revokedTaskIds and nothing else. That is a SHA-256 over the canonical JSON of two sorted string arrays. It is order-independent, because sorted_strings sorts before hashing, and it is not deduplicating, so ["a", "a"] and ["a"] are different epochs with different roots. What it does not carry is any proof structure. There is no inclusion proof, no non-inclusion proof, and no way to answer a membership question without the whole list. A holder of the root alone learns nothing except whether a list it already has matches. If you want proofs against a root, that is the oracle crate, and it is a different object.

What the verifier does with it

validate_revocation_epoch runs as one step inside the fixed pipeline Swarm Authority documents, after the task graph, route plans, joins, and the budget pool, and before terminal receipts and continuation tokens. Its internal order is what makes the refusals readable, because the first failing check returns and nothing after it runs.

Steps 8 and 12 are the pair that makes the list trustworthy rather than merely present. The root is recomputed from the lists the epoch actually carries, so an epoch cannot advertise a digest that does not describe it; the signature covers the whole epoch with the signature field stripped, so the lists cannot be edited without the pinned key. Editing one list and leaving the root alone is swarm revocation epoch root mismatch (swarm_authority_stage0_rejects_revocation_epoch_list_root_mismatch). Editing one list, recomputing the root, and failing to re-sign is swarm revocation epoch signature invalid (swarm_authority_stage0_rejects_unsigned_revocation_epoch_list_reseal). Only six of the fifteen refusals are asserted anywhere in the tree. Steps 1, 2, 3, 4, 6, 9, 10, 11, and 13 have no test and no fixture, so read them as code that has been read rather than code that has been exercised.

Step 14 reaches into the witness chains before those chains are structurally validated, which happens last in the pipeline. A revoked witness-hop issuer therefore rejects the bundle even when the chain it signed would have failed its own checks anyway. The reverse is also worth knowing, because it is a real gap rather than an ordering curiosity: the revoked-subject test names exactly three roles. It does not read the issuer of a continuation token, a route-plan receipt, a join receipt, or a terminal graph receipt. Those issuers are each pinned against the same trusted key slice by their own validator, so a stranger cannot sign them, but revoking one by subject does not stop a bundle it signed.

Step 15 is the one with a shipped bundle behind it. The fixture directory carries an epoch whose revokedTaskIds lists a task the graph still contains, and everything else about the bundle is signed and consistent.

$ 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.

The message carries the task id, so an operator holding only the rejection knows which node to detach and re-plan. The other fourteen conditions in the table produce the same shape on stderr and the same exit status.

The root travels in every hop

A continuation token authorizes one child task, and two of its fields are the epoch it was minted under. validate_continuation_token requires revocationEpochRef to equal the bundle epoch’s epochId(swarm continuation revocation epoch mismatch), requires revocationEpochRootHash to be a lowercase digest, and requires it to equal the epoch’s rootHash field (swarm continuation revocation epoch root mismatch). Neither of those two refusals has a test. The second compares against the declared field rather than recomputing, which costs nothing here only because step 8 has already proved the two equal and returns before this code is reached. Both fields sit inside the token’s signature body, so a presenter can neither retarget a token at a different epoch nor patch its root to match one.

The binding is not vacuous on a token-free bundle, because there is no such thing: require_signed_swarm_delegation_evidence is checked fourth, after the key-slice precondition, the task graph, and the graph signature, and it rejects any bundle whose continuation tokens or witness chains are empty, with signed swarm delegation evidence missing: continuation tokens and witness chains are required. The epoch is validated after route plans, joins, and the budget pool, so every bundle that reaches the epoch check carries at least one token, and every token carries the root.

That is the whole mechanism for making a revocation land on a hop rather than on the plan. The graph is signed and fixed; the epoch is a separate signed artifact naming what the graph must be checked against; and every hop carries the digest of the view it was issued under. Change the lists and the root changes, and every token still carrying the old root fails at the equality check. The tokens are not amended in place by anything; they are re-minted or they stop verifying.

The terminal graph receipt binds the epoch too, but only by id: receipt.revocation_epoch_ref must equal the epoch id (swarm terminal revocation epoch mismatch), and the type carries no root-hash field. A terminal receipt commits to which epoch a graph closed under, not to what that epoch said.

The instant those checks read does not come from the bundle in production. The runtime overwrites it with the request clock before verifying, in the same function that resolves the stored bundle:

bundle.now_unix_ms = now_unix_ms;
verify_swarm_reference_hashes(&bundle, reference)?;
let route_plan = find_route_plan(&bundle, &reference.route_plan_receipt.evidence_id)?;
let route_metadata = verify_route_metadata_matches(route_metadata, route_plan)?;
verify_swarm_authority_bundle(&bundle, trusted_witness_keys).map_err(|error| {
    ChioRuntimeError::Rejected {
        code: "chio_swarm_authority_rejected",
        detail: error.runtime_detail(),
    }
})?;

A stored epoch that was inside its window when the bundle was written and outside it by dispatch is stale, and the whole bundle denies with chio_swarm_authority_rejected. That is the code path, not an observed one: no test in runtime_admission.rs advances the clock past a stored epoch’s window. The request must also name the epoch as one of seven id-plus-digest evidence pairs, and verify_swarm_reference_hashes compares the named id and canonical SHA-256 against the stored artifact before verification runs; a mismatch is chio_swarm_authority_ref_mismatch. The two proof paths that call the same verifier, the chio proof verify CLI and Proof Room, both read SystemTime::now for the same field.

What a new epoch costs

Publishing a revocation is not a one-artifact edit. Because the root is recomputed from the lists and every continuation token commits to that root, a change to either list invalidates every token in the bundle. The stage-0 suite has the operation written out, and it is the closest thing in the tree to a rotation procedure:

fn refresh_revocation_epoch_root(bundle: &mut SwarmAuthorityBundle) -> Result<(), Box<dyn Error>> {
    let root_hash = revocation_epoch_root_hash(
        &bundle.revocation_epoch.revoked_subjects,
        &bundle.revocation_epoch.revoked_task_ids,
    )?;
    bundle.revocation_epoch.root_hash = root_hash.clone();
    sign_revocation_epoch(&mut bundle.revocation_epoch)?;
    for token in &mut bundle.continuation_tokens {
        token.revocation_epoch_root_hash = root_hash.clone();
        sign_continuation_token(token)?;
    }
    Ok(())
}

Recompute, re-sign the epoch, then re-sign every continuation token against the new root. Every name in that excerpt is test-local, and one of them has to be. sign_revocation_epoch and sign_continuation_token are one-line wrappers over the exported sign_swarm_revocation_epoch and sign_swarm_continuation_token, but revocation_epoch_list_root_hash is private to verifier.rs and nothing equivalent is in lib.rs’s pub use list. There is no exported way to compute the root an epoch must carry, so anything that issues one reimplements the canonical-JSON digest by hand. Three places do: swarm_authority_stage0.rs, runtime_admission.rs, and the crate’s own examples/agent_os.rs. All three sort the two lists and hash a serde_json::json! literal keyed revokedSubjects and revokedTaskIds, which is the same object the verifier’s private struct serializes to only because its rename_all produces those two names. They agree today because the field names and the sort order happen to match, and nothing in the build would catch it if they stopped.

The negative fixture on disk is the result of exactly that procedure: fixtures/proof-room/swarm-authority/revoked-task/ keeps epochId at revocation-epoch-swarm-valid, adds task-child-a to revokedTaskIds, carries the new root 1d8a51dd..., and both continuation tokens in that directory carry the same new root under fresh signatures. Nothing about the fixture is malformed. It rejects on the revoked task id and on nothing else, which is what makes it a useful negative.

Guarantees and limits

Claim: revoking one task denies the whole graph

Next Steps

• Continuation Tokens · the artifact that carries the epoch root through every hop, and the single-use id burned before dispatch
• Revocation Propagation · the same word under one authority: capability ids, a pull lane, and a propagation-lag histogram
• Swarm Authority · the fixed pipeline this check runs inside, and why there is no partial verdict
• Task Graphs · the signed plan whose revocationEpochRef names the epoch
• Revocation Store · the node-local set, for contrast: no signature, no window, no root