Settlement

Settlement is how Covenant accounts for resource consumption. Today the daemon writes local receipts. The future on-chain path batches those receipts into the Solana settlement program once the authority, mint, oracle, and reconciliation flows are ready.

Receipt

SettlementReceipt {
  id:               uuid,
  payer:            AgentId,            // who consumed resources
  resource:         "memory" | "compute" | "tool" | "message" | "registration",
  credits_consumed: u64,
  settled_at:       u64,                // unix milliseconds
  memory_record_id: uuid | null,        // set when resource == "memory"
  onchain_sig:      string | null       // populated when flushed on-chain
}

Receipts accumulate in $COVENANT_HOME/receipts/working.jsonl. The daemon writes one receipt per resource event — for example, every memory write produces a receipt with resource = "memory", memory_record_id, and credits_consumed proportional to bytes written.

Credit pricing

Each resource kind has a pricing function that maps the underlying unit (bytes, milliseconds, calls) to credits. The pricing functions are deliberately simple and live in one place, so operators can audit them at a glance and downstream integrations can replicate the math without a dependency.

The default for memory writes is one credit per kilobyte (round up). Compute, tool calls, and egress have their own pricing functions that compose the same way.

Future on-chain flush

The planned on-chain side is an Anchor program for Solana. Its scaffold exposes three instruction shapes:

• initialize — one-shot setup of a Config PDA under seed b"settlement-config"; records the authority, mints, and rates.
• mint_credits(amount_covnt) — exchange burned tokens for credits at the configured rate.
• consume_credits(amount) — destroy credits at the point of consumption (memory write, tool call, etc.).

The intended production flow is for the daemon to batch local receipts and submit consumption to the program. Once an on-chain transaction confirms, the receipt's onchain_sig can be populated with the signature. This is a planned reconciliation path, not deployed behavior.

Planned economic model

The target model is credits minted against an external payment input, credits consumed at resource-use time, and treasury policy that can route a portion of inflows toward buyback or provider payout. Those mechanics require oracle integration, mint authority decisions, and deployment review before they should be treated as operational.

Storage layout

Reading recent receipts

covenant chain status --json
covenant receipts recent --limit 20 --json
covenant chain flush-receipts --limit 20 --json
covenant chain receipt-batches --limit 20 --json
# Or via HTTP:
curl -s 127.0.0.1:8421/receipts/recent?limit=20 | jq

Verification

covenant verify --json cross-checks memory writes against settlement receipts by memory_record_id when the receipt carries one, with owner/resource count fallback for older rows. Missing, duplicate, orphaned, or wrong-payer correlations surface as drift. The daemon is fail-soft on receipt write — a failed receipt does not cancel the memory write — so drift in this dimension is the principal operator-visible indicator of a settlement-side fault.

Release

Local receipts and recent-receipt reads are implemented. On-chain settlement is planned and scaffolded; it is not production and should not be described as deployed.

Related

• Architecture — the settlement scaffold in the broader system map.
• Identity and keys — the same local identity signs capability grants today and is the planned signer boundary for future settlement transactions.
• Audit log — settlement receipts pair 1:1 with memory writes; drift shows up here.