Credit Facilities

IOUs: credit as a signed claim on a receipt

Facilities, bonds, and capital books all account for a more basic record: an IOU minted from a signed receipt. IouEnvelope / IouEnvelopeBody (crate chio-credit) is a claim record signed by a LocalCreditAccount: when a ChioReceipt finalizes as an allowed, priced call, the account verifies the receipt's signature and content-addressed id, then signs an IouEnvelopeBody. Its amount_units and currency are read from the receipt's own financial metadata.

pub struct IouEnvelopeBody {
    /// Schema tag (`chio.credit.iou-envelope.v1`).
    pub schema: String,
    /// Stable identifier for this IOU. Recommended UUIDv7.
    pub iou_id: String,
    /// `id` of the [`ChioReceipt`] that finalized this IOU.
    pub receipt_id: String,
    /// `timestamp` carried over from the originating receipt so the
    /// IOU lifecycle entry can sort by issuance time without joining
    /// against the receipt store.
    pub receipt_timestamp: u64,
    /// Cluster operator (tenant) that owes the obligation, or `None`
    /// for single-tenant deployments.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tenant_id: Option<String>,
    /// Tool server that was invoked. Carried over from the receipt
    /// for cheap denormalised queries.
    pub tool_server: String,
    /// Tool that was invoked.
    pub tool_name: String,
    /// Capability id from the receipt.
    pub capability_id: String,
    /// Cost charged in currency minor units (e.g. USD cents). Always
    /// strictly greater than zero. Zero-price receipts skip IOU
    /// minting entirely.
    pub amount_units: u64,
    /// ISO 4217 currency code.
    pub currency: String,
    /// Issuer public key, expected to match the kernel signing
    /// identity that produced the underlying receipt.
    pub issuer_key: PublicKey,
}

/// Signed IOU envelope. Produced by [`CreditEvaluatorHook::evaluate`]
/// after a finalized receipt is observed, and persisted by the
/// store binding.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct IouEnvelope {
    /// Body that was signed.
    #[serde(flatten)]
    pub body: IouEnvelopeBody,
    /// Signing algorithm used for `signature`; absent defaults to Ed25519.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub algorithm: Option<SigningAlgorithm>,
    /// Detached signature over canonical JSON of `body`.
    pub signature: Signature,
}

The body carries receipt_id, and because a ChioReceipt's id is itself content-addressed, that field is a hash reference to the originating evidence. See Receipts for how that id is derived and signed.

IOUs are persisted through chio-store-sqlite's iou_store (crates/platform/chio-store-sqlite/src/iou_store.rs), keyed by receipt_id so re-processing a finalized receipt is idempotent: a byte-identical envelope is a no-op, and a divergent one is rejected as a conflict. The IOU is the unit every later section aggregates. A facility's outstanding draws, a bond's outstanding_exposure_amount, and the exposure ledger's pending_units and settled_units are, at bottom, aggregates over IOUs minted this way: one signed claim per priced, allowed receipt.

Registered credit schemas

chio.credit.iou-envelope.v1 is the schema tag on the hook's own envelope (IOU_ENVELOPE_SCHEMA in crates/economy/chio-credit/src/hook.rs), and the signed-artifact registry does not list it. These are the credit rows the registry does carry at the pin:

The registered receivable envelope is a wider record. IouEnvelopeBodyV2 (crates/economy/chio-credit/src/iou_v2.rs) carries the schema constant CHIO_RECEIVABLE_IOU_ENVELOPE_V1_SCHEMA from crates/core/chio-core-types/src/signed_artifact.rs and adds, on top of the hook body's fields, an operation id, an obligation id and atom digest, the receipt digest with its content and policy hashes, the debtor and original creditor, the original settlement destination reference, a payee binding digest, the current disposition digest, a due time, a facility id, a credit authority digest, and a signed SignedCreditFacilityBindV1. The hook envelope is what a LocalCreditAccount signs at receipt finalization. The receivable envelope is the record the obligation and assignment types are defined over.

Credit facilities

A credit facility is a pre-approved spending line, like a corporate credit card with a ceiling and terms. Once granted, an agent (or its operator) can draw against the facility to fund tool invocations, capped by the ceiling and policy attached to the facility.

Facility terms

pub struct CreditFacilityTerms {
    pub credit_limit: MonetaryAmount,
    pub utilization_ceiling_bps: u16,
    pub reserve_ratio_bps: u16,
    pub concentration_cap_bps: u16,
    pub ttl_seconds: u64,
    pub capital_source: CreditFacilityCapitalSource,
}

capital_source names where the money behind the line comes from:

pub enum CreditFacilityCapitalSource {
    OperatorInternal,
    ManualProviderReview,
}

Three independent ratios shape what a facility can do:

• Utilization ceiling: caps concurrent outstanding draws as a fraction of credit_limit. A $10,000 facility with 8,000 bps (80%) ceiling allows up to $8,000 outstanding.
• Reserve ratio: the fraction of outstanding exposure that must be held as locked collateral. 1,500 bps (15%) means $150 of reserve for every $1,000 outstanding.
• Concentration cap: limits exposure to any single counterparty. 3,000 bps (30%) on a $10,000 facility means at most $3,000 routed to one provider at a time.

Facility dispositions and lifecycle

The underwriting evaluation rolls into a CreditFacilityDisposition:

• Grant: facility may be issued at the proposed terms.
• ManualReview: borderline; a human or higher-authority signer must approve before issuance.
• Deny: the application fails minimum criteria.

Once issued, the facility moves through CreditFacilityLifecycleState:

Facility reason codes

CreditFacilityReasonCode attaches to findings on the facility report:

• ScoreRestricted, ProbationaryScore, LowConfidence: scorecard gates.
• MixedCurrencyBook: the subject's exposure ledger spans more than one currency. chio-credit nets exposure within a single currency, so a mixed book is reported rather than summed.
• MixedRuntimeAssuranceProvenance, MissingRuntimeAssurance, CertificationNotActive: attestation and certification gates.
• FailedSettlementBacklog, PendingSettlementBacklog: unsettled exposure blocks a fresh facility.
• FacilityGranted: the successful-issuance marker recorded on the report.

Credit bonds

A bond is the collateral object that backs a specific call against a facility. Like a performance bond on a construction contract, the bond locks capital that can be impaired (seized) if the agent fails to settle or violates policy. Bonds reference their facility by id and carry their own currency-coherent terms.

Bond terms

pub struct CreditBondTerms {
    pub facility_id: String,
    pub credit_limit: MonetaryAmount,
    pub collateral_amount: MonetaryAmount,
    pub reserve_requirement_amount: MonetaryAmount,
    pub outstanding_exposure_amount: MonetaryAmount,
    pub reserve_ratio_bps: u16,
    pub coverage_ratio_bps: u16,
    pub capital_source: CreditFacilityCapitalSource,
}

The two ratios on a bond have specific meanings:

• Reserve ratio (bps): the fraction of outstanding exposure that must remain locked as reserve.
• Coverage ratio (bps): the fraction of the facility's credit limit covered by this bond's collateral. A coverage ratio of 10,000 bps (100%) means the bond covers the full facility limit.

Bond lifecycle states

CreditBondLifecycleState tracks where a bond is in its life. Five states ship today:

Bond disposition actions

CreditBondDisposition is the action recommended by the bond evaluator, distinct from its lifecycle state. Four actions ship:

• Lock: lock additional collateral against this bond (typical when sizing up a bond before dispatch).
• Hold: place a hold on the bond (collateral cannot be released or drawn against pending investigation).
• Release: return collateral to the source after clean settlement.
• Impair: seize collateral as a credit loss; pairs with a CreditLossLifecycle event.

Bond reason codes

Findings on a bond report carry a CreditBondReasonCode: ActiveFacilityMissing, MixedCurrencyBook, PendingSettlementBacklog, FailedSettlementBacklog, ProvisionalLossOutstanding, ReserveLocked, ReserveHeld, ReserveReleased, UnderCollateralized.

Bond lifecycle diagram

Exposure ledger

The exposure ledger answers the question how much is this subject currently on the hook for? It scopes by capability, agent subject, or tool server (one anchor is required) and reports receipt-level detail and an aggregate summary:

pub struct ExposureLedgerSupportBoundary {
    pub governed_receipts_authoritative: bool,
    pub underwriting_decisions_authoritative: bool,
    pub settlement_reconciliation_authoritative: bool,
    pub cross_currency_netting_supported: bool,
    pub claim_adjudication_supported: bool,
    pub recovery_lifecycle_supported: bool,
}

impl Default for ExposureLedgerSupportBoundary {
    fn default() -> Self {
        Self {
            governed_receipts_authoritative: true,
            underwriting_decisions_authoritative: true,
            settlement_reconciliation_authoritative: true,
            cross_currency_netting_supported: false,
            claim_adjudication_supported: false,
            recovery_lifecycle_supported: false,
        }
    }
}

Per-currency ledger positions track: governed_max_exposure_units, reserved_units, settled_units, pending_units, failed_units, provisional_loss_units, recovered_units, quoted_premium_units, active_quoted_premium_units.

The ledger is the input to the underwriting evaluator and the scorecard, and it is the authoritative record of which receipts and decisions back a bond.

Capital book

The capital book aggregates a subject's funding sources and the events that have moved capital through them. Where the exposure ledger is receipt-shaped (what did the agent spend?), the capital book is treasury-shaped (where did the money come from and go?).

Funding sources

Each entry on the book is a CapitalBookSource tagged with a kind and counterparty roles:

pub enum CapitalBookSourceKind {
    FacilityCommitment,
    ReserveBook,
}

pub enum CapitalBookRole {
    OperatorTreasury,
    ExternalCapitalProvider,
    AgentCounterparty,
}

Event kinds

Every movement of capital is one of seven CapitalBookEventKind records:

Capital execution instructions

Capital movements are dispatched through signed CapitalExecutionInstructionArtifact records. Each instruction carries a multi-signature authority chain, execution window, and settlement method:

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum CapitalExecutionInstructionAction {
    LockReserve,
    HoldReserve,
    ReleaseReserve,
    TransferFunds,
    CancelInstruction,
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum CapitalExecutionRole {
    OperatorTreasury,
    ExternalCapitalProvider,
    AgentCounterparty,
    LiabilityProvider,
    Reinsurer,
    FacilityProvider,
    Custodian,
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum CapitalExecutionRailKind {
    Manual,
    Api,
    Ach,
    Wire,
    Ledger,
    Sandbox,
    Web3,
}

Intended-vs-reconciled state lets external execution catch up with the signed instruction: CapitalExecutionIntendedState is PendingExecution or CancellationPending; CapitalExecutionReconciledState is NotObserved or Matched.

Capital allocation decisions

Capital allocation uses signed records separate from capital execution. A CapitalExecutionInstructionArtifact dispatches a specific movement, a CapitalAllocationDecisionArtifact decides whether capital may be committed for one governed action and from which source. It precedes execution and produces CapitalAllocationInstructionDraft records rather than dispatching directly.

pub enum CapitalAllocationDecisionOutcome {
    Allocate,
    Queue,
    ManualReview,
    Deny,
}

pub enum CapitalAllocationDecisionReasonCode {
    MissingGovernedReceipt,
    AmbiguousGovernedReceipt,
    MissingRequestedAmount,
    FacilityManualReview,
    FacilityDenied,
    ManualCapitalSource,
    ReserveBookMissing,
    UtilizationCeilingExceeded,
    ConcentrationCapExceeded,
}

The decision carries a CapitalAllocationDecisionSupportBoundary whose defaults mark capital_book_authoritative and simulation_first_only as true, and automatic_dispatch_supported and external_execution_authoritative as false. Chio decides the allocation and drafts the instruction without automatically dispatching capital. It has its own CLI verb group, distinct from chio trust capital-instruction ...:

$ chio trust capital-allocation issue --input-file ./allocation-request.json

Bonded execution

Bonded execution is a runtime gate that checks whether an active bond covers a dispatch. It consults a CreditBondedExecutionControlPolicy on every call:

pub struct CreditBondedExecutionControlPolicy {
    pub version: String,
    pub kill_switch: bool,
    pub maximum_autonomy_tier: Option<GovernedAutonomyTier>,
    pub minimum_runtime_assurance_tier: Option<RuntimeAssuranceTier>,
    pub require_delegated_call_chain: bool,
    pub require_locked_reserve: bool,
    pub deny_if_bond_not_active: bool,
    pub deny_if_outstanding_delinquency: bool,
}

The gate returns a decision: dispatch proceeds when the bond is active, the runtime assurance tier meets the minimum, the autonomy tier is within bounds, and there is no outstanding delinquency. Otherwise the call is held or denied.

Before applying a control-policy change, an operator can dry-run it. A CreditBondedExecutionSimulationReport (built from a CreditBondedExecutionSimulationRequest pairing a CreditBondedExecutionSimulationQuery with a candidate policy) evaluates the current bond against both the default and the simulated policy and reports the CreditBondedExecutionSimulationDelta . It reports whether the gate decision changed and which reasons were added or removed. A related capability replays scorecard and facility logic over historical windows for drift detection: chio trust credit-backtest export (HTTP GET /v1/reports/credit-backtest) produces a backtest report across a configurable window count and width.

Loss lifecycle

When a bonded call goes wrong, the bond moves through a loss lifecycle. CreditLossLifecycleEventKind has five variants:

• Delinquency: outstanding obligation past due.
• Recovery: previously delinquent amount recovered.
• ReserveRelease: held reserve released back to the source.
• ReserveSlash: reserve seized to cover the loss.
• WriteOff: portion of the loss formally written off.

Reserve control execution and appeal windows are tracked separately: CreditReserveControlExecutionState is PendingExecution or Executed, and CreditReserveControlAppealState is Unsupported, Open, or Closed.

Worked example

An issuer creates a USD facility for agent-42 with a $1,000 ceiling, an 8,000 bps utilization ceiling (so up to $800 outstanding at once), and a 1,000 bps reserve ratio (10% of outstanding must be held as locked reserve).

let terms = CreditFacilityTerms {
    credit_limit: MonetaryAmount { units: 100_000, currency: "USD".into() }, // $1,000 in cents
    utilization_ceiling_bps: 8_000,
    reserve_ratio_bps: 1_000,
    concentration_cap_bps: 5_000,
    ttl_seconds: 86_400 * 30, // 30 days
    capital_source: CreditFacilityCapitalSource::OperatorInternal,
};

The agent now wants to make a $100 (10,000 cents) call. Before dispatch, the bonded-execution gate locks 10% of that as bond reserve on top of the $100 draw:

1. Lock: $10 of operator treasury moves to ReserveBook as a Hold event tied to the bond.
2. Draw: $100 is drawn from the facility commitment to fund the call. The exposure ledger now shows pending_units = 10_000 and reserved_units = 1_000.
3. Disburse: on settlement, $100 is disbursed to the provider. The pending position settles to settled_units.
4. Release: the $10 hold is released back to operator treasury. Bond moves to Released.

Dispute path: if the receipt is later disputed and the loss adjudicates against the agent, the bonded reserve can be impaired. A ReserveSlash event records the seizure, and the bond moves to Impaired. The capital book records the seizure as an Impair event with the operator treasury as owner role.

Related

• Underwriting Risk Taxonomy : the inputs that decide whether a facility is granted.
• Settlement Rails : the rails that move capital once an instruction is signed.
• Scorecards : the credit scorecard that summarizes the subject's exposure and reputation context.
• Reconciliation : how external settlement systems reconcile capital execution with the capital book.
• Claims Lifecycle : how an insured loss reconciles back into facility and bond accounting.
• Settlement : settlement systems that move capital across counterparties.
• Credit & Underwriting Guide : worked guide that applies this reference through the CLI.