Skip to content

Align SDK receipt parsing and verification with runtime contract#22

Merged
GsCommand merged 2 commits intomainfrom
codex/fix-sdk-receipt-contract-alignment-issues
Mar 22, 2026
Merged

Align SDK receipt parsing and verification with runtime contract#22
GsCommand merged 2 commits intomainfrom
codex/fix-sdk-receipt-contract-alignment-issues

Conversation

@GsCommand
Copy link
Copy Markdown
Contributor

Motivation

  • The SDK had drifted from the runtime contract by reading receipt.x402.verb as primary and conflating metadata.receipt_id with the payload hash, causing parsing and verification mismatches.
  • The change brings SDK behavior in line with the runtime-core proof model where receipt.verb is canonical and metadata.proof.hash_sha256 is the integrity hash while metadata.receipt_id is a distinct identifier.

Description

  • Treat receipt.verb as the canonical verb and keep receipt.x402.verb only as a documented legacy fallback via a new getReceiptVerb() helper and updated CanonicalReceipt typing.
  • Update verifyReceipt() to validate proof.hash_sha256 (recomputed from the unsigned canonical receipt) and the Ed25519 signature, and to stop requiring metadata.receipt_id === proof.hash_sha256 for success while reporting receipt_id_present and preserving the old equality check as a deprecated telemetry value.
  • Update canonicalization/hashing helpers to continue excluding metadata.receipt_id from the signed payload and keep hash_sha256 as the integrity hash, with types and verification result fields adjusted (receipt_id_present, legacy receipt_id_matches).
  • Refresh unit tests, runtime test vectors, README, and examples so fixtures show a distinct receipt_id, examples print receipt.verb, and tests cover the new default path plus an isolated legacy x402.verb fallback.

Testing

  • Ran npm run typecheck and TypeScript type checks completed successfully.
  • Ran npm run test:unit (build + unit tests + template tests) and all package-local unit and template tests passed.
  • Ran integration/compat checks with node --test tests/*.mjs and node --test ../runtime/tests/*.mjs and all runtime-facing verification tests passed.
  • Commit includes updated fixtures and tests that assert receipt_id is present but not required to equal the signed hash_sha256 as well as a legacy fallback test for x402.verb.

“SDK receipt parsing and verification now matches / still does not match the runtime-aligned receipt contract.”


Codex Task

@GsCommand GsCommand merged commit cfec54b into main Mar 22, 2026
0 of 10 checks passed
@GsCommand GsCommand deleted the codex/fix-sdk-receipt-contract-alignment-issues 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