diff --git a/DEPLOYMENT_GUIDE.md b/DEPLOYMENT_GUIDE.md index 2bddc27..3cb9e78 100644 --- a/DEPLOYMENT_GUIDE.md +++ b/DEPLOYMENT_GUIDE.md @@ -14,7 +14,7 @@ Current release line: Before cutting a release: - confirm both SDK packages are on the same version, - confirm docs reference the same protocol version and receipt model, -- confirm shared test vectors still represent the current signed receipt truth, +- confirm shared test vectors still represent the current signed receipt truth and do not reintroduce x402-first positioning, - decide whether the release is docs-only or publishable. ## 2. Local quality gates @@ -108,8 +108,8 @@ If the public docs site references installation or verification examples, update ## 7. CI expectations CI should stay green for: -- TypeScript typecheck/build/tests, +- TypeScript typecheck/build/package-local tests, - Python lint/typecheck/tests, -- cross-SDK runtime fixture checks. +- optional cross-SDK runtime fixture checks. Do not publish if any of those lanes are red. diff --git a/DEVELOPER_EXPERIENCE.md b/DEVELOPER_EXPERIENCE.md index 5fd6e29..a9dfe5a 100644 --- a/DEVELOPER_EXPERIENCE.md +++ b/DEVELOPER_EXPERIENCE.md @@ -23,7 +23,7 @@ This document is for maintainers and advanced integrators. Start with `README.md The signed payload includes: - `status`, -- `x402` verb metadata, +- the protocol metadata block at `x402` (Commons verb/version metadata; not a commercial SDK claim), - `result` or `error`, - `metadata.receipt_id`, and - `metadata.proof` with `alg`, `canonical`, `signer_id`, `hash_sha256`, and `signature_b64`. @@ -84,5 +84,5 @@ When protocol versions change: 1. update package versions and protocol constants, 2. update root docs and per-package READMEs, 3. regenerate or update shared fixtures, -4. run both SDK test suites plus `runtime/tests`, +4. run both SDK test suites plus the optional cross-SDK `runtime/tests` lane, 5. confirm release instructions in `DEPLOYMENT_GUIDE.md` still match reality. diff --git a/EXAMPLES.md b/EXAMPLES.md index 8351f8a..f2d47e2 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -1,6 +1,6 @@ # CommandLayer SDK Examples -Canonical examples for the CommandLayer SDK repo. +Canonical examples for the CommandLayer SDK repo. These examples keep the Commons v1.1.0 story receipt-first: `receipt` is signed, `runtime_metadata` is optional and unsigned, and the `x402` object is protocol metadata rather than a commercial SDK surface. All examples in this file target: - Protocol-Commons v1.1.0, @@ -16,7 +16,6 @@ All examples in this file target: "x402": { "verb": "summarize", "version": "1.1.0", - "entry": "x402://summarizeagent.eth/summarize/v1.1.0" }, "result": { "summary": "..." diff --git a/MAINTAINER_GUIDE.md b/MAINTAINER_GUIDE.md index b3ed48b..15870e4 100644 --- a/MAINTAINER_GUIDE.md +++ b/MAINTAINER_GUIDE.md @@ -1,3 +1,3 @@ # Maintainer Guide -See `DEVELOPER_EXPERIENCE.md` for maintainer-facing architecture notes and `DEPLOYMENT_GUIDE.md` for release execution details. +Use `DEVELOPER_EXPERIENCE.md` for maintainer-facing architecture notes and contributor workflow. Use `RELEASE_GUIDE.md` for the release sequence and `DEPLOYMENT_GUIDE.md` for the detailed packaging/publish checklist. diff --git a/QUICKSTART.md b/QUICKSTART.md index e80b027..b1829ee 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -83,7 +83,7 @@ Both SDKs return the same shape: } ``` -Use `response.receipt` as the durable protocol artifact. `runtime_metadata` is optional execution context. +Use `response.receipt` as the durable protocol artifact. `runtime_metadata` is optional execution context. The retained `x402` object carries Commons verb metadata and is not a commercial feature signal. ## 4. Verify the receipt @@ -153,4 +153,5 @@ Not claimed as first-class SDK support here: - More recipes: `EXAMPLES.md` - Package docs: `typescript-sdk/README.md`, `python-sdk/README.md` - Maintainer notes: `DEVELOPER_EXPERIENCE.md` -- Release flow: `DEPLOYMENT_GUIDE.md` +- Release guide: `RELEASE_GUIDE.md` +- Deployment checklist: `DEPLOYMENT_GUIDE.md` diff --git a/README.md b/README.md index ea1451c..d940319 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ This repo is aligned to the current CommandLayer v1.1.0 surface: - canonical signed receipts as the verification contract payload, and - optional `runtime_metadata` as unsigned execution context. -Protocol-Commercial / x402 payment flows are not a first-class SDK surface in this repo today. The SDK is Commons-first; if commercial support expands, it should be added explicitly rather than implied. +Protocol-Commercial / x402 payment flows are not a first-class SDK surface in this repo today. The retained `receipt.x402` metadata block is part of the Commons protocol schema here; it should not be read as commercial feature coverage. ## Install @@ -103,7 +103,6 @@ Client methods now return a command response envelope: "x402": { "verb": "summarize", "version": "1.1.0", - "entry": "x402://summarizeagent.eth/summarize/v1.1.0" }, "result": { "summary": "..." @@ -129,7 +128,7 @@ Client methods now return a command response envelope: The canonical signed object is `receipt`. `runtime_metadata` is optional and unsigned. Verification, persistence, and downstream audit should use the canonical `receipt` object. -The SDK still normalizes older blended runtime responses for compatibility, but the repo now documents the v1.1.0 envelope as the single current truth. +The SDK still normalizes older blended runtime responses for compatibility, but that normalization is legacy-only. The repo documents the v1.1.0 envelope as the single canonical public contract. ## Verification @@ -175,7 +174,8 @@ The CLI is intended for demos, CI smoke tests, debugging, and reproducing SDK fl - Fast onboarding: `QUICKSTART.md` - Cookbook examples: `EXAMPLES.md` - Maintainer / architecture notes: `DEVELOPER_EXPERIENCE.md` -- Build, release, and publish flow: `DEPLOYMENT_GUIDE.md` +- Release guide: `RELEASE_GUIDE.md` +- Deployment checklist: `DEPLOYMENT_GUIDE.md` - Changelog: `CHANGELOG.md` - TypeScript package docs: `typescript-sdk/README.md` - Python package docs: `python-sdk/README.md` diff --git a/RELEASE_GUIDE.md b/RELEASE_GUIDE.md index 2834343..085f87c 100644 --- a/RELEASE_GUIDE.md +++ b/RELEASE_GUIDE.md @@ -1,3 +1,9 @@ # Release Guide -See `DEPLOYMENT_GUIDE.md` for the current build, release, and publish workflow. +Use this document as the release entrypoint for the SDK repo. + +- Release story and quality gates: `DEPLOYMENT_GUIDE.md` +- Maintainer architecture/context: `DEVELOPER_EXPERIENCE.md` +- Public changelog for v1.1.0: `CHANGELOG.md` + +The repo should present one release story: Protocol-Commons v1.1.0, the canonical `{ receipt, runtime_metadata? }` response envelope, and self-contained package-local tests before any optional cross-SDK validation. diff --git a/python-sdk/README.md b/python-sdk/README.md index f5be7f2..7e08641 100644 --- a/python-sdk/README.md +++ b/python-sdk/README.md @@ -8,6 +8,8 @@ The Python package mirrors the TypeScript SDK's protocol model: - `runtime_metadata` is optional execution context, and - verification can use an explicit Ed25519 key or ENS discovery. +The retained `response["receipt"]["x402"]` block is Commons protocol metadata, not a commercial SDK surface in this repository. + ## Install ```bash diff --git a/python-sdk/commandlayer/client.py b/python-sdk/commandlayer/client.py index 60f600c..032cf04 100644 --- a/python-sdk/commandlayer/client.py +++ b/python-sdk/commandlayer/client.py @@ -278,7 +278,6 @@ def _build_payload(self, verb: str, body: dict[str, Any]) -> dict[str, Any]: "x402": { "verb": verb, "version": COMMONS_VERSION, - "entry": f"x402://{verb}agent.eth/{verb}/v{COMMONS_VERSION}", }, "actor": body.get("actor", self.actor), **body, diff --git a/python-sdk/tests/test_verify.py b/python-sdk/tests/test_verify.py index c8d856d..3f486b8 100644 --- a/python-sdk/tests/test_verify.py +++ b/python-sdk/tests/test_verify.py @@ -27,7 +27,6 @@ def _signed_receipt() -> tuple[dict[str, object], str]: "x402": { "verb": "summarize", "version": "1.1.0", - "entry": "x402://summarizeagent.eth/summarize/v1.1.0", }, "metadata": { "proof": { diff --git a/test_vectors/README.md b/test_vectors/README.md index 70a50e0..91cd403 100644 --- a/test_vectors/README.md +++ b/test_vectors/README.md @@ -1,6 +1,6 @@ # Test vectors -This directory contains shared receipt fixtures used by both SDKs and the parity check. +This directory contains shared receipt fixtures used by both SDKs and the parity check. The fixtures model the current Commons v1.1.0 receipt contract: `receipt` is canonical, `runtime_metadata` is unsigned, and the `x402` object is retained only as protocol metadata. ## Files diff --git a/test_vectors/expected_hash.txt b/test_vectors/expected_hash.txt index 729e04e..34034be 100644 --- a/test_vectors/expected_hash.txt +++ b/test_vectors/expected_hash.txt @@ -1 +1 @@ -915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1 +509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196 diff --git a/test_vectors/public_key_base64.txt b/test_vectors/public_key_base64.txt index 5a46896..ef2dcde 100644 --- a/test_vectors/public_key_base64.txt +++ b/test_vectors/public_key_base64.txt @@ -1 +1 @@ -jgkIXxvTfIC0U08Xp181TaltbLtMbSq/yJ9JRPS8wNE= +A6EHv/POEL4dcN0Y50vAmWfk1jCbpQ1fHdyGZBJVMbg= diff --git a/test_vectors/receipt_invalid_sig.json b/test_vectors/receipt_invalid_sig.json index a977fe0..c7ced1e 100644 --- a/test_vectors/receipt_invalid_sig.json +++ b/test_vectors/receipt_invalid_sig.json @@ -3,8 +3,7 @@ "status": "success", "x402": { "verb": "summarize", - "version": "1.1.0", - "entry": "x402://parseagent.eth/summarize/v1.1.0" + "version": "1.1.0" }, "result": { "summary": "fixture" @@ -14,9 +13,9 @@ "alg": "ed25519-sha256", "canonical": "cl-stable-json-v1", "signer_id": "runtime.commandlayer.eth", - "hash_sha256": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1", + "hash_sha256": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196", "signature_b64": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==" }, - "receipt_id": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1" + "receipt_id": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196" } } diff --git a/test_vectors/receipt_malformed_pubkey.json b/test_vectors/receipt_malformed_pubkey.json index 0350f6d..bc6464d 100644 --- a/test_vectors/receipt_malformed_pubkey.json +++ b/test_vectors/receipt_malformed_pubkey.json @@ -3,8 +3,7 @@ "status": "success", "x402": { "verb": "summarize", - "version": "1.1.0", - "entry": "x402://parseagent.eth/summarize/v1.1.0" + "version": "1.1.0" }, "result": { "summary": "fixture" @@ -14,9 +13,9 @@ "alg": "ed25519-sha256", "canonical": "cl-stable-json-v1", "signer_id": "runtime.commandlayer.eth", - "hash_sha256": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1", - "signature_b64": "JwwLYGdplh7Yy5U42DAov6V30trEdRbA5Qzh8owG6X0DkGl2/TsaOhtWRJU9Z1uykJVeDFdqijR9ZqoktqjhAg==" + "hash_sha256": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196", + "signature_b64": "RXtxKNIiU4uRSQoTK2wjByZnj3wJsA8g4+Ofuv+y3pUf/d57p1V9dL0vSoYUXLLMgPa7CpxKMsOl50AFhojcCw==" }, - "receipt_id": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1" + "receipt_id": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196" } } diff --git a/test_vectors/receipt_valid.json b/test_vectors/receipt_valid.json index 0350f6d..bc6464d 100644 --- a/test_vectors/receipt_valid.json +++ b/test_vectors/receipt_valid.json @@ -3,8 +3,7 @@ "status": "success", "x402": { "verb": "summarize", - "version": "1.1.0", - "entry": "x402://parseagent.eth/summarize/v1.1.0" + "version": "1.1.0" }, "result": { "summary": "fixture" @@ -14,9 +13,9 @@ "alg": "ed25519-sha256", "canonical": "cl-stable-json-v1", "signer_id": "runtime.commandlayer.eth", - "hash_sha256": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1", - "signature_b64": "JwwLYGdplh7Yy5U42DAov6V30trEdRbA5Qzh8owG6X0DkGl2/TsaOhtWRJU9Z1uykJVeDFdqijR9ZqoktqjhAg==" + "hash_sha256": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196", + "signature_b64": "RXtxKNIiU4uRSQoTK2wjByZnj3wJsA8g4+Ofuv+y3pUf/d57p1V9dL0vSoYUXLLMgPa7CpxKMsOl50AFhojcCw==" }, - "receipt_id": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1" + "receipt_id": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196" } } diff --git a/test_vectors/receipt_valid_v1.json b/test_vectors/receipt_valid_v1.json index 0350f6d..bc6464d 100644 --- a/test_vectors/receipt_valid_v1.json +++ b/test_vectors/receipt_valid_v1.json @@ -3,8 +3,7 @@ "status": "success", "x402": { "verb": "summarize", - "version": "1.1.0", - "entry": "x402://parseagent.eth/summarize/v1.1.0" + "version": "1.1.0" }, "result": { "summary": "fixture" @@ -14,9 +13,9 @@ "alg": "ed25519-sha256", "canonical": "cl-stable-json-v1", "signer_id": "runtime.commandlayer.eth", - "hash_sha256": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1", - "signature_b64": "JwwLYGdplh7Yy5U42DAov6V30trEdRbA5Qzh8owG6X0DkGl2/TsaOhtWRJU9Z1uykJVeDFdqijR9ZqoktqjhAg==" + "hash_sha256": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196", + "signature_b64": "RXtxKNIiU4uRSQoTK2wjByZnj3wJsA8g4+Ofuv+y3pUf/d57p1V9dL0vSoYUXLLMgPa7CpxKMsOl50AFhojcCw==" }, - "receipt_id": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1" + "receipt_id": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196" } } diff --git a/test_vectors/receipt_wrong_kid.json b/test_vectors/receipt_wrong_kid.json index e0bc10e..282c795 100644 --- a/test_vectors/receipt_wrong_kid.json +++ b/test_vectors/receipt_wrong_kid.json @@ -3,8 +3,7 @@ "status": "success", "x402": { "verb": "summarize", - "version": "1.1.0", - "entry": "x402://parseagent.eth/summarize/v1.1.0" + "version": "1.1.0" }, "result": { "summary": "fixture" @@ -14,9 +13,9 @@ "alg": "ed25519-sha256", "canonical": "cl-stable-json-v1", "signer_id": "runtime.commandlayer.eth", - "hash_sha256": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1", - "signature_b64": "JwwLYGdplh7Yy5U42DAov6V30trEdRbA5Qzh8owG6X0DkGl2/TsaOhtWRJU9Z1uykJVeDFdqijR9ZqoktqjhAg==" + "hash_sha256": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196", + "signature_b64": "RXtxKNIiU4uRSQoTK2wjByZnj3wJsA8g4+Ofuv+y3pUf/d57p1V9dL0vSoYUXLLMgPa7CpxKMsOl50AFhojcCw==" }, - "receipt_id": "915ce5bd5d71ac3622a1d3918630dd69ff0d6d22218de84a751817ae60bd54e1" + "receipt_id": "509b71764d0158fab6bb073ed0bf28182bc1fa0227c00dc4ef79a0067e968196" } } diff --git a/typescript-sdk/README.md b/typescript-sdk/README.md index 2c3a7f8..1005e99 100644 --- a/typescript-sdk/README.md +++ b/typescript-sdk/README.md @@ -4,8 +4,8 @@ Official TypeScript/JavaScript SDK for CommandLayer Commons v1.1.0. Use this package to: - call CommandLayer Commons verbs, -- receive a canonical signed receipt, -- capture optional runtime metadata separately, +- receive the canonical signed `receipt`, +- capture optional unsigned `runtime_metadata` separately, - verify receipts offline or through ENS, and - reproduce calls from the CLI. @@ -72,7 +72,7 @@ Client methods return: } ``` -`verifyReceipt()` accepts the canonical `receipt` object. The SDK also accepts a whole response envelope for legacy compatibility, but new integrations should pass `response.receipt` explicitly. +`verifyReceipt()` accepts the canonical `receipt` object. The retained `receipt.x402` block is Commons protocol metadata, not a commercial SDK surface. The SDK also accepts a whole response envelope for legacy compatibility, but new integrations should pass `response.receipt` explicitly. ## Verification modes @@ -111,9 +111,12 @@ commandlayer verify --file receipt.json --public-key "ed25519:BASE64_PUBLIC_KEY" ## Development +`npm test` is package-local and reproducible from this repo alone. The optional protocol integration lane remains available as `npm run test:integration`. + ```bash cd typescript-sdk npm ci npm run typecheck npm test +npm run test:integration ``` diff --git a/typescript-sdk/package.json b/typescript-sdk/package.json index f52b78b..6c5e22e 100644 --- a/typescript-sdk/package.json +++ b/typescript-sdk/package.json @@ -30,7 +30,8 @@ "prepack": "npm run build", "test:cli-smoke": "node scripts/cli-smoke.mjs", "test:unit": "npm run build && node scripts/unit-tests.mjs && npm run test:template", - "test": "npm run test:unit && npm run test:cli-smoke && node --test ../runtime/tests/*.mjs", + "test": "npm run test:unit && npm run test:cli-smoke", + "test:integration": "node --test ../runtime/tests/*.mjs", "test:template": "node scripts/template-tests.mjs" }, "dependencies": { diff --git a/typescript-sdk/scripts/unit-tests.mjs b/typescript-sdk/scripts/unit-tests.mjs index 7a1094c..c1e349d 100644 --- a/typescript-sdk/scripts/unit-tests.mjs +++ b/typescript-sdk/scripts/unit-tests.mjs @@ -196,7 +196,7 @@ await assertRejects( const receipt = { status: "success", - x402: { verb: "summarize", version: "1.1.0", entry: "x402://summarizeagent.eth/summarize/v1.1.0" }, + x402: { verb: "summarize", version: "1.1.0" }, result: { summary: "test" }, metadata: { proof: { diff --git a/typescript-sdk/src/index.ts b/typescript-sdk/src/index.ts index 56b924a..31249f8 100644 --- a/typescript-sdk/src/index.ts +++ b/typescript-sdk/src/index.ts @@ -537,7 +537,7 @@ export class CommandLayerClient { this.ensureVerifyConfigIfEnabled(); const payload = { - x402: { verb, version: commonsVersion, entry: `x402://${verb}agent.eth/${verb}/v${commonsVersion}` }, + x402: { verb, version: commonsVersion }, ...(body.actor ? { actor: body.actor } : { actor: this.actor }), ...body };