@routedock/routedock 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -18,9 +18,9 @@ var path = require('path');
 var facilitator = require('@x402/stellar/exact/facilitator');
 var server$1 = require('@x402/stellar/exact/server');
 var server = require('@x402/core/server');
-var server$3 = require('@stellar/mpp/charge/server');
+var server$4 = require('@stellar/mpp/charge/server');
 var server$2 = require('mppx/server');
-var server$4 = require('@stellar/mpp/channel/server');
+var server$3 = require('@stellar/mpp/channel/server');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -171,10 +171,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,
@@ -189,10 +214,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 {
@@ -210,7 +236,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);
@@ -224,6 +250,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#",
@@ -303,6 +407,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"
@@ -435,6 +547,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",
@@ -580,7 +724,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)) {
@@ -704,6 +848,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}`
     );
   }
@@ -725,6 +870,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;
@@ -904,16 +1070,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)) {
@@ -923,10 +1089,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;
   }
@@ -962,6 +1129,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"
@@ -993,83 +1223,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");
+        return { kind: "free", data: data2 };
       }
-      let paymentRequired;
-      try {
-        paymentRequired = http.decodePaymentRequiredHeader(reqHeader);
-      } catch (err) {
-        throw new RouteDockManifestError("402 X-Payment-Requirements header is malformed", {
-          cause: err
-        });
-      }
-      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}`);
+        throw new RouteDockManifestError(`x402 payment failed: HTTP ${response.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 {
-        }
-      }
-      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 {
@@ -1086,27 +1339,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) {
@@ -1127,7 +1395,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);
   }
 };
@@ -1166,16 +1440,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];
@@ -1400,7 +1676,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) {
@@ -1693,9 +1969,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);
@@ -1745,7 +2022,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 = [];
@@ -1942,7 +2219,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;
@@ -1994,6 +2274,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");
     }
@@ -2137,7 +2423,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."
       );
     }
@@ -2227,7 +2514,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;
@@ -2239,9 +2529,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) {
@@ -2270,12 +2561,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 },
@@ -2289,8 +2581,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";
@@ -2298,13 +2590,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,
@@ -2313,7 +2605,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`
       );
     }
   }
@@ -2321,18 +2614,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":
@@ -2352,22 +2645,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 */
@@ -2417,9 +2718,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 },
@@ -2656,7 +2958,7 @@ var SupabaseSeenTxStore = class {
   }
   supabase;
   async get(key) {
-    const { data, error } = await this.supabase.from("settlements").select("tx_hash, headers").eq("key", key).maybeSingle();
+    const { data, error } = await this.supabase.from("settlements").select("tx_hash, headers, created_at").eq("key", key).maybeSingle();
     if (error) {
       throw new RouteDockNetworkError(`SupabaseSeenTxStore.get failed: ${error.message}`);
     }
@@ -2664,7 +2966,8 @@ var SupabaseSeenTxStore = class {
     const headers = data.headers;
     return {
       txHash: data.tx_hash ?? null,
-      ...headers ? { headers } : {}
+      ...headers ? { headers } : {},
+      createdAt: Date.parse(data.created_at)
     };
   }
   async set(key, record) {
@@ -2672,7 +2975,8 @@ var SupabaseSeenTxStore = class {
       {
         key,
         tx_hash: record.txHash,
-        headers: record.headers ?? null
+        headers: record.headers ?? null,
+        created_at: new Date(record.createdAt ?? Date.now()).toISOString()
       },
       { onConflict: "key" }
     );
@@ -2680,21 +2984,47 @@ var SupabaseSeenTxStore = class {
       throw new RouteDockNetworkError(`SupabaseSeenTxStore.set failed: ${error.message}`);
     }
   }
+  /**
+   * Atomically increment the settlement's replay counter through the
+   * `claim_settlement_replay` Postgres function (migration 006). The UPDATE's
+   * row lock gives concurrent claims distinct counts. Returns `Infinity` when
+   * the key no longer exists, so the caller treats it as spent.
+   */
+  async claimReplay(key) {
+    const { data, error } = await this.supabase.rpc("claim_settlement_replay", {
+      p_key: key
+    });
+    if (error) {
+      throw new RouteDockNetworkError(`SupabaseSeenTxStore.claimReplay failed: ${error.message}`);
+    }
+    if (data == null) return Number.POSITIVE_INFINITY;
+    return data;
+  }
 };
-
-// src/provider/payee.ts
-function resolvePayee(manifest, mode) {
-  const override = manifest.pricing[mode]?.payee;
-  return override ?? manifest.payee;
-}
 function extractPayerAddress(key) {
   if (typeof key !== "string") return null;
   return stellarSdk.StrKey.isValidEd25519PublicKey(key) || stellarSdk.StrKey.isValidMed25519PublicKey(key) ? key : null;
 }
 
 // src/provider/SeenTxStore.ts
+var SETTLEMENT_REPLAY_WINDOW_MS = 6e4;
+var MAX_SETTLEMENT_REPLAYS = 1;
+async function checkSettlementReplay(store, key, now = Date.now()) {
+  const record = await store.get(key);
+  if (!record) return { kind: "miss" };
+  const { createdAt } = record;
+  if (createdAt !== void 0 && now - createdAt > SETTLEMENT_REPLAY_WINDOW_MS) {
+    return { kind: "spent" };
+  }
+  if (store.claimReplay) {
+    const replayed = await store.claimReplay(key);
+    if (replayed > MAX_SETTLEMENT_REPLAYS) return { kind: "spent" };
+  }
+  return { kind: "replay", record };
+}
 var InMemorySeenTxStore = class {
   map = /* @__PURE__ */ new Map();
+  replayCounts = /* @__PURE__ */ new Map();
   order = [];
   constructor(maxEntriesOrOptions = 1e4) {
     const options = typeof maxEntriesOrOptions === "number" ? { maxEntries: maxEntriesOrOptions } : maxEntriesOrOptions;
@@ -2702,7 +3032,8 @@ var InMemorySeenTxStore = class {
     if (options.warn !== false) {
       const isServerless = typeof globalThis.navigator !== "undefined" && globalThis.navigator.userAgent === "Cloudflare-Workers";
       if (isServerless) {
-        console.warn(
+        resolveLogger(options.logger)(
+          "warn",
           "[RouteDock] Using in-memory SeenTxStore: settlement deduplication is NOT durable and resets on every isolate restart. Supply a SupabaseSeenTxStore (or other durable SeenTxStore) for production safety."
         );
       }
@@ -2717,21 +3048,43 @@ var InMemorySeenTxStore = class {
       this.order.push(key);
       if (this.order.length > this.maxEntries) {
         const evicted = this.order.shift();
-        if (evicted !== void 0) this.map.delete(evicted);
+        if (evicted !== void 0) {
+          this.map.delete(evicted);
+          this.replayCounts.delete(evicted);
+        }
       }
     }
     this.map.set(key, record);
   }
+  claimReplay(key) {
+    if (!this.map.has(key)) return Number.POSITIVE_INFINITY;
+    const next = (this.replayCounts.get(key) ?? 0) + 1;
+    this.replayCounts.set(key, next);
+    return next;
+  }
 };
 async function sha256Hex2(input) {
   const buf = new TextEncoder().encode(input);
   const digest = await crypto.subtle.digest("SHA-256", buf);
   return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
-async function paymentIdempotencyKey(getHeader) {
+async function paymentIdempotencyKey(getHeader, scope) {
   const material = getHeader("payment-signature") ?? getHeader("x-payment") ?? getHeader("authorization");
   if (!material) return null;
-  return sha256Hex2(material);
+  return sha256Hex2(
+    [scope.method, scope.path, scope.amount, scope.payTo, material].join("\n")
+  );
+}
+
+// src/provider/settleResult.ts
+function readSettleResult(result) {
+  const settle = result;
+  const failed = (reason) => reason ? { ok: false, reason } : { ok: false };
+  if (!settle || settle.success !== true) return failed(settle?.errorReason);
+  if (typeof settle.transaction !== "string" || settle.transaction.length === 0) {
+    return failed(settle.errorReason);
+  }
+  return { ok: true, txHash: settle.transaction };
 }
 
 // src/provider/x402Handler.ts
@@ -2744,7 +3097,8 @@ function createX402Handler(opts) {
   const caip2 = CAIP22[opts.network];
   const payeeKeypair = stellarSdk.Keypair.fromSecret(opts.payeeSecretKey);
   const signer = stellar.createEd25519Signer(opts.payeeSecretKey, caip2);
-  const seenTxStore = opts.seenTxStore ?? new InMemorySeenTxStore();
+  const logger = resolveLogger(opts.logger);
+  const seenTxStore = opts.seenTxStore ?? new InMemorySeenTxStore({ logger });
   const useOzFacilitator = opts.network === "mainnet" && opts.facilitatorApiKey;
   const localFacilitator = new facilitator.ExactStellarScheme([signer], {
     areFeesSponsored: true
@@ -2765,22 +3119,29 @@ function createX402Handler(opts) {
   }
   const amountInBaseUnits = String(usdcToUnits(opts.amount));
   const payTo = resolvePayee(opts.manifest, "x402");
-  const requirements = {
-    scheme: "exact",
-    network: caip2,
-    asset: opts.assetContract,
-    amount: amountInBaseUnits,
-    payTo,
-    maxTimeoutSeconds: 60,
-    extra: {
-      areFeesSponsored: true,
-      ...useOzFacilitator ? {} : { facilitatorAddresses: [payeeKeypair.publicKey()] }
-    }
-  };
   return async (req, res, next) => {
     try {
-      const paymentHeader = req.headers["payment-signature"] ?? req.headers["x-payment"];
-      if (!paymentHeader) {
+      const endpoint = req.path || req.originalUrl;
+      const assetContract = resolveAssetContract(
+        opts.manifest,
+        "x402",
+        endpoint,
+        opts.assetContract
+      );
+      const requirements = {
+        scheme: "exact",
+        network: caip2,
+        asset: assetContract,
+        amount: amountInBaseUnits,
+        payTo,
+        maxTimeoutSeconds: 60,
+        extra: {
+          areFeesSponsored: true,
+          ...useOzFacilitator ? {} : { facilitatorAddresses: [payeeKeypair.publicKey()] }
+        }
+      };
+      const respondPaymentRequired = async (error, reason) => {
+        const body = { error, ...reason ? { reason } : {} };
         if (ozServer) {
           const resourceInfo = {
             url: `${req.protocol}://${req.get("host") ?? ""}${req.originalUrl}`,
@@ -2790,7 +3151,7 @@ function createX402Handler(opts) {
             [requirements],
             resourceInfo
           );
-          res.status(402).setHeader("Content-Type", "application/json").setHeader("X-Payment-Requirements", http.encodePaymentRequiredHeader(paymentRequired)).json({ error: "Payment Required" });
+          res.status(402).setHeader("Content-Type", "application/json").setHeader("X-Payment-Requirements", http.encodePaymentRequiredHeader(paymentRequired)).json(body);
         } else {
           const x402Response = {
             x402Version: 2,
@@ -2800,19 +3161,35 @@ function createX402Handler(opts) {
             },
             accepts: [requirements]
           };
-          res.status(402).setHeader("Content-Type", "application/json").setHeader("X-Payment-Requirements", http.encodePaymentRequiredHeader(x402Response)).json({ error: "Payment Required" });
+          res.status(402).setHeader("Content-Type", "application/json").setHeader("X-Payment-Requirements", http.encodePaymentRequiredHeader(x402Response)).json(body);
         }
+      };
+      const paymentHeader = req.headers["payment-signature"] ?? req.headers["x-payment"];
+      if (!paymentHeader) {
+        await respondPaymentRequired("Payment Required");
         return;
       }
-      const idempotencyKey = await paymentIdempotencyKey((name) => {
-        const v = req.headers[name.toLowerCase()];
-        return Array.isArray(v) ? v[0] : v;
-      });
+      const idempotencyKey = await paymentIdempotencyKey(
+        (name) => {
+          const v = req.headers[name.toLowerCase()];
+          return Array.isArray(v) ? v[0] : v;
+        },
+        {
+          method: req.method,
+          path: req.originalUrl.split("?")[0],
+          amount: requirements.amount,
+          payTo: requirements.payTo
+        }
+      );
       if (idempotencyKey) {
-        const cached = await seenTxStore.get(idempotencyKey);
-        if (cached) {
-          if (cached.headers) {
-            for (const [k, val] of Object.entries(cached.headers)) {
+        const replayCheck = await checkSettlementReplay(seenTxStore, idempotencyKey);
+        if (replayCheck.kind === "spent") {
+          res.status(402).json({ error: "Payment already used" });
+          return;
+        }
+        if (replayCheck.kind === "replay") {
+          if (replayCheck.record.headers) {
+            for (const [k, val] of Object.entries(replayCheck.record.headers)) {
               res.setHeader(k, val);
             }
           }
@@ -2831,15 +3208,18 @@ function createX402Handler(opts) {
       }
       if (ozServer) {
         const settleResult = await ozServer.settlePayment(payload, requirements);
-        txHash = settleResult.transaction ?? null;
-        if (settleResult) {
-          res.setHeader(
-            "X-Payment-Response",
-            http.encodePaymentResponseHeader(
-              settleResult
-            )
-          );
+        const outcome = readSettleResult(settleResult);
+        if (!outcome.ok) {
+          await respondPaymentRequired("Payment settlement failed", outcome.reason);
+          return;
         }
+        txHash = outcome.txHash;
+        res.setHeader(
+          "X-Payment-Response",
+          http.encodePaymentResponseHeader(
+            settleResult
+          )
+        );
       } else {
         const verifyResult = await localFacilitator.verify(
           payload,
@@ -2856,15 +3236,18 @@ function createX402Handler(opts) {
           payload,
           requirements
         );
-        txHash = settleResult.transaction ?? null;
-        if (settleResult) {
-          res.setHeader(
-            "X-Payment-Response",
-            http.encodePaymentResponseHeader(
-              settleResult
-            )
-          );
+        const outcome = readSettleResult(settleResult);
+        if (!outcome.ok) {
+          await respondPaymentRequired("Payment settlement failed", outcome.reason);
+          return;
         }
+        txHash = outcome.txHash;
+        res.setHeader(
+          "X-Payment-Response",
+          http.encodePaymentResponseHeader(
+            settleResult
+          )
+        );
       }
       if (idempotencyKey) {
         const headers = {};
@@ -2872,17 +3255,21 @@ function createX402Handler(opts) {
         if (typeof paymentResponse === "string") {
           headers["X-Payment-Response"] = paymentResponse;
         }
-        await seenTxStore.set(idempotencyKey, { txHash, headers });
+        await seenTxStore.set(idempotencyKey, { txHash, headers, createdAt: Date.now() });
       }
       if (txHash && opts.onSettled) {
         Promise.resolve().then(() => opts.onSettled(txHash, opts.amount, "x402", payerAddress)).catch((err) => {
-          console.error("[x402] onSettled callback error:", err);
+          logger("error", "[x402] onSettled callback error", { error: err });
           opts.onCallbackError?.(err, "onSettled");
         });
       }
       next();
     } catch (err) {
-      console.error("[x402] Settlement error:", err);
+      if (err instanceof RouteDockManifestError) {
+        next(err);
+        return;
+      }
+      logger("error", "[x402] Settlement error", { error: err });
       res.status(500).json({ error: "Payment settlement failed" });
     }
   };
@@ -2895,20 +3282,37 @@ function createMppChargeHandler(opts) {
   const networkId = MPP_NETWORK[opts.network];
   const amountHumanReadable = opts.amount;
   const recipient = resolvePayee(opts.manifest, "mpp-charge");
-  const seenTxStore = opts.seenTxStore ?? new InMemorySeenTxStore();
-  const mppx = server$2.Mppx.create({
-    secretKey: opts.payeeSecretKey,
-    methods: [
-      server$3.stellar.charge({
-        recipient,
-        currency: opts.assetContract,
-        network: networkId,
-        feePayer: { envelopeSigner: opts.payeeSecretKey }
-      })
-    ]
-  });
+  const logger = resolveLogger(opts.logger);
+  const seenTxStore = opts.seenTxStore ?? new InMemorySeenTxStore({ logger });
+  const mppxInstances = /* @__PURE__ */ new Map();
+  function getMppx(contract) {
+    let instance = mppxInstances.get(contract);
+    if (!instance) {
+      instance = server$2.Mppx.create({
+        secretKey: opts.payeeSecretKey,
+        methods: [
+          server$4.stellar.charge({
+            recipient,
+            currency: contract,
+            network: networkId,
+            feePayer: { envelopeSigner: opts.payeeSecretKey }
+          })
+        ]
+      });
+      mppxInstances.set(contract, instance);
+    }
+    return instance;
+  }
   return async (req, res, next) => {
     try {
+      const endpoint = req.path || req.originalUrl;
+      const assetContract = resolveAssetContract(
+        opts.manifest,
+        "mpp-charge",
+        endpoint,
+        opts.assetContract
+      );
+      const mppx = getMppx(assetContract);
       let payerAddress = null;
       try {
         const authHeader = req.headers["authorization"];
@@ -2924,15 +3328,27 @@ function createMppChargeHandler(opts) {
         }
       } catch {
       }
-      const idempotencyKey = await paymentIdempotencyKey((name) => {
-        const v = req.headers[name.toLowerCase()];
-        return Array.isArray(v) ? v[0] : v;
-      });
+      const idempotencyKey = await paymentIdempotencyKey(
+        (name) => {
+          const v = req.headers[name.toLowerCase()];
+          return Array.isArray(v) ? v[0] : v;
+        },
+        {
+          method: req.method,
+          path: req.originalUrl.split("?")[0],
+          amount: amountHumanReadable,
+          payTo: recipient
+        }
+      );
       if (idempotencyKey) {
-        const cached = await seenTxStore.get(idempotencyKey);
-        if (cached) {
-          if (cached.headers) {
-            for (const [k, val] of Object.entries(cached.headers)) {
+        const replayCheck = await checkSettlementReplay(seenTxStore, idempotencyKey);
+        if (replayCheck.kind === "spent") {
+          res.status(402).json({ error: "Payment already used" });
+          return;
+        }
+        if (replayCheck.kind === "replay") {
+          if (replayCheck.record.headers) {
+            for (const [k, val] of Object.entries(replayCheck.record.headers)) {
               res.setHeader(k, val);
             }
           }
@@ -2944,7 +3360,7 @@ function createMppChargeHandler(opts) {
       const handler = mppx["stellar/charge"];
       const result = await handler({
         amount: amountHumanReadable,
-        currency: opts.assetContract,
+        currency: assetContract,
         recipient,
         description: opts.manifest.name
       })(fetchReq);
@@ -2975,12 +3391,13 @@ function createMppChargeHandler(opts) {
       if (idempotencyKey) {
         await seenTxStore.set(idempotencyKey, {
           txHash: reference ?? null,
-          headers: receiptHeaders
+          headers: receiptHeaders,
+          createdAt: Date.now()
         });
       }
       if (reference && opts.onSettled) {
         Promise.resolve().then(() => opts.onSettled(reference, opts.amount, "mpp-charge", payerAddress)).catch((err) => {
-          console.error("[mpp-charge] onSettled callback error:", err);
+          logger("error", "[mpp-charge] onSettled callback error", { error: err });
           opts.onCallbackError?.(err, "onSettled");
         });
       }
@@ -3081,8 +3498,9 @@ function createMppSessionHandler(opts) {
   const networkId = MPP_NETWORK2[opts.network];
   const rateHuman = opts.rate;
   const payeeKeypair = stellarSdk.Keypair.fromSecret(opts.payeeSecretKey);
+  const logger = resolveLogger(opts.logger);
   const voucherRecordKey = `routedock:session:voucher:${opts.channelFactory}`;
-  const innerStore = server$4.Store.memory();
+  const innerStore = server$3.Store.memory();
   let record = null;
   let voucherCount = 0;
   let sessionOpened = false;
@@ -3132,7 +3550,7 @@ function createMppSessionHandler(opts) {
           reason
         });
       } catch (err) {
-        console.error("[mpp-session] onOrphaned handler failed:", err);
+        logger("error", "[mpp-session] onOrphaned handler failed", { error: err });
       }
     }
   }
@@ -3179,7 +3597,7 @@ function createMppSessionHandler(opts) {
       sessionOpened = true;
       if (opts.onSessionOpen) {
         Promise.resolve().then(() => opts.onSessionOpen(opts.channelFactory, record.payer)).catch((err) => {
-          console.error("[mpp-session] onSessionOpen callback error:", err);
+          logger("error", "[mpp-session] onSessionOpen callback error", { error: err });
           opts.onCallbackError?.(err, "onSessionOpen");
         });
       }
@@ -3187,7 +3605,7 @@ function createMppSessionHandler(opts) {
     if (opts.onVoucher) {
       const humanAmount = (Number(record.amount) / 1e7).toFixed(7);
       Promise.resolve().then(() => opts.onVoucher(opts.channelFactory, voucherCount, humanAmount, record.signature)).catch((err) => {
-        console.error("[mpp-session] onVoucher callback error:", err);
+        logger("error", "[mpp-session] onVoucher callback error", { error: err });
         opts.onCallbackError?.(err, "onVoucher");
       });
     }
@@ -3197,7 +3615,7 @@ function createMppSessionHandler(opts) {
     methods: [
       withTypedChannelErrors(
         onVerifiedCredential(
-          server$4.stellar.channel({
+          server$3.stellar.channel({
             channel: opts.channelFactory,
             commitmentKey: opts.commitmentPublicKey,
             network: networkId,
@@ -3228,7 +3646,7 @@ function createMppSessionHandler(opts) {
         }
         if (closeAmount > 0n && closeSig) {
           const closePayer = record?.payer ?? null;
-          const closeTxHash = await server$4.close({
+          const closeTxHash = await server$3.close({
             channel: opts.channelFactory,
             amount: closeAmount,
             signature: Buffer.from(closeSig, "hex"),
@@ -3240,7 +3658,7 @@ function createMppSessionHandler(opts) {
           if (opts.onSettled) {
             const totalPaid = (Number(closeAmount) / 1e7).toFixed(7);
             Promise.resolve().then(() => opts.onSettled(closeTxHash, totalPaid, "mpp-session", closePayer)).catch((err) => {
-              console.error("[mpp-session] onSettled callback error:", err);
+              logger("error", "[mpp-session] onSettled callback error", { error: err });
               opts.onCallbackError?.(err, "onSettled");
             });
           }
@@ -3251,7 +3669,7 @@ function createMppSessionHandler(opts) {
               payeeKeypair.publicKey()
             );
             if (!settlementAddresses) {
-              console.error("[mpp-session] skipped session_settled vault record: payer address unavailable");
+              logger("warn", "[mpp-session] skipped session_settled vault record: payer address unavailable");
             } else {
               try {
                 const { Networks: Networks2 } = await import('@stellar/stellar-sdk');
@@ -3274,7 +3692,7 @@ function createMppSessionHandler(opts) {
                 preparedTx.sign(payeeKeypair);
                 await server.sendTransaction(preparedTx);
               } catch (recordErr) {
-                console.error("[mpp-session] failed to record session_settled on vault:", recordErr);
+                logger("error", "[mpp-session] failed to record session_settled on vault", { error: recordErr });
               }
             }
           }
@@ -3331,12 +3749,13 @@ function routedock(opts) {
           payeeSecretKey: opts.payeeSecretKey,
           network: opts.network,
           amount: x402Price,
-          assetContract: opts.assetContract,
+          ...opts.assetContract ? { assetContract: opts.assetContract } : {},
           ...opts.facilitatorApiKey ? { facilitatorApiKey: opts.facilitatorApiKey } : {},
           manifest: signedManifest,
           ...opts.onSettled ? { onSettled: opts.onSettled } : {},
           ...opts.onCallbackError ? { onCallbackError: opts.onCallbackError } : {},
-          ...opts.seenTxStore ? { seenTxStore: opts.seenTxStore } : {}
+          ...opts.seenTxStore ? { seenTxStore: opts.seenTxStore } : {},
+          ...opts.logger ? { logger: opts.logger } : {}
         })
       );
     }
@@ -3350,11 +3769,12 @@ function routedock(opts) {
           payeeSecretKey: opts.payeeSecretKey,
           network: opts.network,
           amount: chargePrice,
-          assetContract: opts.assetContract,
+          ...opts.assetContract ? { assetContract: opts.assetContract } : {},
           manifest: signedManifest,
           ...opts.onSettled ? { onSettled: opts.onSettled } : {},
           ...opts.onCallbackError ? { onCallbackError: opts.onCallbackError } : {},
-          ...opts.seenTxStore ? { seenTxStore: opts.seenTxStore } : {}
+          ...opts.seenTxStore ? { seenTxStore: opts.seenTxStore } : {},
+          ...opts.logger ? { logger: opts.logger } : {}
         })
       );
     }
@@ -3372,7 +3792,7 @@ function routedock(opts) {
           network: opts.network,
           channelFactory: sessionPricing.channelFactory,
           rate: sessionPricing.rate,
-          assetContract: opts.assetContract,
+          ...opts.assetContract ? { assetContract: opts.assetContract } : {},
           manifest: signedManifest,
           commitmentPublicKey: opts.commitmentPublicKey,
           ...opts.onSettled ? { onSettled: opts.onSettled } : {},
@@ -3380,7 +3800,8 @@ function routedock(opts) {
           ...opts.onVoucher ? { onVoucher: opts.onVoucher } : {},
           ...opts.onCallbackError ? { onCallbackError: opts.onCallbackError } : {},
           ...opts.onOrphaned ? { onOrphaned: opts.onOrphaned } : {},
-          ...opts.idleTimeoutMs != null ? { idleTimeoutMs: opts.idleTimeoutMs } : {}
+          ...opts.idleTimeoutMs != null ? { idleTimeoutMs: opts.idleTimeoutMs } : {},
+          ...opts.logger ? { logger: opts.logger } : {}
         })
       );
     }
@@ -3544,25 +3965,26 @@ async function reconcileAbandonedSessions(opts) {
   }
 }
 async function runStartupReconciliation(opts, logger) {
-  const log = logger || console.log;
-  log("[SessionReconciler] Running startup reconciliation...");
+  const log = resolveLogger(logger);
+  log("info", "[SessionReconciler] Running startup reconciliation...");
   try {
     const stats = await reconcileAbandonedSessions(opts);
     if (stats.orphanedCount === 0) {
-      log("[SessionReconciler] No orphaned sessions found");
+      log("info", "[SessionReconciler] No orphaned sessions found");
       return;
     }
     log(
+      "info",
       `[SessionReconciler] Found ${stats.orphanedCount} orphaned session(s). Recovered: ${stats.recoveredCount}, Skipped: ${stats.skippedCount}, Failed: ${stats.failedCount}`
     );
     if (stats.errors.length > 0) {
-      log("[SessionReconciler] Reconciliation errors:");
+      log("warn", "[SessionReconciler] Reconciliation errors:");
       for (const err of stats.errors) {
-        log(`  - ${err.channelId}: ${err.reason}`);
+        log("warn", `  - ${err.channelId}: ${err.reason}`);
       }
     }
   } catch (err) {
-    log(`[SessionReconciler] Startup reconciliation failed: ${formatMppError(err)}`);
+    log("error", `[SessionReconciler] Startup reconciliation failed: ${formatMppError(err)}`);
   }
 }
 function tryDecodeBase64(value) {
@@ -3749,23 +4171,32 @@ 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.decimalToStroops = decimalToStroops;
 exports.decodeAuthSignature = decodeAuthSignature;
 exports.fetchLedgerSequence = fetchLedgerSequence;
 exports.fetchManifest = fetchManifest;
+exports.getEligibleAssets = getEligibleAssets;
 exports.httpStatusToError = httpStatusToError;
 exports.invalidateManifest = invalidateManifest;
+exports.isAssetEligible = isAssetEligible;
 exports.manifestDigest = manifestDigest;
+exports.noopLogger = noopLogger;
+exports.normalizeManifestAssets = normalizeManifestAssets;
 exports.parseRetryAfterMs = parseRetryAfterMs;
 exports.paymentContextFromManifest = paymentContextFromManifest;
 exports.prepareNulthSigner = prepareNulthSigner;
 exports.rankProvidersByLatency = rankProvidersByLatency;
 exports.reconcileAbandonedSessions = reconcileAbandonedSessions;
 exports.registerProvider = registerProvider;
+exports.resolveAssetContract = resolveAssetContract;
+exports.resolveLogger = resolveLogger;
 exports.routedock = routedock;
 exports.runStartupReconciliation = runStartupReconciliation;
+exports.selectAsset = selectAsset;
 exports.selectMode = selectMode;
 exports.setNulthPaymentContext = setNulthPaymentContext;
 exports.signManifest = signManifest;
@@ -3774,3 +4205,4 @@ exports.usdcToUnits = usdcToUnits;
 exports.verifyManifestSignature = verifyManifestSignature;
 exports.withRetry = withRetry;
 exports.wrapFetchError = wrapFetchError;
+exports.wrapMppError = wrapMppError;