Skip to content

docs: align receipt verb and verification contract language#42

Merged
GsCommand merged 1 commit intomainfrom
codex/fix-documentation-inconsistencies-in-sdk-contracts
Apr 26, 2026
Merged

docs: align receipt verb and verification contract language#42
GsCommand merged 1 commit intomainfrom
codex/fix-documentation-inconsistencies-in-sdk-contracts

Conversation

@GsCommand
Copy link
Copy Markdown
Contributor

Motivation

  • Ensure documentation matches the SDK behavior that the canonical verb is at top-level receipt.verb and that receipt.x402.verb is legacy/commercial fallback only.
  • Clarify verification semantics so the recomputed proof hash is compared to metadata.proof.hash_sha256 while metadata.receipt_id is optional compatibility metadata and not required for a successful ok verification.
  • Update examples and Quickstart text so Commons examples include the top-level "verb": "summarize" and avoid presenting x402 as the primary contract.

Description

  • Updated wording and examples in README.md, QUICKSTART.md, EXAMPLES.md, typescript-sdk/README.md, and python-sdk/docs/verification.md to reflect the canonical verb and revised verification language.
  • Replaced references that treated receipt.x402.verb as primary with text explaining receipt.verb is canonical and receipt.x402.verb is a legacy/commercial fallback.
  • Revised verification steps to state the recomputed hash must be compared to metadata.proof.hash_sha256, and to document that metadata.receipt_id, when present, is a compatibility/diagnostic check and not a hard requirement for ok.
  • Added top-level "verb": "summarize" to canonical receipt examples and changed the Quickstart final bullet to: "Read the verb from receipt.verb. Legacy/commercial payloads may expose receipt.x402.verb as a fallback.".

Testing

  • Ran TypeScript package checks in typescript-sdk with npm run typecheck and the TypeScript unit/cli tests with npm test, and the package test suites completed successfully (unit/template/cli smoke all passed).
  • Ran Python tests in python-sdk with pytest -q and the Python test suite passed.
  • Attempts to run npm commands from the repository root (npm run typecheck / npm test at /workspace/sdk) failed due to a missing root package.json, but package-level automated tests were executed and passed.

Codex Task

@GsCommand GsCommand merged commit 0cebbf6 into main Apr 26, 2026
10 checks passed
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