Skip to main content
Status: Draft (Retroactive — code-first) Type: Standards Track Category: Core Created: 2026-05-11 Requires: CIP-2 (Off-Chain Compute), CIP-3 (Dual-Metered Gas), CIP-18 (Payments) — wire-format alignment Companions: CIP-7 (Stream Protocol) — independent feed usage billing
Cowboy Cloud and Cowboy Chain. This CIP specifies the Cowboy protocol. Cowboy Cloud runs on this protocol today. Cowboy Chain, a public network on the same protocol, is under consideration for a future release. Where the two differ, this CIP says so.

1. Abstract

This CIP retroactively specifies the MPP Session protocol that has been committed to code as SESSION_ACTOR = 0x0C along with full Rust-side handler scaffolding and runner-side voucher library. The session protocol implements the Session mode of the IETF Machine Payment Protocol (MPP) — the wire complement to MPP’s intent="charge" mode covered by CIP-18. Where CIP-18 covers single-call payments (HTTP request → 402 → credential → settle, one chain tx per call), CIP-8 covers high-frequency micro-billing — typical for LLM token streaming, paid HTTP/MCP loops, or long-lived AI sessions — where the payer opens an on-chain escrow once, exchanges payer-signed accumulating SessionVouchers off-chain with the Runner over an arbitrary number of micro-calls, and settles on-chain in three transactions (Open + Settle + Finalize) instead of N. This CIP is retroactive: code precedes specification. The intent here is to capture and ratify what is already deployed as a PoC, close the spec-vs-code gap surfaced in wiki/drift.md V-11 / V-12 / V-13, and provide a stable normative reference for follow-on work (dispute mechanism, cross-chain bridges, CIP-20 fungible-token sessions, fiat rails).

Dependencies

The Requires header lists the hard dependencies; this subsection pins the precise revision and the specific surface each one is leaned on, so a reviewer can see the full chain at a glance and knows not to ratify CIP-8 ahead of them: CIP-7 (Stream Protocol) is a companion, not a dependency — it defines feed delivery and provider-reported cumulative usage settlement, with separate authorization and no shared on-chain state with CIP-8.

2. Motivation

CIP-18’s intent="charge" flow requires one HTTP round-trip per request and one PaymentGate settle per request. For high-frequency machine-to-machine workloads — agent A streaming LLM tokens from agent B, an MCP tool loop, a metered HTTP API consumed in a tight loop — this is too coarse:
  • Each call carries challenge / verify / settle overhead.
  • Per-call settle generates one chain tx; an 8-hour LLM session can generate millions.
  • Failure mid-session leaves accounting ambiguous unless restart-safe.
The MPP Session model — already in production for Stripe + Tempo Labs IETF submissions — solves this by:
  1. Escrow once. Payer locks max_amount (a session ceiling) on chain at OpenSession. This is the upper bound on what the runner can ever extract.
  2. Cumulative voucher off-chain. Each off-chain call returns a payer-signed EIP-712 SessionVoucher with a monotonically increasing cumulative_amount — the total owed for the session up to and including this call. The latest voucher fully supersedes all previous ones; restart-safe.
  3. Batch on-chain settle. Runner submits the latest voucher (any time, or periodically, or at end) via Settle. PaymentGate-style splits apply: 89% runner, 10% burn, 1% treasury.
  4. Close + dispute window + Finalize. Payer (or contract on expires_at_block) triggers Close → opens dispute window → Slash available within window → after DISPUTE_WINDOW_BLOCKS=75 blocks, Finalize returns unused (max_amount - spent) to payer.
End-to-end: 3 chain tx + N off-chain HTTP, vs. CIP-18 charge mode’s N chain tx + N off-chain HTTP.

3. Why This CIP Is Retroactive

The MPP Session research (refs/runner/2026-04-28_MPP_Session_Research.md) and implementation plan (refs/plans/2026-05-06_mpp_session_implementation.md) were intended to be a PoC. However:
  1. The v2 CIP alignment round (2026-04-21) had not yet drafted a Session model — the payments proposal then excluded streaming metered billing; the current CIP-18 §3 still excludes within-request streaming billing.
  2. The PoC went directly to code: the SESSION_ACTOR = 0x0C allocation, six on-chain handlers, a full off-chain voucher library and the EIP-712 domain were all implemented before this specification.
  3. The v2.r2 system actor sequence (May 2026) accepted 0x0C = SESSION_ACTOR and renumbered CIP-14 v2 / CIP-10 v2 / CIP-18 around it, rather than asking the code to relocate.
This CIP therefore formalizes what code already does. It supersedes both the MPP Session research/plan documents and wiki/concepts/mpp-session.md (which now points here for the normative spec).

4. Architecture


5. Address & Storage

5.1 System Actor

(Declared in wiki/entities/system-actors.md.)

5.2 Storage layout

Sessions persist under SESSION_ACTOR’s actor-KV at key:
Vouchers are never stored on chain. They live only:
  • in the payer’s off-chain wallet (last-signed)
  • in the runner daemon’s local cache (latest received per session)
Only the most recently Settle-d voucher’s cumulative_amount and nonce survive on-chain, as fields of the Session record.

6. On-Chain Types

6.1 Session record

The record is:

6.2 SessionStatus

The terminal states (Settled / Refunded / Slashed) accept no further handlers. Disputed is transient and is resolved by the existing CIP-2 Result Verifier (0x03) + commit-reveal mechanism (see §11).

6.3 SessionId

The payer supplies session_id on OpenSession. The handler verifies !exists(session_id) and rejects collisions. nonce is a payer-chosen u64 — typically a monotonic counter inside the payer wallet, but anything that avoids collision with prior (payer, runner) sessions is acceptable.

6.4 SessionAsset

PoC implementation only supports Cby. Cip20(...) is a typed placeholder — handlers reject it with ExecutionError::Unsupported until follow-on work wires it in.

7. Off-Chain Types

7.1 SessionVoucher

The voucher is:
Cumulative semantics. cumulative_amount is the total the payer owes the runner across all calls in the session up to and including the call that produced this voucher. It is monotonically increasing across vouchers for a given session_id. The latest voucher therefore fully replaces all previous ones — a power-on idempotency property: if the runner crashes and loses prior vouchers but keeps voucher_k, settling voucher_k captures everything voucher_ would have settled. Nonce. Strictly increasing per session. The on-chain Settle handler rejects any voucher with nonce <= session.last_voucher_nonce. Combined with cumulative monotonicity this prevents replay across nonces. Expires_at. Block-height ceiling. Settle reverts after current_block > expires_at. Forces fresh vouchers if the runner sits on stale ones. Usage_digest. Opaque to chain. Off-chain it is keccak256(canonical(usage_log)) where usage_log is whatever the runner and payer agree on (LLM token counts, HTTP byte counts, MCP tool-call counts). The chain never inspects it; downstream auditing tools may.

7.2 EIP-712 domain

The domain is:
SESSION_ACTOR_ADDR is the 20-byte form of SESSION_ACTOR = 0x0C (19 zero bytes + 0x0C). The voucher typehash uses the canonical EIP-712 type string:
Every slot signs this same digest. The trusted current account policy must authorize the recovered indexed keys at signature.policy_revision; an address-derived account uses revision zero and exactly one entry at index zero. Route session reports instead carry the zero account, revision zero and one metering-key-authorized slot.

8. Handlers (six)

The handlers below are SystemInstruction opcodes 52–57 (SessionOpen through SessionSlash), executed by SESSION_ACTOR=0x0C; §12 gives their encodings and also lists opcode 58.

8.1 OpenSession

8.2 Deposit

8.3 Settle

Settlement fully reuses the CIP-2 SettlementConfig split — there is no separate payout template.

8.4 CloseSession

Settle continues to work during Closing so the runner can flush any final voucher.

8.5 Finalize

8.6 Slash (deferred)

Slash is the dispute hook. PoC is no-op; the design space is the same as CIP-2’s existing N-of-M consensus + slashing path; integration is follow-on work (V-12 follow-up).

9. Settlement Reuse

Settlement on Settle (§8.3) uses SettlementConfig from GOVERNANCE_SYSTEM_ACTOR=0x09 exactly as CIP-2 runner job settlement does. The same SettlementConfig{runner_percent, burn_percent, treasury_percent} value (default 89/10/1) governs both paths. Governance updates via UpdateSettlementConfig propagate automatically to both single-job and session settle paths. The CIP-14 §9.7 target_pool enum does apply to MPP Session settlement: the implicit pool is MAIN. A future revision may introduce target_pool: SESSION if session-specific economics emerge (e.g. different runner/burn split for high-frequency vs. coarse jobs).

10. Relationship to Other CIPs

vs. CIP-18 (Payments)

Orthogonal but complementary: A future revision may unify them at the wire layer (both share intent="charge" for the per-voucher cumulative semantics, just at different rates).

vs. CIP-2 (Off-Chain Compute / Runners)

Reuses all of CIP-2:
  • Runner registration (Runner Registry 0x01) is a precondition for OpenSession (the runner must be registered).
  • Result Verifier (0x03) is the dispute path’s settle/slash arbiter (future).
  • VRF runner selection does not apply — MPP Session picks runners by URL (off-chain DNS-addressable agent endpoints), not VRF.

vs. CIP-7 (Stream Protocol)

Orthogonal — both can coexist on the same actor: The CIP-7 replacement retires the old Stream Key Manager at 0x0D and permanently reserves the address. It does not reuse CIP-8 vouchers or introduce a new SessionActor funding mode.

vs. CIP-14 v2.r2 / CIP-15 v2.r2 (Ingress)

MPP Session lives off the CIP-14/15 Gateway path. A runner with a public HTTP endpoint may itself sit behind a Cowboy Gateway (CIP-14 ingress.http entitlement + ROUTE_REGISTRY 0x0E) for DNS addressability, but the session wire — voucher exchange + Settle / Finalize tx — does not pass through the Gateway. CIP-19’s MCP ingress similarly handles per-tool-call payment via CIP-18; a session-mode MCP loop would be an MCP client persisting outside the Gateway scope.

11. Dispute Mechanism

PoC: the Slash handler returns ExecutionError::Unsupported. Future activation maps the dispute to CIP-2’s existing N-of-M commit-reveal:
The CIP-2 verification path is unchanged — MPP Session is layered on top.

12. Opcode / SystemInstruction question (V-12 closure)

The session handlers are SystemInstruction variants with the numeric codec assignments below. The rest of the System numbering is in CIP-13 §1. Session operations and any future additions MUST NOT reuse an occupied numeric assignment; no open-ended range is free. An instruction is u8 0x00 (System) ‖ u8 opcode ‖ args, with args in the order listed. Integers are fixed-width big-endian, Address is 20 raw bytes and [32]u8 is raw. Lengths are canonical unsigned varints (varint). Decoders reject unknown tags, out-of-bound counts and trailing bytes. SessionOpenAssigned names a model instead of a runner, and the chain draws the runner. model is UTF-8 of at most 256 bytes. n ≤ 8. signer_tag is 0 (none) or 1 (a 20-byte address follows). AccountSignature is the CIP-40 §7.1 encoding. Every slot must satisfy SECP256K1_EIP712_OBJECT_POLICY (§13), or decoding fails. A single-key voucher (revision 0, one slot at index 0) is 188 bytes.

13. EIP-712 chainId source (V-13 closure)

The domain type is exactly EIP712Domain(string name,string version,uint256 chainId,address verifyingContract,bytes32 salt). Every producer obtains the real Cowboy chain_id and chain_instance_id from CIP-40’s closed /chain-info object, and the verifier takes them from the running chain’s trusted identity. There is no separate session chain ID or chain-ID-1 constant. verifyingContract separates Session-actor vouchers from Trading Post per-call receipts; salt = chain_instance_id separates repeated geneses. Vouchers and route session reports use SignatureSlot under SECP256K1_EIP712_OBJECT_POLICY: algorithm 1, mode 1, no public key, low-S, 65-byte r ‖ s ‖ v with v in {0,1}. Verification consumes the final 32-byte EIP-712 digest via SignedMessage::Eip712Digest, without another hash or native object frame. All producers and consumers build the domain from the trusted chain identity.

14. Security Considerations


15. Reserved Paths / Names

None at this layer. MPP Session is fully off-chain on the runner side; the on-chain surface is SESSION_ACTOR=0x0C actor messages only. If a future CIP introduces a discovery path (e.g. /_cowboy/session/{session_id} for clients to query session status via Gateway), that path will be reserved in a follow-on CIP.

16. Future Work

  • Slash activation. Wire dispute resolution to CIP-2 Result Verifier; deploy chosen verification mode (default MajorityVote).
  • SessionAsset::Cip20 activation. Enable CIP-20 fungible-token sessions (stablecoin micro-billing).
  • Cross-chain session bridge. Pair with CIP-25 cross-chain mailbox to allow Cowboy-anchored session escrow with off-chain runners on other chains.
  • TEE attestation integration. Composite attestation from CIP-23 v2 may be offered as a tighter verification mode for premium session classes.
  • Wire convergence with CIP-18. Consider unifying MPP intent="charge" cumulative-voucher semantics under a shared intent="session" registration; would require IETF coordination.
  • target_pool: SESSION discriminant. If session economics warrant a different runner/burn split, add to the SettlementConfig.target_pool enum.
  • Indexer-friendly events. The session events form the basis of off-chain billing indexers. Each payload is a raw concatenation with fixed-width big-endian integers and no length prefixes: asset_tag is 0 for Cby and 1 for Cip20. signer is the key that signs the session’s vouchers: the payer, or the signer a SessionOpenAssigned names. refund is 0 when nothing was unspent.

17. Backwards Compatibility

Strictly additive. SESSION_ACTOR = 0x0C was previously unallocated in v1 CIP space; this CIP ratifies code’s allocation. No existing on-chain actors, RPCs, or PVM syscalls are modified. Actors without active sessions are unaffected. Runners opt in by implementing the session voucher exchange; runners not implementing session voucher exchange continue to operate on the CIP-2 single-job path unchanged.

18. References

  • refs/runner/2026-04-28_MPP_Session_Research.md — research origin (superseded by this CIP for normative claims)
  • refs/plans/2026-05-06_mpp_session_implementation.md — implementation plan (superseded for normative claims)
  • IETF MPP draft draft-ryan-httpauth-payment — wire-format ancestry
  • CIP-2 §5 — Runner registration / settlement (reused)
  • CIP-3 — Dual gas (orthogonal; session settle is paid by tx submitter, not metered against session escrow)
  • CIP-18 — sibling Payments CIP (charge mode)

Retroactive note. If code changes after this CIP is approved (e.g. handler signature evolution, new asset variants, dispute activation), update this CIP via an r2 revision rather than starting a CIP-X v2. The v1 → v2 split convention (per CIP-14 / CIP-10 / etc.) is reserved for forward-looking redesigns; minor in-place revisions use rN suffixes only.