Credit Facilities

Facility records

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,
}

Facility dispositions and lifecycle

• Grant: the facility may be issued at the proposed terms.
• ManualReview: borderline; a person reviews before the facility supports an automatic grant.
• Deny: the application fails minimum criteria.

CreditFacilityLifecycleState after issuance:

• Active: the current record. Credit authority also requires Grant, met prerequisites, applicable scope, and a valid time window.
• Superseded: replaced by a newer facility, for amended terms or an adjusted ceiling.
• Denied: the application was denied at issuance.
• Expired: expires_at elapsed without renewal.

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, not summed.
• MixedRuntimeAssuranceProvenance, MissingRuntimeAssurance, CertificationNotActive: attestation and certification gates.
• FailedSettlementBacklog, PendingSettlementBacklog: unsettled exposure blocks a fresh facility.
• FacilityGranted: the successful-issuance marker on the report.

Bonds and IOUs

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,
}

• reserve_ratio_bps: the fraction of outstanding exposure that stays locked as reserve.
• coverage_ratio_bps: the fraction of the facility's credit limit this bond's collateral covers; 10,000 bps covers the full limit.

The nominated settlement rail carries out any lock, release, or transfer the bond describes, and the capital book records what the rail reports.

Bond lifecycle states

CreditBondLifecycleState has five states:

• Active: the bond is live and backs outstanding exposure.
• Superseded: replaced by a newer bond, after resized collateral or a facility amendment.
• Released: the record marks the reserve released; the rail's observation records the movement.
• Impaired: the record marks collateral impaired, associated with loss evidence.
• Expired: the bond's TTL elapsed without renewal.

Bond disposition actions

CreditBondDisposition is the action the bond evaluator recommends, distinct from the lifecycle state:

• Lock: reserve backing is recorded as locked against the facility's exposure.
• Hold: reserve is held against unresolved settlement or exposure findings.
• Release: the release disposition, when the evaluated exposure permits it.
• Impair: impairment associated with 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.

IOU envelope

The account signs the envelope with its configured signing backend. Selected fields of IouEnvelopeBody:

pub receipt_id: String,
pub receipt_timestamp: u64,
pub tenant_id: Option<String>,
pub tool_server: String,
pub tool_name: String,
pub capability_id: String,
pub amount_units: u64,
pub currency: String,
pub issuer_key: PublicKey,

The IOU hook is one credit entry point. The exposure ledger also reads governed receipts, underwriting decisions, and settlement reconciliation directly, so facilities and capital books draw on more than the hook's IOU rows.

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 leaves it out. These are the credit rows the registry carries at the pin:

The registered receivable envelope is wider. 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. On top of the hook body's fields it adds 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. A LocalCreditAccount signs the hook envelope at receipt finalization; the obligation and assignment types are defined over the receivable envelope.

Exposure and capital

Exposure ledger support boundary and positions

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 positions track governed_max_exposure_units, reserved_units, settled_units, pending_units, failed_units, provisional_loss_units, recovered_units, quoted_premium_units, and active_quoted_premium_units.

Funding sources

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

pub enum CapitalBookSourceKind {
    FacilityCommitment,
    ReserveBook,
}

pub enum CapitalBookRole {
    OperatorTreasury,
    ExternalCapitalProvider,
    AgentCounterparty,
}

Capital book event kinds

Recorded positions and changes use seven CapitalBookEventKind records:

• Commit: a commitment attributed to a facility or bond.
• Hold: held reserve derived from the bond's recorded posture.
• Draw: an outstanding amount drawn against a facility, derived from credit evidence.
• Disburse: a disbursement attributed to the recorded event; its receipt or loss evidence shows the source.
• Release: a release attributed to reserve or commitment evidence.
• Repay: a repayment recorded against an outstanding draw.
• Impair: an impairment attributed to recorded credit loss.

Capital execution instructions

A signed CapitalExecutionInstructionArtifact carries an authority chain, an execution window, and a settlement method; authority-step proofs bind the relevant roles.

#[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,
}

CapitalExecutionIntendedState is PendingExecution or CancellationPending; CapitalExecutionReconciledState is NotObserved or Matched. The capital book's default support boundary sets source_of_funds_authoritative to true and automatic_capital_execution_supported to false: chio-credit signs the instruction, the nominated settlement method moves the funds, and reconciliation matches the result afterward.

Capital allocation decisions

A CapitalExecutionInstructionArtifact specifies a movement to execute. A CapitalAllocationDecisionArtifact decides whether capital may be committed for one governed action, and from which source, by selecting a governed receipt already in the evidence store and producing CapitalAllocationInstructionDraft records.

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

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

The decision's CapitalAllocationDecisionSupportBoundary defaults capital_book_authoritative and simulation_first_only to true, and automatic_dispatch_supported and external_execution_authoritative to false: the decision drafts instructions and an operator issues them. Allocation has its own CLI verb group, chio trust capital-allocation, distinct from chio trust capital-instruction.

Simulation and sources

Bonded execution

The bonded-execution simulation evaluates whether a bond meets a candidate control policy for a stated autonomy tier, runtime assurance tier, and call-chain presence. The policy type is CreditBondedExecutionControlPolicy:

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 report returns Allow or Deny with findings after checking the active facility and bond, prerequisites, autonomy limits, the call-chain requirement, reserve requirements, and delinquency. It runs as a trust control plane simulation: it dispatches no tool and changes no kernel call path.

A CreditBondedExecutionSimulationReport, built from a CreditBondedExecutionSimulationRequest that pairs a CreditBondedExecutionSimulationQuery with a candidate policy, evaluates the current bond against both the default and the simulated policy. Its CreditBondedExecutionSimulationDelta says whether the gate decision changed and which reasons were added or removed. For drift, chio trust credit-backtest export (HTTP GET /v1/reports/credit-backtest) replays scorecard and facility logic over a configurable count and width of past windows.

Implementation sources

The struct excerpts above omit documentation comments and unrelated fields.

• crates/economy/chio-credit/src/lib.rs: facility, bond, and exposure contracts.
• crates/economy/chio-credit/src/local_account.rs: trusted receipt checks and IOU minting.
• crates/economy/chio-credit/src/obligation/credit_admission.rs: facility authority resolution.
• crates/platform/chio-control-plane/src/trust_control/reports.rs: capital allocation evaluation.
• crates/platform/chio-control-plane/src/trust_control/credit_and_loss.rs: facility and bond reports, loss records, and bond simulation.