Operating an Economy

Every decision below is the operator’s, and none of them is expressed in one file. Rail allocation, facility ceilings, and bond requirements are policy an operator sets against the shipped types; reputation ceilings live in a HushSpec policy extension; guard and adapter wiring lives in chio.yaml. The crates the decisions land in are chio-credit for rails, facilities, and bonds, chio-market for coverage, chio-federation for peering, and chio-control-plane for the materialized issuance policy.

The loop, stage by stage

One governed call passes through these stages. Each names the object it produces and the page that owns it.

Choosing settlement rails

Operators commonly use several settlement methods. Choose the method per counterparty. A starting layout:

The full rail catalog is on Settlement Rails; the on-chain specifics are on On-Chain Settlement.

Provider allowlists

Each settlement method has an allowlist. API methods name payment processors; Web3 methods name on-chain networks, where the official chain set uses Base first, with Arbitrum as a limited secondary. The operator's configuration names the providers it will speak to and rejects everything else. Three principles:

• Allowlist by default. Add a provider only after the legal, security, and compliance review is complete. Do not let configuration drift add a settlement method.
• Pin custody providers. Each CapitalExecutionRail carries a custody_provider_id; tooling treats that as the authoritative name and refuses settlements where the rail and the dispatched custody do not match.
• Pin chains by id, not name. Web3 deployments use the chain_id field, not a human-readable network name. CAIP-2 ids are the safest pattern.

Sizing credit facilities

A facility caps total exposure across an agent or a class of agents. The configuration is covered in detail on Credit Facilities; the operating question is how to size the ceiling.

Three inputs:

1. Expected volume. Take the historical receipt rate and project forward. The exposure ledger's settled_units column over the last 30 days is the most honest baseline.
2. Reputation band. Higher reputation tiers get higher ceilings; new agents start at the lowest tier. Bands are policy, not free numbers; they should be documented and reviewed quarterly.
3. Settlement latency. The slower the rail, the more headroom the facility needs. ACH-settled agents can see two to three days of in-flight exposure that a Web3 agent would have already settled.

A starting rule is: ceiling = projected daily volume × max-settlement-latency-days × 1.5. The 1.5 multiplier allows for spike days. Review the ceiling quarterly against actual utilization.

Bond requirements

Bonds are operator-funded collateral held in ChioBondVault (on-chain) or in custodial accounts (off-chain). They are not insurance; they are operator collateral for higher-risk capabilities.

Require a bond when:

• The capability touches a high-risk class (financial trades, medical advice, system-of-record writes). The risk class lives in the underwriting decision.
• The agent is new and has no track record; require a bond as a probationary measure that can drop after N successful settled calls.
• The counterparty has explicitly contracted for it (some enterprise integrations require recourse against operator collateral).

Bond size is set at issuance; each disposition change is a signed CreditBondDisposition from chio-credit (Lock, Hold, Release, Impair). The watchdog drives expiry and renewal automation.

Insurance gates

LiabilityCoverageClass in chio-market is the vocabulary both sides of a coverage decision use: tool_execution, data_breach, financial_loss, professional_liability, and regulatory_response. A provider policy lists the classes it covers per jurisdiction, and is refused when that list is empty or repeats a class; a quote and a binding each name exactly one. Which capabilities require which class, and what happens when one is absent, is the operator’s to place:

• Per-capability. The capability names the classes it requires, and issuance refuses one the agent cannot evidence.
• Per-tool. A single tool carries its own requirement even when its capability does not, so a database write can demand data_breach on its own.
• Per-jurisdiction. When a rail's jurisdiction or the agent's home jurisdiction mandates specific coverage by law (financial-services jurisdictions, healthcare jurisdictions).

Coverage details are on Liability Market.

Federation peer onboarding

Bringing a new bilateral peer online has a stable workflow:

1. Exchange kernel public keys. Both operators publish their kernel signing key fingerprints over a side-channel (signed PDF, in-person, registered domain).
2. Negotiate scope. Agree on which capability classes, which jurisdictions, and which settlement rails are in-scope for the peering. Smaller is safer.
3. Stand up the bilateral receipt channel. Each operator can read the other's receipts for capabilities in scope. See Bilateral Receipts.
4. Configure the rail. Either share an on-chain escrow contract address or stand up a dedicated rail per peer. The pinned chain id prevents drift.
5. Run a sandbox round-trip. Use the Sandbox rail to verify cooperative settlement before enabling a production settlement method.
6. Document revocation. Both sides must agree in writing on the procedure if either party needs to revoke peering. The agreed procedure is the bootstrap for the Bootstrap Federated Trust guide's revocation hooks.

Signing keys and manifest signing

The kernel signs receipts; operators sign tool manifests. Both depend on the operator’s key-management system:

• Storage. Receipt-signing keys live in an HSM, KMS, or equivalent. They do not appear in source control or environment variables.
• Rotation. Quarterly is a reasonable default; faster on incident. Rotation produces a new public key fingerprint that downstream verifiers must accept. Both old and new keys remain valid during the overlap window; new receipts use the new key, and old receipts retain verifiability.
• Revocation. A revoked key cannot sign new receipts or manifests. Old receipts signed by the revoked key remain valid (the receipt log is append-only) but should be flagged in audits.
• Backup and recovery. A tested recovery procedure is mandatory. Lost keys cannot be regenerated; the operator either recovers from backup or rolls out a new key and explicitly orphans the old fingerprint.

The tactical procedures are on Rotate Keys & Revoke.

Reputation and issuance ceilings

A composite reputation score decides which tier an agent falls in, and the tier carries a scope ceiling that issuance applies. Both the tiers and their ceilings are named by the operator, not by the crate. materialize_reputation_issuance_policy in chio-control-plane reads the reputation block of a HushSpec policy and produces a ReputationIssuancePolicy: the scoring config, three probationary values, and a list of tiers sorted by score range.

Three defaults apply when the scoring block omits them. probationary_receipt_count is 1000, probationary_min_days is 30, and probationary_score_ceiling is 0.60. The first two do double duty: whatever they resolve to also becomes the scoring model’s history_receipt_target and history_day_target, so raising the probation window also lengthens the history an agent needs before its depth component saturates.

The four tiers below are the ones the shipped example policy declares, with the ceilings it gives them. Monetary values are minor units, so units: 100 is one dollar.

Reputation covers the eight scoring weights and the decay model; Scorecards covers the credit-side bands and reason codes.

Compliance policy

Compliance policy answers: which jurisdictions, which evidence requirements per class, which framework mappings are operationally enforced.

• Jurisdictions. Pin per-rail. The optional jurisdiction field on CapitalExecutionRail is used by policy at decision time.
• Evidence requirements. High-risk classes require runtime-assurance evidence and may require human-in-the-loop approval. The kernel's policy schema declares this; the operator stands up the corresponding evidence producer.
• Framework mappings. Reference Compliance Frameworks for the canonical mappings to NIST AI RMF, EU AI Act, ISO 42001, and SOC 2; operationally, the operator picks which frameworks their deployment claims and stands up the evidence to support those claims.

Operating cadence

A typical cadence for a production operator:

Failure recovery patterns

Stuck settlement

1. Watchdog fires EscrowTimeout or FinalityObservation.
2. Operator inspects the recovery action: retry, refund, or manual review.
3. For a refund, dispatch prepare_escrow_refund with operator override.
4. For a retry, resubmit the dispatch under the same id; the watchdog's state fingerprint guards against duplicate execution.
5. Document the resolution in the exposure ledger so the audit trail is complete.

Claim dispute

1. Counterparty raises a dispute against a settled receipt.
2. Operator opens a claim per Claims.
3. Both sides exchange evidence (receipts, observed-cost meter records, rail-side proofs).
4. Outcome posts as a follow-up receipt and, if applicable, a refund or chargeback.

Federated revocation

1. Either side decides to terminate peering.
2. Both operators issue revocation receipts with the agreed effective time.
3. In-flight settlements either complete (if before the effective time) or fall back to per-operator terms (if after).
4. Bilateral receipt channels are closed; auditors receive the full revocation history on request.

Where each knob is configured

There is no single operator file. chio.yaml configures the runtime; a HushSpec policy configures issuance ceilings; rails, facilities, bonds, and coverage are constructed as typed values by the code that dispatches them. Knowing which is which matters because chio.yaml applies deny_unknown_fields to every section, so a key from the wrong layer is a parse-time error rather than an ignored line.

The issuance side is the one an economy operator edits most, and the repository carries a working example of it. The scoring block below sets the eight weights, the decay half-life, and the three probationary values; the tier that follows shows the ceiling shape every tier repeats.

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

Every struct behind that block forbids unknown fields. A tier requires score_range and max_scope, and ttl_seconds is the only required member inside the ceiling; every other field there defaults or may be omitted. Deployment shape is on Sidecar HTTP Service.

See also

Related documentation:

• Agentic Economy Overview
• Economy Stack
• Passports · Reputation · Scorecards
• Manifests · Underwriting
• Credit Facilities · Liability Market · Claims
• Settlement Rails · On-Chain Settlement · Reconciliation
• Bilateral Federation · Bilateral Receipts · Portable Reputation
• Compliance Certificates · Regulatory APIs
• Procurement Tour
• Configuration · Sidecar HTTP Service