uvd-x402-sdk 2.79.0 → 2.81.0

package/README.md

@@ -877,6 +877,8 @@ try {
 |---|---|---|
 | **402** | the payment was **rejected** | sign a **new** authorization |
 | **503** | **no verdict was reached** | resend the **same** credential |
+| **502** `upstream_rpc_unavailable` | the node never answered; nothing was broadcast | resend the **same** credential |
+| **502** `settlement_unconfirmed` | broadcast, **and it may be mined** | **send nothing** — look up the hash |
 
 Charging a `503` as a `402` makes the buyer sign and broadcast a second payment
 for money that was never refused — and the first authorization is still
@@ -893,6 +895,11 @@ if (!result.success) {
     // result.reason            -> 'holder_unknown' | 'forward_failed' | ...
     // result.retryAfterSeconds -> already clamped, never an hour
     // result.safeToReplay      -> true only if the facilitator proved nothing ran
+  } else if (isSettlementUnconfirmed(result)) {
+    // NOT a refusal: the transfer was broadcast and may already be mined.
+    // Reconcile — never re-send.
+    // result.transaction -> the hash, in that chain's own encoding
+    // result.paymentId   -> the same id a successful settle would have printed
   } else {
     // A real refusal. result.errorReason says why.
   }
@@ -935,12 +942,68 @@ new FacilitatorClient({ retries: 0 });   // never replay; default is 2 extra att
 misconfigured facilitator answering `Retry-After: 3600` would otherwise hang the
 request for an hour.
 
+### The two `502`s mean opposite things — branch on the body, not the status
+
+`POST /settle` answers `502` for two situations that call for opposite moves:
+
+| body `error` | `Retry-After` | did the money move? | retry? |
+|---|---|---|---|
+| `upstream_rpc_unavailable` | `30` | no, nothing was broadcast | **yes** |
+| `settlement_unconfirmed` | **absent** | **maybe — it may be mined** | **never** |
+
+`settlement_unconfirmed` is emitted when the transaction went out and no receipt
+ever came back. Retrying it re-signs a **new** authorization with a **fresh
+nonce**, which the chain accepts as a second, perfectly valid payment for the
+same purchase — the buyer pays twice, in exactly the case the facilitator emits
+this error to prevent. `authorizationState` does not stop it: the second
+authorization is genuinely new.
+
+So the status alone cannot decide. This SDK reads the body:
+
+```typescript
+import { isSettlementUnconfirmed, SETTLEMENT_UNCONFIRMED } from 'uvd-x402-sdk';
+
+const result = await client.settle(payment, requirements);
+
+if (!result.success && isSettlementUnconfirmed(result)) {
+  // result.retryable  -> false. Do not resend, and do not ask for a signature.
+  // result.transaction -> what to look up on chain
+  // result.paymentId   -> matches the id a successful settle prints, so a
+  //                       payment later found confirmed reconciles cleanly
+  await reconcileOnChain(result.transaction);
+}
+```
+
+`result.transaction` is **not always `0x`-prefixed** — Algorand prints base32 and
+Solana base58. Pass it through verbatim; reformatting it makes it unpasteable in
+an explorer, and pasting it is the entire remedy on offer.
+
+The same reading applies to `Erc8004LookupError` (`POST /register` goes through
+the same EVM path, so a mint can come back unconfirmed too) and to every gasless
+escrow call. An explicit `retryable: false` in a facilitator body always wins
+over the status — but only ever **downgrades**: a body claiming `retryable: true`
+on a `402` will not make this SDK resend a genuinely refused credential.
+
+Three independent signals stop a retry, because the cost of missing one is a
+second payment: the explicit `retryable: false`, the named
+`settlement_unconfirmed`, and — the general rule — **any 5xx body carrying a
+transaction hash at all**, under any of `transaction`, `transaction.hash`,
+`txHash`, `tx_hash` or `transaction_hash`. A hash in a *failure* means the
+facilitator got as far as broadcasting, whatever it called the error, so that
+last rule holds for codes that do not exist yet. It is the Python SDK's
+anti-double-settle guard, adopted here.
+
 ### Middleware
 
 `createPaymentMiddleware` and `createHonoMiddleware` answer **503 with a
 `Retry-After` header** — not `402`, not `500` — whenever the facilitator reached
 no verdict, and keep answering `402` for genuine rejections.
 
+An unconfirmed settlement is the one 5xx that goes out as **`500`, with no
+`Retry-After`**: "stop" is the correct instruction when the transfer may already
+be mining. The body carries `transaction`, `paymentId` and `retryable: false`, so
+the buyer's client can reconcile instead of paying again.
+
 ## ERC-8004 Trustless Agents
 
 Build verifiable on-chain reputation for AI agents and services. Supports **21 networks** (19 EVM + 2 Solana).

package/dist/adapters/index.d.mts

@@ -1,6 +1,6 @@
-import { Q as X402Version, k as PaymentResult } from '../index-ZH10otHE.mjs';
-export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-CYIVd4xO.mjs';
-import '../wallet-0cX9Pw2F.mjs';
+import { X as X402Version, a as PaymentResult } from '../index-D5uN1cIM.mjs';
+export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-Z9v4GxOZ.mjs';
+import '../wallet-w7BnImDG.mjs';
 
 /**
  * uvd-x402-sdk - Wagmi/Viem Adapter

package/dist/adapters/index.d.ts

@@ -1,6 +1,6 @@
-import { Q as X402Version, k as PaymentResult } from '../index-ZH10otHE.js';
-export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-DTDixPzO.js';
-import '../wallet-0cX9Pw2F.js';
+import { X as X402Version, a as PaymentResult } from '../index-D5uN1cIM.js';
+export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-C-KmORG9.js';
+import '../wallet-w7BnImDG.js';
 
 /**
  * uvd-x402-sdk - Wagmi/Viem Adapter

package/dist/backend/index.d.mts

@@ -1,5 +1,5 @@
-import { S as SigningWalletAdapter } from '../wallet-0cX9Pw2F.mjs';
-import { Q as X402Version, x as X402Header, G as X402PayloadData } from '../index-ZH10otHE.mjs';
+import { S as SigningWalletAdapter } from '../wallet-w7BnImDG.mjs';
+import { X as X402Version, h as X402Header, i as X402PayloadData } from '../index-D5uN1cIM.mjs';
 
 /**
  * Reading a facilitator refusal as DATA instead of prose.
@@ -45,8 +45,34 @@ import { Q as X402Version, x as X402Header, G as X402PayloadData } from '../inde
  * sequence that once minted five duplicate agents — reconcile with
  * `GET /identity/{network}/owner/{recipient}` or `getRegisterStatus` instead.
  *
+ * # The two `502`s of `/settle`, which mean opposite things
+ *
+ * | body `error`               | `Retry-After` | did the money move? | retry?    |
+ * |----------------------------|---------------|---------------------|-----------|
+ * | `upstream_rpc_unavailable` | `30`          | no, never broadcast | **yes**   |
+ * | `settlement_unconfirmed`   | **absent**    | **maybe — mined?**  | **NEVER** |
+ *
+ * `settlement_unconfirmed` is answered after the transaction was broadcast and
+ * no receipt ever arrived, so it MAY be mined. Retrying re-signs a new
+ * authorization with a fresh nonce, which the chain accepts as a second,
+ * perfectly valid payment for the same purchase — the buyer pays twice, in
+ * exactly the case the facilitator emits it to prevent. The `transaction` hash
+ * and `paymentId` travel in the body so the caller can LOOK AT THE CHAIN; they
+ * are not an invitation to send it again.
+ *
+ * The status cannot tell the two apart, which is why this file used to get it
+ * wrong: every `502` was retryable, and until `settlement_unconfirmed` existed
+ * that was correct. **Branch on the body.**
+ *
+ * The general form of that rule — **a 5xx whose body carries a transaction hash
+ * was broadcast, whatever the error is called** — is adopted from the Python
+ * SDK, which has carried it as its anti-double-settle guard
+ * (`uvd_x402_sdk/client.py`, `_is_retryable_settle_error`) while this one had
+ * only the status to go on.
+ *
  * Source of the shape: x402-rs `src/handlers.rs` `writer_lease_unavailable()`
- * and `require_writer_lease()`.
+ * and `require_writer_lease()`; `SettlementUnconfirmedResponse` in
+ * `src/types.rs`, built in the `IntoResponse` of `FacilitatorLocalError`.
  */
 /**
  * A `reason` the facilitator attaches to a writer-lease 503.
@@ -72,6 +98,13 @@ declare const REPLAYABLE_LEASE_REASONS: readonly WriterLeaseReason[];
  * automatically. Resolve it by reading state, not by re-POSTing.
  */
 declare const AMBIGUOUS_LEASE_REASONS: readonly WriterLeaseReason[];
+/**
+ * The facilitator's `error` code for a settle it broadcast and could not confirm.
+ *
+ * The transaction may be mined. This is the one upstream failure that must
+ * never be retried; reconcile with `transaction` / `paymentId` instead.
+ */
+declare const SETTLEMENT_UNCONFIRMED = "settlement_unconfirmed";
 /**
  * Ceiling, in seconds, on how long an automatic retry will wait.
  *
@@ -98,6 +131,24 @@ interface FacilitatorErrorInfo {
     status: number;
     /** The facilitator's own `reason`, when the body carried one. */
     reason?: string;
+    /**
+     * The facilitator's machine-readable `error` code, verbatim.
+     *
+     * Some codes carry a `(ref: <uuid>)` suffix, so compare with care —
+     * {@link SETTLEMENT_UNCONFIRMED} is emitted bare. Branch on this rather than
+     * on the status: `/settle` has two `502`s that mean opposite things.
+     */
+    errorCode?: string;
+    /**
+     * The hash of a transaction that WAS broadcast, in that chain's own encoding.
+     *
+     * Present on {@link SETTLEMENT_UNCONFIRMED}. Not always `0x`-prefixed:
+     * Algorand prints base32 and Solana base58, and reformatting it makes it
+     * unpasteable in an explorer — which is the entire remedy on offer.
+     */
+    transaction?: string;
+    /** `keccak256(caip2 ‖ txHash)`, the same id a successful settle would print. */
+    paymentId?: string;
     /**
      * Seconds to wait before retrying, already clamped to
      * {@link MAX_RETRY_AFTER_SECONDS}. Absent when the answer is not retryable.
@@ -126,6 +177,15 @@ interface FacilitatorFailureFields {
     status?: number;
     /** The facilitator's `reason` for the refusal (see {@link WriterLeaseReason}). */
     reason?: string;
+    /** The facilitator's machine-readable `error` code (see {@link FacilitatorErrorInfo.errorCode}). */
+    errorCode?: string;
+    /**
+     * A transaction that WAS broadcast and could not be confirmed. Look it up on
+     * chain; do NOT send the payment again. See {@link SETTLEMENT_UNCONFIRMED}.
+     */
+    transaction?: string;
+    /** The payment id for that transaction, identical to the one a settle prints. */
+    paymentId?: string;
     /** True when the same request may be sent again without re-signing anything. */
     retryable?: boolean;
     /** Seconds to wait before retrying, clamped to {@link MAX_RETRY_AFTER_SECONDS}. */
@@ -149,6 +209,41 @@ declare function parseRetryAfterSeconds(response: {
         get?: (name: string) => string | null;
     };
 }): number | undefined;
+/** Everything this SDK reads out of a facilitator error body. */
+interface ParsedFacilitatorErrorBody {
+    /** The `error` code, verbatim. */
+    errorCode?: string;
+    /** The writer-lease `reason`. */
+    reason?: string;
+    /** A broadcast transaction hash, in its own chain's encoding. */
+    transaction?: string;
+    /** The payment id for that hash. */
+    paymentId?: string;
+    /**
+     * The facilitator's OWN retry verdict, when it stated one.
+     *
+     * `undefined` on every body that does not carry the field — which is most of
+     * them, so absence means "the facilitator did not say", never "no".
+     */
+    retryable?: boolean;
+}
+/**
+ * Read a JSON error body, tolerating anything that is not one.
+ *
+ * Exported so {@link FacilitatorErrorInfo} and `Erc8004LookupError` read the
+ * SAME fields the same way. Two subtly different parses of the same body is how
+ * one code path stops honouring a `retryable: false` the other one honours.
+ */
+declare function parseFacilitatorErrorBody(body: string): ParsedFacilitatorErrorBody;
+/**
+ * This refusal reports a transaction that may already be mined.
+ *
+ * The caller's move is to look up `transaction` / `paymentId` on chain. Sending
+ * the payment again is the double-charge.
+ */
+declare function isSettlementUnconfirmed(failure: {
+    errorCode?: string;
+}): boolean;
 /**
  * Turn a non-2xx facilitator response into {@link FacilitatorErrorInfo}.
  *
@@ -2118,6 +2213,13 @@ declare class Erc8004LookupError extends Error {
      * `502` and `504` join `503` and `429` here: a gateway that answered on the
      * facilitator's behalf is exactly as silent about the agent's existence, and
      * reading either as absence has the same consequence -- a duplicate mint.
+     *
+     * **Except when the body says otherwise.** `POST /register` goes through the
+     * same EVM `send_transaction_from` as a settle, so it can answer
+     * `settlement_unconfirmed`: the mint was broadcast and may be mined. That is
+     * a `502` where retrying is precisely the thing that mints the duplicate this
+     * class exists to prevent, so an explicit `retryable: false` wins over the
+     * status. See {@link SETTLEMENT_UNCONFIRMED}.
      */
     get retryable(): boolean;
     /**
@@ -2127,6 +2229,18 @@ declare class Erc8004LookupError extends Error {
      * request may be re-sent; see {@link isReplayableLeaseReason}.
      */
     get reason(): string | undefined;
+    /** The facilitator's machine-readable `error` code, when the body carried one. */
+    get errorCode(): string | undefined;
+    /**
+     * A transaction that WAS broadcast and could not be confirmed.
+     *
+     * Present on `settlement_unconfirmed`. This is what to do INSTEAD of
+     * retrying: look it up on chain. An error that carries "do not retry" and no
+     * hash leaves the caller with nothing to act on.
+     */
+    get transaction(): string | undefined;
+    /** The payment id for {@link transaction}, identical to a successful settle's. */
+    get paymentId(): string | undefined;
     /**
      * The facilitator NAMED a reason proving it executed nothing.
      *
@@ -3261,4 +3375,4 @@ declare class AdvancedEscrowClient {
     private sendViaAdapter;
 }
 
-export { AMBIGUOUS_LEASE_REASONS, type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, type AtomStats, BASE_MAINNET_CONTRACTS, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarRegisterOptions, type BazaarResource, type CreateEscrowOptions, DEFAULT_FACILITATOR_RETRIES, DEFAULT_RETRY_AFTER_SECONDS, DEPOSIT_LIMIT_USDC, type DiscoveryAccepts, type DiscoveryCuration, type DiscoveryHealth, type DiscoveryHealthStatus, type DiscoveryListOptions, type DiscoveryPagination, type DiscoveryRegisterOptions, type DiscoveryResource, type DiscoveryResponse, type DiscoverySource, type DiscoveryStats, type DiscoveryTier, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, Erc8004LookupError, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FacilitatorErrorInfo, type FacilitatorFailureFields, type FacilitatorFetchOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, HEALTH_FILTERS, type HonoMiddlewareOptions, type IdentityByOwnerResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, MAX_RETRY_AFTER_SECONDS, MAX_SEARCH_LEN, type MetadataEntryParam, OPERATOR_ABI, OPERATOR_ABI_CREATE3, PAYMENT_INFO_TYPEHASH, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentPayloadV2, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type PaymentRequirementsV2, type PrepareRelayFeedbackRequest, type PrepareRelayFeedbackResponse, type PrepareRelayResponseRequest, type ProofOfPayment, RELAYED_FEEDBACK_NETWORKS, REPLAYABLE_LEASE_REASONS, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type RegisterJobResponse, type RegisterJobStatus, RegistrationPendingError, type RelayAuthorizationParams, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type ResourceInfoV2, type SettleRequest, type SettleRequestV2, type SettleResponse, type SettleResponseWithProof, type SubmitRelayFeedbackRequest, type SubmitRelayResponseRequest, TIER_FILTERS, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyRequestV2, type VerifyResponse, WRITER_LEASE_REASONS, type WriterLeaseReason, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildSettleRequestForVersion, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestForVersion, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, carryFailureFields, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isAmbiguousLeaseReason, isEscrowExpired, isEscrowSupportedOnChain, isRegisterJobTerminal, isReplayableLeaseReason, parsePaymentHeader, parseRetryAfterSeconds, readFacilitatorError, resolveEnvelopeVersion, supportsRelayedFeedback, toPaymentRequirementsV2, toResourceInfoV2, wireNetwork };
+export { AMBIGUOUS_LEASE_REASONS, type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, type AtomStats, BASE_MAINNET_CONTRACTS, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarRegisterOptions, type BazaarResource, type CreateEscrowOptions, DEFAULT_FACILITATOR_RETRIES, DEFAULT_RETRY_AFTER_SECONDS, DEPOSIT_LIMIT_USDC, type DiscoveryAccepts, type DiscoveryCuration, type DiscoveryHealth, type DiscoveryHealthStatus, type DiscoveryListOptions, type DiscoveryPagination, type DiscoveryRegisterOptions, type DiscoveryResource, type DiscoveryResponse, type DiscoverySource, type DiscoveryStats, type DiscoveryTier, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, Erc8004LookupError, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FacilitatorErrorInfo, type FacilitatorFailureFields, type FacilitatorFetchOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, HEALTH_FILTERS, type HonoMiddlewareOptions, type IdentityByOwnerResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, MAX_RETRY_AFTER_SECONDS, MAX_SEARCH_LEN, type MetadataEntryParam, OPERATOR_ABI, OPERATOR_ABI_CREATE3, PAYMENT_INFO_TYPEHASH, type ParsedFacilitatorErrorBody, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentPayloadV2, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type PaymentRequirementsV2, type PrepareRelayFeedbackRequest, type PrepareRelayFeedbackResponse, type PrepareRelayResponseRequest, type ProofOfPayment, RELAYED_FEEDBACK_NETWORKS, REPLAYABLE_LEASE_REASONS, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type RegisterJobResponse, type RegisterJobStatus, RegistrationPendingError, type RelayAuthorizationParams, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type ResourceInfoV2, SETTLEMENT_UNCONFIRMED, type SettleRequest, type SettleRequestV2, type SettleResponse, type SettleResponseWithProof, type SubmitRelayFeedbackRequest, type SubmitRelayResponseRequest, TIER_FILTERS, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyRequestV2, type VerifyResponse, WRITER_LEASE_REASONS, type WriterLeaseReason, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildSettleRequestForVersion, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestForVersion, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, carryFailureFields, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isAmbiguousLeaseReason, isEscrowExpired, isEscrowSupportedOnChain, isRegisterJobTerminal, isReplayableLeaseReason, isSettlementUnconfirmed, parseFacilitatorErrorBody, parsePaymentHeader, parseRetryAfterSeconds, readFacilitatorError, resolveEnvelopeVersion, supportsRelayedFeedback, toPaymentRequirementsV2, toResourceInfoV2, wireNetwork };

package/dist/backend/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SigningWalletAdapter } from '../wallet-0cX9Pw2F.js';
-import { Q as X402Version, x as X402Header, G as X402PayloadData } from '../index-ZH10otHE.js';
+import { S as SigningWalletAdapter } from '../wallet-w7BnImDG.js';
+import { X as X402Version, h as X402Header, i as X402PayloadData } from '../index-D5uN1cIM.js';
 
 /**
  * Reading a facilitator refusal as DATA instead of prose.
@@ -45,8 +45,34 @@ import { Q as X402Version, x as X402Header, G as X402PayloadData } from '../inde
  * sequence that once minted five duplicate agents — reconcile with
  * `GET /identity/{network}/owner/{recipient}` or `getRegisterStatus` instead.
  *
+ * # The two `502`s of `/settle`, which mean opposite things
+ *
+ * | body `error`               | `Retry-After` | did the money move? | retry?    |
+ * |----------------------------|---------------|---------------------|-----------|
+ * | `upstream_rpc_unavailable` | `30`          | no, never broadcast | **yes**   |
+ * | `settlement_unconfirmed`   | **absent**    | **maybe — mined?**  | **NEVER** |
+ *
+ * `settlement_unconfirmed` is answered after the transaction was broadcast and
+ * no receipt ever arrived, so it MAY be mined. Retrying re-signs a new
+ * authorization with a fresh nonce, which the chain accepts as a second,
+ * perfectly valid payment for the same purchase — the buyer pays twice, in
+ * exactly the case the facilitator emits it to prevent. The `transaction` hash
+ * and `paymentId` travel in the body so the caller can LOOK AT THE CHAIN; they
+ * are not an invitation to send it again.
+ *
+ * The status cannot tell the two apart, which is why this file used to get it
+ * wrong: every `502` was retryable, and until `settlement_unconfirmed` existed
+ * that was correct. **Branch on the body.**
+ *
+ * The general form of that rule — **a 5xx whose body carries a transaction hash
+ * was broadcast, whatever the error is called** — is adopted from the Python
+ * SDK, which has carried it as its anti-double-settle guard
+ * (`uvd_x402_sdk/client.py`, `_is_retryable_settle_error`) while this one had
+ * only the status to go on.
+ *
  * Source of the shape: x402-rs `src/handlers.rs` `writer_lease_unavailable()`
- * and `require_writer_lease()`.
+ * and `require_writer_lease()`; `SettlementUnconfirmedResponse` in
+ * `src/types.rs`, built in the `IntoResponse` of `FacilitatorLocalError`.
  */
 /**
  * A `reason` the facilitator attaches to a writer-lease 503.
@@ -72,6 +98,13 @@ declare const REPLAYABLE_LEASE_REASONS: readonly WriterLeaseReason[];
  * automatically. Resolve it by reading state, not by re-POSTing.
  */
 declare const AMBIGUOUS_LEASE_REASONS: readonly WriterLeaseReason[];
+/**
+ * The facilitator's `error` code for a settle it broadcast and could not confirm.
+ *
+ * The transaction may be mined. This is the one upstream failure that must
+ * never be retried; reconcile with `transaction` / `paymentId` instead.
+ */
+declare const SETTLEMENT_UNCONFIRMED = "settlement_unconfirmed";
 /**
  * Ceiling, in seconds, on how long an automatic retry will wait.
  *
@@ -98,6 +131,24 @@ interface FacilitatorErrorInfo {
     status: number;
     /** The facilitator's own `reason`, when the body carried one. */
     reason?: string;
+    /**
+     * The facilitator's machine-readable `error` code, verbatim.
+     *
+     * Some codes carry a `(ref: <uuid>)` suffix, so compare with care —
+     * {@link SETTLEMENT_UNCONFIRMED} is emitted bare. Branch on this rather than
+     * on the status: `/settle` has two `502`s that mean opposite things.
+     */
+    errorCode?: string;
+    /**
+     * The hash of a transaction that WAS broadcast, in that chain's own encoding.
+     *
+     * Present on {@link SETTLEMENT_UNCONFIRMED}. Not always `0x`-prefixed:
+     * Algorand prints base32 and Solana base58, and reformatting it makes it
+     * unpasteable in an explorer — which is the entire remedy on offer.
+     */
+    transaction?: string;
+    /** `keccak256(caip2 ‖ txHash)`, the same id a successful settle would print. */
+    paymentId?: string;
     /**
      * Seconds to wait before retrying, already clamped to
      * {@link MAX_RETRY_AFTER_SECONDS}. Absent when the answer is not retryable.
@@ -126,6 +177,15 @@ interface FacilitatorFailureFields {
     status?: number;
     /** The facilitator's `reason` for the refusal (see {@link WriterLeaseReason}). */
     reason?: string;
+    /** The facilitator's machine-readable `error` code (see {@link FacilitatorErrorInfo.errorCode}). */
+    errorCode?: string;
+    /**
+     * A transaction that WAS broadcast and could not be confirmed. Look it up on
+     * chain; do NOT send the payment again. See {@link SETTLEMENT_UNCONFIRMED}.
+     */
+    transaction?: string;
+    /** The payment id for that transaction, identical to the one a settle prints. */
+    paymentId?: string;
     /** True when the same request may be sent again without re-signing anything. */
     retryable?: boolean;
     /** Seconds to wait before retrying, clamped to {@link MAX_RETRY_AFTER_SECONDS}. */
@@ -149,6 +209,41 @@ declare function parseRetryAfterSeconds(response: {
         get?: (name: string) => string | null;
     };
 }): number | undefined;
+/** Everything this SDK reads out of a facilitator error body. */
+interface ParsedFacilitatorErrorBody {
+    /** The `error` code, verbatim. */
+    errorCode?: string;
+    /** The writer-lease `reason`. */
+    reason?: string;
+    /** A broadcast transaction hash, in its own chain's encoding. */
+    transaction?: string;
+    /** The payment id for that hash. */
+    paymentId?: string;
+    /**
+     * The facilitator's OWN retry verdict, when it stated one.
+     *
+     * `undefined` on every body that does not carry the field — which is most of
+     * them, so absence means "the facilitator did not say", never "no".
+     */
+    retryable?: boolean;
+}
+/**
+ * Read a JSON error body, tolerating anything that is not one.
+ *
+ * Exported so {@link FacilitatorErrorInfo} and `Erc8004LookupError` read the
+ * SAME fields the same way. Two subtly different parses of the same body is how
+ * one code path stops honouring a `retryable: false` the other one honours.
+ */
+declare function parseFacilitatorErrorBody(body: string): ParsedFacilitatorErrorBody;
+/**
+ * This refusal reports a transaction that may already be mined.
+ *
+ * The caller's move is to look up `transaction` / `paymentId` on chain. Sending
+ * the payment again is the double-charge.
+ */
+declare function isSettlementUnconfirmed(failure: {
+    errorCode?: string;
+}): boolean;
 /**
  * Turn a non-2xx facilitator response into {@link FacilitatorErrorInfo}.
  *
@@ -2118,6 +2213,13 @@ declare class Erc8004LookupError extends Error {
      * `502` and `504` join `503` and `429` here: a gateway that answered on the
      * facilitator's behalf is exactly as silent about the agent's existence, and
      * reading either as absence has the same consequence -- a duplicate mint.
+     *
+     * **Except when the body says otherwise.** `POST /register` goes through the
+     * same EVM `send_transaction_from` as a settle, so it can answer
+     * `settlement_unconfirmed`: the mint was broadcast and may be mined. That is
+     * a `502` where retrying is precisely the thing that mints the duplicate this
+     * class exists to prevent, so an explicit `retryable: false` wins over the
+     * status. See {@link SETTLEMENT_UNCONFIRMED}.
      */
     get retryable(): boolean;
     /**
@@ -2127,6 +2229,18 @@ declare class Erc8004LookupError extends Error {
      * request may be re-sent; see {@link isReplayableLeaseReason}.
      */
     get reason(): string | undefined;
+    /** The facilitator's machine-readable `error` code, when the body carried one. */
+    get errorCode(): string | undefined;
+    /**
+     * A transaction that WAS broadcast and could not be confirmed.
+     *
+     * Present on `settlement_unconfirmed`. This is what to do INSTEAD of
+     * retrying: look it up on chain. An error that carries "do not retry" and no
+     * hash leaves the caller with nothing to act on.
+     */
+    get transaction(): string | undefined;
+    /** The payment id for {@link transaction}, identical to a successful settle's. */
+    get paymentId(): string | undefined;
     /**
      * The facilitator NAMED a reason proving it executed nothing.
      *
@@ -3261,4 +3375,4 @@ declare class AdvancedEscrowClient {
     private sendViaAdapter;
 }
 
-export { AMBIGUOUS_LEASE_REASONS, type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, type AtomStats, BASE_MAINNET_CONTRACTS, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarRegisterOptions, type BazaarResource, type CreateEscrowOptions, DEFAULT_FACILITATOR_RETRIES, DEFAULT_RETRY_AFTER_SECONDS, DEPOSIT_LIMIT_USDC, type DiscoveryAccepts, type DiscoveryCuration, type DiscoveryHealth, type DiscoveryHealthStatus, type DiscoveryListOptions, type DiscoveryPagination, type DiscoveryRegisterOptions, type DiscoveryResource, type DiscoveryResponse, type DiscoverySource, type DiscoveryStats, type DiscoveryTier, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, Erc8004LookupError, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FacilitatorErrorInfo, type FacilitatorFailureFields, type FacilitatorFetchOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, HEALTH_FILTERS, type HonoMiddlewareOptions, type IdentityByOwnerResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, MAX_RETRY_AFTER_SECONDS, MAX_SEARCH_LEN, type MetadataEntryParam, OPERATOR_ABI, OPERATOR_ABI_CREATE3, PAYMENT_INFO_TYPEHASH, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentPayloadV2, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type PaymentRequirementsV2, type PrepareRelayFeedbackRequest, type PrepareRelayFeedbackResponse, type PrepareRelayResponseRequest, type ProofOfPayment, RELAYED_FEEDBACK_NETWORKS, REPLAYABLE_LEASE_REASONS, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type RegisterJobResponse, type RegisterJobStatus, RegistrationPendingError, type RelayAuthorizationParams, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type ResourceInfoV2, type SettleRequest, type SettleRequestV2, type SettleResponse, type SettleResponseWithProof, type SubmitRelayFeedbackRequest, type SubmitRelayResponseRequest, TIER_FILTERS, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyRequestV2, type VerifyResponse, WRITER_LEASE_REASONS, type WriterLeaseReason, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildSettleRequestForVersion, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestForVersion, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, carryFailureFields, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isAmbiguousLeaseReason, isEscrowExpired, isEscrowSupportedOnChain, isRegisterJobTerminal, isReplayableLeaseReason, parsePaymentHeader, parseRetryAfterSeconds, readFacilitatorError, resolveEnvelopeVersion, supportsRelayedFeedback, toPaymentRequirementsV2, toResourceInfoV2, wireNetwork };
+export { AMBIGUOUS_LEASE_REASONS, type AdvancedAuthorizationResult, AdvancedEscrowClient, type AdvancedEscrowClientOptions, type AdvancedEscrowContracts, type AdvancedEscrowTaskTier, type AdvancedPaymentInfo, type AdvancedTransactionResult, type AgentId, type AgentIdentity, type AgentRegistration, type AgentRegistrationFile, type AgentService, type AtomStats, BASE_MAINNET_CONTRACTS, BazaarClient, type BazaarClientOptions, type BazaarDiscoverOptions, type BazaarDiscoverResponse, type BazaarRegisterOptions, type BazaarResource, type CreateEscrowOptions, DEFAULT_FACILITATOR_RETRIES, DEFAULT_RETRY_AFTER_SECONDS, DEPOSIT_LIMIT_USDC, type DiscoveryAccepts, type DiscoveryCuration, type DiscoveryHealth, type DiscoveryHealthStatus, type DiscoveryListOptions, type DiscoveryPagination, type DiscoveryRegisterOptions, type DiscoveryResource, type DiscoveryResponse, type DiscoverySource, type DiscoveryStats, type DiscoveryTier, type Dispute, type DisputeOutcome, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, type Erc8004ClientOptions, Erc8004LookupError, type Erc8004Network, EscrowClient, type EscrowClientOptions, type EscrowPayment, type EscrowStateResponse, type EscrowStatus, FacilitatorClient, type FacilitatorClientOptions, type FacilitatorErrorInfo, type FacilitatorFailureFields, type FacilitatorFetchOptions, type FeedbackEntry, type FeedbackParams, type FeedbackRequest, type FeedbackResponse, HEALTH_FILTERS, type HonoMiddlewareOptions, type IdentityByOwnerResponse, type IdentityMetadataResponse, type IdentityTotalSupplyResponse, MAX_RETRY_AFTER_SECONDS, MAX_SEARCH_LEN, type MetadataEntryParam, OPERATOR_ABI, OPERATOR_ABI_CREATE3, PAYMENT_INFO_TYPEHASH, type ParsedFacilitatorErrorBody, type PaymentAcceptance, type PaymentMiddlewareOptions, type PaymentPayloadV2, type PaymentRequirementResolver, type PaymentRequirements, type PaymentRequirementsOptions, type PaymentRequirementsV2, type PrepareRelayFeedbackRequest, type PrepareRelayFeedbackResponse, type PrepareRelayResponseRequest, type ProofOfPayment, RELAYED_FEEDBACK_NETWORKS, REPLAYABLE_LEASE_REASONS, type RefundRequest, type RefundStatus, type RegisterAgentRequest, type RegisterAgentResponse, type RegisterJobResponse, type RegisterJobStatus, RegistrationPendingError, type RelayAuthorizationParams, type ReputationResponse, type ReputationSummary, type RequestRefundOptions, type ResourceInfoV2, SETTLEMENT_UNCONFIRMED, type SettleRequest, type SettleRequestV2, type SettleResponse, type SettleResponseWithProof, type SubmitRelayFeedbackRequest, type SubmitRelayResponseRequest, TIER_FILTERS, TIER_TIMINGS, USDC_DOMAIN_NAME, type VerifiedPaymentState, type VerifyRequest, type VerifyRequestV2, type VerifyResponse, WRITER_LEASE_REASONS, type WriterLeaseReason, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildSettleRequestForVersion, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestForVersion, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, carryFailureFields, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isAmbiguousLeaseReason, isEscrowExpired, isEscrowSupportedOnChain, isRegisterJobTerminal, isReplayableLeaseReason, isSettlementUnconfirmed, parseFacilitatorErrorBody, parsePaymentHeader, parseRetryAfterSeconds, readFacilitatorError, resolveEnvelopeVersion, supportsRelayedFeedback, toPaymentRequirementsV2, toResourceInfoV2, wireNetwork };