Settlement

Settlement is how Covenant accounts for resource consumption. The model is intentionally split: every action that consumes resources writes a local receipt; receipts are batched and flushed to the on-chain settlement program; once flushed, receipts are reconcilable from chain state alone.

Receipt

SettlementReceipt {
  id:               uuid,
  payer:            AgentId,            // who consumed resources
  resource:         "memory" | "compute" | "tool" | "egress",
  credits_consumed: u64,
  settled_at:       u64,                // unix milliseconds
  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" 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.

Flushing on-chain

The on-chain side is a single Anchor program for Solana. It exposes three instructions:

• 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 daemon batches off-chain receipts and submits them via consume_credits. Once the on-chain transaction confirms, the receipt's onchain_sig is populated with the signature; from that point the receipt is reconcilable from chain state alone.

Buyback

Credits are minted in exchange for burned tokens. The mint side burns; the consume side destroys. Net circulating supply contracts as the system is used. The buyback shape leans on the on-chain program to prevent simultaneous mint and consume races and to bind credits to a single authority per cluster.

Storage layout

Reading recent receipts

covenant receipts recent --limit 20
# Or via HTTP:
curl -s 127.0.0.1:8421/receipts/recent?limit=20 | jq

Verification

covenant verify cross-checks memory writes against settlement receipts: a successful memory write that did not produce a receipt (or the reverse) shows up as drift. The daemon is fail-soft on receipt write — a failed receipt does not cancel the memory write — so drift here is the most common operator-visible signal of a settlement-side bug.

Implementation status

Off-chain receipts are live. The on-chain Anchor program is scaffolded and emits structured events; the SPL token CPIs and oracle wiring are gated on a downstream change. Receipts carry onchain_sig: null until the on-chain side is fully connected.

Related

• Architecture — the on-chain program in the broader system map.
• Identity and keys — the same key signs settlement transactions and capability grants.
• Audit log — settlement receipts pair 1:1 with memory writes; drift shows up here.