@piprail/sdk 2.10.0 → 2.11.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.11.0] — 2026-06-21 — A2A interop hardening: spec-correct merchant status + verified x402-V2 conformance
+
+A2A transport correctness, after a **live cross-check against Google's official `x402` / `x402_a2a`
+libraries** (reproducible harness + verdict in `examples/a2a-interop/`). One behavior fix on the A2A rejection path;
+HTTP and every other rail are byte-identical to 2.10.0.
+
+- **fix(a2a): a rejected proof now re-challenges as `payment-required`, not the client-only
+  `payment-rejected`.** Per the A2A x402 spec §5.1 and Google's reference merchant executor, a MERCHANT
+  emits only `payment-required` / `payment-completed` / `payment-failed`; `payment-rejected` and
+  `payment-submitted` are CLIENT→merchant statuses. A rejection is now signalled by the appended failure
+  receipt + the `x402.payment.error` code — the retry loop and the `input-required` state are unchanged.
+- **interop: PipRail's A2A envelopes are byte-conformant with the current x402 V2 standard.** The
+  canonical `x402` lib parses our `PaymentRequired` + `PaymentPayload` (CAIP-2 networks, `amount`,
+  `x402Version: 2`, nested `accepted`); the five `x402.payment.*` keys + the extension URI match
+  `x402_a2a` verbatim. The deferred emit-version question is resolved — **v2** (the live standard; the
+  legacy v0.1 `x402-a2a` package is bitrotted and not targeted). New always-on guard:
+  `test/transports/a2a-wire-conformance.test.ts`; reproducible cross-check harness: `examples/a2a-interop/`.
+- **docs(a2a):** the A2A guide is now fully runnable — a real `@a2a-js/sdk` `AgentExecutor` mount, a
+  complete AgentCard, where the buyer's payload comes from, and the co-resident one-gate pattern.
+- No public API change. A2A remains seller-side (the `A2APayer` buyer + AP2 mandate carriage stay deferred).
+
 ## [2.10.0] — 2026-06-20 — x402 parity: verifiable receipts · the `upto` metered rail · A2A transport
 
 Four ratified-x402 capabilities, all **additive and opt-in** — omit the new options and the 402, the

package/dist/index.cjs

@@ -7586,7 +7586,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-rejected",
+      [A2A_STATUS_KEY]: "payment-required",
       [A2A_ERROR_KEY]: toA2AErrorCode(result.error),
       [A2A_REQUIRED_KEY]: result.challenge,
       ...toA2APaymentReceipts(receipts)

package/dist/index.d.cts

@@ -7964,15 +7964,21 @@ interface A2ATaskRecord {
  *  • B7 — `receipts[]` is the UNION `(X402Receipt | SettleOutcome)[]` (it carries FAILED
  *    attempts); a fulfill-throws-AFTER-settle ends the Task `completed` with the successful
  *    receipt + an error annotation (NEVER re-challenge / failed — the money already moved).
- *  • Emit strict `x402Version: 2` (the inbound object-cores absorb v1). The emit version is
- *    the deferred B8 live-interop ship-gate — do NOT change it here.
+ *  • Emit `x402Version: 2` — RESOLVED 2026-06-21: v2 IS the live x402 standard. A live cross-check
+ *    against Google's official libs (reproducible harness in `examples/a2a-interop/`) showed the canonical
+ *    `x402` lib (2.13.1, V2: `amount` / CAIP-2 / nested `accepted`) parses our PaymentRequired +
+ *    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.
  *
  * ── DEFERRED (NOT built here — see the x402-parity/03-a2a-transport plan) ──────
- *  • Phase 4 — the A2A BUYER (`A2APayer`): trails on live interop.
- *  • Phase 5 — AP2 `CartMandate`/`PaymentMandate` carriage (payment-carriage only, no
- *    mandate-trust machinery).
- *  • B8 ship-gate — the live Google `adk-demo` reference-client run + the final v1-vs-v2
- *    emit-version decision (a live-runtime gate, not buildable offline).
+ *  • Phase 4 — the A2A BUYER (`A2APayer`): the HTTP buyer mints the payload that rides A2A today.
+ *  • Phase 5 — AP2 `CartMandate`/`PaymentMandate` carriage (the Embedded Flow; no mandate-trust machinery).
+ *  • B8 ship-gate — RESOLVED at the wire level (above). A live `adk-demo` AGENT run is blocked by that
+ *    package's dependency bitrot (won't import on current `x402`/`a2a-sdk`), not by PipRail.
  */
 
 /** The x402 A2A extension URI the x402-foundation doc + ALL Google reference code cite

package/dist/index.d.ts

@@ -7964,15 +7964,21 @@ interface A2ATaskRecord {
  *  • B7 — `receipts[]` is the UNION `(X402Receipt | SettleOutcome)[]` (it carries FAILED
  *    attempts); a fulfill-throws-AFTER-settle ends the Task `completed` with the successful
  *    receipt + an error annotation (NEVER re-challenge / failed — the money already moved).
- *  • Emit strict `x402Version: 2` (the inbound object-cores absorb v1). The emit version is
- *    the deferred B8 live-interop ship-gate — do NOT change it here.
+ *  • Emit `x402Version: 2` — RESOLVED 2026-06-21: v2 IS the live x402 standard. A live cross-check
+ *    against Google's official libs (reproducible harness in `examples/a2a-interop/`) showed the canonical
+ *    `x402` lib (2.13.1, V2: `amount` / CAIP-2 / nested `accepted`) parses our PaymentRequired +
+ *    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.
  *
  * ── DEFERRED (NOT built here — see the x402-parity/03-a2a-transport plan) ──────
- *  • Phase 4 — the A2A BUYER (`A2APayer`): trails on live interop.
- *  • Phase 5 — AP2 `CartMandate`/`PaymentMandate` carriage (payment-carriage only, no
- *    mandate-trust machinery).
- *  • B8 ship-gate — the live Google `adk-demo` reference-client run + the final v1-vs-v2
- *    emit-version decision (a live-runtime gate, not buildable offline).
+ *  • Phase 4 — the A2A BUYER (`A2APayer`): the HTTP buyer mints the payload that rides A2A today.
+ *  • Phase 5 — AP2 `CartMandate`/`PaymentMandate` carriage (the Embedded Flow; no mandate-trust machinery).
+ *  • B8 ship-gate — RESOLVED at the wire level (above). A live `adk-demo` AGENT run is blocked by that
+ *    package's dependency bitrot (won't import on current `x402`/`a2a-sdk`), not by PipRail.
  */
 
 /** The x402 A2A extension URI the x402-foundation doc + ALL Google reference code cite

package/dist/index.js

@@ -7586,7 +7586,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-rejected",
+      [A2A_STATUS_KEY]: "payment-required",
       [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.10.0",
+  "version": "2.11.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",