Operating an Economy

The end state is one operator deployment in which every call routed through the kernel is admitted under issuance ceilings, spends inside holds and caps before dispatch, settles over a rail chosen per counterparty, and leaves receipts that export for finance and audit.

The kernel runs in process, as a sidecar, or under the process host. The finding-market and web3 modules are off by default and payment rails are modules outside the kernel, so a deployment turns on the ones its application uses. Credit, underwriting, and reputation are part of every build.

An economy has no single operator file. chio.yaml configures the runtime, a HushSpec policy configures issuance ceilings, and rails, facilities, bonds, and coverage are typed values the dispatching code constructs.

1. Configure the runtime and check the host

Write chio.yaml with the signing key, receipt store, tool adapters, and guard pipeline, and route the application's calls through that kernel. kernel plus one adapters entry is a valid file; other keys default.

chio doctor

You should see every report at ok and exit code 0. A rail, facility, bond, or reputation section at the root of chio.yaml fails to parse, because every section refuses unknown fields. Node preflight reads each report, and Configuration is the field reference.

2. Set issuance ceilings by reputation tier

Issuance reads the reputation block of a HushSpec policy: eight scoring weights, a decay half-life, three probationary values, and tiers that pair a score range with a max_scope ceiling.

extensions:
  reputation:
    scoring:
      weights:
        boundary_pressure: 0.20
        resource_stewardship: 0.10
        least_privilege: 0.15
        history_depth: 0.10
        tool_diversity: 0.05
        delegation_hygiene: 0.15
        reliability: 0.15
        incident_correlation: 0.10
      temporal_decay_half_life_days: 30
      probationary_receipt_count: 1000
      probationary_min_days: 30
      probationary_score_ceiling: 0.60

    tiers:
      probationary:
        score_range: [0.0, 0.40]
        max_scope:
          operations: [read, get]
          max_invocations: 50
          max_cost_per_invocation:
            units: 100
            currency: "USD"
          max_total_cost:
            units: 1000
            currency: "USD"
          max_delegation_depth: 0
          ttl_seconds: 60
          constraints_required: true

You should see the policy load without a parse error, since every struct behind the block refuses unknown fields. Before delegating work, inspect an issued capability's subject, scope, budget, and expiry: a changed policy governs new grants, and a grant already issued keeps its own terms. Passports and Reputation cover the evidence a tier is computed from.

3. Choose a settlement rail per counterparty

Rails plug in as optional modules behind the kernel. Holds and caps stop spend before dispatch, and the rail's outcome is observed and recorded as a SettlementStatus. A starting layout:

• Allowlist providers. Each method names the processors or networks it speaks to and refuses the rest; add one after legal, security, and compliance review. Web3 uses Base first, with Arbitrum as a limited secondary.
• Pin custody. Each CapitalExecutionRail carries a custody_provider_id, and tooling refuses a settlement whose rail and dispatched custody differ.
• Pin chains by id. Web3 rails name a chain_id, preferably a CAIP-2 id, instead of a network name.

4. Size facilities, bonds, and coverage

A facility caps total exposure for an agent or a class of agents. Size it from expected volume (the exposure ledger's settled_units over the last 30 days), the reputation band, and the rail's observed settlement latency. With USD 100 per day, a three-day settlement horizon, and a 1.5 buffer, a policy selects a USD 450 ceiling; the horizon and buffer are the operator's assumptions, reviewed against outstanding exposure and utilization.

Require a bond, operator-funded collateral, when a capability touches a high-risk class, when an agent has no track record yet, or when a counterparty contracts for recourse. Require coverage per capability, per tool, or per jurisdiction where law mandates it, as in financial services and healthcare; issuance refuses a class the agent cannot evidence. The values each decision takes are in the reference tail, and Credit facilities, Underwriting, and Liability market cover each decision.

5. Onboard a partner with its card

The partner sends its partner card. Adding it pins the partner's kernel key; the default cross-organization transport is HTTPS with mTLS or signed bodies.

chio partner add partner-card.json --name partner

partner    did:chio:z6MkpA7…c2T, named partner
kernel     9b07…d31c, pinned from its card

You should see your partner's DID and its kernel key pinned from the card. Agree a small treaty naming the capability classes, jurisdictions, and rails in scope; each kernel admits under its own policy.

Run a Sandbox round-trip before a production rail, and agree in writing how either side revokes: revoking the treaty ends every grant issued under it, delegated ones included, and Bootstrap federated trust wires that procedure into revocation. Bilateral receipts lets each side read the other's receipts in scope.

6. Exercise a call, a refusal, and the export

Run one admitted call and one deliberately refused call through the application (an outside buyer's quote, and a refund the buyer's grant does not cover), then export the records and verify them against the kernel key your trust file pins.

chio evidence export --admin-all --output ./audit
chio evidence verify --input ./audit

verified   2 receipts, 1 checkpoint, kernel larkfield
trust      ~/.chio/trust.toml

You should see both receipts verify, the refused one with no tool effect. Retrieve them from the durable stores, bilateral records included when the application depends on them. The admitted call's instruction and the rail's observation name the same amount, currency, and parties.

Billing projects chio.billing-export.v1 through create_billing_export, the audit APIs return a signed chio.regulatory.receipt-export.v1 view, and Reconciliation resolves each hold against its observed cost. For governed parameters, inspect the resolved fiscal schedule and its sequence, and test the stale-anchor path.

Signing keys rotate without an outage

The kernel signs receipts and operators sign tool manifests, with keys in OS key custody (credential: or systemd-creds on headless hosts, Keychain or Secret Service on desktops), behind remote signing, or in hardware custody; plaintext seed files are for development.

• Rotation. Authority key history keeps receipts signed before the rotation verifiable, so verifiers accept the new key without losing the old one. Distribute the replacement through the verifier's trusted channel first.
• Revocation. Remove a compromised key from admission and verification trust. The revoked private key can still sign, so review records signed inside the compromise window against the retained evidence.
• Recovery. Restore signing material from an authorized backup, or provision a replacement and update trust explicitly.

Rotate keys and revoke walks both procedures.

A cadence keeps settlements, exports, and ceilings current

The watchdog scheduler runs settlement watchdog jobs on cron and the settlement executor carries out payment instructions. The reviews below are the operator's; adapt the frequencies to the deployment.

Stalled settlements, disputed claims, and ended partnerships each recover from their records

A settlement stays pending

Signal. A watchdog alert, or a dead-lettered row in chio settle status. Cause. The rail's outcome is pending, failed, or unknown. Action. Locate the dispatch, its instruction, and the latest rail observation; assess_watchdog_execution compares the reported execution with the job's expected state fingerprint, timing, and operator override. An unknown outcome is never dispatched again: query the rail, reconcile, and prepare an authorized retry or refund only when the rail's checks permit it. Retain the instruction, observation, and reconciliation result with the incident.

A claim is disputed

Signal. A provider response contests a covered loss. Action. Separate a disputed coverage decision from an unmatched payment observation, then use the claim record commands to submit the package, response, dispute, or adjudication with its signed inputs. An award that authorizes payment produces a payout instruction, which is tracked through observation and reconciliation like any other payment.

A partnership ends

Signal. A partner is compromised or the agreement ends. Action. Revoke the treaty; every grant issued under it ends, and the live revocation feed carries the change to each verifier. Confirm that a new call under a withdrawn grant is refused, then reconcile work already dispatched under its rail contract, since revocation ends future access and leaves completed transfers to reconciliation. Retain the receipts already signed, the keys needed to verify them, and the withdrawal record. Relationship changes and interrupted exchanges cover each side's part.

Configuration layers and issuance tiers

Next: choose the rail for your first counterparty