@piprail/sdk 2.12.0 → 2.13.1

package/dist/index.d.cts

@@ -4622,10 +4622,12 @@ declare class MaxRetriesExceededError extends PipRailError {
     /**
      * The proof ref — recover with it, don't re-pay. Its meaning depends on the
      * scheme: for `onchain-proof` it's the already-broadcast transaction ref
-     * (re-verify or re-submit it). For a standard `exact` rail it's the EIP-3009
-     * authorization NONCE (a `0x…` 32-byte value, NOT a tx hash) — re-PRESENT the
-     * same signed authorization, never re-sign a fresh nonce; check the token's
-     * `authorizationState(from, nonce)` before assuming it didn't settle.
+     * (re-verify or re-submit it). For a standard `exact` rail it's the authorization's
+     * single-use marker (NOT a tx hash) — re-PRESENT the same signed authorization, never
+     * re-sign a fresh nonce, and verify it on-chain before assuming it didn't settle. On
+     * EVM that marker is the EIP-3009 NONCE (a `0x…` value), checked via the token's
+     * `authorizationState(from, nonce)`; the non-EVM `exact` rails key off their own marker
+     * (Solana tx signature, Algorand group id, Aptos account sequence number, NEAR access-key nonce).
      */
     readonly ref?: string;
     constructor(message: string, options?: ErrorOptions & {
@@ -7306,7 +7308,11 @@ interface DeliverReceiptOptions {
     url: string;
     /**
      * Shared secret. When set, the raw JSON body is signed HMAC-SHA256 and sent as
-     * `<signatureHeader>: sha256=<hex>` so the receiver can verify authenticity.
+     * `<signatureHeader>: sha256=<hex>` so the receiver can verify authenticity. Signing uses Web
+     * Crypto (`crypto.subtle`) — always present on the supported runtimes (Node ≥ 20, modern
+     * browsers). On a runtime that lacks it the body is sent **unsigned, with no signature header**,
+     * so a receiver must treat a *missing* signature as unauthenticated (reject it), never silently
+     * accept an unsigned body.
      */
     secret?: string;
     /** Extra retry attempts after the first send (default 5 → up to 6 POSTs total). */
@@ -7834,11 +7840,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 +7954,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 +7987,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 +8031,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 +8098,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

@@ -4622,10 +4622,12 @@ declare class MaxRetriesExceededError extends PipRailError {
     /**
      * The proof ref — recover with it, don't re-pay. Its meaning depends on the
      * scheme: for `onchain-proof` it's the already-broadcast transaction ref
-     * (re-verify or re-submit it). For a standard `exact` rail it's the EIP-3009
-     * authorization NONCE (a `0x…` 32-byte value, NOT a tx hash) — re-PRESENT the
-     * same signed authorization, never re-sign a fresh nonce; check the token's
-     * `authorizationState(from, nonce)` before assuming it didn't settle.
+     * (re-verify or re-submit it). For a standard `exact` rail it's the authorization's
+     * single-use marker (NOT a tx hash) — re-PRESENT the same signed authorization, never
+     * re-sign a fresh nonce, and verify it on-chain before assuming it didn't settle. On
+     * EVM that marker is the EIP-3009 NONCE (a `0x…` value), checked via the token's
+     * `authorizationState(from, nonce)`; the non-EVM `exact` rails key off their own marker
+     * (Solana tx signature, Algorand group id, Aptos account sequence number, NEAR access-key nonce).
      */
     readonly ref?: string;
     constructor(message: string, options?: ErrorOptions & {
@@ -7306,7 +7308,11 @@ interface DeliverReceiptOptions {
     url: string;
     /**
      * Shared secret. When set, the raw JSON body is signed HMAC-SHA256 and sent as
-     * `<signatureHeader>: sha256=<hex>` so the receiver can verify authenticity.
+     * `<signatureHeader>: sha256=<hex>` so the receiver can verify authenticity. Signing uses Web
+     * Crypto (`crypto.subtle`) — always present on the supported runtimes (Node ≥ 20, modern
+     * browsers). On a runtime that lacks it the body is sent **unsigned, with no signature header**,
+     * so a receiver must treat a *missing* signature as unauthenticated (reject it), never silently
+     * accept an unsigned body.
      */
     secret?: string;
     /** Extra retry attempts after the first send (default 5 → up to 6 POSTs total). */
@@ -7834,11 +7840,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 +7954,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 +7987,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 +8031,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 +8098,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

@@ -31,7 +31,7 @@ import {
   parseUnits,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-SC2ZYDHD.js";
+} from "./chunk-O32N6MFN.js";
 
 // src/drivers/registry.ts
 var byFamily = /* @__PURE__ */ new Map();
@@ -2329,7 +2329,7 @@ var loaders = {
   solana: async () => {
     let mod;
     try {
-      mod = await import("./solana-ELUWO6N5.js");
+      mod = await import("./solana-VYLWFNAH.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Solana selected, but its packages aren't installed. Run: npm install @solana/web3.js @solana/spl-token bs58`,
@@ -2341,7 +2341,7 @@ var loaders = {
   ton: async () => {
     let mod;
     try {
-      mod = await import("./ton-7GKCTC5H.js");
+      mod = await import("./ton-NNKQFQ6U.js");
     } catch (cause) {
       throw new MissingDriverError(
         `TON selected, but its packages aren't installed. Run: npm install @ton/ton @ton/core @ton/crypto`,
@@ -2353,7 +2353,7 @@ var loaders = {
   stellar: async () => {
     let mod;
     try {
-      mod = await import("./stellar-ASP2THL2.js");
+      mod = await import("./stellar-KBR4V77T.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Stellar selected, but its package isn't installed. Run: npm install @stellar/stellar-sdk`,
@@ -2365,7 +2365,7 @@ var loaders = {
   xrpl: async () => {
     let mod;
     try {
-      mod = await import("./xrpl-DD7TJL5L.js");
+      mod = await import("./xrpl-37E23W53.js");
     } catch (cause) {
       throw new MissingDriverError(
         `XRPL selected, but its package isn't installed. Run: npm install xrpl`,
@@ -2377,7 +2377,7 @@ var loaders = {
   tron: async () => {
     let mod;
     try {
-      mod = await import("./tron-BMCWN5SS.js");
+      mod = await import("./tron-W2D5PQXV.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Tron selected, but its package isn't installed. Run: npm install tronweb`,
@@ -2389,7 +2389,7 @@ var loaders = {
   sui: async () => {
     let mod;
     try {
-      mod = await import("./sui-FZIKZNVI.js");
+      mod = await import("./sui-BXHB6D3W.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Sui selected, but its package isn't installed. Run: npm install @mysten/sui`,
@@ -2401,7 +2401,7 @@ var loaders = {
   near: async () => {
     let mod;
     try {
-      mod = await import("./near-FZBUICCS.js");
+      mod = await import("./near-VDATC5AV.js");
     } catch (cause) {
       throw new MissingDriverError(
         `NEAR selected, but its package isn't installed. Run: npm install near-api-js`,
@@ -2413,7 +2413,7 @@ var loaders = {
   aptos: async () => {
     let mod;
     try {
-      mod = await import("./aptos-LY67Q6QF.js");
+      mod = await import("./aptos-RYQOSFBQ.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Aptos selected, but its package isn't installed. Run: npm install @aptos-labs/ts-sdk`,
@@ -2425,7 +2425,7 @@ var loaders = {
   algorand: async () => {
     let mod;
     try {
-      mod = await import("./algorand-AA3WXKW4.js");
+      mod = await import("./algorand-TQCYK2XT.js");
     } catch (cause) {
       throw new MissingDriverError(
         `Algorand selected, but its package isn't installed. Run: npm install algosdk`,
@@ -3449,6 +3449,24 @@ var SpendLedger = class {
   }
 };
 
+// src/util/exactRecovery.ts
+function exactSettleCheckHint(family, payerFrom, nonce) {
+  switch (family) {
+    case "evm":
+      return `the EIP-3009 \`authorizationState(${payerFrom}, ${nonce})\` (or, on the Permit2 method, the Permit2 nonce bitmap)`;
+    case "solana":
+      return `the buyer's transaction signature (a duplicate signature is the chain's own replay guard; plus the SPL-Memo nonce when present)`;
+    case "algorand":
+      return `the atomic group / transaction id`;
+    case "aptos":
+      return `the sender's account sequence number`;
+    case "near":
+      return `the access-key nonce (\`${nonce}\`)`;
+    default:
+      return `the single-use marker (\`ref=${nonce}\`)`;
+  }
+}
+
 // src/client.ts
 var DEFAULT_SCHEMES = ["onchain-proof"];
 var RECIPIENT_FIX = {
@@ -4760,7 +4778,7 @@ var PipRailClient = class {
   async payExactRail(net, wallet, accept, url, init, quote) {
     if (!net.payExact) {
       throw new UnsupportedSchemeError(
-        `the ${net.family} family can't pay a standard 'exact' rail (supported on EVM, Solana, Algorand + NEAR today).`
+        `the ${net.family} family can't pay a standard 'exact' rail (supported on EVM, Solana, Algorand, Aptos + NEAR today).`
       );
     }
     throwIfAborted(init?.signal);
@@ -4793,7 +4811,7 @@ var PipRailClient = class {
         response = await fetch(url, { ...init ?? {}, headers, signal });
       } catch (err) {
         throw new PaymentTimeoutError(
-          `exact: no response after submitting the authorization (nonce=${nonce}) to ${hostOf2(url)}. The facilitator may have already settled it \u2014 verify on-chain with authorizationState(${payerFrom}, ${nonce}) before re-presenting; do NOT re-pay.`,
+          `exact: no response after submitting the authorization (nonce=${nonce}) to ${hostOf2(url)}. The facilitator may have already settled it \u2014 verify on-chain via ${exactSettleCheckHint(net.family, payerFrom, nonce)} before re-presenting the SAME signed authorization; do NOT re-pay.`,
           { cause: err, ref: nonce }
         );
       } finally {
@@ -4809,7 +4827,7 @@ var PipRailClient = class {
         const receipt = parseReceipt(response);
         this.captureReceipt(response, url);
         this.safeEmit({ kind: "payment-settled", receipt, ...settle ? { settle } : {} });
-        const ref = settle?.transaction || receipt?.transaction || `eip3009-nonce:${nonce}`;
+        const ref = settle?.transaction || receipt?.transaction || `${net.family === "evm" ? "eip3009" : net.family}-nonce:${nonce}`;
         this.recordSpend(quote, ref);
         return response;
       }
@@ -4828,7 +4846,7 @@ var PipRailClient = class {
       ...lastReason ? { code: lastReason.error, detail: lastReason.detail } : {}
     });
     throw new MaxRetriesExceededError(
-      `exact: server still returned 402 after submitting the signed authorization (nonce=${nonce}). Last rejection: ${why}. Re-present the SAME authorization \u2014 do NOT re-sign a fresh nonce; verify authorizationState(${payerFrom}, ${nonce}) first. ref=${nonce}.`,
+      `exact: server still returned 402 after submitting the signed authorization (nonce=${nonce}). Last rejection: ${why}. Re-present the SAME authorization \u2014 do NOT re-sign a fresh nonce; verify on-chain via ${exactSettleCheckHint(net.family, payerFrom, nonce)} first. ref=${nonce}.`,
       { ref: nonce }
     );
   }
@@ -7478,11 +7496,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 +7590,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 +7620,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/{near-6KAQVVG2.cjs → near-UDPFA6SV.cjs}

@@ -10,7 +10,7 @@
 
 
 
-var _chunkMWBT7MCEcjs = require('./chunk-MWBT7MCE.cjs');
+var _chunkDCOUJZPLcjs = require('./chunk-DCOUJZPL.cjs');
 
 // src/drivers/near/index.ts
 var _nearapijs = require('near-api-js');
@@ -61,18 +61,18 @@ async function payNear(params) {
     return res.hash;
   } catch (err) {
     if (isNearRegistrationError(err)) {
-      throw new (0, _chunkMWBT7MCEcjs.RecipientNotReadyError)(
+      throw new (0, _chunkDCOUJZPLcjs.RecipientNotReadyError)(
         `NEAR recipient ${accept.payTo} isn't registered on token ${accept.asset} (NEP-145 storage_deposit) \u2014 register it once (\u22480.00125 NEAR) before it can receive. (NEAR: not registered)`,
         { cause: err }
       );
     }
     if (isNearAffordability(err)) {
-      throw new (0, _chunkMWBT7MCEcjs.InsufficientFundsError)(
+      throw new (0, _chunkDCOUJZPLcjs.InsufficientFundsError)(
         err instanceof Error ? err.message : "Insufficient NEAR balance for the payment.",
         { cause: err }
       );
     }
-    throw _nullishCoalesce(_chunkMWBT7MCEcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
+    throw _nullishCoalesce(_chunkDCOUJZPLcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
   }
 }
 async function payNearNative(params) {
@@ -82,12 +82,12 @@ async function payNearNative(params) {
     return res.hash;
   } catch (err) {
     if (isNearAffordability(err)) {
-      throw new (0, _chunkMWBT7MCEcjs.InsufficientFundsError)(
+      throw new (0, _chunkDCOUJZPLcjs.InsufficientFundsError)(
         err instanceof Error ? err.message : "Insufficient NEAR balance for the payment.",
         { cause: err }
       );
     }
-    throw _nullishCoalesce(_chunkMWBT7MCEcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
+    throw _nullishCoalesce(_chunkDCOUJZPLcjs.toInsufficientFundsError.call(void 0, err), () => ( err));
   }
 }
 function isNearRegistrationError(err) {
@@ -109,28 +109,28 @@ var NONCE_BLOCK_MULTIPLIER = 1000000n;
 async function payExactNear(input) {
   const { signer, senderId, blockHeight, accessKeyNonce, accept } = input;
   if (accept.asset === "native") {
-    throw new (0, _chunkMWBT7MCEcjs.UnsupportedSchemeError)(
+    throw new (0, _chunkDCOUJZPLcjs.UnsupportedSchemeError)(
       "NEAR exact is NEP-141-only (an ft_transfer); native NEAR is not exact-payable. Pay via onchain-proof."
     );
   }
   if (!isValidNearAccountId(accept.asset)) {
-    throw new (0, _chunkMWBT7MCEcjs.UnsupportedSchemeError)(`NEAR exact: asset "${accept.asset}" must be a NEP-141 contract account id.`);
+    throw new (0, _chunkDCOUJZPLcjs.UnsupportedSchemeError)(`NEAR exact: asset "${accept.asset}" must be a NEP-141 contract account id.`);
   }
   if (!isValidNearAccountId(accept.payTo)) {
-    throw new (0, _chunkMWBT7MCEcjs.UnsupportedSchemeError)(`NEAR exact: payTo "${accept.payTo}" is not a valid NEAR account id.`);
+    throw new (0, _chunkDCOUJZPLcjs.UnsupportedSchemeError)(`NEAR exact: payTo "${accept.payTo}" is not a valid NEAR account id.`);
   }
   if (!isValidNearAccountId(senderId)) {
-    throw new (0, _chunkMWBT7MCEcjs.UnsupportedSchemeError)(`NEAR exact: sender "${senderId}" is not a valid NEAR account id.`);
+    throw new (0, _chunkDCOUJZPLcjs.UnsupportedSchemeError)(`NEAR exact: sender "${senderId}" is not a valid NEAR account id.`);
   }
   const t = accept.maxTimeoutSeconds;
   if (!Number.isInteger(t) || t <= 0) {
-    throw new (0, _chunkMWBT7MCEcjs.UnsupportedSchemeError)("NEAR exact: maxTimeoutSeconds must be a positive integer.");
+    throw new (0, _chunkDCOUJZPLcjs.UnsupportedSchemeError)("NEAR exact: maxTimeoutSeconds must be a positive integer.");
   }
   const timeoutBlocks = BigInt(Math.max(1, Math.ceil(t / ESTIMATED_BLOCK_SECONDS)));
   const maxBlockHeight = blockHeight + timeoutBlocks;
   const nonce = accessKeyNonce + 1n;
   if (nonce >= blockHeight * NONCE_BLOCK_MULTIPLIER) {
-    throw new (0, _chunkMWBT7MCEcjs.UnsupportedSchemeError)(
+    throw new (0, _chunkDCOUJZPLcjs.UnsupportedSchemeError)(
       "NEAR exact: the access-key nonce is at the protocol ceiling for this block height; cannot build a delegate action."
     );
   }
@@ -259,7 +259,7 @@ async function verifyAndSettleExactNear(input) {
     if (/not enough|insufficient|exceeded the prepaid gas|NotEnoughBalance|doesn't have enough|is not registered/i.test(m)) {
       return fail("tx_reverted", `the ft_transfer would fail on chain: ${shorten(m)}.`);
     }
-    throw new (0, _chunkMWBT7MCEcjs.SettlementError)(
+    throw new (0, _chunkDCOUJZPLcjs.SettlementError)(
       `NEAR exact settle: the relayer could not submit the delegate (${shorten(m)}). The buyer's signed delegate is still valid \u2014 fund/fix the relayer and the buyer can re-present it.`,
       { cause: err }
     );
@@ -408,13 +408,13 @@ function txNotFound(hash) {
 
 function assertNearWallet(wallet, network) {
   if (typeof wallet !== "object" || wallet === null) {
-    throw new (0, _chunkMWBT7MCEcjs.WrongFamilyError)(
+    throw new (0, _chunkDCOUJZPLcjs.WrongFamilyError)(
       `chain ${network} is NEAR; wallet must be { accountId, key } (key = ed25519:\u2026).`
     );
   }
-  _chunkMWBT7MCEcjs.assertNoLegacyWalletKey.call(void 0, wallet, "NEAR");
+  _chunkDCOUJZPLcjs.assertNoLegacyWalletKey.call(void 0, wallet, "NEAR");
   if (!("accountId" in wallet) || !("key" in wallet)) {
-    throw new (0, _chunkMWBT7MCEcjs.WrongFamilyError)(
+    throw new (0, _chunkDCOUJZPLcjs.WrongFamilyError)(
       `chain ${network} is NEAR; wallet must be { accountId, key } (key = ed25519:\u2026).`
     );
   }
@@ -422,13 +422,13 @@ function assertNearWallet(wallet, network) {
 }
 function resolveNearWallet(config) {
   if (!config.accountId || !config.key) {
-    throw new (0, _chunkMWBT7MCEcjs.WrongFamilyError)("NEAR wallet needs { accountId, key } (key = ed25519:\u2026).");
+    throw new (0, _chunkDCOUJZPLcjs.WrongFamilyError)("NEAR wallet needs { accountId, key } (key = ed25519:\u2026).");
   }
   let signer;
   try {
     signer = _nearapijs.KeyPairSigner.fromSecretKey(config.key);
   } catch (cause) {
-    throw new (0, _chunkMWBT7MCEcjs.WrongFamilyError)("NEAR wallet { key } is not a valid ed25519:\u2026 secret key.", {
+    throw new (0, _chunkDCOUJZPLcjs.WrongFamilyError)("NEAR wallet { key } is not a valid ed25519:\u2026 secret key.", {
       cause
     });
   }
@@ -490,16 +490,16 @@ function makeNearNetwork(preset, rpcUrl) {
         const info = preset.tokens[token.toUpperCase()];
         if (!info) {
           const known = Object.keys(preset.tokens).join(", ") || "(none built in)";
-          throw new (0, _chunkMWBT7MCEcjs.UnknownTokenError)(
+          throw new (0, _chunkDCOUJZPLcjs.UnknownTokenError)(
             `token "${token}" isn't built in for NEAR (known: ${known}). Pass { contractId, decimals } for a custom NEP-141.`
           );
         }
         return { asset: info.contractId, decimals: info.decimals, symbol: info.symbol };
       }
-      _chunkMWBT7MCEcjs.rejectForeignToken.call(void 0, token, "near", network);
+      _chunkDCOUJZPLcjs.rejectForeignToken.call(void 0, token, "near", network);
       const t = token;
       if (!t.contractId || typeof t.decimals !== "number") {
-        throw new (0, _chunkMWBT7MCEcjs.WrongFamilyError)(
+        throw new (0, _chunkDCOUJZPLcjs.WrongFamilyError)(
           `chain ${network} is NEAR; a custom token must be { contractId, decimals }.`
         );
       }
@@ -518,12 +518,12 @@ function makeNearNetwork(preset, rpcUrl) {
     },
     assertValidPayTo(payTo) {
       if (payTo.startsWith("0x")) {
-        throw new (0, _chunkMWBT7MCEcjs.WrongFamilyError)(
+        throw new (0, _chunkDCOUJZPLcjs.WrongFamilyError)(
           `chain ${network} is NEAR, but payTo "${payTo}" looks like an EVM/Sui 0x address.`
         );
       }
       if (!isValidNearAccountId(payTo)) {
-        throw new (0, _chunkMWBT7MCEcjs.WrongFamilyError)(
+        throw new (0, _chunkDCOUJZPLcjs.WrongFamilyError)(
           `chain ${network} is NEAR, but payTo "${payTo}" is not a valid NEAR account id.`
         );
       }
@@ -567,10 +567,10 @@ function makeNearNetwork(preset, rpcUrl) {
         if (tx && tx.success) return { height: "0" };
       } catch (e11) {
       }
-      throw new (0, _chunkMWBT7MCEcjs.ConfirmationTimeoutError)(`NEAR tx ${hash} not confirmed in time.`);
+      throw new (0, _chunkDCOUJZPLcjs.ConfirmationTimeoutError)(`NEAR tx ${hash} not confirmed in time.`);
     },
     async estimateCost() {
-      return _chunkMWBT7MCEcjs.nativeCost.call(void 0, {
+      return _chunkDCOUJZPLcjs.nativeCost.call(void 0, {
         symbol: "NEAR",
         decimals: NEAR_DECIMALS,
         fee: 1500000000000000000000n,
@@ -692,7 +692,7 @@ function makeNearNetwork(preset, rpcUrl) {
       try {
         relayerWallet = resolveNearWallet(relayer._native);
       } catch (err) {
-        throw new (0, _chunkMWBT7MCEcjs.SettlementError)(
+        throw new (0, _chunkDCOUJZPLcjs.SettlementError)(
           `NEAR exact settle: the relayer wallet is invalid (${err instanceof Error ? err.message : String(err)}).`,
           { cause: err }
         );

package/dist/{near-FZBUICCS.js → near-VDATC5AV.js}

@@ -10,7 +10,7 @@ import {
   nativeCost,
   rejectForeignToken,
   toInsufficientFundsError
-} from "./chunk-SC2ZYDHD.js";
+} from "./chunk-O32N6MFN.js";
 
 // src/drivers/near/index.ts
 import { JsonRpcProvider, Account, actions as actions2 } from "near-api-js";