@piprail/sdk 2.11.0 → 2.13.0

package/CHANGELOG.md

@@ -4,6 +4,65 @@ 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
+Permit2 dialect. Additive; no default changes, every other chain/rail byte-identical to 2.11.0.
+
+- **feat(bnb): add `U` (United Stables) as a built-in BNB token.** `0xcE24439F2D9C6a2289F741120FE202248B666666`
+  (18dp) — the **first-listed token in Binance's own x402 set** (U/USD1/USDT/USDC) and the BNB Agent
+  Survival Pack settlement unit. Native **EIP-3009** (domain name `"United Stables"`, version `"1"`
+  derived from `DOMAIN_SEPARATOR`, no `version()`), so it routes onto the existing gasless
+  `transferWithAuthorization` rail with **no new protocol code** — like FDUSD/USD1. On-chain-verified,
+  and **live-proven on BNB mainnet**: a keyless facilitator (Pieverse) sponsored the gas — buyer AND
+  merchant paid **zero BNB** (settle tx `0x2b3b8c51ae81df441551301c44a64652c84c796af3b9d03ec58ea38f1cb013d5`).
+  Dexter + Pieverse both accept `U`; self-settle gasless also works. Grouped as `USD` for budget policy.
+- **feat(x402): the buyer tolerates the `permit2-exact` `assetTransferMethod` label.** Binance's x402
+  facilitator ("b402") labels its EVM-Permit2 exact rail `permit2-exact` (the coinbase/x402 spec uses
+  bare `permit2`). PipRail still **emits** `permit2`; the buyer now treats `permit2-exact` as the same
+  Permit2 rail, so it can pay a Binance-issued 402. The gate/seller side already discriminates on
+  payload shape, so it was unaffected. Additive — no existing `permit2`/`eip3009` rail changes.
+
 ## [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`
@@ -1610,6 +1669,10 @@ straight into your wallet. The API is small and self-contained.
   to your wallet; PipRail never holds funds.
 - `viem ^2.21` is a peer dependency. Node 20+ or a modern browser.
 
+[2.12.0]: https://www.npmjs.com/package/@piprail/sdk
+[2.11.0]: https://www.npmjs.com/package/@piprail/sdk
+[2.10.0]: https://www.npmjs.com/package/@piprail/sdk
+[2.9.0]: https://www.npmjs.com/package/@piprail/sdk
 [2.8.0]: https://www.npmjs.com/package/@piprail/sdk
 [2.7.0]: https://www.npmjs.com/package/@piprail/sdk
 [2.6.0]: https://www.npmjs.com/package/@piprail/sdk

package/dist/index.cjs

@@ -149,11 +149,15 @@ var CHAINS = {
       // Binance-Peg (NOT EIP-3009) → the `exact` rail uses Permit2.
       USDC: { address: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", decimals: 18, symbol: "USDC" },
       USDT: { address: "0x55d398326f99059fF775485246999027B3197955", decimals: 18, symbol: "USDT" },
-      // FDUSD + USD1 ARE EIP-3009 (transferWithAuthorization) → the `exact` rail uses the gasless,
-      // no-Permit2-approve path. Both hardcode EIP-712 domain version "1" (no version() — the SDK
-      // derives it from DOMAIN_SEPARATOR). Verified on-chain (symbol/decimals/domain match).
+      // FDUSD, USD1 + U ARE EIP-3009 (transferWithAuthorization) → the `exact` rail uses the gasless,
+      // no-Permit2-approve path. All three hardcode EIP-712 domain version "1" (no version() — the
+      // SDK derives it from DOMAIN_SEPARATOR). Verified on-chain (symbol/decimals/domain match).
       FDUSD: { address: "0xc5f0f7b66764F6ec8C8Dff7BA683102295E16409", decimals: 18, symbol: "FDUSD" },
-      USD1: { address: "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d", decimals: 18, symbol: "USD1" }
+      USD1: { address: "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d", decimals: 18, symbol: "USD1" },
+      // U (United Stables) — the first-listed token in Binance's own x402 set (U/USD1/USDT/USDC) and
+      // the BNB Agent Survival Pack settlement unit. EIP-3009 (domain name "United Stables",
+      // version "1" derived from DOMAIN_SEPARATOR 0x358738…1679b6). On-chain-verified 2026-06-21.
+      U: { address: "0xcE24439F2D9C6a2289F741120FE202248B666666", decimals: 18, symbol: "U" }
     }
   },
   avalanche: {
@@ -2118,7 +2122,8 @@ function makeEvmNetwork(resolved) {
     async estimateCost(accept) {
       const { decimals, symbol } = resolved.chain.nativeCurrency;
       if (accept.scheme === "exact") {
-        const permit2 = accept.extra.assetTransferMethod === "permit2";
+        const m = accept.extra.assetTransferMethod;
+        const permit2 = m === "permit2" || m === "permit2-exact";
         return _chunkMWBT7MCEcjs.nativeCost.call(void 0, {
           symbol,
           decimals,
@@ -2198,10 +2203,12 @@ function makeEvmNetwork(resolved) {
     // `assetTransferMethod`: `permit2` (any ERC-20 — e.g. Binance-Peg USDC on BNB, signs a
     // Permit2 witness transfer + lazily does the one-time approval) or `eip3009` (re-derives
     // the token's EIP-712 domain on-chain + signs transferWithAuthorization). Never broadcasts.
+    // `permit2-exact` is Binance b402's foreign-dialect alias for `permit2` — treated identically.
     // Throws UnsupportedSchemeError for a contract signer (or a non-EIP-3009 token on the eip3009 path).
     async payExact(wallet, accept) {
       const a = wallet._native;
-      if (accept.extra.assetTransferMethod === "permit2") {
+      const method = accept.extra.assetTransferMethod;
+      if (method === "permit2" || method === "permit2-exact") {
         const { payload: payload2, payerFrom: payerFrom2, nonce: nonce2 } = await payPermit2Evm({
           publicClient,
           walletClient: a.walletClient,
@@ -3070,6 +3077,8 @@ var BUILTIN_DENOMS = {
   USDT: "USD",
   USD1: "USD",
   FDUSD: "USD",
+  U: "USD",
+  // United Stables — BNB EIP-3009 stablecoin (1:1 USDC/USDT/USD1-backed)
   RLUSD: "USD",
   EURC: "EUR"
 };
@@ -6332,25 +6341,25 @@ var KNOWN_FACILITATORS = {
       note: "Pieverse \u2014 keyless, sponsors gas (Monad USDC EIP-3009). LIVE-settled on Monad 2026-06-17 (tx 0x00cfeb93876e5ef57dcb002510038b7304913233ca286d7ab33c72a8b119eb0d)."
     }
   ],
-  // BNB Chain (eip155:56). Dexter keyless-settles the EVM EIP-3009 exact rail — but ONLY for BNB's
-  // EIP-3009 tokens (FDUSD / USD1); BNB's USDC/USDT are Binance-Peg (Permit2), which no facilitator
+  // BNB Chain (eip155:56). Dexter + Pieverse keyless-settle the EVM EIP-3009 exact rail for BNB's
+  // EIP-3009 tokens (FDUSD / USD1 / U); BNB's USDC/USDT are Binance-Peg (Permit2), which no facilitator
   // settles. Dexter also enforces a ~$0.003 dynamic settlement floor on BNB, so a sub-$0.003 payment
   // is rejected (amount_too_low) — fine for real prices, but the floor is real. LIVE-settled with
-  // FDUSD, buyer paid zero BNB — this beats the BNB token-overlap wall that blocked AEON/Pieverse.
+  // FDUSD + U, buyer paid zero BNB — this beats the BNB token-overlap wall that blocked AEON/Pieverse.
   "eip155:56": [
     {
       url: "https://x402.dexter.cash",
       keyless: true,
       schemes: ["exact"],
       settles: ["eip3009"],
-      note: "Dexter \u2014 keyless, gas-sponsored. BNB EIP-3009 tokens FDUSD/USD1 ONLY (Binance-Peg USDC/USDT are Permit2 \u2192 not facilitator-settleable); ~$0.003 dynamic floor. LIVE-settled on BNB 2026-06-17 with FDUSD (tx 0x6d9eb4e4939f3f3c74cb19424cc7822d66ec8ed5c5c7c330d9f88a5f9ad59e9e)."
+      note: "Dexter \u2014 keyless, gas-sponsored. BNB EIP-3009 tokens FDUSD/USD1/U (Binance-Peg USDC/USDT are Permit2 \u2192 not facilitator-settleable); ~$0.003 dynamic floor. LIVE-settled on BNB 2026-06-17 with FDUSD (tx 0x6d9eb4e4939f3f3c74cb19424cc7822d66ec8ed5c5c7c330d9f88a5f9ad59e9e); accepts U (verify confirmed 2026-06-21)."
     },
     {
       url: "https://facilitator.pieverse.io",
       keyless: true,
       schemes: ["exact"],
       settles: ["eip3009"],
-      note: "Pieverse \u2014 keyless, sponsors gas. BNB EIP-3009 tokens FDUSD/USD1 (same Binance-Peg caveat as Dexter). LIVE-settled on BNB 2026-06-17 with FDUSD (tx 0xb9c76affc45bd07a51559efd813ca71516fc30625478724476c2cf42fc2203d3) \u2014 a 2nd keyless BNB facilitator (failover for Dexter)."
+      note: "Pieverse \u2014 keyless, sponsors gas. BNB EIP-3009 tokens FDUSD/USD1/U (same Binance-Peg caveat as Dexter). LIVE-settled on BNB with FDUSD 2026-06-17 (tx 0xb9c76affc45bd07a51559efd813ca71516fc30625478724476c2cf42fc2203d3) AND with the U / United Stables token 2026-06-21 (tx 0x2b3b8c51ae81df441551301c44a64652c84c796af3b9d03ec58ea38f1cb013d5, buyer 0 BNB) \u2014 a 2nd keyless BNB facilitator (failover for Dexter)."
     }
   ],
   // HyperEVM (eip155:999). Ultravioleta DAO keyless-settles the EVM EIP-3009 exact rail (HyperEVM's
@@ -7469,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",
@@ -7556,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);
@@ -7586,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

@@ -1,5 +1,5 @@
-import { C as Caip2, X as X402AcceptEntry, x as X402AnyAccept, z as X402ExactAcceptEntry, d as ExactPaymentPayloadAny, p as SignedReceipt, w as VerifyResult, G as X402UptoAcceptEntry, n as Permit2UptoPaymentPayload, v as SpendSummary, y as X402Challenge, D as X402Receipt, S as SettleOutcome, u as SpendStore, s as SpendLedger, t as SpendRecord, o as PipRailReceipt, V as VerifyErrorCode, a as AssetId, A as AddressId, P as PaidReceipt } from './ledger-OQos-tmj.cjs';
-export { E as EXT_OFFER_RECEIPT, b as ExactAuthorizationWire, c as ExactPaymentPayload, H as HEADER_REQUIRED, e as HEADER_RESPONSE, f as HEADER_RESPONSE_V1, g as HEADER_SIGNATURE, h as HEADER_SIGNATURE_V1, i as ParsedExactPayment, j as ParsedUptoPayment, k as Permit2Authorization, l as Permit2PaymentPayload, m as Permit2UptoAuthorization, q as SpendAssetTotal, r as SpendDenomTotal, B as X402PaymentSignature, F as X402ResourceObject, I as buildChallengeHeader, J as buildExactSignatureHeader, K as buildReceiptExtension, L as buildReceiptHeader, M as buildSignatureHeader, N as buildUptoSignatureHeader, O as decodeBase64Json, Q as memorySpendStore, R as parseChallenge, T as parseExactObject, U as parseExactPaymentHeader, W as parseReceipt, Y as parseReceiptExtension, Z as parseSettleResponse, _ as parseSignatureHeader, $ as parseSignatureObject, a0 as parseUptoObject, a1 as parseUptoPaymentHeader, a2 as pickAccept } from './ledger-OQos-tmj.cjs';
+import { C as Caip2, X as X402AcceptEntry, x as X402AnyAccept, z as X402ExactAcceptEntry, d as ExactPaymentPayloadAny, p as SignedReceipt, w as VerifyResult, G as X402UptoAcceptEntry, n as Permit2UptoPaymentPayload, v as SpendSummary, y as X402Challenge, D as X402Receipt, S as SettleOutcome, u as SpendStore, s as SpendLedger, t as SpendRecord, o as PipRailReceipt, V as VerifyErrorCode, a as AssetId, A as AddressId, P as PaidReceipt } from './ledger-mF_SoiDB.cjs';
+export { E as EXT_OFFER_RECEIPT, b as ExactAuthorizationWire, c as ExactPaymentPayload, H as HEADER_REQUIRED, e as HEADER_RESPONSE, f as HEADER_RESPONSE_V1, g as HEADER_SIGNATURE, h as HEADER_SIGNATURE_V1, i as ParsedExactPayment, j as ParsedUptoPayment, k as Permit2Authorization, l as Permit2PaymentPayload, m as Permit2UptoAuthorization, q as SpendAssetTotal, r as SpendDenomTotal, B as X402PaymentSignature, F as X402ResourceObject, I as buildChallengeHeader, J as buildExactSignatureHeader, K as buildReceiptExtension, L as buildReceiptHeader, M as buildSignatureHeader, N as buildUptoSignatureHeader, O as decodeBase64Json, Q as memorySpendStore, R as parseChallenge, T as parseExactObject, U as parseExactPaymentHeader, W as parseReceipt, Y as parseReceiptExtension, Z as parseSettleResponse, _ as parseSignatureHeader, $ as parseSignatureObject, a0 as parseUptoObject, a1 as parseUptoPaymentHeader, a2 as pickAccept } from './ledger-mF_SoiDB.cjs';
 import * as viem_zksync from 'viem/zksync';
 import * as abitype from 'abitype';
 import * as viem_chains from 'viem/chains';
@@ -740,9 +740,7 @@ declare const CHAINS: {
                     } | {
                         blockHash: `0x${string}` | null;
                         blockNumber: bigint | null;
-                        blockTimestamp
-                        /** EVM chain id, e.g. 5000 for Mantle. */
-                        ? /** EVM chain id, e.g. 5000 for Mantle. */: bigint | undefined;
+                        blockTimestamp?: bigint | undefined;
                         from: abitype.Address;
                         gas: bigint;
                         hash: viem.Hash;
@@ -986,6 +984,11 @@ declare const CHAINS: {
                 decimals: number;
                 symbol: string;
             };
+            U: {
+                address: "0xcE24439F2D9C6a2289F741120FE202248B666666";
+                decimals: number;
+                symbol: string;
+            };
         };
     };
     avalanche: {
@@ -2454,9 +2457,7 @@ declare const CHAINS: {
                         chainId: number;
                         type: "eip7702";
                         gasPrice?: undefined | undefined;
-                        maxFeePerBlobGas
-                        /** JSON-RPC endpoint. */
-                        ? /** JSON-RPC endpoint. */: undefined | undefined;
+                        maxFeePerBlobGas?: undefined | undefined;
                         maxFeePerGas: bigint;
                         maxPriorityFeePerGas: bigint;
                         l1BatchNumber: bigint | null;
@@ -3293,7 +3294,15 @@ declare const CHAINS: {
                         maxPriorityFeePerGas: bigint;
                         isSystemTx?: undefined | undefined;
                         mint?: undefined | undefined;
-                        sourceHash?: undefined | undefined;
+                        sourceHash
+                        /**
+                         * Normalise a `ChainInput` (+ optional rpc override) into the
+                         * `{ chain, chainId, rpcUrl, tokens }` the wallet and verifier need.
+                         */
+                        ? /**
+                         * Normalise a `ChainInput` (+ optional rpc override) into the
+                         * `{ chain, chainId, rpcUrl, tokens }` the wallet and verifier need.
+                         */: undefined | undefined;
                     } | {
                         blockHash: `0x${string}` | null;
                         blockNumber: bigint | null;
@@ -7825,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
@@ -7939,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
@@ -7970,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.
@@ -8008,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). */
@@ -8069,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

@@ -1,5 +1,5 @@
-import { C as Caip2, X as X402AcceptEntry, x as X402AnyAccept, z as X402ExactAcceptEntry, d as ExactPaymentPayloadAny, p as SignedReceipt, w as VerifyResult, G as X402UptoAcceptEntry, n as Permit2UptoPaymentPayload, v as SpendSummary, y as X402Challenge, D as X402Receipt, S as SettleOutcome, u as SpendStore, s as SpendLedger, t as SpendRecord, o as PipRailReceipt, V as VerifyErrorCode, a as AssetId, A as AddressId, P as PaidReceipt } from './ledger-OQos-tmj.js';
-export { E as EXT_OFFER_RECEIPT, b as ExactAuthorizationWire, c as ExactPaymentPayload, H as HEADER_REQUIRED, e as HEADER_RESPONSE, f as HEADER_RESPONSE_V1, g as HEADER_SIGNATURE, h as HEADER_SIGNATURE_V1, i as ParsedExactPayment, j as ParsedUptoPayment, k as Permit2Authorization, l as Permit2PaymentPayload, m as Permit2UptoAuthorization, q as SpendAssetTotal, r as SpendDenomTotal, B as X402PaymentSignature, F as X402ResourceObject, I as buildChallengeHeader, J as buildExactSignatureHeader, K as buildReceiptExtension, L as buildReceiptHeader, M as buildSignatureHeader, N as buildUptoSignatureHeader, O as decodeBase64Json, Q as memorySpendStore, R as parseChallenge, T as parseExactObject, U as parseExactPaymentHeader, W as parseReceipt, Y as parseReceiptExtension, Z as parseSettleResponse, _ as parseSignatureHeader, $ as parseSignatureObject, a0 as parseUptoObject, a1 as parseUptoPaymentHeader, a2 as pickAccept } from './ledger-OQos-tmj.js';
+import { C as Caip2, X as X402AcceptEntry, x as X402AnyAccept, z as X402ExactAcceptEntry, d as ExactPaymentPayloadAny, p as SignedReceipt, w as VerifyResult, G as X402UptoAcceptEntry, n as Permit2UptoPaymentPayload, v as SpendSummary, y as X402Challenge, D as X402Receipt, S as SettleOutcome, u as SpendStore, s as SpendLedger, t as SpendRecord, o as PipRailReceipt, V as VerifyErrorCode, a as AssetId, A as AddressId, P as PaidReceipt } from './ledger-mF_SoiDB.js';
+export { E as EXT_OFFER_RECEIPT, b as ExactAuthorizationWire, c as ExactPaymentPayload, H as HEADER_REQUIRED, e as HEADER_RESPONSE, f as HEADER_RESPONSE_V1, g as HEADER_SIGNATURE, h as HEADER_SIGNATURE_V1, i as ParsedExactPayment, j as ParsedUptoPayment, k as Permit2Authorization, l as Permit2PaymentPayload, m as Permit2UptoAuthorization, q as SpendAssetTotal, r as SpendDenomTotal, B as X402PaymentSignature, F as X402ResourceObject, I as buildChallengeHeader, J as buildExactSignatureHeader, K as buildReceiptExtension, L as buildReceiptHeader, M as buildSignatureHeader, N as buildUptoSignatureHeader, O as decodeBase64Json, Q as memorySpendStore, R as parseChallenge, T as parseExactObject, U as parseExactPaymentHeader, W as parseReceipt, Y as parseReceiptExtension, Z as parseSettleResponse, _ as parseSignatureHeader, $ as parseSignatureObject, a0 as parseUptoObject, a1 as parseUptoPaymentHeader, a2 as pickAccept } from './ledger-mF_SoiDB.js';
 import * as viem_zksync from 'viem/zksync';
 import * as abitype from 'abitype';
 import * as viem_chains from 'viem/chains';
@@ -740,9 +740,7 @@ declare const CHAINS: {
                     } | {
                         blockHash: `0x${string}` | null;
                         blockNumber: bigint | null;
-                        blockTimestamp
-                        /** EVM chain id, e.g. 5000 for Mantle. */
-                        ? /** EVM chain id, e.g. 5000 for Mantle. */: bigint | undefined;
+                        blockTimestamp?: bigint | undefined;
                         from: abitype.Address;
                         gas: bigint;
                         hash: viem.Hash;
@@ -986,6 +984,11 @@ declare const CHAINS: {
                 decimals: number;
                 symbol: string;
             };
+            U: {
+                address: "0xcE24439F2D9C6a2289F741120FE202248B666666";
+                decimals: number;
+                symbol: string;
+            };
         };
     };
     avalanche: {
@@ -2454,9 +2457,7 @@ declare const CHAINS: {
                         chainId: number;
                         type: "eip7702";
                         gasPrice?: undefined | undefined;
-                        maxFeePerBlobGas
-                        /** JSON-RPC endpoint. */
-                        ? /** JSON-RPC endpoint. */: undefined | undefined;
+                        maxFeePerBlobGas?: undefined | undefined;
                         maxFeePerGas: bigint;
                         maxPriorityFeePerGas: bigint;
                         l1BatchNumber: bigint | null;
@@ -3293,7 +3294,15 @@ declare const CHAINS: {
                         maxPriorityFeePerGas: bigint;
                         isSystemTx?: undefined | undefined;
                         mint?: undefined | undefined;
-                        sourceHash?: undefined | undefined;
+                        sourceHash
+                        /**
+                         * Normalise a `ChainInput` (+ optional rpc override) into the
+                         * `{ chain, chainId, rpcUrl, tokens }` the wallet and verifier need.
+                         */
+                        ? /**
+                         * Normalise a `ChainInput` (+ optional rpc override) into the
+                         * `{ chain, chainId, rpcUrl, tokens }` the wallet and verifier need.
+                         */: undefined | undefined;
                     } | {
                         blockHash: `0x${string}` | null;
                         blockNumber: bigint | null;
@@ -7825,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
@@ -7939,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
@@ -7970,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.
@@ -8008,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). */
@@ -8069,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

@@ -149,11 +149,15 @@ var CHAINS = {
       // Binance-Peg (NOT EIP-3009) → the `exact` rail uses Permit2.
       USDC: { address: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", decimals: 18, symbol: "USDC" },
       USDT: { address: "0x55d398326f99059fF775485246999027B3197955", decimals: 18, symbol: "USDT" },
-      // FDUSD + USD1 ARE EIP-3009 (transferWithAuthorization) → the `exact` rail uses the gasless,
-      // no-Permit2-approve path. Both hardcode EIP-712 domain version "1" (no version() — the SDK
-      // derives it from DOMAIN_SEPARATOR). Verified on-chain (symbol/decimals/domain match).
+      // FDUSD, USD1 + U ARE EIP-3009 (transferWithAuthorization) → the `exact` rail uses the gasless,
+      // no-Permit2-approve path. All three hardcode EIP-712 domain version "1" (no version() — the
+      // SDK derives it from DOMAIN_SEPARATOR). Verified on-chain (symbol/decimals/domain match).
       FDUSD: { address: "0xc5f0f7b66764F6ec8C8Dff7BA683102295E16409", decimals: 18, symbol: "FDUSD" },
-      USD1: { address: "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d", decimals: 18, symbol: "USD1" }
+      USD1: { address: "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d", decimals: 18, symbol: "USD1" },
+      // U (United Stables) — the first-listed token in Binance's own x402 set (U/USD1/USDT/USDC) and
+      // the BNB Agent Survival Pack settlement unit. EIP-3009 (domain name "United Stables",
+      // version "1" derived from DOMAIN_SEPARATOR 0x358738…1679b6). On-chain-verified 2026-06-21.
+      U: { address: "0xcE24439F2D9C6a2289F741120FE202248B666666", decimals: 18, symbol: "U" }
     }
   },
   avalanche: {
@@ -2118,7 +2122,8 @@ function makeEvmNetwork(resolved) {
     async estimateCost(accept) {
       const { decimals, symbol } = resolved.chain.nativeCurrency;
       if (accept.scheme === "exact") {
-        const permit2 = accept.extra.assetTransferMethod === "permit2";
+        const m = accept.extra.assetTransferMethod;
+        const permit2 = m === "permit2" || m === "permit2-exact";
         return nativeCost({
           symbol,
           decimals,
@@ -2198,10 +2203,12 @@ function makeEvmNetwork(resolved) {
     // `assetTransferMethod`: `permit2` (any ERC-20 — e.g. Binance-Peg USDC on BNB, signs a
     // Permit2 witness transfer + lazily does the one-time approval) or `eip3009` (re-derives
     // the token's EIP-712 domain on-chain + signs transferWithAuthorization). Never broadcasts.
+    // `permit2-exact` is Binance b402's foreign-dialect alias for `permit2` — treated identically.
     // Throws UnsupportedSchemeError for a contract signer (or a non-EIP-3009 token on the eip3009 path).
     async payExact(wallet, accept) {
       const a = wallet._native;
-      if (accept.extra.assetTransferMethod === "permit2") {
+      const method = accept.extra.assetTransferMethod;
+      if (method === "permit2" || method === "permit2-exact") {
         const { payload: payload2, payerFrom: payerFrom2, nonce: nonce2 } = await payPermit2Evm({
           publicClient,
           walletClient: a.walletClient,
@@ -3070,6 +3077,8 @@ var BUILTIN_DENOMS = {
   USDT: "USD",
   USD1: "USD",
   FDUSD: "USD",
+  U: "USD",
+  // United Stables — BNB EIP-3009 stablecoin (1:1 USDC/USDT/USD1-backed)
   RLUSD: "USD",
   EURC: "EUR"
 };
@@ -6332,25 +6341,25 @@ var KNOWN_FACILITATORS = {
       note: "Pieverse \u2014 keyless, sponsors gas (Monad USDC EIP-3009). LIVE-settled on Monad 2026-06-17 (tx 0x00cfeb93876e5ef57dcb002510038b7304913233ca286d7ab33c72a8b119eb0d)."
     }
   ],
-  // BNB Chain (eip155:56). Dexter keyless-settles the EVM EIP-3009 exact rail — but ONLY for BNB's
-  // EIP-3009 tokens (FDUSD / USD1); BNB's USDC/USDT are Binance-Peg (Permit2), which no facilitator
+  // BNB Chain (eip155:56). Dexter + Pieverse keyless-settle the EVM EIP-3009 exact rail for BNB's
+  // EIP-3009 tokens (FDUSD / USD1 / U); BNB's USDC/USDT are Binance-Peg (Permit2), which no facilitator
   // settles. Dexter also enforces a ~$0.003 dynamic settlement floor on BNB, so a sub-$0.003 payment
   // is rejected (amount_too_low) — fine for real prices, but the floor is real. LIVE-settled with
-  // FDUSD, buyer paid zero BNB — this beats the BNB token-overlap wall that blocked AEON/Pieverse.
+  // FDUSD + U, buyer paid zero BNB — this beats the BNB token-overlap wall that blocked AEON/Pieverse.
   "eip155:56": [
     {
       url: "https://x402.dexter.cash",
       keyless: true,
       schemes: ["exact"],
       settles: ["eip3009"],
-      note: "Dexter \u2014 keyless, gas-sponsored. BNB EIP-3009 tokens FDUSD/USD1 ONLY (Binance-Peg USDC/USDT are Permit2 \u2192 not facilitator-settleable); ~$0.003 dynamic floor. LIVE-settled on BNB 2026-06-17 with FDUSD (tx 0x6d9eb4e4939f3f3c74cb19424cc7822d66ec8ed5c5c7c330d9f88a5f9ad59e9e)."
+      note: "Dexter \u2014 keyless, gas-sponsored. BNB EIP-3009 tokens FDUSD/USD1/U (Binance-Peg USDC/USDT are Permit2 \u2192 not facilitator-settleable); ~$0.003 dynamic floor. LIVE-settled on BNB 2026-06-17 with FDUSD (tx 0x6d9eb4e4939f3f3c74cb19424cc7822d66ec8ed5c5c7c330d9f88a5f9ad59e9e); accepts U (verify confirmed 2026-06-21)."
     },
     {
       url: "https://facilitator.pieverse.io",
       keyless: true,
       schemes: ["exact"],
       settles: ["eip3009"],
-      note: "Pieverse \u2014 keyless, sponsors gas. BNB EIP-3009 tokens FDUSD/USD1 (same Binance-Peg caveat as Dexter). LIVE-settled on BNB 2026-06-17 with FDUSD (tx 0xb9c76affc45bd07a51559efd813ca71516fc30625478724476c2cf42fc2203d3) \u2014 a 2nd keyless BNB facilitator (failover for Dexter)."
+      note: "Pieverse \u2014 keyless, sponsors gas. BNB EIP-3009 tokens FDUSD/USD1/U (same Binance-Peg caveat as Dexter). LIVE-settled on BNB with FDUSD 2026-06-17 (tx 0xb9c76affc45bd07a51559efd813ca71516fc30625478724476c2cf42fc2203d3) AND with the U / United Stables token 2026-06-21 (tx 0x2b3b8c51ae81df441551301c44a64652c84c796af3b9d03ec58ea38f1cb013d5, buyer 0 BNB) \u2014 a 2nd keyless BNB facilitator (failover for Dexter)."
     }
   ],
   // HyperEVM (eip155:999). Ultravioleta DAO keyless-settles the EVM EIP-3009 exact rail (HyperEVM's
@@ -7469,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",
@@ -7556,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);
@@ -7586,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/dist/{ledger-OQos-tmj.d.cts → ledger-mF_SoiDB.d.cts}

@@ -92,7 +92,13 @@ interface X402ExactAcceptEntry {
          *  authorizing exactly one NEP-141 `ft_transfer` to `payTo` (per `scheme_exact_near.md`); a
          *  facilitator-selected relayer (`feePayer` below) prepays gas + the 1 yoctoNEAR and submits, so
          *  the buyer holds zero NEAR. PipRail self-settles ALL. */
-        assetTransferMethod: 'eip3009' | 'permit2' | 'svm' | 'algorand' | 'aptos' | 'near';
+        assetTransferMethod: 'eip3009' | 'permit2'
+        /** A FOREIGN-dialect alias for `'permit2'` — Binance's x402 ("b402") facilitator labels its
+         *  EVM-Permit2 exact rail `'permit2-exact'` (the coinbase/x402 spec uses bare `'permit2'`).
+         *  PipRail EMITS only `'permit2'`; it TOLERATES `'permit2-exact'` inbound so the buyer pays a
+         *  Binance-issued 402 (the buyer treats the two as one rail). NB: settlement still requires the
+         *  rail to bind PipRail's canonical x402ExactPermit2Proxy — see the buyer in drivers/evm. */
+         | 'permit2-exact' | 'svm' | 'algorand' | 'aptos' | 'near';
         /** EIP-712 domain name of the token. OPTIONAL per the exact-EVM scheme (only
          *  `assetTransferMethod` is required) — a foreign rail may omit it. NEVER assumed
          *  from the symbol (USDC's on-chain name() is "USD Coin", not "USDC"); a PipRail gate

package/dist/{ledger-OQos-tmj.d.ts → ledger-mF_SoiDB.d.ts}

@@ -92,7 +92,13 @@ interface X402ExactAcceptEntry {
          *  authorizing exactly one NEP-141 `ft_transfer` to `payTo` (per `scheme_exact_near.md`); a
          *  facilitator-selected relayer (`feePayer` below) prepays gas + the 1 yoctoNEAR and submits, so
          *  the buyer holds zero NEAR. PipRail self-settles ALL. */
-        assetTransferMethod: 'eip3009' | 'permit2' | 'svm' | 'algorand' | 'aptos' | 'near';
+        assetTransferMethod: 'eip3009' | 'permit2'
+        /** A FOREIGN-dialect alias for `'permit2'` — Binance's x402 ("b402") facilitator labels its
+         *  EVM-Permit2 exact rail `'permit2-exact'` (the coinbase/x402 spec uses bare `'permit2'`).
+         *  PipRail EMITS only `'permit2'`; it TOLERATES `'permit2-exact'` inbound so the buyer pays a
+         *  Binance-issued 402 (the buyer treats the two as one rail). NB: settlement still requires the
+         *  rail to bind PipRail's canonical x402ExactPermit2Proxy — see the buyer in drivers/evm. */
+         | 'permit2-exact' | 'svm' | 'algorand' | 'aptos' | 'near';
         /** EIP-712 domain name of the token. OPTIONAL per the exact-EVM scheme (only
          *  `assetTransferMethod` is required) — a foreign rail may omit it. NEVER assumed
          *  from the symbol (USDC's on-chain name() is "USD Coin", not "USDC"); a PipRail gate

package/dist/node.d.cts

@@ -1,5 +1,5 @@
-import { u as SpendStore } from './ledger-OQos-tmj.cjs';
-export { Q as memorySpendStore } from './ledger-OQos-tmj.cjs';
+import { u as SpendStore } from './ledger-mF_SoiDB.cjs';
+export { Q as memorySpendStore } from './ledger-mF_SoiDB.cjs';
 
 /**
  * A durable {@link SpendStore} backed by a local JSONL file (one settled payment per

package/dist/node.d.ts

@@ -1,5 +1,5 @@
-import { u as SpendStore } from './ledger-OQos-tmj.js';
-export { Q as memorySpendStore } from './ledger-OQos-tmj.js';
+import { u as SpendStore } from './ledger-mF_SoiDB.js';
+export { Q as memorySpendStore } from './ledger-mF_SoiDB.js';
 
 /**
  * A durable {@link SpendStore} backed by a local JSONL file (one settled payment per

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "2.11.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",