uvd-x402-sdk 2.75.0 → 2.76.0

package/dist/index.d.mts

@@ -4,7 +4,7 @@ export { A as AlgorandPaymentPayload, C as CAIP2_IDENTIFIERS, a as CAIP2_TO_CHAI
 import { S as SigningWalletAdapter } from './wallet-0cX9Pw2F.mjs';
 export { E as EIP3009Authorization, a as EIP3009Params } from './wallet-0cX9Pw2F.mjs';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from './ows-CYIVd4xO.mjs';
-export { FacilitatorClient, FacilitatorClientOptions, HonoMiddlewareOptions, PaymentAcceptance, PaymentMiddlewareOptions, PaymentPayloadV2, PaymentRequirementsV2, ResourceInfoV2, SettleRequestV2, VerifiedPaymentState, VerifyRequestV2, X402_CORS_HEADERS, X402_HEADER_NAMES, buildPaymentRequirements, buildSettleRequest, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestV2, create402Response, createHonoMiddleware, createPaymentMiddleware, extractPaymentFromHeaders, getCorsHeaders } from './backend/index.mjs';
+export { AMBIGUOUS_LEASE_REASONS, DEFAULT_FACILITATOR_RETRIES, DEFAULT_RETRY_AFTER_SECONDS, FacilitatorClient, FacilitatorClientOptions, FacilitatorErrorInfo, FacilitatorFailureFields, FacilitatorFetchOptions, HonoMiddlewareOptions, MAX_RETRY_AFTER_SECONDS, PaymentAcceptance, PaymentMiddlewareOptions, PaymentPayloadV2, PaymentRequirementsV2, REPLAYABLE_LEASE_REASONS, ResourceInfoV2, SettleRequestV2, VerifiedPaymentState, VerifyRequestV2, WRITER_LEASE_REASONS, WriterLeaseReason, X402_CORS_HEADERS, X402_HEADER_NAMES, buildPaymentRequirements, buildSettleRequest, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestV2, create402Response, createHonoMiddleware, createPaymentMiddleware, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, isAmbiguousLeaseReason, isReplayableLeaseReason, parseRetryAfterSeconds, readFacilitatorError } from './backend/index.mjs';
 
 /**
  * DX402 `durable-evidence`: recover a paid response after the fact.
@@ -303,6 +303,41 @@ interface AnchorOptions {
      * anchor for the same payment supersedes it.
      */
     sign?: (digest: Uint8Array) => string | Promise<string>;
+    /**
+     * `(sealedBytes) => pointer`. Bring your own storage.
+     *
+     * Without this the sealed envelope travels **inside** the anchor request and
+     * the facilitator hosts it, which is the easy path and stays the default. With
+     * it, the SDK still seals exactly as before -- the buyer has to be able to
+     * decrypt, so the sealing is not optional -- then hands you the ciphertext,
+     * you write it wherever you keep durable bytes, and you return the pointer
+     * that addresses it. The request then carries only that pointer, so the
+     * ciphertext never travels through the anchor call and
+     * {@link ANCHOR_MAX_REQUEST_BYTES} does not apply to your body.
+     *
+     * A callable rather than a precomputed pointer, for the same reason
+     * {@link AnchorOptions.sign} is one: the SDK must seal first, and only then
+     * can anything be uploaded. Handing in a pointer computed in advance would
+     * mean addressing bytes that do not exist yet.
+     *
+     * The returned pointer is what the buyer will dereference, so it must be
+     * readable by them -- see {@link dereferencePointer} for the schemes the SDK
+     * resolves out of the box. It is also bound into the seller signature.
+     *
+     * **It is never allowed to break the sale.** If it throws or returns
+     * something unusable, the anchor degrades to a skip and the payment is
+     * untouched.
+     */
+    upload?: (sealed: Uint8Array) => string | Promise<string>;
+    /**
+     * Which storage family the pointer belongs to: `s3`, `ipfs` or `arweave`.
+     *
+     * Defaults to `s3`, and in {@link AnchorOptions.upload} mode it is inferred
+     * from the pointer's scheme when you do not say. Distinct from `storage`,
+     * which names one of the FACILITATOR's own offers and is meaningless when you
+     * supply the bytes yourself.
+     */
+    backend?: 's3' | 'ipfs' | 'arweave';
     retention?: string;
     facilitator?: string;
     fetch?: typeof fetch;
@@ -322,10 +357,15 @@ interface AnchorOptions {
  * identical, the ed25519 form was refused (`409 dx402_already_anchored`) and the
  * EVM form superseded the provisional.
  *
- * `pointer` stays empty on both branches: this call sends `sealed`, so the
- * facilitator issues the pointer and you cannot sign what you have not seen.
+ * `pointer` defaults to the empty string, which is right when you send `sealed`:
+ * the facilitator issues the pointer and you cannot sign what you have not seen.
+ * When you supply your OWN pointer it must be passed here **verbatim** -- the
+ * facilitator verifies against `req.pointer` when one is present and against
+ * `""` when it is absent (x402-rs `dx402/service.rs`, `signed_pointer`), so
+ * signing the empty string alongside a pointer produces a signature that never
+ * verifies and an anchor that silently stays provisional.
  */
-declare function sellerDigestFor(paymentId: string, contentHash: string, payee: string, network: string): Uint8Array | undefined;
+declare function sellerDigestFor(paymentId: string, contentHash: string, payee: string, network: string, pointer?: string): Uint8Array | undefined;
 /**
  * Largest `POST /dx402/anchor` request the facilitator accepts, mirroring its
  * `MAX_REQUEST_BODY_BYTES` (default 64 KiB, an anti-OOM bound on every route).

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { A as AlgorandPaymentPayload, C as CAIP2_IDENTIFIERS, a as CAIP2_TO_CHAI
 import { S as SigningWalletAdapter } from './wallet-0cX9Pw2F.js';
 export { E as EIP3009Authorization, a as EIP3009Params } from './wallet-0cX9Pw2F.js';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from './ows-DTDixPzO.js';
-export { FacilitatorClient, FacilitatorClientOptions, HonoMiddlewareOptions, PaymentAcceptance, PaymentMiddlewareOptions, PaymentPayloadV2, PaymentRequirementsV2, ResourceInfoV2, SettleRequestV2, VerifiedPaymentState, VerifyRequestV2, X402_CORS_HEADERS, X402_HEADER_NAMES, buildPaymentRequirements, buildSettleRequest, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestV2, create402Response, createHonoMiddleware, createPaymentMiddleware, extractPaymentFromHeaders, getCorsHeaders } from './backend/index.js';
+export { AMBIGUOUS_LEASE_REASONS, DEFAULT_FACILITATOR_RETRIES, DEFAULT_RETRY_AFTER_SECONDS, FacilitatorClient, FacilitatorClientOptions, FacilitatorErrorInfo, FacilitatorFailureFields, FacilitatorFetchOptions, HonoMiddlewareOptions, MAX_RETRY_AFTER_SECONDS, PaymentAcceptance, PaymentMiddlewareOptions, PaymentPayloadV2, PaymentRequirementsV2, REPLAYABLE_LEASE_REASONS, ResourceInfoV2, SettleRequestV2, VerifiedPaymentState, VerifyRequestV2, WRITER_LEASE_REASONS, WriterLeaseReason, X402_CORS_HEADERS, X402_HEADER_NAMES, buildPaymentRequirements, buildSettleRequest, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestV2, create402Response, createHonoMiddleware, createPaymentMiddleware, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, isAmbiguousLeaseReason, isReplayableLeaseReason, parseRetryAfterSeconds, readFacilitatorError } from './backend/index.js';
 
 /**
  * DX402 `durable-evidence`: recover a paid response after the fact.
@@ -303,6 +303,41 @@ interface AnchorOptions {
      * anchor for the same payment supersedes it.
      */
     sign?: (digest: Uint8Array) => string | Promise<string>;
+    /**
+     * `(sealedBytes) => pointer`. Bring your own storage.
+     *
+     * Without this the sealed envelope travels **inside** the anchor request and
+     * the facilitator hosts it, which is the easy path and stays the default. With
+     * it, the SDK still seals exactly as before -- the buyer has to be able to
+     * decrypt, so the sealing is not optional -- then hands you the ciphertext,
+     * you write it wherever you keep durable bytes, and you return the pointer
+     * that addresses it. The request then carries only that pointer, so the
+     * ciphertext never travels through the anchor call and
+     * {@link ANCHOR_MAX_REQUEST_BYTES} does not apply to your body.
+     *
+     * A callable rather than a precomputed pointer, for the same reason
+     * {@link AnchorOptions.sign} is one: the SDK must seal first, and only then
+     * can anything be uploaded. Handing in a pointer computed in advance would
+     * mean addressing bytes that do not exist yet.
+     *
+     * The returned pointer is what the buyer will dereference, so it must be
+     * readable by them -- see {@link dereferencePointer} for the schemes the SDK
+     * resolves out of the box. It is also bound into the seller signature.
+     *
+     * **It is never allowed to break the sale.** If it throws or returns
+     * something unusable, the anchor degrades to a skip and the payment is
+     * untouched.
+     */
+    upload?: (sealed: Uint8Array) => string | Promise<string>;
+    /**
+     * Which storage family the pointer belongs to: `s3`, `ipfs` or `arweave`.
+     *
+     * Defaults to `s3`, and in {@link AnchorOptions.upload} mode it is inferred
+     * from the pointer's scheme when you do not say. Distinct from `storage`,
+     * which names one of the FACILITATOR's own offers and is meaningless when you
+     * supply the bytes yourself.
+     */
+    backend?: 's3' | 'ipfs' | 'arweave';
     retention?: string;
     facilitator?: string;
     fetch?: typeof fetch;
@@ -322,10 +357,15 @@ interface AnchorOptions {
  * identical, the ed25519 form was refused (`409 dx402_already_anchored`) and the
  * EVM form superseded the provisional.
  *
- * `pointer` stays empty on both branches: this call sends `sealed`, so the
- * facilitator issues the pointer and you cannot sign what you have not seen.
+ * `pointer` defaults to the empty string, which is right when you send `sealed`:
+ * the facilitator issues the pointer and you cannot sign what you have not seen.
+ * When you supply your OWN pointer it must be passed here **verbatim** -- the
+ * facilitator verifies against `req.pointer` when one is present and against
+ * `""` when it is absent (x402-rs `dx402/service.rs`, `signed_pointer`), so
+ * signing the empty string alongside a pointer produces a signature that never
+ * verifies and an anchor that silently stays provisional.
  */
-declare function sellerDigestFor(paymentId: string, contentHash: string, payee: string, network: string): Uint8Array | undefined;
+declare function sellerDigestFor(paymentId: string, contentHash: string, payee: string, network: string, pointer?: string): Uint8Array | undefined;
 /**
  * Largest `POST /dx402/anchor` request the facilitator accepts, mirroring its
  * `MAX_REQUEST_BODY_BYTES` (default 64 KiB, an anti-OOM bound on every route).

package/dist/index.js

@@ -1584,13 +1584,13 @@ function chainIdFor(network) {
   if (Number.isFinite(byId) && byId > 0) return getChainById(byId)?.chainId;
   return getChainByName(name)?.chainId;
 }
-function sellerDigestFor(paymentId2, contentHash2, payee, network) {
+function sellerDigestFor(paymentId2, contentHash2, payee, network, pointer = "") {
   if (isEvmAddress(payee)) {
     const chainId = chainIdFor(network);
     if (!chainId) return void 0;
-    return anchorDigest(paymentId2, contentHash2, "", payee, chainId);
+    return anchorDigest(paymentId2, contentHash2, pointer, payee, chainId);
   }
-  return anchorDigest(paymentId2, contentHash2, "", ZERO_ADDRESS, 0);
+  return anchorDigest(paymentId2, contentHash2, pointer, ZERO_ADDRESS, 0);
 }
 var ANCHOR_MAX_REQUEST_BYTES = 64 * 1024;
 function toBase64(bytes) {
@@ -1601,6 +1601,11 @@ function toBase64(bytes) {
   }
   return btoa(out);
 }
+function backendForPointer(pointer) {
+  if (pointer.startsWith("ipfs://")) return "ipfs";
+  if (pointer.startsWith("ar://")) return "arweave";
+  return "s3";
+}
 async function anchorEvidence(body, opts) {
   try {
     const recipients = [
@@ -1611,14 +1616,29 @@ async function anchorEvidence(body, opts) {
     }
     const blob = sealEvidenceTo(body, recipients, opts.paymentId);
     const hash = contentHash(body);
+    let pointer;
+    if (opts.upload) {
+      try {
+        pointer = await opts.upload(blob);
+      } catch {
+        return { v: 1, skipped: "anchor_failed", stage: "upload" };
+      }
+      if (typeof pointer !== "string" || pointer.trim() === "") {
+        return { v: 1, skipped: "anchor_failed", stage: "upload" };
+      }
+      pointer = pointer.trim();
+    }
     const payload = {
       paymentId: opts.paymentId,
       network: opts.network,
       txHash: opts.txHash,
       payer: opts.payer,
       payee: opts.payee,
-      sealed: toBase64(blob),
-      backend: "s3",
+      // Exactly one of these. The facilitator dispatches on their presence:
+      // `sealed` -> it hosts and derives the pointer; `pointer` alone -> it uses
+      // yours; neither -> error (x402-rs `dx402/service.rs`).
+      ...pointer !== void 0 ? { pointer } : { sealed: toBase64(blob) },
+      backend: opts.backend ?? (pointer !== void 0 ? backendForPointer(pointer) : "s3"),
       contentHash: hash,
       keyAlg: opts.payerKey.length === 32 ? "ECIES-X25519" : "ECIES-secp256k1",
       mode: "direct",
@@ -1632,7 +1652,7 @@ async function anchorEvidence(body, opts) {
       payload.storage = opts.storage;
     }
     if (opts.sign) {
-      const digest = sellerDigestFor(opts.paymentId, hash, opts.payee, opts.network);
+      const digest = sellerDigestFor(opts.paymentId, hash, opts.payee, opts.network, pointer ?? "");
       if (digest === void 0) {
         unsigned = "unknown_chain_id";
       } else {
@@ -1640,7 +1660,7 @@ async function anchorEvidence(body, opts) {
       }
     }
     const wire = JSON.stringify(payload);
-    if (new TextEncoder().encode(wire).length > ANCHOR_MAX_REQUEST_BYTES) {
+    if (pointer === void 0 && new TextEncoder().encode(wire).length > ANCHOR_MAX_REQUEST_BYTES) {
       return { v: 1, skipped: "too_large" };
     }
     const base = (opts.facilitator ?? "https://facilitator.ultravioletadao.xyz").replace(
@@ -3723,6 +3743,118 @@ async function buildEscrowPreAuth(wallet, params) {
   });
 }
 
+// src/backend/facilitator-error.ts
+var WRITER_LEASE_REASONS = [
+  "holder_unknown",
+  "forwarding_disabled",
+  "forwarded_but_not_writer",
+  "body_unreadable",
+  "forward_failed"
+];
+var REPLAYABLE_LEASE_REASONS = [
+  "holder_unknown",
+  "forwarding_disabled",
+  "forwarded_but_not_writer",
+  "body_unreadable"
+];
+var AMBIGUOUS_LEASE_REASONS = ["forward_failed"];
+var MAX_RETRY_AFTER_SECONDS = 15;
+var DEFAULT_RETRY_AFTER_SECONDS = 5;
+var DEFAULT_FACILITATOR_RETRIES = 2;
+function isReplayableLeaseReason(reason) {
+  return REPLAYABLE_LEASE_REASONS.includes(reason);
+}
+function isAmbiguousLeaseReason(reason) {
+  return AMBIGUOUS_LEASE_REASONS.includes(reason);
+}
+function parseRetryAfterSeconds(response) {
+  let raw;
+  try {
+    raw = response?.headers?.get?.("retry-after");
+  } catch {
+    return void 0;
+  }
+  if (raw === null || raw === void 0 || raw === "") return void 0;
+  const seconds = Number(raw);
+  if (!Number.isFinite(seconds) || seconds < 0) return void 0;
+  return Math.min(seconds, MAX_RETRY_AFTER_SECONDS);
+}
+function reasonFrom(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed && typeof parsed === "object" && typeof parsed.reason === "string") {
+      return parsed.reason;
+    }
+  } catch {
+  }
+  return void 0;
+}
+async function readFacilitatorError(response) {
+  let body = "";
+  try {
+    body = await response.text();
+  } catch {
+    body = "";
+  }
+  const status = response.status;
+  const reason = reasonFrom(body);
+  const retryable = status === 429 || status === 502 || status === 503 || status === 504;
+  const retryAfterSeconds = retryable ? parseRetryAfterSeconds(response) ?? DEFAULT_RETRY_AFTER_SECONDS : void 0;
+  const safeToReplay = status === 429 || status === 503 && isReplayableLeaseReason(reason);
+  return {
+    error: `Facilitator error: ${status} - ${body}`,
+    status,
+    reason,
+    retryAfterSeconds,
+    retryable,
+    safeToReplay,
+    body
+  };
+}
+function failureFields(info) {
+  return {
+    status: info.status,
+    retryable: info.retryable,
+    safeToReplay: info.safeToReplay,
+    ...info.reason !== void 0 ? { reason: info.reason } : {},
+    ...info.retryAfterSeconds !== void 0 ? { retryAfterSeconds: info.retryAfterSeconds } : {}
+  };
+}
+function carryFailureFields(source) {
+  return {
+    ...source.status !== void 0 ? { status: source.status } : {},
+    ...source.reason !== void 0 ? { reason: source.reason } : {},
+    ...source.retryable !== void 0 ? { retryable: source.retryable } : {},
+    ...source.retryAfterSeconds !== void 0 ? { retryAfterSeconds: source.retryAfterSeconds } : {},
+    ...source.safeToReplay !== void 0 ? { safeToReplay: source.safeToReplay } : {}
+  };
+}
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function facilitatorFetch(url, init, options) {
+  const retries = options.retries ?? DEFAULT_FACILITATOR_RETRIES;
+  const canReplay = options.canReplay ?? ((info) => info.safeToReplay);
+  const doFetch = options.fetchImpl ?? fetch;
+  const sleep = options.sleepImpl ?? defaultSleep;
+  let attempt = 0;
+  for (; ; ) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), options.timeoutMs);
+    let response;
+    try {
+      response = await doFetch(url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    if (response.ok) return { response };
+    const error = await readFacilitatorError(response);
+    if (attempt >= retries || !error.retryable || !canReplay(error)) {
+      return { response, error };
+    }
+    attempt += 1;
+    await sleep((error.retryAfterSeconds ?? DEFAULT_RETRY_AFTER_SECONDS) * 1e3);
+  }
+}
+
 // src/backend/index.ts
 function parsePaymentHeader(headerValue) {
   if (!headerValue) {
@@ -3829,10 +3961,12 @@ var FacilitatorClient = class {
   baseUrl;
   timeout;
   explicitTimeout;
+  retries;
   constructor(options = {}) {
     this.baseUrl = options.baseUrl || "https://facilitator.ultravioletadao.xyz";
     this.explicitTimeout = options.timeout !== void 0;
     this.timeout = options.timeout || 3e4;
+    this.retries = options.retries;
   }
   /**
    * Get timeout for a specific network, using per-chain defaults when no explicit timeout was set.
@@ -3859,29 +3993,31 @@ var FacilitatorClient = class {
    */
   async verify(paymentHeader, requirements) {
     const body = buildVerifyRequest(paymentHeader, requirements);
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(`${this.baseUrl}/verify`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(body),
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorText = await response.text();
+      const { response, error } = await facilitatorFetch(
+        `${this.baseUrl}/verify`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(body)
+        },
+        { timeoutMs: this.timeout, retries: this.retries }
+      );
+      if (error) {
         return {
           isValid: false,
-          invalidReason: `Facilitator error: ${response.status} - ${errorText}`
+          invalidReason: error.error,
+          ...failureFields(error)
         };
       }
       return await response.json();
     } catch (error) {
-      clearTimeout(timeoutId);
       return {
         isValid: false,
-        invalidReason: error instanceof Error ? error.message : "Unknown error"
+        invalidReason: error instanceof Error ? error.message : "Unknown error",
+        retryable: true,
+        safeToReplay: false,
+        retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS
       };
     }
   }
@@ -3897,21 +4033,21 @@ var FacilitatorClient = class {
   async settle(paymentHeader, requirements) {
     const body = buildSettleRequest(paymentHeader, requirements);
     const settleTimeout = this.getTimeout(requirements.network);
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), settleTimeout);
     try {
-      const response = await fetch(`${this.baseUrl}/settle`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(body),
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorText = await response.text();
+      const { response, error } = await facilitatorFetch(
+        `${this.baseUrl}/settle`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(body)
+        },
+        { timeoutMs: settleTimeout, retries: this.retries }
+      );
+      if (error) {
         return {
           success: false,
-          error: `Facilitator error: ${response.status} - ${errorText}`
+          error: error.error,
+          ...failureFields(error)
         };
       }
       const result = await response.json();
@@ -3952,10 +4088,12 @@ var FacilitatorClient = class {
         payer: result.payer
       };
     } catch (error) {
-      clearTimeout(timeoutId);
       return {
         success: false,
-        error: error instanceof Error ? error.message : "Unknown error"
+        error: error instanceof Error ? error.message : "Unknown error",
+        retryable: true,
+        safeToReplay: false,
+        retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS
       };
     }
   }
@@ -3975,7 +4113,8 @@ var FacilitatorClient = class {
       return {
         verified: false,
         settled: false,
-        error: verifyResult.invalidReason
+        error: verifyResult.invalidReason,
+        ...carryFailureFields(verifyResult)
       };
     }
     const settleResult = await this.settle(paymentHeader, requirements);
@@ -3983,7 +4122,8 @@ var FacilitatorClient = class {
       verified: true,
       settled: settleResult.success,
       transactionHash: settleResult.transactionHash,
-      error: settleResult.error
+      error: settleResult.error,
+      ...carryFailureFields(settleResult)
     };
   }
   /**
@@ -4385,10 +4525,29 @@ function createVerifiedPaymentState(client, payment, requirements, verifyResult)
     }
   };
 }
+function respondUnavailable(res, message, failure) {
+  const seconds = Math.max(1, Math.ceil(failure.retryAfterSeconds ?? DEFAULT_RETRY_AFTER_SECONDS));
+  const body = {
+    error: message,
+    reason: failure.reason ?? failure.invalidReason ?? failure.error,
+    retryable: true,
+    retryAfterSeconds: seconds,
+    // False for `forward_failed` and for a bare timeout: the write may already
+    // have landed, so the caller must reconcile before resending.
+    safeToReplay: failure.safeToReplay === true
+  };
+  const staged = res.status(503);
+  if (typeof staged.set === "function") {
+    staged.set({ "Retry-After": String(seconds) }).json(body);
+    return;
+  }
+  staged.json(body);
+}
 function createPaymentMiddleware(getRequirements, options = {}) {
   const client = new FacilitatorClient({
     baseUrl: options.facilitatorUrl || options.baseUrl,
-    timeout: options.timeout
+    timeout: options.timeout,
+    retries: options.retries
   });
   const settlementStrategy = options.settlementStrategy || "before-handler";
   return async (req, res, next) => {
@@ -4403,6 +4562,10 @@ function createPaymentMiddleware(getRequirements, options = {}) {
     const requirements = buildPaymentRequirements(reqOptions);
     const verifyResult = await client.verify(payment, requirements);
     if (!verifyResult.isValid) {
+      if (verifyResult.retryable) {
+        respondUnavailable(res, "Payment verification unavailable", verifyResult);
+        return;
+      }
       res.status(402).json({
         error: "Payment verification failed",
         reason: verifyResult.invalidReason
@@ -4413,6 +4576,10 @@ function createPaymentMiddleware(getRequirements, options = {}) {
     if (settlementStrategy === "before-handler") {
       const settleResult = await req.x402.settle();
       if (!settleResult.success) {
+        if (settleResult.retryable) {
+          respondUnavailable(res, "Payment settlement unavailable", settleResult);
+          return;
+        }
         res.status(500).json({
           error: "Payment settlement failed",
           reason: settleResult.error || "Unknown settlement error"
@@ -4423,10 +4590,25 @@ function createPaymentMiddleware(getRequirements, options = {}) {
     next();
   };
 }
+function honoUnavailable(c, message, failure) {
+  const seconds = Math.max(1, Math.ceil(failure.retryAfterSeconds ?? DEFAULT_RETRY_AFTER_SECONDS));
+  c.header?.("Retry-After", String(seconds));
+  return c.json(
+    {
+      error: message,
+      reason: failure.reason ?? failure.invalidReason ?? failure.error,
+      retryable: true,
+      retryAfterSeconds: seconds,
+      safeToReplay: failure.safeToReplay === true
+    },
+    503
+  );
+}
 function createHonoMiddleware(options) {
   const client = new FacilitatorClient({
     baseUrl: options.facilitatorUrl || options.baseUrl,
-    timeout: options.timeout
+    timeout: options.timeout,
+    retries: options.retries
   });
   const settlementStrategy = options.settlementStrategy || "before-handler";
   if (!options.accepts[0]) {
@@ -4466,6 +4648,9 @@ function createHonoMiddleware(options) {
     }
     const verifyResult = await client.verify(parsed, requirement);
     if (!verifyResult.isValid) {
+      if (verifyResult.retryable) {
+        return honoUnavailable(c, "Payment verification unavailable", verifyResult);
+      }
       return c.json({
         error: "Payment verification failed",
         reason: verifyResult.invalidReason
@@ -4476,6 +4661,9 @@ function createHonoMiddleware(options) {
     if (settlementStrategy === "before-handler") {
       const settleResult = await verifiedPayment.settle();
       if (!settleResult.success) {
+        if (settleResult.retryable) {
+          return honoUnavailable(c, "Payment settlement unavailable", settleResult);
+        }
         return c.json({
           error: "Payment settlement failed",
           reason: settleResult.error || "Unknown error"
@@ -4508,14 +4696,17 @@ var ESCROW_TIMEOUT_MS = {
   // Monad: 90s
 };
 
+exports.AMBIGUOUS_LEASE_REASONS = AMBIGUOUS_LEASE_REASONS;
 exports.ANCHOR_MAX_REQUEST_BYTES = ANCHOR_MAX_REQUEST_BYTES;
 exports.CAIP2_IDENTIFIERS = CAIP2_IDENTIFIERS;
 exports.CAIP2_TO_CHAIN = CAIP2_TO_CHAIN;
 exports.ContentHashMismatch = ContentHashMismatch;
 exports.DEFAULT_CHAIN = DEFAULT_CHAIN;
 exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
+exports.DEFAULT_FACILITATOR_RETRIES = DEFAULT_FACILITATOR_RETRIES;
 exports.DEFAULT_FACILITATOR_URL = DEFAULT_FACILITATOR_URL;
 exports.DEFAULT_PAYMENT_HEADER = DEFAULT_PAYMENT_HEADER;
+exports.DEFAULT_RETRY_AFTER_SECONDS = DEFAULT_RETRY_AFTER_SECONDS;
 exports.DELEGATE_PREFIX = DELEGATE_PREFIX;
 exports.DX402Error = DX402Error;
 exports.ESCROW_DEPOSIT_LIMIT_USD = ESCROW_DEPOSIT_LIMIT_USD;
@@ -4527,13 +4718,16 @@ exports.EvidenceSkipped = EvidenceSkipped;
 exports.FACILITATOR_ADDRESSES = FACILITATOR_ADDRESSES;
 exports.FacilitatorClient = FacilitatorClient;
 exports.KEEPALIVE_INTERVAL_MS = KEEPALIVE_INTERVAL_MS;
+exports.MAX_RETRY_AFTER_SECONDS = MAX_RETRY_AFTER_SECONDS;
 exports.OPERATOR_FEE_BPS = OPERATOR_FEE_BPS;
 exports.OWSWalletAdapter = OWSWalletAdapter;
 exports.PAYMENT_HEADER_NAMES = PAYMENT_HEADER_NAMES;
+exports.REPLAYABLE_LEASE_REASONS = REPLAYABLE_LEASE_REASONS;
 exports.SMA_WRAP_TARGETS = SMA_WRAP_TARGETS;
 exports.SSEParser = SSEParser;
 exports.SUPPORTED_CHAINS = SUPPORTED_CHAINS;
 exports.TrafficStreamError = TrafficStreamError;
+exports.WRITER_LEASE_REASONS = WRITER_LEASE_REASONS;
 exports.X402Client = X402Client;
 exports.X402Error = X402Error;
 exports.X402_CORS_HEADERS = X402_CORS_HEADERS;
@@ -4577,6 +4771,7 @@ exports.encodeX402Header = encodeX402Header;
 exports.evidenceFromHeaders = evidenceFromHeaders;
 exports.evidenceHeader = evidenceHeader;
 exports.extractPaymentFromHeaders = extractPaymentFromHeaders;
+exports.facilitatorFetch = facilitatorFetch;
 exports.fetchNonce = fetchNonce;
 exports.generatePaymentOptions = generatePaymentOptions;
 exports.getAlgorandChains = getAlgorandChains;
@@ -4599,10 +4794,12 @@ exports.getTokenByAddress = getTokenByAddress;
 exports.getTokenConfig = getTokenConfig;
 exports.getXRPLChains = getXRPLChains;
 exports.isAlgorandChain = isAlgorandChain;
+exports.isAmbiguousLeaseReason = isAmbiguousLeaseReason;
 exports.isCAIP2Format = isCAIP2Format;
 exports.isChainSupported = isChainSupported;
 exports.isDelegated = isDelegated;
 exports.isEndToEnd = isEndToEnd;
+exports.isReplayableLeaseReason = isReplayableLeaseReason;
 exports.isSVMChain = isSVMChain;
 exports.isSuiChain = isSuiChain;
 exports.isTokenSupported = isTokenSupported;
@@ -4611,11 +4808,13 @@ exports.matchesFilters = matchesFilters;
 exports.needsAccountWrap = needsAccountWrap;
 exports.parseEvidenceHeader = parseEvidenceHeader;
 exports.parseNetworkIdentifier = parseNetworkIdentifier;
+exports.parseRetryAfterSeconds = parseRetryAfterSeconds;
 exports.parseSealed = parseSealed;
 exports.parseTrafficEvent = parseTrafficEvent;
 exports.payerKeyFromEvmSignature = payerKeyFromEvmSignature;
 exports.payerKeyFromSolanaAddress = payerKeyFromSolanaAddress;
 exports.paymentChallengeFrom = paymentChallengeFrom;
+exports.readFacilitatorError = readFacilitatorError;
 exports.recoverEvidence = recoverEvidence;
 exports.replaySafeTypedData = replaySafeTypedData;
 exports.resolveDelegation = resolveDelegation;