Skip to content

Rewrite SDK around current receipt contract#23

Merged
GsCommand merged 2 commits intomainfrom
codex/rewrite-sdk-for-commandlayer-receipt-contract
Mar 22, 2026
Merged

Rewrite SDK around current receipt contract#23
GsCommand merged 2 commits intomainfrom
codex/rewrite-sdk-for-commandlayer-receipt-contract

Conversation

@GsCommand
Copy link
Copy Markdown
Contributor

Motivation

  • Align both TypeScript and Python SDKs to the current CommandLayer Commons receipt contract (v1.1.0) by removing mixed legacy assumptions and making the canonical receipt object the single source of truth.
  • Make request construction, receipt typing, verb extraction, and verification explicit and hard to misuse for new integrations.
  • Keep only minimal, clearly-labeled legacy compatibility (normalization of older blended envelopes) so the main public surfaces are clean and trustworthy.

Description

  • Request construction: added explicit Commons and Commercial builders (buildCommonsRequest / build_commons_request and buildCommercialRequest / build_commercial_request) and made client verb methods emit the canonical Commons envelope (x402, actor, body) by default in both SDKs.
  • Receipt typing & verb extraction: replaced loose/legacy receipt shapes with precise types/models for receipt.x402, metadata.proof, and metadata.receipt_id, and added extractReceiptVerb / extract_receipt_verb helpers to read the canonical receipt.x402.verb.
  • Verification logic: rewrote verification in both languages to (1) extract the canonical receipt, (2) strip metadata.receipt_id and signature/hash fields to form the unsigned receipt, (3) canonicalize with cl-stable-json-v1, (4) recompute sha256, (5) require metadata.receipt_id === metadata.proof.hash_sha256, and (6) verify Ed25519 signature over the UTF‑8 hash string; ENS signer resolution now emits clear errors on missing/malformed TXT records.
  • receipt_id semantics and documentation: standardized semantics so metadata.receipt_id is the receipt hash identifier and must equal metadata.proof.hash_sha256; README, QUICKSTART, EXAMPLES, and package READMEs were rewritten to teach the single canonical contract.
  • Tests & examples: updated unit tests to cover the new builders and verb extraction helpers and kept parity verification vectors; examples and quickstart rewritten to show the clean, Commons-first happy paths.
  • Intentionally retained legacy surfaces: only normalizeCommandResponse / normalize_command_response (accept older blended payloads with top-level trace and convert to { receipt, runtime_metadata }) and support for passing either a raw receipt or full response envelope into verification helpers; both are explicitly marked compatibility-only.
  • Migration notes: callers should persist response.receipt (not runtime_metadata), switch any implicit verb discovery to receipt.x402.verb or the new extraction helpers, and move payment/commercial shaping into the dedicated commercial builders where needed.

Testing

  • TypeScript: ran cd typescript-sdk && npm test (unit + template + CLI smoke); all tests passed and DTS/typecheck completed successfully.
  • TypeScript typecheck: ran cd typescript-sdk && npm run typecheck; the typecheck succeeded.
  • Python: ran cd python-sdk && pytest; test suite passed (24 passed, 1 warning) and parity vectors remain aligned.

Codex Task

@GsCommand GsCommand merged commit 86212e3 into main Mar 22, 2026
0 of 10 checks passed
@GsCommand GsCommand deleted the codex/rewrite-sdk-for-commandlayer-receipt-contract branch April 23, 2026 22:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant