@piprail/sdk 2.12.0 → 2.13.0

package/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to `@piprail/sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [2.13.0] — 2026-06-21 — A2A hardening: spec-correct `payment-failed`, schema-contract precision + exhaustive edge-case coverage
+
+An extreme-hardening pass on the **x402-over-A2A seller transport**, audited against the **real
+`@a2a-js/sdk` 0.3.13 types**, the **a2a-x402 spec (v0.1+v0.2)**, Google's **reference `x402_a2a`
+executor**, and the canonical **x402 V2** lib. Net: **zero runtime defects found** — the wire is
+schema-perfect. This ships the two correctness fixes plus a comprehensive test + doc-precision pass.
+HTTP and every other rail are byte-identical to 2.12.0; additive, defaults unchanged.
+
+- **fix(a2a): a rejected (failed-verification) proof now emits `x402.payment.status: payment-failed`,
+  not `payment-required`.** a2a.md §9 is a MUST — *"If a payment fails, the server MUST set
+  x402.payment.status to payment-failed"* — and its worked **expired-signature** example (a
+  verification failure) emits `payment-failed`. Google's reference executor matches it verbatim
+  (`verify_response.is_valid == false → record_payment_failure → PAYMENT_FAILED`). **Retryability is
+  unchanged** — it rides on the A2A Task `state` (`input-required`), with a fresh challenge re-issued in
+  `x402.payment.required` + the failure receipt + the `x402.payment.error` code. (2.11.0 correctly
+  removed the client-only `payment-rejected` but landed on `payment-required`; this is the final notch.)
+  A genuine first/no-proof challenge is still `payment-required`.
+- **fix(a2a): a tx-suppressed success receipt (`receipts.includeTxHash:false`) is no longer dropped**
+  when an earlier failed attempt on the same task shares the empty `transaction`. The `receipts[]`
+  dedupe now skips the empty-string transaction (an empty tx is not an idempotency key), so a
+  `payment-completed` task always carries its success receipt. Default (`includeTxHash:true`) unaffected.
+- **fix(a2a): `wrong_recipient` / `transfer_not_found` map to the spec's `SETTLEMENT_FAILED`, not
+  `INVALID_AMOUNT`.** Neither is an amount mismatch; the a2a.md §9.1 enum has no recipient/not-found
+  member, so its catch-all `SETTLEMENT_FAILED` is the correct nearest fit — a buyer is no longer told to
+  retry with a "corrected amount" when the real issue is a recipient/asset. The raw PipRail code still
+  rides in `extensions.piprail`. `INVALID_AMOUNT` is now reserved for genuine amount errors.
+- **test: +24 A2A coverage cases** (the suite is now exhaustive) — the `payment-failed` rejection
+  contract; standard **`exact` (EIP-3009) happy-path settle over A2A** (the scheme a real Google client
+  sends); the **`upto` metered rail over A2A** incl. a `$0` settle; **multi-chain CAIP-2 rail selection**;
+  the **forged-`accepted` guard** (an unoffered network/asset can't redirect funds); the
+  tx-suppressed-dedupe regression; `fulfill` throwing a non-Error / returning `undefined`; `newTaskId`
+  minting; TTL-eviction + receipts-cap **boundary** (tail-preserving) cases; the host-adapter
+  required-field-set contract; and the **error-enum codomain guard** (every emitted code is one of the 7
+  canonical `x402ErrorCode` members).
+- **docs: the A2A guide is corrected + sharpened** — the lifecycle table/prose pair a rejection with
+  `payment-failed` (retry via `input-required`); a new **"Which A2A package?"** note (A2A is a Linux
+  Foundation project, official runtime `@a2a-js/sdk`); a **transport-metadata** note (PipRail emits x402
+  payment state; the host adapter stamps the SDK-required `contextId`/`messageId`/`artifactId`);
+  `receipt.amount` clarified as base units; the buyer-payload snippet made internally consistent.
+
 ## [2.12.0] — 2026-06-21 — BNB: the `U` (United Stables) token + Binance `permit2-exact` interop
 
 BNB Chain max-out — full token parity with Binance's own x402 set, plus tolerance for Binance's

package/dist/index.cjs

@@ -7478,11 +7478,18 @@ var MAX_TASK_RECEIPTS = 64;
 var VERIFY_CODE_TO_A2A_ERROR = {
   payment_expired: "EXPIRED_PAYMENT",
   tx_already_used: "DUPLICATE_NONCE",
+  // Genuine amount mismatches only — the spec defines INVALID_AMOUNT as "the payment amount does
+  // not match the required amount" (a2a.md §9.1), so keep it strictly for amount errors.
   amount_too_low: "INVALID_AMOUNT",
   upto_settle_exceeds_max: "INVALID_AMOUNT",
   signature_invalid: "INVALID_SIGNATURE",
-  transfer_not_found: "INVALID_AMOUNT",
-  wrong_recipient: "INVALID_AMOUNT",
+  // NOT amount mismatches — a proof for an unoffered asset/network, or paid to the wrong recipient.
+  // The spec's 7-member enum (errors.py x402ErrorCode) has no WRONG_RECIPIENT/TRANSFER_NOT_FOUND, so
+  // these map to SETTLEMENT_FAILED — its explicit catch-all "the transaction failed on-chain for a
+  // reason other than the above" (a2a.md §9.1) — never INVALID_AMOUNT, which would mislead a buyer
+  // into retrying with a corrected amount. The raw PipRail code still rides in extensions.piprail.
+  transfer_not_found: "SETTLEMENT_FAILED",
+  wrong_recipient: "SETTLEMENT_FAILED",
   tx_reverted: "SETTLEMENT_FAILED",
   tx_not_found: "EXPIRED_PAYMENT",
   insufficient_confirmations: "EXPIRED_PAYMENT",
@@ -7565,7 +7572,7 @@ function createA2APaymentHandler(options) {
   const store = _nullishCoalesce(options.taskStore, () => ( defaultTaskStore()));
   function appendReceipt(taskId, entry) {
     const prior = _nullishCoalesce(_optionalChain([store, 'access', _138 => _138.get, 'call', _139 => _139(taskId), 'optionalAccess', _140 => _140.receipts]), () => ( []));
-    const isDup = "success" in entry && entry.success === true && prior.some((r) => "transaction" in r && r.transaction === entry.transaction);
+    const isDup = "success" in entry && entry.success === true && entry.transaction !== "" && prior.some((r) => "transaction" in r && r.transaction === entry.transaction);
     const next = isDup ? prior : [...prior, entry];
     const receipts = next.length > MAX_TASK_RECEIPTS ? next.slice(-MAX_TASK_RECEIPTS) : next;
     store.set(taskId, { receipts }, ttlMs);
@@ -7595,7 +7602,7 @@ function createA2APaymentHandler(options) {
     const network = _nullishCoalesce(attempted, () => ( singleNetworkOf(result.challenge)));
     const receipts = appendReceiptFailed(taskId, result.error, result.detail, network);
     const metadata = {
-      [A2A_STATUS_KEY]: "payment-required",
+      [A2A_STATUS_KEY]: "payment-failed",
       [A2A_ERROR_KEY]: toA2AErrorCode(result.error),
       [A2A_REQUIRED_KEY]: result.challenge,
       ...toA2APaymentReceipts(receipts)

package/dist/index.d.cts

@@ -7834,11 +7834,11 @@ declare const PERMIT2_UPTO_WITNESS_TYPES: {
 declare function renderLandingPage(sd: SelfDescription): string;
 
 /**
- * Minimal, DUCK-TYPED Google Agent2Agent (A2A) shapes — the structural surface the
- * PipRail A2A transport reads/writes, and NOTHING more. Like `ExpressLikeRequest` in
- * `server.ts`, these declare only the fields the adapter touches, so any A2A runtime's
- * objects (the official `@a2a-js/sdk`, ADK, or a hand-rolled JSON-RPC handler) satisfy
- * them structurally — **with ZERO `@a2a` dependency**.
+ * Minimal, DUCK-TYPED Agent2Agent (A2A) shapes — the structural surface the PipRail A2A
+ * transport reads/writes, and NOTHING more. Like `ExpressLikeRequest` in `server.ts`, these
+ * declare only the fields the adapter touches, so any A2A runtime's objects (the official
+ * `@a2a-js/sdk` — `a2aproject` org, the Linux Foundation A2A project — ADK, or a hand-rolled
+ * JSON-RPC handler) satisfy them structurally — **with ZERO `@a2a` dependency**.
  *
  * x402-over-A2A carries PipRail's existing `PaymentRequired`/`PaymentPayload`/
  * `SettlementResponse` envelopes inside A2A `Task`/`Message` `metadata`, keyed off five
@@ -7948,9 +7948,11 @@ interface A2ATaskRecord {
 }
 
 /**
- * x402-over-A2A — the SELLER-side transport adapter (Google Agent2Agent).
+ * x402-over-A2A — the SELLER-side transport adapter for the Agent2Agent (A2A) protocol.
  *
- * A2A is x402's third official transport (alongside HTTP and MCP). It carries PipRail's
+ * A2A is an open protocol (created by Google, now a Linux Foundation project — a2a-protocol.org;
+ * official JS runtime `@a2a-js/sdk` from the `a2aproject` org). It is x402's third official transport
+ * (alongside HTTP and MCP). It carries PipRail's
  * BYTE-IDENTICAL `PaymentRequired`/`PaymentPayload`/`SettlementResponse` envelopes inside
  * A2A `Task`/`Message` JSON-RPC `metadata` (five namespaced `x402.payment.*` keys) keyed
  * off a coarse A2A Task state — instead of base64 HTTP headers. It is a thin codec + adapter
@@ -7979,9 +7981,15 @@ interface A2ATaskRecord {
  *    PaymentPayload byte-identically, while the legacy v0.1 `x402_a2a` package (x402Version 1,
  *    `maxAmountRequired`, chain slugs) is bitrotted. Inbound v1 object-cores are absorbed for the
  *    standard `exact` scheme; PipRail-native `onchain-proof` is always v2 (never sent v1-flat).
- *  • Merchant statuses are spec-bounded: `payment-required` (incl. a retryable re-challenge of a
- *    rejected proof) / `payment-completed` / `payment-failed`. `payment-rejected` + `payment-submitted`
- *    are CLIENT→merchant statuses we never emit.
+ *  • Merchant statuses are spec-bounded: `payment-required` (a genuine first/no-proof challenge) /
+ *    `payment-completed` / `payment-failed`. A SUBMITTED proof that fails verification (expired /
+ *    wrong-amount / replayed) emits `payment-failed` — the a2a.md §9 rule ("If a payment fails, the
+ *    server MUST set x402.payment.status to payment-failed") and its EXPIRED-signature example, which
+ *    Google's reference executor matches verbatim (`is_valid == false → record_payment_failure →
+ *    PAYMENT_FAILED`). Retryability rides on the A2A Task `state` (`input-required`), NOT the status —
+ *    so a rejection is `payment-failed` + `input-required` (retry) while a terminal settlement error is
+ *    `payment-failed` + `failed`. `payment-rejected` + `payment-submitted` are CLIENT→merchant statuses
+ *    we never emit.
  *
  * ── DEFERRED (NOT built here — see the x402-parity/03-a2a-transport plan) ──────
  *  • Phase 4 — the A2A BUYER (`A2APayer`): the HTTP buyer mints the payload that rides A2A today.
@@ -8017,6 +8025,12 @@ declare function toA2AErrorCode(code: string): string;
  * Build the `input-required` payment-request Task carrying the challenge as RAW JSON
  * (NOT base64) in `x402.payment.required` + `x402.payment.status = 'payment-required'`.
  * `parts` are any human-readable message parts the merchant wants alongside it.
+ *
+ * Returns a **transport-metadata** Task: it carries the x402 `payment` state, NOT the host-owned
+ * ids the `@a2a-js/sdk` runtime requires (`Task.contextId`, `status.message.messageId`/`parts`,
+ * `artifacts[].artifactId` are all REQUIRED in the SDK's types). The host adapter stamps those
+ * before publishing — see the `@a2a-js/sdk` mount in the docs / `examples/a2a-server/lib.mjs`.
+ * This keeps the protocol layer chain- and runtime-agnostic (zero `@a2a` dependency).
  */
 declare function toA2APaymentRequired(taskId: string, challenge: X402Challenge, parts?: A2APart[]): A2ATask;
 /** Build the `x402.payment.receipts` metadata block (an ARRAY, append-only, B7 union). */
@@ -8078,9 +8092,15 @@ interface A2APaymentHandler {
      * `gate.verify()`'s `VerifyPaymentResult` exactly:
      *  - no payload yet            → Task `input-required` + `x402.payment.required`
      *  - payload, verified+settled → Task `completed` + `x402.payment.receipts` + artifacts
-     *  - payload, rejected         → Task `input-required` re-challenge (RETRYABLE)
+     *  - payload, rejected         → Task `input-required` re-challenge, status `payment-failed` (RETRYABLE)
      *  - settle threw (relayer)    → Task `failed` + `x402.payment.error`  (NOT retryable)
      *  - settle OK but fulfill threw → Task `completed` + receipt + error annotation (B7)
+     *
+     * The returned Task is **transport metadata only** — it carries the x402 `payment.*` state but NOT
+     * the host-owned ids the `@a2a-js/sdk` runtime requires (`Task.contextId`, `status.message.messageId`
+     * /`parts`, `artifacts[].artifactId`). The host adapter (the `AgentExecutor`) stamps those before
+     * `bus.publish` — see the mount in the docs / `examples/a2a-server/lib.mjs`. This keeps the protocol
+     * layer free of any `@a2a` dependency.
      */
     handleMessage(message: A2AMessage, taskId?: string): Promise<A2ATask>;
     /** Stamp the x402 extension into an AgentCard's `capabilities.extensions` (§2.4). */

package/dist/index.d.ts

@@ -7834,11 +7834,11 @@ declare const PERMIT2_UPTO_WITNESS_TYPES: {
 declare function renderLandingPage(sd: SelfDescription): string;
 
 /**
- * Minimal, DUCK-TYPED Google Agent2Agent (A2A) shapes — the structural surface the
- * PipRail A2A transport reads/writes, and NOTHING more. Like `ExpressLikeRequest` in
- * `server.ts`, these declare only the fields the adapter touches, so any A2A runtime's
- * objects (the official `@a2a-js/sdk`, ADK, or a hand-rolled JSON-RPC handler) satisfy
- * them structurally — **with ZERO `@a2a` dependency**.
+ * Minimal, DUCK-TYPED Agent2Agent (A2A) shapes — the structural surface the PipRail A2A
+ * transport reads/writes, and NOTHING more. Like `ExpressLikeRequest` in `server.ts`, these
+ * declare only the fields the adapter touches, so any A2A runtime's objects (the official
+ * `@a2a-js/sdk` — `a2aproject` org, the Linux Foundation A2A project — ADK, or a hand-rolled
+ * JSON-RPC handler) satisfy them structurally — **with ZERO `@a2a` dependency**.
  *
  * x402-over-A2A carries PipRail's existing `PaymentRequired`/`PaymentPayload`/
  * `SettlementResponse` envelopes inside A2A `Task`/`Message` `metadata`, keyed off five
@@ -7948,9 +7948,11 @@ interface A2ATaskRecord {
 }
 
 /**
- * x402-over-A2A — the SELLER-side transport adapter (Google Agent2Agent).
+ * x402-over-A2A — the SELLER-side transport adapter for the Agent2Agent (A2A) protocol.
  *
- * A2A is x402's third official transport (alongside HTTP and MCP). It carries PipRail's
+ * A2A is an open protocol (created by Google, now a Linux Foundation project — a2a-protocol.org;
+ * official JS runtime `@a2a-js/sdk` from the `a2aproject` org). It is x402's third official transport
+ * (alongside HTTP and MCP). It carries PipRail's
  * BYTE-IDENTICAL `PaymentRequired`/`PaymentPayload`/`SettlementResponse` envelopes inside
  * A2A `Task`/`Message` JSON-RPC `metadata` (five namespaced `x402.payment.*` keys) keyed
  * off a coarse A2A Task state — instead of base64 HTTP headers. It is a thin codec + adapter
@@ -7979,9 +7981,15 @@ interface A2ATaskRecord {
  *    PaymentPayload byte-identically, while the legacy v0.1 `x402_a2a` package (x402Version 1,
  *    `maxAmountRequired`, chain slugs) is bitrotted. Inbound v1 object-cores are absorbed for the
  *    standard `exact` scheme; PipRail-native `onchain-proof` is always v2 (never sent v1-flat).
- *  • Merchant statuses are spec-bounded: `payment-required` (incl. a retryable re-challenge of a
- *    rejected proof) / `payment-completed` / `payment-failed`. `payment-rejected` + `payment-submitted`
- *    are CLIENT→merchant statuses we never emit.
+ *  • Merchant statuses are spec-bounded: `payment-required` (a genuine first/no-proof challenge) /
+ *    `payment-completed` / `payment-failed`. A SUBMITTED proof that fails verification (expired /
+ *    wrong-amount / replayed) emits `payment-failed` — the a2a.md §9 rule ("If a payment fails, the
+ *    server MUST set x402.payment.status to payment-failed") and its EXPIRED-signature example, which
+ *    Google's reference executor matches verbatim (`is_valid == false → record_payment_failure →
+ *    PAYMENT_FAILED`). Retryability rides on the A2A Task `state` (`input-required`), NOT the status —
+ *    so a rejection is `payment-failed` + `input-required` (retry) while a terminal settlement error is
+ *    `payment-failed` + `failed`. `payment-rejected` + `payment-submitted` are CLIENT→merchant statuses
+ *    we never emit.
  *
  * ── DEFERRED (NOT built here — see the x402-parity/03-a2a-transport plan) ──────
  *  • Phase 4 — the A2A BUYER (`A2APayer`): the HTTP buyer mints the payload that rides A2A today.
@@ -8017,6 +8025,12 @@ declare function toA2AErrorCode(code: string): string;
  * Build the `input-required` payment-request Task carrying the challenge as RAW JSON
  * (NOT base64) in `x402.payment.required` + `x402.payment.status = 'payment-required'`.
  * `parts` are any human-readable message parts the merchant wants alongside it.
+ *
+ * Returns a **transport-metadata** Task: it carries the x402 `payment` state, NOT the host-owned
+ * ids the `@a2a-js/sdk` runtime requires (`Task.contextId`, `status.message.messageId`/`parts`,
+ * `artifacts[].artifactId` are all REQUIRED in the SDK's types). The host adapter stamps those
+ * before publishing — see the `@a2a-js/sdk` mount in the docs / `examples/a2a-server/lib.mjs`.
+ * This keeps the protocol layer chain- and runtime-agnostic (zero `@a2a` dependency).
  */
 declare function toA2APaymentRequired(taskId: string, challenge: X402Challenge, parts?: A2APart[]): A2ATask;
 /** Build the `x402.payment.receipts` metadata block (an ARRAY, append-only, B7 union). */
@@ -8078,9 +8092,15 @@ interface A2APaymentHandler {
      * `gate.verify()`'s `VerifyPaymentResult` exactly:
      *  - no payload yet            → Task `input-required` + `x402.payment.required`
      *  - payload, verified+settled → Task `completed` + `x402.payment.receipts` + artifacts
-     *  - payload, rejected         → Task `input-required` re-challenge (RETRYABLE)
+     *  - payload, rejected         → Task `input-required` re-challenge, status `payment-failed` (RETRYABLE)
      *  - settle threw (relayer)    → Task `failed` + `x402.payment.error`  (NOT retryable)
      *  - settle OK but fulfill threw → Task `completed` + receipt + error annotation (B7)
+     *
+     * The returned Task is **transport metadata only** — it carries the x402 `payment.*` state but NOT
+     * the host-owned ids the `@a2a-js/sdk` runtime requires (`Task.contextId`, `status.message.messageId`
+     * /`parts`, `artifacts[].artifactId`). The host adapter (the `AgentExecutor`) stamps those before
+     * `bus.publish` — see the mount in the docs / `examples/a2a-server/lib.mjs`. This keeps the protocol
+     * layer free of any `@a2a` dependency.
      */
     handleMessage(message: A2AMessage, taskId?: string): Promise<A2ATask>;
     /** Stamp the x402 extension into an AgentCard's `capabilities.extensions` (§2.4). */

package/dist/index.js

@@ -7478,11 +7478,18 @@ var MAX_TASK_RECEIPTS = 64;
 var VERIFY_CODE_TO_A2A_ERROR = {
   payment_expired: "EXPIRED_PAYMENT",
   tx_already_used: "DUPLICATE_NONCE",
+  // Genuine amount mismatches only — the spec defines INVALID_AMOUNT as "the payment amount does
+  // not match the required amount" (a2a.md §9.1), so keep it strictly for amount errors.
   amount_too_low: "INVALID_AMOUNT",
   upto_settle_exceeds_max: "INVALID_AMOUNT",
   signature_invalid: "INVALID_SIGNATURE",
-  transfer_not_found: "INVALID_AMOUNT",
-  wrong_recipient: "INVALID_AMOUNT",
+  // NOT amount mismatches — a proof for an unoffered asset/network, or paid to the wrong recipient.
+  // The spec's 7-member enum (errors.py x402ErrorCode) has no WRONG_RECIPIENT/TRANSFER_NOT_FOUND, so
+  // these map to SETTLEMENT_FAILED — its explicit catch-all "the transaction failed on-chain for a
+  // reason other than the above" (a2a.md §9.1) — never INVALID_AMOUNT, which would mislead a buyer
+  // into retrying with a corrected amount. The raw PipRail code still rides in extensions.piprail.
+  transfer_not_found: "SETTLEMENT_FAILED",
+  wrong_recipient: "SETTLEMENT_FAILED",
   tx_reverted: "SETTLEMENT_FAILED",
   tx_not_found: "EXPIRED_PAYMENT",
   insufficient_confirmations: "EXPIRED_PAYMENT",
@@ -7565,7 +7572,7 @@ function createA2APaymentHandler(options) {
   const store = options.taskStore ?? defaultTaskStore();
   function appendReceipt(taskId, entry) {
     const prior = store.get(taskId)?.receipts ?? [];
-    const isDup = "success" in entry && entry.success === true && prior.some((r) => "transaction" in r && r.transaction === entry.transaction);
+    const isDup = "success" in entry && entry.success === true && entry.transaction !== "" && prior.some((r) => "transaction" in r && r.transaction === entry.transaction);
     const next = isDup ? prior : [...prior, entry];
     const receipts = next.length > MAX_TASK_RECEIPTS ? next.slice(-MAX_TASK_RECEIPTS) : next;
     store.set(taskId, { receipts }, ttlMs);
@@ -7595,7 +7602,7 @@ function createA2APaymentHandler(options) {
     const network = attempted ?? singleNetworkOf(result.challenge);
     const receipts = appendReceiptFailed(taskId, result.error, result.detail, network);
     const metadata = {
-      [A2A_STATUS_KEY]: "payment-required",
+      [A2A_STATUS_KEY]: "payment-failed",
       [A2A_ERROR_KEY]: toA2AErrorCode(result.error),
       [A2A_REQUIRED_KEY]: result.challenge,
       ...toA2APaymentReceipts(receipts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "Accept x402 crypto payments across 29 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & XRPL — in a couple of lines. No backend, no database, no fee; payments settle straight to your wallet.",
   "type": "module",
   "main": "./dist/index.cjs",