@routedock/routedock 0.2.0 → 0.3.0

package/dist/client.cjs

@@ -165,10 +165,35 @@ function wrapFetchError(err, context) {
   if (err instanceof RouteDockError) return err;
   return new RouteDockNetworkError(`${context}: ${String(err)}`, { cause: err });
 }
+function wrapMppError(err, context) {
+  if (err instanceof RouteDockError) return err;
+  if (err instanceof TypeError || err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError")) {
+    return new RouteDockNetworkError(`${context}: ${String(err)}`, { cause: err });
+  }
+  return new RouteDockSignatureError(`${context}: ${String(err)}`, { cause: err });
+}
 
 // src/types.ts
 var DEFAULT_MAX_SESSION_DURATION_MS = 36e5;
 
+// src/internal/logger.ts
+function createConsoleLogger() {
+  return (level, message, fields) => {
+    const values = fields ? Object.values(fields) : [];
+    if (values.length > 0) {
+      console[level](message, ...values);
+    } else {
+      console[level](message);
+    }
+  };
+}
+var consoleLogger = createConsoleLogger();
+var noopLogger = () => {
+};
+function resolveLogger(logger, fallback = consoleLogger) {
+  return logger ?? fallback;
+}
+
 // src/internal/retry.ts
 var DEFAULT_RETRY_POLICY = {
   maxAttempts: 4,
@@ -183,10 +208,11 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 async function withRetry(fn, policy = {}) {
-  const { maxAttempts, baseDelayMs, maxDelayMs, onRetry } = {
+  const { maxAttempts, baseDelayMs, maxDelayMs, onRetry, logger } = {
     ...DEFAULT_RETRY_POLICY,
     ...policy
   };
+  const log = resolveLogger(logger);
   let lastError;
   for (let attempt = 0; attempt < maxAttempts; attempt++) {
     try {
@@ -204,7 +230,7 @@ async function withRetry(fn, policy = {}) {
         try {
           await onRetry(attempt, err, delay);
         } catch (cbErr) {
-          console.error("[withRetry] onRetry callback threw:", cbErr);
+          log("error", "[withRetry] onRetry callback threw:", { error: cbErr });
         }
       }
       await sleep(delay);
@@ -218,6 +244,84 @@ var USDC_ISSUERS = {
 };
 var usdcToUnits = nulthSdk.usdcToStroops;
 
+// src/internal/assetUtils.ts
+function normalizeManifestAssets(manifest) {
+  if (manifest.assets && manifest.assets.length > 0) {
+    return manifest.assets;
+  }
+  if (manifest.asset && manifest.asset_contract) {
+    return [
+      {
+        asset: manifest.asset,
+        asset_contract: manifest.asset_contract
+      }
+    ];
+  }
+  throw new RouteDockManifestError(
+    "Manifest must define either assets[] or root asset/asset_contract fields"
+  );
+}
+function getEligibleAssets(manifest, mode, endpoint) {
+  const assets = normalizeManifestAssets(manifest);
+  return assets.filter((asset) => {
+    if (asset.modes && !asset.modes.includes(mode)) {
+      return false;
+    }
+    if (endpoint && asset.endpoints && asset.endpoints.length > 0) {
+      const trimmedEndpoint = endpoint.replace(/^\//, "");
+      if (asset.endpoints.includes(endpoint) || asset.endpoints.includes(trimmedEndpoint)) {
+        return true;
+      }
+      if (manifest.endpoints) {
+        let pathname = endpoint;
+        if (endpoint.startsWith("http://") || endpoint.startsWith("https://")) {
+          try {
+            pathname = new URL(endpoint).pathname;
+          } catch {
+          }
+        }
+        const trimmedPathname = pathname.replace(/^\//, "");
+        const matchesEndpoint = Object.entries(manifest.endpoints).some(([key, desc]) => {
+          const pathMatches = desc.path === pathname || desc.path === endpoint || desc.path.replace(/\/+$/, "") === pathname.replace(/\/+$/, "") || desc.path.replace(/^\//, "") === trimmedPathname;
+          const keyMatches = key === endpoint || key === trimmedEndpoint;
+          if (pathMatches || keyMatches) {
+            return asset.endpoints.includes(key) || asset.endpoints.includes(desc.path) || asset.endpoints.includes(desc.path.replace(/^\//, ""));
+          }
+          return false;
+        });
+        if (!matchesEndpoint) {
+          return false;
+        }
+      } else {
+        return false;
+      }
+    }
+    return true;
+  });
+}
+function resolveAssetContract(manifest, mode, endpoint, explicitContract) {
+  if (manifest.assets && manifest.assets.length > 0) {
+    return selectAsset(manifest, mode, endpoint).asset_contract;
+  }
+  return explicitContract ?? selectAsset(manifest, mode, endpoint).asset_contract;
+}
+function selectAsset(manifest, mode, endpoint) {
+  const eligible = getEligibleAssets(manifest, mode, endpoint);
+  if (eligible.length === 0) {
+    const endpointMsg = endpoint ? ` for endpoint '${endpoint}'` : "";
+    throw new RouteDockManifestError(
+      `No eligible assets found for mode '${mode}'${endpointMsg}`
+    );
+  }
+  return eligible[0];
+}
+function isAssetEligible(manifest, assetIdentifier, mode, endpoint) {
+  const eligible = getEligibleAssets(manifest, mode, endpoint);
+  return eligible.some(
+    (asset) => asset.asset === assetIdentifier || asset.asset_contract === assetIdentifier
+  );
+}
+
 // src/schemas/routedock.schema.json
 var routedock_schema_default = {
   $schema: "http://json-schema.org/draft-07/schema#",
@@ -297,6 +401,14 @@ var routedock_schema_default = {
       type: "string",
       description: "Stellar Asset Contract (SAC) address for the payment asset"
     },
+    assets: {
+      type: "array",
+      minItems: 1,
+      items: {
+        $ref: "#/definitions/AssetConfig"
+      },
+      description: "Payment assets accepted by this provider. Each asset can be scoped to specific modes and endpoints. When present, assets[0] must match the root-level asset and asset_contract."
+    },
     payee: {
       type: "string",
       description: "Stellar address (G...) that receives payments"
@@ -429,6 +541,38 @@ var routedock_schema_default = {
       enum: ["x402", "mpp-charge", "mpp-session", "mpp-session-ws"],
       description: "A supported RouteDock payment mode"
     },
+    AssetConfig: {
+      type: "object",
+      description: "Payment asset configuration with optional mode and endpoint scoping",
+      required: ["asset", "asset_contract"],
+      additionalProperties: false,
+      properties: {
+        asset: {
+          type: "string",
+          description: "Asset ticker symbol (e.g. 'USDC' or 'XLM')"
+        },
+        asset_contract: {
+          type: "string",
+          description: "Stellar Asset Contract (SAC) address for the payment asset"
+        },
+        modes: {
+          type: "array",
+          items: {
+            $ref: "#/definitions/PaymentMode"
+          },
+          uniqueItems: true,
+          description: "Optional: restrict this asset to specific payment modes. If omitted, available for all modes."
+        },
+        endpoints: {
+          type: "array",
+          items: {
+            type: "string"
+          },
+          uniqueItems: true,
+          description: "Optional: restrict this asset to specific endpoints (by name). If omitted, available for all endpoints."
+        }
+      }
+    },
     PricingConfig: {
       type: "object",
       description: "Per-request pricing for x402 or mpp-charge modes",
@@ -574,7 +718,7 @@ var routedock_schema_default = {
 
 // package.json
 var package_default = {
-  version: "0.2.0"};
+  version: "0.3.0"};
 var MANIFEST_SIGNATURE_VERSION = "2";
 function canonicalize(value) {
   if (Array.isArray(value)) {
@@ -688,6 +832,7 @@ function assertEndpointActive(manifest, url, logger) {
     const [key, descriptor] = deprecated;
     const sunsetSuffix = descriptor.sunset_at ? `; sunset_at ${descriptor.sunset_at}` : "";
     logger(
+      "warn",
       `[RouteDock] WARNING: ${manifest.name} \u2192 ${pathname}; endpoint '${key}' is deprecated${sunsetSuffix}`
     );
   }
@@ -709,6 +854,27 @@ function assertManifestValid(manifest, baseUrl) {
       }
     }
   }
+  if (manifest.assets !== void 0) {
+    if (!Array.isArray(manifest.assets) || manifest.assets.length === 0) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: assets must be a non-empty array when defined`
+      );
+    }
+    for (let i = 0; i < manifest.assets.length; i++) {
+      const a = manifest.assets[i];
+      if (!a || typeof a.asset !== "string" || typeof a.asset_contract !== "string") {
+        throw new RouteDockManifestError(
+          `Invalid manifest${context}: assets[${i}] must define asset and asset_contract strings`
+        );
+      }
+    }
+    const first = manifest.assets[0];
+    if (first.asset !== manifest.asset || first.asset_contract !== manifest.asset_contract) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: assets[0] (${first.asset}:${first.asset_contract}) must match root asset fields (${manifest.asset}:${manifest.asset_contract})`
+      );
+    }
+  }
 }
 var CACHE_TTL_MS = 6e4;
 var DEFAULT_MANIFEST_CACHE_MAX_SIZE = 512;
@@ -888,16 +1054,16 @@ function logSelection(manifest, selection, log, deprecated) {
   const reason = selection.reason ? ` (${selection.reason})` : "";
   if (deprecated) {
     log(
+      "warn",
       `[RouteDock] WARNING: ${manifest.name} \u2192 ${selection.mode}${reason}; selected deprecated mode because no active supported mode is available`
     );
     return;
   }
-  log(`[RouteDock] ${manifest.name} \u2192 ${selection.mode}${reason}`);
+  log("info", `[RouteDock] ${manifest.name} \u2192 ${selection.mode}${reason}`);
 }
 function selectMode(manifest, options = {}) {
   const modes = manifest.modes;
-  const log = options.logger ?? (() => {
-  });
+  const log = options.logger ?? noopLogger;
   const deprecatedSet = new Set(manifest.deprecated_modes ?? []);
   if (options.forceMode) {
     if (!modes.includes(options.forceMode)) {
@@ -907,10 +1073,11 @@ function selectMode(manifest, options = {}) {
     }
     if (deprecatedSet.has(options.forceMode)) {
       log(
+        "warn",
         `[RouteDock] WARNING: ${manifest.name} \u2192 ${options.forceMode} (forced); selected mode is deprecated`
       );
     } else {
-      log(`[RouteDock] ${manifest.name} \u2192 ${options.forceMode} (forced)`);
+      log("info", `[RouteDock] ${manifest.name} \u2192 ${options.forceMode} (forced)`);
     }
     return options.forceMode;
   }
@@ -946,6 +1113,69 @@ function rankProvidersByLatency(manifests, targetRegion) {
     return 0;
   });
 }
+
+// src/internal/payee.ts
+function resolvePayee(manifest, mode) {
+  const override = manifest.pricing[mode]?.payee;
+  return override ?? manifest.payee;
+}
+
+// src/client/challenge.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isPositiveIntegerString(value) {
+  return typeof value === "string" && /^[1-9]\d*$/.test(value);
+}
+function checkAmount(amount, maxAmount) {
+  if (!isPositiveIntegerString(amount)) {
+    return new RouteDockPolicyRejectError("challenge_amount_invalid");
+  }
+  let max;
+  try {
+    max = nulthSdk.usdcToStroops(maxAmount);
+  } catch {
+    return new RouteDockPolicyRejectError("challenge_amount_invalid");
+  }
+  if (BigInt(amount) > max) {
+    return new RouteDockPolicyRejectError("challenge_amount_exceeds_manifest");
+  }
+  return null;
+}
+function checkX402Accept(accept, manifest, network, maxAmount) {
+  if (accept.network !== network) {
+    return new RouteDockPolicyRejectError("challenge_network_mismatch");
+  }
+  if (accept.payTo !== resolvePayee(manifest, "x402")) {
+    return new RouteDockPolicyRejectError("challenge_payee_mismatch");
+  }
+  if (accept.asset !== manifest.asset_contract) {
+    return new RouteDockPolicyRejectError("challenge_asset_mismatch");
+  }
+  return checkAmount(accept.amount, maxAmount);
+}
+function filterX402Accepts(accepts, manifest, network, maxAmount) {
+  return accepts.filter((accept) => checkX402Accept(accept, manifest, network, maxAmount) === null);
+}
+function checkChargeChallenge(request, manifest, network, maxAmount) {
+  const methodDetails = request["methodDetails"];
+  const rawNetwork = isRecord(methodDetails) ? methodDetails["network"] : void 0;
+  const challengeNetwork = rawNetwork === void 0 ? "stellar:testnet" : rawNetwork;
+  if (challengeNetwork !== network) {
+    return new RouteDockPolicyRejectError("challenge_network_mismatch");
+  }
+  const recipient = request["recipient"];
+  if (typeof recipient !== "string" || recipient !== resolvePayee(manifest, "mpp-charge")) {
+    return new RouteDockPolicyRejectError("challenge_payee_mismatch");
+  }
+  const currency = request["currency"];
+  if (typeof currency !== "string" || currency !== manifest.asset_contract) {
+    return new RouteDockPolicyRejectError("challenge_asset_mismatch");
+  }
+  return checkAmount(request["amount"], maxAmount);
+}
+
+// src/client/x402Client.ts
 var CAIP2 = {
   testnet: "stellar:testnet",
   mainnet: "stellar:pubnet"
@@ -977,83 +1207,106 @@ var X402Client = class _X402Client {
     if (!pricing.facilitator) {
       throw new RouteDockManifestError("manifest.pricing.x402.facilitator missing");
     }
-    return withRetry(async () => {
-      let init;
+    const caip2 = CAIP2[this.network];
+    const probe = await withRetry(async () => {
+      let init2;
       try {
-        init = await fetch(url, { headers: { "X-Preferred-Mode": "x402" } });
+        init2 = await fetch(url, { headers: { "X-Preferred-Mode": "x402" } });
       } catch (err) {
         throw wrapFetchError(err, "x402 initial request");
       }
-      if (init.status !== 402) {
-        if (!init.ok) {
+      if (init2.status !== 402) {
+        if (!init2.ok) {
           throw httpStatusToError(
-            `x402 initial request failed: HTTP ${init.status}`,
-            init.status,
-            init
+            `x402 initial request failed: HTTP ${init2.status}`,
+            init2.status,
+            init2
           );
         }
         let data2;
         try {
-          data2 = await init.json();
+          data2 = await init2.json();
         } catch {
-          throw new RouteDockManifestError(`Failed to parse JSON from non-402 response (HTTP ${init.status})`);
+          throw new RouteDockManifestError(
+            `Failed to parse JSON from non-402 response (HTTP ${init2.status})`
+          );
         }
-        return { data: data2, txHash: null, mode: "x402", amount: "0", timestamp: Date.now() };
-      }
-      const reqHeader = init.headers.get("X-Payment-Requirements");
-      if (!reqHeader) {
-        throw new RouteDockManifestError("402 response missing X-Payment-Requirements header");
-      }
-      let paymentRequired;
-      try {
-        paymentRequired = http.decodePaymentRequiredHeader(reqHeader);
-      } catch (err) {
-        throw new RouteDockManifestError("402 X-Payment-Requirements header is malformed", {
-          cause: err
-        });
+        return { kind: "free", data: data2 };
       }
-      let paymentPayload;
-      try {
-        paymentPayload = await this.httpClient.createPaymentPayload(paymentRequired);
-      } catch (err) {
-        throw new RouteDockSignatureError(`x402 payment signing failed: ${String(err)}`, {
-          cause: err
-        });
-      }
-      const paymentHeaders = this.httpClient.encodePaymentSignatureHeader(paymentPayload);
-      let settled;
+      return { kind: "payment-required", init: init2 };
+    }, this.retryPolicy);
+    if (probe.kind === "free") {
+      return { data: probe.data, txHash: null, mode: "x402", amount: "0", timestamp: Date.now() };
+    }
+    const init = probe.init;
+    const reqHeader = init.headers.get("X-Payment-Requirements");
+    if (!reqHeader) {
+      throw new RouteDockManifestError("402 response missing X-Payment-Requirements header");
+    }
+    let paymentRequired;
+    try {
+      paymentRequired = http.decodePaymentRequiredHeader(reqHeader);
+    } catch (err) {
+      throw new RouteDockManifestError("402 X-Payment-Requirements header is malformed", {
+        cause: err
+      });
+    }
+    const firstAccept = paymentRequired.accepts[0];
+    if (!firstAccept) {
+      throw new RouteDockManifestError("402 response carries no payment accepts");
+    }
+    const allowed = filterX402Accepts(paymentRequired.accepts, manifest, caip2, pricing.amount);
+    if (allowed.length === 0) {
+      throw checkX402Accept(firstAccept, manifest, caip2, pricing.amount);
+    }
+    let paymentPayload;
+    try {
+      paymentPayload = await this.httpClient.createPaymentPayload({
+        ...paymentRequired,
+        accepts: allowed
+      });
+    } catch (err) {
+      throw new RouteDockSignatureError(`x402 payment signing failed: ${String(err)}`, {
+        cause: err
+      });
+    }
+    const paymentHeaders = this.httpClient.encodePaymentSignatureHeader(paymentPayload);
+    const signedAmount = nulthSdk.stroopsToUsdc(BigInt(paymentPayload.accepted.amount));
+    const settled = await withRetry(async () => {
+      let response;
       try {
-        settled = await fetch(url, { headers: paymentHeaders });
+        response = await fetch(url, { headers: paymentHeaders });
       } catch (err) {
         throw wrapFetchError(err, "x402 settlement request");
       }
-      if (!settled.ok) {
-        if (settled.status >= 500 || settled.status === 429 || settled.status === 503) {
+      if (!response.ok) {
+        if (response.status >= 500 || response.status === 429 || response.status === 503) {
           throw httpStatusToError(
-            `x402 payment failed: HTTP ${settled.status}`,
-            settled.status,
-            settled
+            `x402 payment failed: HTTP ${response.status}`,
+            response.status,
+            response
           );
         }
-        throw new RouteDockManifestError(`x402 payment failed: HTTP ${settled.status}`);
-      }
-      let txHash = null;
-      const responseHeader = settled.headers.get("X-Payment-Response");
-      if (responseHeader) {
-        try {
-          const settleResponse = http.decodePaymentResponseHeader(responseHeader);
-          txHash = settleResponse.transaction ?? null;
-        } catch {
-        }
+        throw new RouteDockManifestError(`x402 payment failed: HTTP ${response.status}`);
       }
-      let data;
+      return response;
+    }, this.retryPolicy);
+    let txHash = null;
+    const responseHeader = settled.headers.get("X-Payment-Response");
+    if (responseHeader) {
       try {
-        data = await settled.json();
+        const settleResponse = http.decodePaymentResponseHeader(responseHeader);
+        txHash = settleResponse.transaction ?? null;
       } catch {
-        throw new RouteDockManifestError("Failed to parse JSON from settled response");
       }
-      return { data, txHash, mode: "x402", amount: pricing.amount, timestamp: Date.now() };
-    }, this.retryPolicy);
+    }
+    let data;
+    try {
+      data = await settled.json();
+    } catch {
+      throw new RouteDockManifestError("Failed to parse JSON from settled response");
+    }
+    return { data, txHash, mode: "x402", amount: signedAmount, timestamp: Date.now() };
   }
 };
 var MppChargeClient = class {
@@ -1070,27 +1323,42 @@ var MppChargeClient = class {
     if (!pricing) {
       throw new RouteDockManifestError("manifest.pricing.mpp-charge missing");
     }
-    return withRetry(async () => {
-      let txHash = null;
-      const mppx = client$2.Mppx.create({
-        polyfill: false,
-        methods: [
-          client$3.stellar.charge({
-            keypair: this.keypair,
-            mode: "pull",
-            onProgress(event) {
-              if (event.type === "paid") {
-                txHash = event.hash;
-              }
+    const caip2 = this.network === "mainnet" ? "stellar:pubnet" : "stellar:testnet";
+    let txHash = null;
+    let signedAmount;
+    let credential;
+    const mppx = client$2.Mppx.create({
+      polyfill: false,
+      methods: [
+        client$3.stellar.charge({
+          keypair: this.keypair,
+          mode: "pull",
+          onProgress(event) {
+            if (event.type === "paid") {
+              txHash = event.hash;
             }
-          })
-        ]
-      });
+          }
+        })
+      ],
+      onChallenge: async (challenge, { createCredential }) => {
+        const request = challenge.request;
+        const rejection = checkChargeChallenge(request, manifest, caip2, pricing.amount);
+        if (rejection) throw rejection;
+        const amount = request["amount"];
+        if (typeof amount !== "string") {
+          throw new RouteDockPolicyRejectError("challenge_amount_invalid");
+        }
+        signedAmount = nulthSdk.stroopsToUsdc(BigInt(amount));
+        credential ??= await createCredential();
+        return credential;
+      }
+    });
+    return withRetry(async () => {
       let response;
       try {
-        response = await mppx.fetch(url);
+        response = credential ? await mppx.rawFetch(url, { headers: { Authorization: credential } }) : await mppx.fetch(url);
       } catch (err) {
-        throw wrapFetchError(err, "MPP charge request");
+        throw wrapMppError(err, "MPP charge request");
       }
       if (!response.ok) {
         if (response.status >= 500 || response.status === 429 || response.status === 503) {
@@ -1111,7 +1379,13 @@ var MppChargeClient = class {
           { cause }
         );
       }
-      return { data, txHash, mode: "mpp-charge", amount: pricing.amount, timestamp: Date.now() };
+      return {
+        data,
+        txHash,
+        mode: "mpp-charge",
+        amount: signedAmount ?? pricing.amount,
+        timestamp: Date.now()
+      };
     }, this.retryPolicy);
   }
 };
@@ -1150,16 +1424,18 @@ function resolveStoreNetworkId(network) {
   return network === mpp.STELLAR_PUBNET ? mpp.STELLAR_PUBNET : mpp.STELLAR_TESTNET;
 }
 var MppSessionClient = class {
-  constructor(keypair, network, retryPolicy, webSocketFactory = defaultWebSocketFactory) {
+  constructor(keypair, network, retryPolicy, webSocketFactory = defaultWebSocketFactory, logger = consoleLogger) {
     this.keypair = keypair;
     this.network = network;
     this.retryPolicy = retryPolicy;
     this.webSocketFactory = webSocketFactory;
+    this.logger = logger;
   }
   keypair;
   network;
   retryPolicy;
   webSocketFactory;
+  logger;
   async openSession(url, manifest, commitmentSecret, options, onSpend) {
     const mode = options?.mode ?? "mpp-session";
     const pricing = manifest.pricing[mode];
@@ -1384,7 +1660,7 @@ var MppSessionClient = class {
             if (abortController.signal.aborted) {
               throw err;
             }
-            throw wrapFetchError(err, "Voucher request");
+            throw wrapMppError(err, "Voucher request");
           }
           if (!resp.ok) {
             if (resp.status >= 500 || resp.status === 429 || resp.status === 503) {
@@ -1677,9 +1953,10 @@ var MppSessionClient = class {
         emit("session:timeout", { maxDurationMs });
         void handle.close().catch((error) => {
           emit("session:close-failed", { maxDurationMs, error });
-          console.warn(
+          this.logger(
+            "warn",
             `RouteDock: maxDuration auto-close failed after ${maxDurationMs}ms \u2014 the channel may still hold collateral; retry close() or call requestRefund().`,
-            error
+            { error }
           );
         });
       }, maxDurationMs);
@@ -1729,7 +2006,7 @@ var MppSessionClient = class {
       );
       onSigned?.();
     } catch (err) {
-      throw wrapFetchError(err, "Voucher credential");
+      throw wrapMppError(err, "Voucher credential");
     }
     const wsUrl = url.replace(/^http/, "ws");
     const queue = [];
@@ -1926,7 +2203,10 @@ var NulthClient = class {
         `NulthClient cannot use the insecure mock prover on mainnet; a production prover is required (network must be 'testnet', got ${String(config.network)})`
       );
     }
-    console.warn("NulthClient is using the insecure mock prover; proofs are not cryptographically sound");
+    resolveLogger(config.logger)(
+      "warn",
+      "NulthClient is using the insecure mock prover; proofs are not cryptographically sound"
+    );
   }
   config;
   policy;
@@ -1978,6 +2258,12 @@ var NulthClient = class {
     return proof;
   }
   enforcePolicy(context) {
+    if (context.amountStroops < 0n) {
+      throw new RangeError(`Invalid amountStroops: ${context.amountStroops}`);
+    }
+    if (!Number.isSafeInteger(context.ledgerSequence) || context.ledgerSequence < 0) {
+      throw new RangeError(`Invalid ledgerSequence: ${context.ledgerSequence}`);
+    }
     if (this.policy.expiryLedger !== void 0 && context.ledgerSequence > this.policy.expiryLedger) {
       throw new NulthPolicyError("session_expired", "Nulth session expired");
     }
@@ -2121,7 +2407,8 @@ var InMemorySpendStore = class {
   state = null;
   constructor(options = {}) {
     if (options.warn !== false) {
-      console.warn(
+      resolveLogger(options.logger)(
+        "warn",
         "[RouteDock] Using in-memory SpendStore: the daily spend cap is NOT durable and resets on every process restart. Inject a persistent SpendStore via RouteDockClientConfig.spendStore for production safety."
       );
     }
@@ -2211,7 +2498,10 @@ var RouteDockClient = class _RouteDockClient {
     this.network = config.network;
     this.spendCap = config.spendCap ? normalizeSpendCap(config.spendCap) : void 0;
     this.retryPolicy = config.retryPolicy;
-    this.spendStore = config.spendStore ?? new InMemorySpendStore({ warn: !!config.spendCap });
+    this.spendStore = config.spendStore ?? new InMemorySpendStore({
+      warn: !!config.spendCap,
+      ...config.logger && { logger: config.logger }
+    });
     this.logger = config.logger;
     this.manifestTimeoutMs = config.manifestTimeoutMs;
     this.expectedPayee = config.expectedPayee;
@@ -2223,9 +2513,10 @@ var RouteDockClient = class _RouteDockClient {
       _secrets.set(this, config.commitmentSecret);
     }
     const secretKey = this.keypair.secret();
-    this.x402 = new X402Client(secretKey, this.network, this.retryPolicy);
-    this.charge = new MppChargeClient(this.keypair, this.network, this.retryPolicy);
-    this.session = new MppSessionClient(this.keypair, this.network, this.retryPolicy);
+    const retryPolicy = this.logger ? { ...this.retryPolicy, logger: this.logger } : this.retryPolicy;
+    this.x402 = new X402Client(secretKey, this.network, retryPolicy);
+    this.charge = new MppChargeClient(this.keypair, this.network, retryPolicy);
+    this.session = new MppSessionClient(this.keypair, this.network, retryPolicy, void 0, this.logger);
   }
   /** Fetch manifest and select mode — shared by pay() and estimateCost(). */
   async _resolveManifest(url, options) {
@@ -2254,12 +2545,13 @@ var RouteDockClient = class _RouteDockClient {
    * call before committing to a payment — for approval gates and manual
    * trustline remediation.
    */
-  async preflight(manifest) {
+  async preflight(manifest, mode, endpoint) {
     assertManifestValid(manifest);
-    await this._checkTrustline(manifest);
+    const selectedAsset = mode ? selectAsset(manifest, mode, endpoint).asset : manifest.asset;
+    await this._checkTrustline(manifest, selectedAsset);
     return {
       hasTrustline: true,
-      asset: manifest.asset,
+      asset: selectedAsset,
       modes: manifest.modes,
       ...manifest.regions && { regions: manifest.regions },
       ...manifest.latency_hints && { latency_hints: manifest.latency_hints },
@@ -2273,8 +2565,8 @@ var RouteDockClient = class _RouteDockClient {
    * trustline is missing. Results are cached per (account, asset) so the
    * per-payment overhead is one RPC call amortized to zero after the first.
    */
-  async _checkTrustline(manifest) {
-    const cacheKey = `${this.network}:${this.keypair.publicKey()}:${manifest.asset}`;
+  async _checkTrustline(manifest, targetAsset = manifest.asset) {
+    const cacheKey = `${this.network}:${this.keypair.publicKey()}:${targetAsset}`;
     const cached = _RouteDockClient._trustlineCache.get(cacheKey);
     if (cached && Date.now() < cached.expiresAt) return;
     const horizonUrl = this.network === "testnet" ? "https://horizon-testnet.stellar.org" : "https://horizon.stellar.org";
@@ -2282,13 +2574,13 @@ var RouteDockClient = class _RouteDockClient {
     try {
       const account = await server.loadAccount(this.keypair.publicKey());
       const balances = account.balances;
-      const expectedIssuer = getAssetIssuer(manifest.asset, this.network);
+      const expectedIssuer = getAssetIssuer(targetAsset, this.network);
       const hasTrustline = balances.some(
-        (b) => typeof b === "object" && b !== null && "asset_code" in b && b.asset_code === manifest.asset && (!expectedIssuer || b.asset_issuer === expectedIssuer)
+        (b) => typeof b === "object" && b !== null && (targetAsset === "XLM" && b.asset_type === "native" || "asset_code" in b && b.asset_code === targetAsset && (!expectedIssuer || b.asset_issuer === expectedIssuer))
       );
       if (!hasTrustline) {
-        const remediation = expectedIssuer ? `Run: stellar tx new --source ${this.keypair.publicKey()} --network ${this.network} change-trust --asset ${manifest.asset}:${expectedIssuer} --limit 100000` : `Establish a trustline for ${manifest.asset} with the appropriate issuer on ${this.network}`;
-        throw new RouteDockTrustlineError(manifest.asset, expectedIssuer || "unknown", remediation);
+        const remediation = expectedIssuer ? `Run: stellar tx new --source ${this.keypair.publicKey()} --network ${this.network} change-trust --asset ${targetAsset}:${expectedIssuer} --limit 100000` : `Establish a trustline for ${targetAsset} with the appropriate issuer on ${this.network}`;
+        throw new RouteDockTrustlineError(targetAsset, expectedIssuer || "unknown", remediation);
       }
       _RouteDockClient._trustlineCache.set(cacheKey, {
         exists: true,
@@ -2297,7 +2589,8 @@ var RouteDockClient = class _RouteDockClient {
     } catch (err) {
       if (err instanceof RouteDockTrustlineError) throw err;
       this.logger?.(
-        `[RouteDock] Trustline preflight: could not verify trustline for ${manifest.asset} \u2014 continuing`
+        "warn",
+        `[RouteDock] Trustline preflight: could not verify trustline for ${targetAsset} \u2014 continuing`
       );
     }
   }
@@ -2305,18 +2598,18 @@ var RouteDockClient = class _RouteDockClient {
    * Pay for one request at `url`. Fetches manifest, selects payment mode,
    * runs trustline preflight, reserves local spend cap BEFORE executing the
    * payment, then commits the spend record on success. Rolls back the
-   * reservation if the on-chain payment fails. Concurrent pay() calls are
-   * serialized through a per-instance mutex to prevent spend-cap overrun.
+   * reservation if the on-chain payment fails, and also when the call
+   * completes without paying anything (an x402 endpoint answering a plain
+   * 200 with no challenge). Concurrent pay() calls are serialized through a
+   * per-instance mutex to prevent spend-cap overrun.
    */
   async pay(url, options) {
     const baseUrl = new URL(url).origin;
     const manifest = await fetchManifest(baseUrl, this.retryPolicy, this.manifestTimeoutMs, this.expectedPayee);
     assertEndpointActive(manifest, url, this.logger);
     const mode = selectMode(manifest, { ...options, ...this.logger && { logger: this.logger } });
-    await this._checkTrustline(manifest);
-    if (this.vault?.mode === "nulth") {
-      return this._payWithNulthVault(url, manifest, mode);
-    }
+    const selectedAsset = selectAsset(manifest, mode, url).asset;
+    await this._checkTrustline(manifest, selectedAsset);
     let amount;
     switch (mode) {
       case "x402":
@@ -2336,22 +2629,30 @@ var RouteDockClient = class _RouteDockClient {
     const reserveId = await this._checkAndReserveSpend(amount, baseUrl);
     let result;
     try {
-      switch (mode) {
-        case "x402":
-          result = await this.x402.pay(url, manifest);
-          break;
-        case "mpp-charge":
-          result = await this.charge.pay(url, manifest);
-          break;
-        default:
-          throw new RouteDockManifestError(`Unknown payment mode: ${mode}`);
+      if (this.vault?.mode === "nulth") {
+        result = await this._payWithNulthVault(url, manifest, mode);
+      } else {
+        switch (mode) {
+          case "x402":
+            result = await this.x402.pay(url, manifest);
+            break;
+          case "mpp-charge":
+            result = await this.charge.pay(url, manifest);
+            break;
+          default:
+            throw new RouteDockManifestError(`Unknown payment mode: ${mode}`);
+        }
       }
     } catch (err) {
       await this._rollbackSpend(reserveId).catch(() => {
       });
       throw err;
     }
-    await this._commitSpend(reserveId);
+    if (result.txHash === null && result.amount === "0") {
+      await this._rollbackSpend(reserveId);
+    } else {
+      await this._commitSpend(reserveId);
+    }
     return result;
   }
   /** Nulth ZK vault path — proof built off-chain, attached as auth signature */
@@ -2401,9 +2702,10 @@ var RouteDockClient = class _RouteDockClient {
       default:
         throw new RouteDockManifestError(`Unknown payment mode: ${mode}`);
     }
+    const selectedAsset = selectAsset(manifest, mode, url).asset;
     return {
       amount,
-      asset: manifest.asset,
+      asset: selectedAsset,
       mode,
       manifest,
       ...manifest.regions && { regions: manifest.regions },
@@ -2816,20 +3118,30 @@ exports.assertManifestValid = assertManifestValid;
 exports.assertNulthVaultManifest = assertNulthVaultManifest;
 exports.backoffDelayMs = backoffDelayMs;
 exports.configureManifestCache = configureManifestCache;
+exports.consoleLogger = consoleLogger;
+exports.createConsoleLogger = createConsoleLogger;
 exports.createNulthSigner = createNulthSigner;
 exports.createPolicyState = createPolicyState;
 exports.decodeAuthSignature = decodeAuthSignature;
 exports.fetchLedgerSequence = fetchLedgerSequence;
 exports.fetchManifest = fetchManifest;
+exports.getEligibleAssets = getEligibleAssets;
 exports.httpStatusToError = httpStatusToError;
 exports.invalidateManifest = invalidateManifest;
+exports.isAssetEligible = isAssetEligible;
+exports.noopLogger = noopLogger;
+exports.normalizeManifestAssets = normalizeManifestAssets;
 exports.parseRetryAfterMs = parseRetryAfterMs;
 exports.paymentContextFromManifest = paymentContextFromManifest;
 exports.prepareNulthSigner = prepareNulthSigner;
 exports.rankProvidersByLatency = rankProvidersByLatency;
+exports.resolveAssetContract = resolveAssetContract;
+exports.resolveLogger = resolveLogger;
+exports.selectAsset = selectAsset;
 exports.selectMode = selectMode;
 exports.setNulthPaymentContext = setNulthPaymentContext;
 exports.usdcToMicros = usdcToMicros;
 exports.usdcToUnits = usdcToUnits;
 exports.withRetry = withRetry;
 exports.wrapFetchError = wrapFetchError;
+exports.wrapMppError = wrapMppError;