Authoritative Spend

Seven checks run in order, and the first failure names itself

The store writes TrustLevel::Mediated onto a receipt at persistence time, and a receipt emitted beside the kernel can carry the same stamp, so the stamp alone says nothing about a held budget or a guard that ran. The predicate turns that difference into a conjunction a program evaluates: nothing is weighed, nothing defaults to true, and it returns at the first check that fails.

1. The receipt signature verifies. The nonce signature covers only the nonce, so this check stops a nonce holder from forging receipt fields around it. A verification error and a false result both refuse.
2. The signer is an admitted kernel key. The receipt’s kernel_key appears in the caller’s admitted set.
3. The decision is a mediated Allow. Five fields in sequence: receipt kind MediatedDecision, boundary class Prevent, no observation_outcome, trust level Mediated, and an Allow decision.
4. The hold reconciled and moved. The receipt projects a BudgetAuthorityReceiptRef with a non-empty hold id, its budget-authority block pins the frozen profile exactly, its terminal mutation is a reconcile (a reverse or a release fails), and its exposed units are above zero.
5. The receipt names the nonce. The budget-authority block’s execution nonce id equals the presented nonce’s id. When the nonce also names a reserved hold, that hold is the one this receipt settled; a nonce naming no reserved hold binds through the id alone, which is the single-shot and strict-retry path.
6. The nonce binds this exact call. Four equalities against the receipt: capability_id, tool_server, tool_name, and parameter_hash. The refusal names the field that differed.
7. The nonce is signed by the same key. The nonce signature verifies under the receipt’s own kernel key; a nonce signed by another admitted key is refused.

A consumer runs the predicate before it books a charge

Pass the receipt, the presented nonce, and the kernel keys your consumer admits. Your application loads those verified inputs and chooses which keys to trust.

use chio_core_types::receipt::{
    is_authoritative_spend_receipt,
    NotAuthoritativeReason, PresentedNonceView,
};
use chio_core_types::{crypto::PublicKey, receipt::body::ChioReceipt};

fn verify_charge(
    receipt: &ChioReceipt,
    admitted_keys: &[PublicKey],
    nonce: &dyn PresentedNonceView,
) -> Result<(), NotAuthoritativeReason> {
    is_authoritative_spend_receipt(receipt, admitted_keys, nonce)
}

On Ok(()), book the charge as governed spend, then read the rail outcome before marking it paid. On ReservedHoldMismatch, fetch the nonce for the original hold; editing the signed receipt breaks its signature. On NonceBindingMismatch, refuse the pair and keep the refusal for investigation.

The predicate pins the receipt profile chio.mediated_spend.v1, demands the nonce schema chio.execution_nonce.v1, and reads the hold strength the store declares as BudgetGuaranteeLevel. Reconciliation holds the ledger view of the same contract under the same ids.

Read more in the predicate source, which carries every refusal branch.

Every refusal is a typed reason

The return type is Result<(), NotAuthoritativeReason>, so a consumer that rejects a receipt records which clause it failed. Each clause maps to at least one variant, which lets a conformance matrix flip the clauses one at a time.

/// Distinct rejection reasons; each of the (a)-(f) conjunction fragments maps to
/// at least one variant so a conformance matrix can flip them independently.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum NotAuthoritativeReason {
    ReceiptSignatureInvalid,
    SignerNotAdmitted,
    NotMediatedDecision,
    NotPreventBoundary,
    ObservationOutcomePresent,
    NotMediatedTrustLevel,
    NotAllowDecision,
    MissingBudgetAuthority,
    HoldNotReconciled,
    ExposureNotCommitted,
    NonceLinkMissing,
    NonceLinkMismatch,
    /// The presented nonce cryptographically names a reserved budget hold that
    /// differs from the receipt's committed `budget_authority.hold_id`. The
    /// nonce id links the two artifacts, but the hold the nonce reserved is not
    /// the hold this receipt settled, so the receipt is not authoritative for
    /// the presented nonce. Fail-closed on this cross-binding inconsistency.
    ReservedHoldMismatch,
    NonceBindingMismatch {
        field: &'static str,
    },
    NonceSignatureInvalid,
    /// The receipt's budget-authority block does not pin the frozen
    /// `MEDIATED_SPEND_PROFILE`, so its contract shape is unversioned or a
    /// different version than the consumer requires.
    MissingOrWrongMediatedSpendProfile,
    /// The receipt's guarantee level is weaker than the operator-configured
    /// floor (R4 truthfulness). Unrelated to `TrustLevel::Mediated`.
    GuaranteeLevelBelowFloor {
        minimum: String,
        actual: String,
    },
    /// The operator-configured guarantee floor is not a recognized level, so it
    /// cannot be ranked. Fail-closed rather than admitting every receipt.
    UnknownGuaranteeFloor {
        minimum: String,
    },
    /// The receipt's own guarantee level is not a recognized level, so its
    /// truthfulness claim cannot be ranked. An unrecognized level ranks as the
    /// weakest, which would silently clear the weakest valid floor; fail-closed
    /// instead so a typoed or forged level never passes as authoritative.
    UnknownGuaranteeLevel {
        actual: String,
    },
}

The last three variants come from a second check. receipt_meets_guarantee_floor compares the level a receipt declares with the floor the operator configures, and refuses when either string is unrecognized, so a mistyped or forged level never ranks as the weakest one and slips past.

The execution nonce binds one invocation

The kernel signs a single-use body that pins one invocation, and the signature covers the canonical JSON of that body. On the wire it travels as SignedExecutionNonce: the body under nonce, the Ed25519 signature beside it, and the two optional fields omitted when absent.

/// Signable body of a kernel-issued execution nonce.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ExecutionNonce {
    pub schema: String,
    pub nonce_id: String,
    pub issued_at: i64,
    pub expires_at: i64,
    pub bound_to: NonceBinding,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reserved_hold_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub reserving_request_id: Option<String>,
}

The six fields of bound_to are what the predicate compares against the receipt:

• capability_id, tool_server, and tool_name equal the receipt fields of the same names.
• parameter_hash equals action.parameter_hash on the receipt.
• request_id names the invocation under verification; an empty value is refused, so every nonce names an identified call.
• subject_id rides on the binding under the signature.

Nonce verification runs separately from the predicate and fails closed on a wrong schema, a passed expiry, a differing binding field, a bad signature, an already consumed nonce, an encoding failure, or an unreachable replay store. Reservation is single-use: a durable store keeps the consumed marker until the signed expiry, so pruning a row never lets a live nonce replay.

Read more in Replay protection, which draws the consumed marker across a restart.

The budget store declares how strong its hold is

A hold that moved says nothing about how strong it was, so the receipt carries the level its budget store declares. The four levels are totally ordered by rank, which lets an operator pin a floor.

Two revocation-commit paths accept only SingleNodeAtomic and HaLinearizable, so a store declaring an escrowed or advisory hold records no revocation commit. Elsewhere the predicate checks that the level is one it recognizes and ranks at or above the operator’s floor. Whether the store delivers what it declares is the store’s conformance obligation, outside what a signature can show.

The hold reserves the worst case, then reconciles to the cost

Before dispatch the kernel holds the worst case: quote.quoted_cost when a quote is present, otherwise max_cost_per_invocation. The call dispatches under the signed nonce only after the hold is recorded.

When the reply returns, the hold reconciles down to the realized cost and the unused reservation returns to the capability budget. A refused call or an abort before execution reverses the hold, with no charge and no authoritative spend receipt. A lost reply keeps its hold until the outcome is resolved, and the call is never dispatched again. A worst case that would exceed the budget is refused before dispatch with a signed deny receipt.

The authoritative number is the reserve-and-reconcile pair, which is why the predicate refuses a hold whose terminal mutation was a reverse or a release. The kernel records each economic mutation durably as one of 5 admission states joined by 6 legal transitions, and 3 of those states can exit to the not-applied terminal, so a mutation that stops short is recorded as not applied. Recovery inspects the original operation and its retained state before choosing the next transition.

Read more in Durability, which covers the full admission machine and the reversal steps for a dropped evaluation, and in the admission state source.

A receipt records governed spend; payment is a separate fact

The authority to spend comes before the receipt: capability, policy, and guards let the kernel decide Allow before any money moves, and the receipt is what that decision leaves behind. The predicate checks evidence of governed spend. A processor’s result, a beneficiary’s receipt of funds, and chain finality are settlement evidence a consumer reads separately before it marks a charge paid.

Two records declare slots for direct pointers back to the nonce and the hold. The comptroller surface report chio.comptroller.surface-report.v1, served at /v1/reports/comptroller-surface on chio trust serve, and the off-chain settlement receipt both declare optional execution_nonce_ref and hold_ref strings. The predicate reads the linkage from the receipt’s own budget-authority block, the copy under the kernel’s signature.

Read more in Verify Commerce Evidence, which works through why the decision comes before the money, and Operator Reports for the surface report route.

Next: confirm the charge was paid