From 61518a4cdef4688e43298653a5d8aa64b537697d Mon Sep 17 00:00:00 2001 From: Greg Soucy Date: Fri, 22 May 2026 16:26:50 -0400 Subject: [PATCH] Add x402 to CLAS paid-action receipt design doc --- .../x402-commandlayer-receipts.md | 270 ++++++++++++++++++ 1 file changed, 270 insertions(+) create mode 100644 docs/integrations/x402-commandlayer-receipts.md diff --git a/docs/integrations/x402-commandlayer-receipts.md b/docs/integrations/x402-commandlayer-receipts.md new file mode 100644 index 0000000..4a648a6 --- /dev/null +++ b/docs/integrations/x402-commandlayer-receipts.md @@ -0,0 +1,270 @@ +# x402 → CommandLayer Paid-Action Receipt Integration Design + +## 1. Overview + +This document defines a **documentation-only** integration design for representing x402 paid HTTP/API actions as CommandLayer-signed CLAS action receipts. + +The integration separates two concerns that are often conflated: + +1. **Payment settlement attestation (x402 domain)**: whether a payment requirement was negotiated, presented, and accepted under x402-compatible rules. +2. **Execution attestation (CommandLayer domain)**: what action was requested, what runtime executed, and what result was produced, with CLAS `metadata.proof` and signature evidence. + +No production x402 implementation is included here. + +## 2. Why x402 matters for CommandLayer + +x402 introduces a standard interaction model for paid HTTP/API actions. For CommandLayer, this matters because it enables: + +- explicit pre-execution payment gating for premium actions, +- uniform expression of payment requirements and acceptance state, +- deterministic mapping from paid request context to signed CLAS receipts, +- portable post-execution verification using CommandLayer signatures and VerifyAgent. + +x402 improves economic coordination for APIs, while CommandLayer preserves verifiable agent/runtime execution semantics. + +## 3. Trust boundary + +### Boundary A: client ↔ x402 payment negotiation/settlement + +- Covers payment requirement discovery, payment submission, and settlement acceptance/rejection. +- Establishes whether payment conditions were met for a specific paid action request. +- Trust result: "payment was accepted/rejected under the configured x402 provider flow." + +### Boundary B: CommandLayer runtime execution + receipt signing + +- Starts after the runtime decides a paid action is authorized to execute. +- Covers action input capture, execution outcome capture, and CLAS receipt signing. +- Trust result: "CommandLayer attests what executed and what result was returned." + +**Important**: + +- x402 payment proof is **not** a CLAS action receipt. +- x402 does **not** prove that the agent/runtime executed the action correctly. +- Public third-party verification begins when CommandLayer emits a signed CLAS receipt. + +## 4. Paid-action lifecycle + +1. **Client requests paid action**. +2. **Server returns `402 Payment Required`** with x402 payment requirements. +3. **Client pays through x402** and resubmits proof/payment context. +4. **Server verifies/accepts payment** using configured x402 provider adapters. +5. **Agent/runtime executes action** under CommandLayer policy. +6. **CommandLayer emits signed receipt** containing execution and payment linkage metadata. +7. **VerifyAgent verifies receipt** (signature integrity, policy checks, trace coherence). + +## 5. CLAS receipt shape + +A CLAS paid-action receipt should encode execution truth plus payment linkage, while keeping payment settlement and execution proof semantically separate: + +```json +{ + "receipt_id": "rcpt:clas:act_01JW7R6Y8W8JQ5H7GH2D0P0F8N", + "action": "summarize.text", + "status": "succeeded", + "requested_at": "2026-05-22T12:00:00Z", + "executed_at": "2026-05-22T12:00:02Z", + "result": { + "summary": "Short technical summary..." + }, + "metadata": { + "trace": { + "request_id": "req_9f2f5f25", + "payment_id": "pay_x402_7f31", + "provider": "x402-compatible", + "workflow_id": "wf_2a10" + }, + "proof": { + "payment": { + "scheme": "x402", + "settlement_status": "accepted", + "payment_ref": "pay_x402_7f31" + }, + "execution": { + "runtime_id": "rt_prod_1", + "agent_id": "agent_summarizer_v3", + "policy_hash": "sha256:ab12..." + } + } + }, + "proof": { + "signature": [ + { + "role": "runtime", + "alg": "Ed25519", + "key_id": "cl_runtime_key_2026_01", + "sig": "base64..." + } + ] + } +} +``` + +## 6. `metadata.trace` usage + +`metadata.trace` provides correlation fields across request ingress, payment processing, execution, and verification. + +Recommended minimum fields: + +- `request_id`: idempotency/correlation anchor for the paid action attempt, +- `payment_id`: x402 payment correlation identifier, +- `receipt_id`: CLAS artifact identifier (may also appear top-level), +- `workflow_id` or equivalent runtime correlation identifier. + +Guidelines: + +- include stable identifiers, not secrets; +- avoid raw private keys, bearer tokens, or full card/wallet secrets; +- keep trace values deterministic enough for replay analysis and duplicate detection. + +## 7. `proof.signature` roles + +CommandLayer supports single-signature and multi-signature role entries. For paid actions, roles may include: + +- `user`: indicates end-user assent or request signing (optional). +- `payer`: indicates payer-side cryptographic attestation where available (optional and provider-dependent). +- `agent`: attests agent-level transformation/decision output. +- `runtime`: attests execution envelope and canonical receipt emission. +- `verifier`: attests post-hoc verification outcome in derived or companion receipts. + +Role notes: + +- Minimum public-verification baseline is usually a valid `runtime` signature. +- Multi-signature receipts should preserve explicit role labeling to avoid signature ambiguity. + +## 8. Example: paid summarize action + +### Paid action request + +```json +{ + "request_id": "req_9f2f5f25", + "action": "summarize.text", + "input": { + "text": "Long technical document..." + }, + "payment": { + "required": true, + "plan": "pro", + "max_amount": "0.05", + "currency": "USD" + } +} +``` + +### Payment accepted event + +```json +{ + "event": "payment.accepted", + "request_id": "req_9f2f5f25", + "payment_id": "pay_x402_7f31", + "provider": "x402-compatible", + "settled_amount": "0.05", + "currency": "USD", + "accepted_at": "2026-05-22T12:00:01Z" +} +``` + +### CLAS receipt after execution + +```json +{ + "receipt_id": "rcpt:clas:act_01JW7R6Y8W8JQ5H7GH2D0P0F8N", + "request_id": "req_9f2f5f25", + "payment_id": "pay_x402_7f31", + "action": "summarize.text", + "status": "succeeded", + "result": { + "summary": "Short technical summary..." + }, + "proof": { + "signature": [ + { + "role": "runtime", + "alg": "Ed25519", + "key_id": "cl_runtime_key_2026_01", + "sig": "base64..." + } + ] + } +} +``` + +## 9. Example: paid verification call + +A verifier-facing flow can be payment-gated while still yielding a CLAS-verifiable output artifact: + +1. Client requests `verify.receipt` for a target receipt. +2. Service returns `402` with verification pricing requirements. +3. Client completes x402 payment flow. +4. Service executes VerifyAgent and/or runtime verification. +5. Service returns verification result plus signed verification receipt. + +Illustrative response payload: + +```json +{ + "action": "verify.receipt", + "target_receipt_id": "rcpt:clas:act_01JW7R6Y8W8JQ5H7GH2D0P0F8N", + "verification": { + "status": "valid", + "checks": ["signature", "trace_consistency", "policy_constraints"] + }, + "proof": { + "signature": [ + { + "role": "verifier", + "alg": "Ed25519", + "key_id": "cl_verify_key_2026_01", + "sig": "base64..." + } + ] + } +} +``` + +## 10. Failure modes + +- **payment missing**: no valid payment context after `402` requirement; action is not executed. +- **payment invalid**: payment proof fails provider validation; action is not executed. +- **payment accepted but action failed**: receipt should record `status: failed` with structured error outcome. +- **action executed but receipt signing failed**: execution occurred but no portable attestation; must emit internal critical event and retry/compensate. +- **duplicate payment/action request**: idempotency logic must prevent duplicate execution and duplicate receipts. +- **verifier unavailable**: verification action cannot complete; return explicit retriable/unavailable state. + +## 11. Idempotency + +Use three distinct identifiers: + +- `request_id`: semantic action-attempt identity. +- `payment_id`: settlement identity in x402 provider domain. +- `receipt_id`: CLAS attestation artifact identity. + +Recommended constraints: + +- one `request_id` maps to at most one canonical execution outcome; +- one accepted `payment_id` is bound to one request scope/policy scope; +- one canonical execution outcome maps to one canonical `receipt_id` (retries should not fork receipt truth). + +## 12. Settlement vs execution proof + +Settlement proof answers: **"Was payment accepted for this request scope?"** + +Execution proof answers: **"What action executed, under what runtime context, with what result?"** + +Design rule: keep these proofs linked but non-substitutable. A valid payment signal is insufficient to claim execution correctness; a valid execution receipt does not imply payment settlement unless explicitly linked. + +## 13. Future integration with Coinbase AgentKit / Agentic Wallet + +Future adapters may use Coinbase AgentKit or Agentic Wallet primitives as one x402-compatible payment backend. In that model: + +- AgentKit/Wallet tools can originate payer intents and settlement references. +- CommandLayer still owns canonical action execution receipt emission. +- Provider abstraction remains open so non-Coinbase x402-compatible providers can be added without changing CLAS receipt semantics. + +## 14. Non-goals + +- This design does **not** claim CommandLayer settles payments. +- This design does **not** claim x402 alone proves agent/runtime execution. +- This design does **not** require Coinbase/CDP as the only x402 provider. +- This design does **not** introduce production x402 runtime code in this change.