@routedock/routedock 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -2,17 +2,17 @@
 
 var nulthSdk = require('@routedock/nulth-sdk');
 var stellarSdk = require('@stellar/stellar-sdk');
+var sha2_js = require('@noble/hashes/sha2.js');
 var jsonSchema = require('@cfworker/json-schema');
-var crypto$1 = require('crypto');
 var stellar = require('@x402/stellar');
-var client = require('@x402/stellar/exact/client');
-var client$1 = require('@x402/core/client');
+var client = require('@x402/core/client');
 var http = require('@x402/core/http');
-var client$3 = require('@stellar/mpp/charge/client');
-var client$2 = require('mppx/client');
-var mpp = require('@stellar/mpp');
-var client$4 = require('@stellar/mpp/channel/client');
+var client$2 = require('@stellar/mpp/charge/client');
+var client$1 = require('mppx/client');
 var mppx = require('mppx');
+var mpp = require('@stellar/mpp');
+var client$3 = require('@stellar/mpp/channel/client');
+var crypto$1 = require('crypto');
 var fs = require('fs/promises');
 var path = require('path');
 var facilitator = require('@x402/stellar/exact/facilitator');
@@ -123,6 +123,20 @@ var RouteDockPolicyRejectError = class extends RouteDockError {
     this.reason = reason;
   }
 };
+var RouteDockPaymentRejectedError = class extends RouteDockError {
+  status;
+  /** The provider's `reason` field, if its response body was JSON and had one. */
+  reason;
+  /** The provider's `error` field (short summary), if present. */
+  providerError;
+  constructor(message, status, details = {}, options = {}) {
+    super(message, "PAYMENT_REJECTED", false, options);
+    this.name = "RouteDockPaymentRejectedError";
+    this.status = status;
+    if (details.reason !== void 0) this.reason = details.reason;
+    if (details.providerError !== void 0) this.providerError = details.providerError;
+  }
+};
 var RouteDockChannelStateError = class extends RouteDockError {
   constructor(message, options = {}) {
     super(message, "CHANNEL_STATE", false, options);
@@ -167,6 +181,59 @@ function httpStatusToError(message, status, response) {
   }
   return new RouteDockNetworkError(message, opts);
 }
+var MAX_REJECTION_BODY_BYTES = 64 * 1024;
+var MAX_REJECTION_FIELD_CHARS = 500;
+async function readBoundedText(response, limit) {
+  const body = response.body;
+  if (!body) return null;
+  const reader = body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > limit) {
+        await reader.cancel().catch(() => void 0);
+        return null;
+      }
+      chunks.push(value);
+    }
+  } catch {
+    return null;
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(bytes);
+}
+async function paymentRejectedError(label, status, response) {
+  let reason;
+  let providerError;
+  try {
+    const text = await readBoundedText(response, MAX_REJECTION_BODY_BYTES);
+    const body = text === null ? null : JSON.parse(text);
+    if (body !== null && typeof body === "object") {
+      const { reason: r, error: e } = body;
+      if (typeof r === "string" && r.length > 0) reason = r.slice(0, MAX_REJECTION_FIELD_CHARS);
+      if (typeof e === "string" && e.length > 0) providerError = e.slice(0, MAX_REJECTION_FIELD_CHARS);
+    }
+  } catch {
+  }
+  const detail = reason ?? providerError;
+  return new RouteDockPaymentRejectedError(
+    `${label}: HTTP ${status}${detail ? ` \u2014 ${detail}` : ""}`,
+    status,
+    {
+      ...reason !== void 0 ? { reason } : {},
+      ...providerError !== void 0 ? { providerError } : {}
+    }
+  );
+}
 function wrapFetchError(err, context) {
   if (err instanceof RouteDockError) return err;
   return new RouteDockNetworkError(`${context}: ${String(err)}`, { cause: err });
@@ -231,23 +298,34 @@ async function withRetry(fn, policy = {}) {
       if (!err.retryable || attempt >= maxAttempts - 1) {
         throw err;
       }
-      const delay = err.retryAfterMs !== void 0 ? err.retryAfterMs : backoffDelayMs(attempt, baseDelayMs, maxDelayMs);
+      const delay2 = Math.min(
+        err.retryAfterMs ?? backoffDelayMs(attempt, baseDelayMs, maxDelayMs),
+        maxDelayMs
+      );
       if (onRetry) {
         try {
-          await onRetry(attempt, err, delay);
+          await onRetry(attempt, err, delay2);
         } catch (cbErr) {
           log("error", "[withRetry] onRetry callback threw:", { error: cbErr });
         }
       }
-      await sleep(delay);
+      await sleep(delay2);
     }
   }
   throw lastError ?? new RouteDockError("Retry exhausted", "NETWORK", false);
 }
+
+// src/network.ts
 var USDC_ISSUERS = {
   testnet: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
   mainnet: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
 };
+var HORIZON_URLS = {
+  testnet: "https://horizon-testnet.stellar.org",
+  mainnet: "https://horizon.stellar.org"
+};
+
+// src/internal/usdc.ts
 var usdcToUnits = nulthSdk.usdcToStroops;
 
 // src/internal/assetUtils.ts
@@ -328,6 +406,138 @@ function isAssetEligible(manifest, assetIdentifier, mode, endpoint) {
   );
 }
 
+// package.json
+var package_default = {
+  version: "0.4.0"};
+
+// src/internal/encoding.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function utf8ToBytes(text) {
+  return encoder.encode(text);
+}
+function bytesToUtf8(bytes) {
+  return decoder.decode(bytes);
+}
+function bytesToBase64(bytes) {
+  const chunk = 32768;
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+  }
+  return btoa(binary);
+}
+function base64ToBytes(b64) {
+  const end = b64.indexOf("=");
+  let clean = (end === -1 ? b64 : b64.slice(0, end)).replace(/-/g, "+").replace(/_/g, "/").replace(/[^A-Za-z0-9+/]/g, "");
+  if (clean.length % 4 === 1) clean = clean.slice(0, -1);
+  const binary = atob(clean);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+function base64ToUtf8(b64) {
+  return bytesToUtf8(base64ToBytes(b64));
+}
+function hexToBytes(hex) {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  if (clean.length % 2 !== 0) {
+    throw new Error("hexToBytes: hex string must have an even length");
+  }
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+function bytesToHex(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += bytes[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+function sha256(data) {
+  return sha2_js.sha256(typeof data === "string" ? utf8ToBytes(data) : data);
+}
+
+// src/manifest/sign.ts
+var MANIFEST_SIGNATURE_VERSION = "2";
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value).sort().map((key) => [key, canonicalize(value[key])])
+    );
+  }
+  return value;
+}
+function manifestDigest(manifest) {
+  const { signature: _omit, ...rest } = manifest;
+  const canonical = JSON.stringify(canonicalize(rest));
+  return sha256(utf8ToBytes(canonical));
+}
+function signManifest(manifest, payeeSecretKey) {
+  const keypair = stellarSdk.Keypair.fromSecret(payeeSecretKey);
+  const versionedManifest = {
+    ...manifest,
+    signature_version: MANIFEST_SIGNATURE_VERSION
+  };
+  const digest = manifestDigest(versionedManifest);
+  const sig = keypair.sign(digest);
+  return { ...versionedManifest, signature: bytesToBase64(sig) };
+}
+function verifyManifestSignature(manifest, expectedPayee) {
+  if (!manifest.signature) {
+    throw new RouteDockSignatureError(
+      "Manifest is missing a signature field \u2014 cannot verify payee authenticity"
+    );
+  }
+  if (manifest.signature_version !== MANIFEST_SIGNATURE_VERSION) {
+    throw new RouteDockSignatureError(
+      `Manifest signature version must be ${MANIFEST_SIGNATURE_VERSION}; legacy signatures are not safe because nested fields were excluded from their digest`
+    );
+  }
+  if (expectedPayee !== void 0 && manifest.payee !== expectedPayee) {
+    throw new RouteDockSignatureError(
+      `Manifest payee ${manifest.payee} does not match expected payee ${expectedPayee}`
+    );
+  }
+  let keypair;
+  try {
+    keypair = stellarSdk.Keypair.fromPublicKey(manifest.payee);
+  } catch (err) {
+    throw new RouteDockSignatureError(
+      `Manifest payee ${manifest.payee} is not a valid Stellar public key`,
+      { cause: err }
+    );
+  }
+  const digest = manifestDigest(manifest);
+  let sigBytes;
+  try {
+    sigBytes = base64ToBytes(manifest.signature);
+  } catch {
+    throw new RouteDockSignatureError("Manifest signature is not valid base64");
+  }
+  let valid = false;
+  try {
+    valid = keypair.verify(digest, sigBytes);
+  } catch {
+    throw new RouteDockSignatureError(
+      `Manifest signature verification failed for payee ${manifest.payee}`
+    );
+  }
+  if (!valid) {
+    throw new RouteDockSignatureError(
+      `Manifest signature verification failed for payee ${manifest.payee}`
+    );
+  }
+}
+
 // src/schemas/routedock.schema.json
 var routedock_schema_default = {
   $schema: "http://json-schema.org/draft-07/schema#",
@@ -405,6 +615,7 @@ var routedock_schema_default = {
     },
     asset_contract: {
       type: "string",
+      pattern: "^C[A-Z2-7]{55}$",
       description: "Stellar Asset Contract (SAC) address for the payment asset"
     },
     assets: {
@@ -417,6 +628,7 @@ var routedock_schema_default = {
     },
     payee: {
       type: "string",
+      pattern: "^G[A-Z2-7]{55}$",
       description: "Stellar address (G...) that receives payments"
     },
     pricing: {
@@ -587,6 +799,7 @@ var routedock_schema_default = {
       properties: {
         amount: {
           type: "string",
+          pattern: "^[0-9]+(\\.[0-9]{1,7})?$",
           description: "Cost per request in the payment asset (decimal string, e.g. '0.001')"
         },
         per: {
@@ -600,6 +813,7 @@ var routedock_schema_default = {
         },
         payee: {
           type: "string",
+          pattern: "^G[A-Z2-7]{55}$",
           description: "Optional per-mode payee override (Stellar G... address). Directs settlements for this mode to a separate account for treasury separation. Falls back to the top-level 'payee' when omitted."
         }
       }
@@ -612,6 +826,7 @@ var routedock_schema_default = {
       properties: {
         rate: {
           type: "string",
+          pattern: "^[0-9]+(\\.[0-9]{1,7})?$",
           description: "Cost per voucher in the payment asset (decimal string, e.g. '0.0001')"
         },
         per: {
@@ -621,10 +836,12 @@ var routedock_schema_default = {
         },
         channel_factory: {
           type: "string",
+          pattern: "^C[A-Z2-7]{55}$",
           description: "Stable Soroban factory address (C...) used to deploy a per-session channel"
         },
         min_deposit: {
           type: "string",
+          pattern: "^[0-9]+(\\.[0-9]{1,7})?$",
           description: "Minimum initial deposit to open a channel (decimal string)"
         },
         refund_waiting_period_ledgers: {
@@ -722,78 +939,110 @@ var routedock_schema_default = {
   }
 };
 
-// package.json
-var package_default = {
-  version: "0.3.0"};
-var MANIFEST_SIGNATURE_VERSION = "2";
-function canonicalize(value) {
-  if (Array.isArray(value)) {
-    return value.map(canonicalize);
-  }
-  if (value !== null && typeof value === "object") {
-    return Object.fromEntries(
-      Object.keys(value).sort().map((key) => [key, canonicalize(value[key])])
-    );
+// src/manifest/validate.ts
+var validator = new jsonSchema.Validator(routedock_schema_default, "7");
+function validateManifestSchema(manifest, source) {
+  const result = validator.validate(manifest);
+  if (!result.valid) {
+    const msgs = result.errors.map((err) => err.error).join("; ");
+    throw new RouteDockManifestError(`Invalid manifest${source ? ` at ${source}` : ""}: ${msgs}`);
   }
-  return value;
 }
-function manifestDigest(manifest) {
-  const { signature: _omit, ...rest } = manifest;
-  const canonical = JSON.stringify(canonicalize(rest));
-  return crypto$1.createHash("sha256").update(canonical, "utf8").digest();
-}
-function signManifest(manifest, payeeSecretKey) {
-  const keypair = stellarSdk.Keypair.fromSecret(payeeSecretKey);
-  const versionedManifest = {
-    ...manifest,
-    signature_version: MANIFEST_SIGNATURE_VERSION
-  };
-  const digest = manifestDigest(versionedManifest);
-  const sig = keypair.sign(digest);
-  return { ...versionedManifest, signature: Buffer.from(sig).toString("base64") };
-}
-function verifyManifestSignature(manifest, expectedPayee) {
-  if (!manifest.signature) {
-    throw new RouteDockSignatureError(
-      "Manifest is missing a signature field \u2014 cannot verify payee authenticity"
-    );
-  }
-  if (manifest.signature_version !== MANIFEST_SIGNATURE_VERSION) {
-    throw new RouteDockSignatureError(
-      `Manifest signature version must be ${MANIFEST_SIGNATURE_VERSION}; legacy signatures are not safe because nested fields were excluded from their digest`
-    );
+function assertManifestValid(manifest, baseUrl) {
+  const context = baseUrl ? ` at ${baseUrl}` : "";
+  if (manifest.latency_hints !== void 0) {
+    if (!Array.isArray(manifest.regions) || manifest.regions.length === 0) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: latency_hints defined without declaring regions`
+      );
+    }
+    const regionSet = new Set(manifest.regions);
+    for (const region of Object.keys(manifest.latency_hints)) {
+      if (!regionSet.has(region)) {
+        throw new RouteDockManifestError(
+          `Invalid manifest${context}: latency_hints key '${region}' is not declared in regions (${manifest.regions.join(", ")})`
+        );
+      }
+    }
   }
-  if (expectedPayee !== void 0 && manifest.payee !== expectedPayee) {
-    throw new RouteDockSignatureError(
-      `Manifest payee ${manifest.payee} does not match expected payee ${expectedPayee}`
-    );
+  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})`
+      );
+    }
   }
-  const keypair = stellarSdk.Keypair.fromPublicKey(manifest.payee);
-  const digest = manifestDigest(manifest);
-  let sigBytes;
-  try {
-    sigBytes = Buffer.from(manifest.signature, "base64");
-  } catch {
-    throw new RouteDockSignatureError("Manifest signature is not valid base64");
+  assertPricingMatchesModes(manifest, context);
+  assertDeprecatedModesListed(manifest, context);
+  assertPricesParse(manifest, context);
+}
+function assertPricingMatchesModes(manifest, context) {
+  const pricing = manifest.pricing ?? {};
+  for (const mode of manifest.modes ?? []) {
+    if (pricing[mode] === void 0 || pricing[mode] === null) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: mode '${mode}' is listed in modes but pricing.${mode} is missing`
+      );
+    }
   }
-  let valid = false;
-  try {
-    valid = keypair.verify(digest, sigBytes);
-  } catch {
-    throw new RouteDockSignatureError(
-      `Manifest signature verification failed for payee ${manifest.payee}`
-    );
+}
+function assertDeprecatedModesListed(manifest, context) {
+  if (manifest.deprecated_modes === void 0) return;
+  const modes = new Set(manifest.modes ?? []);
+  for (const mode of manifest.deprecated_modes) {
+    if (!modes.has(mode)) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: deprecated_modes entry '${mode}' is not listed in modes`
+      );
+    }
   }
-  if (!valid) {
-    throw new RouteDockSignatureError(
-      `Manifest signature verification failed for payee ${manifest.payee}`
-    );
+}
+var PRICE_FIELDS = {
+  x402: ["amount"],
+  "mpp-charge": ["amount"],
+  "mpp-session": ["rate", "min_deposit"],
+  "mpp-session-ws": ["rate", "min_deposit"]
+};
+function assertPricesParse(manifest, context) {
+  const pricing = manifest.pricing ?? {};
+  for (const [mode, fields] of Object.entries(PRICE_FIELDS)) {
+    const entry = pricing[mode];
+    if (entry === void 0 || entry === null) continue;
+    for (const field of fields) {
+      const value = entry[field];
+      try {
+        if (typeof value !== "string") {
+          throw new RangeError(`expected a decimal string, got ${typeof value}`);
+        }
+        nulthSdk.usdcToStroops(value);
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new RouteDockManifestError(
+          `Invalid manifest${context}: pricing.${mode}.${field} ${JSON.stringify(value)} is not a valid amount (${detail})`,
+          { cause: err }
+        );
+      }
+    }
   }
 }
 
 // src/client/ModeRouter.ts
-var validator = new jsonSchema.Validator(routedock_schema_default, "7");
 var SDK_VERSION = package_default.version;
+var SUPPORTED_MANIFEST_MAJOR = 1;
 function parseMajorMinor(version) {
   const parts = version.split(".");
   return [Number.parseInt(parts[0] ?? "0", 10), Number.parseInt(parts[1] ?? "0", 10)];
@@ -811,6 +1060,14 @@ function assertClientVersionSupported(manifest, baseUrl) {
     );
   }
 }
+function assertManifestVersionSupported(manifest, baseUrl) {
+  const [major] = parseMajorMinor(manifest.routedock);
+  if (major > SUPPORTED_MANIFEST_MAJOR) {
+    throw new RouteDockClientVersionError(
+      `Manifest version ${manifest.routedock} from provider at ${baseUrl} has schema major version ${major}, which is newer than the highest version this SDK supports (${SUPPORTED_MANIFEST_MAJOR}.x). Please upgrade the SDK.`
+    );
+  }
+}
 function assertManifestActive(manifest, baseUrl) {
   const sunsetAt = manifest.sunset_at;
   if (!sunsetAt) return;
@@ -826,11 +1083,16 @@ function assertManifestActive(manifest, baseUrl) {
     );
   }
 }
-function assertEndpointActive(manifest, url, logger) {
+function assertEndpointActive(manifest, url, logger, method) {
   const pathname = new URL(url).pathname;
-  const matches = Object.entries(manifest.endpoints).filter(
+  const pathMatches = Object.entries(manifest.endpoints).filter(
     ([, descriptor]) => descriptor.path === pathname
   );
+  if (pathMatches.length === 0) return;
+  const requestedMethod = method?.toUpperCase();
+  const matches = requestedMethod ? pathMatches.filter(
+    ([, descriptor]) => descriptor.method.toUpperCase() === requestedMethod
+  ) : pathMatches;
   if (matches.length === 0) return;
   const now = Date.now();
   const allSunset = matches.every(([, descriptor]) => {
@@ -853,45 +1115,6 @@ function assertEndpointActive(manifest, url, logger) {
     );
   }
 }
-function assertManifestValid(manifest, baseUrl) {
-  const context = baseUrl ? ` at ${baseUrl}` : "";
-  if (manifest.latency_hints !== void 0) {
-    if (!Array.isArray(manifest.regions) || manifest.regions.length === 0) {
-      throw new RouteDockManifestError(
-        `Invalid manifest${context}: latency_hints defined without declaring regions`
-      );
-    }
-    const regionSet = new Set(manifest.regions);
-    for (const region of Object.keys(manifest.latency_hints)) {
-      if (!regionSet.has(region)) {
-        throw new RouteDockManifestError(
-          `Invalid manifest${context}: latency_hints key '${region}' is not declared in regions (${manifest.regions.join(", ")})`
-        );
-      }
-    }
-  }
-  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;
 var DEFAULT_MANIFEST_TIMEOUT_MS = 5e3;
@@ -932,6 +1155,7 @@ var LruCache = class {
   }
 };
 var manifestCache = new LruCache(DEFAULT_MANIFEST_CACHE_MAX_SIZE);
+var inflightManifestFetches = /* @__PURE__ */ new Map();
 function configureManifestCache(maxSize) {
   if (!Number.isInteger(maxSize) || maxSize <= 0) {
     throw new RouteDockManifestError("Invalid manifest cache size: " + maxSize);
@@ -967,10 +1191,27 @@ async function fetchManifest(baseUrl, retryPolicy, manifestTimeoutMs = DEFAULT_M
   if (cached && Date.now() < cached.expiresAt) {
     verifyManifestSignature(cached.manifest, expectedPayee);
     assertClientVersionSupported(cached.manifest, baseUrl);
+    assertManifestVersionSupported(cached.manifest, baseUrl);
     assertManifestValid(cached.manifest, baseUrl);
     assertManifestActive(cached.manifest, baseUrl);
     return cached.manifest;
   }
+  let inflight = inflightManifestFetches.get(baseUrl);
+  if (!inflight) {
+    inflight = fetchAndCacheManifest(baseUrl, retryPolicy, manifestTimeoutMs).finally(() => {
+      inflightManifestFetches.delete(baseUrl);
+    });
+    inflightManifestFetches.set(baseUrl, inflight);
+  }
+  const manifest = await inflight;
+  verifyManifestSignature(manifest, expectedPayee);
+  assertClientVersionSupported(manifest, baseUrl);
+  assertManifestVersionSupported(manifest, baseUrl);
+  assertManifestValid(manifest, baseUrl);
+  assertManifestActive(manifest, baseUrl);
+  return manifest;
+}
+async function fetchAndCacheManifest(baseUrl, retryPolicy, manifestTimeoutMs = DEFAULT_MANIFEST_TIMEOUT_MS) {
   const url = baseUrl.replace(/\/$/, "") + "/.well-known/routedock.json";
   return withRetry(async () => {
     let raw;
@@ -1007,15 +1248,12 @@ async function fetchManifest(baseUrl, retryPolicy, manifestTimeoutMs = DEFAULT_M
     } catch (err) {
       throw new RouteDockManifestError(`Manifest at ${url} is not valid JSON`, { cause: err });
     }
-    const result = validator.validate(raw);
-    if (!result.valid) {
-      const msgs = result.errors.map((err) => err.error).join("; ");
-      throw new RouteDockManifestError(`Invalid manifest at ${url}: ${msgs}`);
-    }
+    validateManifestSchema(raw, url);
     const manifest = raw;
     assertManifestValid(manifest, baseUrl);
-    verifyManifestSignature(manifest, expectedPayee);
+    verifyManifestSignature(manifest);
     assertClientVersionSupported(manifest, baseUrl);
+    assertManifestVersionSupported(manifest, baseUrl);
     assertManifestActive(manifest, baseUrl);
     manifestCache.set(baseUrl, { manifest, fetchedAt: Date.now(), expiresAt });
     return manifest;
@@ -1130,6 +1368,48 @@ function rankProvidersByLatency(manifests, targetRegion) {
   });
 }
 
+// src/internal/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/internal/request.ts
+var DEFAULT_METHOD = "GET";
+var BODYLESS_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD"]);
+function isReplayable(body) {
+  return typeof body === "string" || body instanceof ArrayBuffer || ArrayBuffer.isView(body) || typeof Blob !== "undefined" && body instanceof Blob || typeof FormData !== "undefined" && body instanceof FormData || typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams;
+}
+async function bufferBody(body) {
+  if (isReplayable(body)) return body;
+  return new Response(body).arrayBuffer();
+}
+async function prepareRequest(request) {
+  const method = (request?.method ?? DEFAULT_METHOD).toUpperCase();
+  const headers = new Headers(request?.headers);
+  const body = request?.body;
+  if (body === void 0 || BODYLESS_METHODS.has(method)) {
+    return { method, headers };
+  }
+  return { method, headers, body: await bufferBody(body) };
+}
+function toRequestInit(prepared, overrides) {
+  const headers = new Headers(prepared.headers);
+  if (overrides) {
+    new Headers(overrides).forEach((value, name) => headers.set(name, value));
+  }
+  const init = { method: prepared.method, headers };
+  if (prepared.body !== void 0) {
+    init.body = prepared.body;
+  }
+  return init;
+}
+
 // src/internal/payee.ts
 function resolvePayee(manifest, mode) {
   const override = manifest.pricing[mode]?.payee;
@@ -1190,6 +1470,102 @@ function checkChargeChallenge(request, manifest, network, maxAmount) {
   }
   return checkAmount(request["amount"], maxAmount);
 }
+var defaultIo = {
+  async expirationLedger(network, maxTimeoutSeconds) {
+    const { sequence } = await stellar.getRpcClient(network).getLatestLedger();
+    const secondsPerLedger = await stellar.getEstimatedLedgerCloseTimeSeconds(network);
+    return sequence + Math.ceil(maxTimeoutSeconds / secondsPerLedger);
+  },
+  async assemble({ asset, from, payTo, amount, networkPassphrase, rpcUrl }) {
+    return stellarSdk.contract.AssembledTransaction.build({
+      contractId: asset,
+      method: "transfer",
+      // SEP-41: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0041.md#interface
+      args: [
+        stellarSdk.nativeToScVal(from, { type: "address" }),
+        stellarSdk.nativeToScVal(payTo, { type: "address" }),
+        stellarSdk.nativeToScVal(amount, { type: "i128" })
+      ],
+      networkPassphrase,
+      rpcUrl,
+      parseResultXdr: (result) => result
+    });
+  }
+};
+var NulthStellarScheme = class {
+  constructor(signer, io = defaultIo) {
+    this.signer = signer;
+    this.io = io;
+  }
+  signer;
+  io;
+  scheme = "exact";
+  async createPaymentPayload(x402Version, paymentRequirements) {
+    try {
+      this.validateRequirements(paymentRequirements);
+    } catch (err) {
+      throw new Error(
+        `Invalid input parameters for creating Nulth Stellar payment, cause: ${String(err)}`
+      );
+    }
+    const from = this.signer.address;
+    const { network, payTo, asset, amount, maxTimeoutSeconds } = paymentRequirements;
+    if (!paymentRequirements.extra.areFeesSponsored) {
+      throw new Error("Nulth exact scheme requires areFeesSponsored to be true");
+    }
+    const maxLedger = await this.io.expirationLedger(network, maxTimeoutSeconds);
+    const tx = await this.io.assemble({
+      asset,
+      from,
+      payTo,
+      amount,
+      networkPassphrase: stellar.getNetworkPassphrase(network),
+      rpcUrl: stellar.getRpcUrl(network)
+    });
+    stellar.handleSimulationResult(tx.simulation);
+    const signers = tx.needsNonInvokerSigningBy();
+    if (!signers.includes(from) || signers.length > 1) {
+      throw new Error(`Expected to sign with [${from}], but got [${signers.join(", ")}]`);
+    }
+    await tx.signAuthEntries({
+      address: from,
+      signAuthEntry: this.signer.signAuthEntry,
+      expiration: maxLedger,
+      authorizeEntry: nulthSdk.nulthAuthorizeEntry
+    });
+    await tx.simulate();
+    stellar.handleSimulationResult(tx.simulation);
+    const remaining = tx.needsNonInvokerSigningBy();
+    if (remaining.length > 0) {
+      throw new Error(`unexpected signer(s) required: [${remaining.join(", ")}]`);
+    }
+    if (!tx.built) {
+      throw new Error("Nulth payment transaction has no assembled envelope to send");
+    }
+    return { x402Version, payload: { transaction: tx.built.toXDR() } };
+  }
+  validateRequirements(requirements) {
+    const { scheme, network, payTo, asset, amount } = requirements;
+    if (typeof amount !== "string" || !Number.isInteger(Number(amount)) || Number(amount) <= 0) {
+      throw new Error(`Invalid amount: ${amount}. Amount must be a positive integer.`);
+    }
+    if (scheme !== this.scheme) {
+      throw new Error(`Unsupported scheme: ${scheme}`);
+    }
+    if (!stellar.isStellarNetwork(network)) {
+      throw new Error(`Unsupported Stellar network: ${network}`);
+    }
+    if (!stellar.validateStellarDestinationAddress(payTo)) {
+      throw new Error(`Invalid Stellar destination address: ${payTo}`);
+    }
+    if (!stellar.validateStellarAssetAddress(asset)) {
+      throw new Error(`Invalid Stellar asset address: ${asset}`);
+    }
+  }
+};
+function selectStellarScheme(signer) {
+  return nulthSdk.isNulthStellarSigner(signer) ? new NulthStellarScheme(signer) : new stellar.ExactStellarScheme(signer);
+}
 
 // src/client/x402Client.ts
 var CAIP2 = {
@@ -1197,25 +1573,29 @@ var CAIP2 = {
   mainnet: "stellar:pubnet"
 };
 var X402Client = class _X402Client {
-  constructor(secretKeyOrSigner, network, retryPolicy) {
+  constructor(secretKeyOrSigner, network, retryPolicy, preSignHook, logger) {
     this.network = network;
     this.retryPolicy = retryPolicy;
+    this.preSignHook = preSignHook;
     const caip2 = CAIP2[network];
     this.signer = typeof secretKeyOrSigner === "string" ? stellar.createEd25519Signer(secretKeyOrSigner, caip2) : secretKeyOrSigner;
-    const scheme = new client.ExactStellarScheme(this.signer);
-    const core = new client$1.x402Client();
+    const scheme = selectStellarScheme(this.signer);
+    const core = new client.x402Client();
     core.register(caip2, scheme);
-    this.httpClient = new client$1.x402HTTPClient(core);
+    this.httpClient = new client.x402HTTPClient(core);
+    this.logger = logger;
   }
   network;
   retryPolicy;
+  preSignHook;
   httpClient;
   signer;
+  logger;
   /** Replace signer (e.g. swap to Nulth ZK account payer before pay) */
   withSigner(signer) {
-    return new _X402Client(signer, this.network, this.retryPolicy);
+    return new _X402Client(signer, this.network, this.retryPolicy, this.preSignHook, this.logger);
   }
-  async pay(url, manifest) {
+  async pay(url, manifest, request) {
     const pricing = manifest.pricing.x402;
     if (!pricing) {
       throw new RouteDockManifestError("manifest.pricing.x402 missing");
@@ -1224,13 +1604,15 @@ var X402Client = class _X402Client {
       throw new RouteDockManifestError("manifest.pricing.x402.facilitator missing");
     }
     const caip2 = CAIP2[this.network];
+    const prepared = await prepareRequest(request);
     const probe = await withRetry(async () => {
       let init2;
       try {
-        init2 = await fetch(url, { headers: { "X-Preferred-Mode": "x402" } });
+        init2 = await fetch(url, toRequestInit(prepared, { "X-Preferred-Mode": "x402" }));
       } catch (err) {
         throw wrapFetchError(err, "x402 initial request");
       }
+      this.logger?.("debug", "[x402] unpaid probe response", { status: init2.status });
       if (init2.status !== 402) {
         if (!init2.ok) {
           throw httpStatusToError(
@@ -1247,6 +1629,11 @@ var X402Client = class _X402Client {
             `Failed to parse JSON from non-402 response (HTTP ${init2.status})`
           );
         }
+        this.logger?.(
+          "debug",
+          "[x402] unpaid probe returned non-402 success \u2014 serving as free response",
+          { status: init2.status }
+        );
         return { kind: "free", data: data2 };
       }
       return { kind: "payment-required", init: init2 };
@@ -1275,6 +1662,18 @@ var X402Client = class _X402Client {
     if (allowed.length === 0) {
       throw checkX402Accept(firstAccept, manifest, caip2, pricing.amount);
     }
+    if (this.preSignHook) {
+      let decision;
+      try {
+        decision = await this.preSignHook({ url, manifest, accepts: allowed });
+      } catch (err) {
+        throw new RouteDockPolicyRejectError("pre_sign_hook_error", { cause: err });
+      }
+      if (!decision || decision.approve !== true) {
+        const reason = decision && decision.approve === false ? decision.reason : void 0;
+        throw new RouteDockPolicyRejectError(reason ?? "pre_sign_rejected");
+      }
+    }
     let paymentPayload;
     try {
       paymentPayload = await this.httpClient.createPaymentPayload({
@@ -1288,13 +1687,15 @@ var X402Client = class _X402Client {
     }
     const paymentHeaders = this.httpClient.encodePaymentSignatureHeader(paymentPayload);
     const signedAmount = nulthSdk.stroopsToUsdc(BigInt(paymentPayload.accepted.amount));
+    this.logger?.("debug", "[x402] sending paid request with payment header");
     const settled = await withRetry(async () => {
       let response;
       try {
-        response = await fetch(url, { headers: paymentHeaders });
+        response = await fetch(url, toRequestInit(prepared, paymentHeaders));
       } catch (err) {
         throw wrapFetchError(err, "x402 settlement request");
       }
+      this.logger?.("debug", "[x402] paid request response", { status: response.status });
       if (!response.ok) {
         if (response.status >= 500 || response.status === 429 || response.status === 503) {
           throw httpStatusToError(
@@ -1303,17 +1704,28 @@ var X402Client = class _X402Client {
             response
           );
         }
-        throw new RouteDockManifestError(`x402 payment failed: HTTP ${response.status}`);
+        throw await paymentRejectedError("x402 payment failed", response.status, response);
       }
       return response;
     }, this.retryPolicy);
     let txHash = null;
     const responseHeader = settled.headers.get("X-Payment-Response");
-    if (responseHeader) {
+    if (!responseHeader) {
+      this.logger?.("debug", "[x402] settled 2xx carried no X-Payment-Response header");
+    } else {
       try {
-        const settleResponse = http.decodePaymentResponseHeader(responseHeader);
-        txHash = settleResponse.transaction ?? null;
-      } catch {
+        const outcome = readSettleResult(http.decodePaymentResponseHeader(responseHeader));
+        if (outcome.ok) {
+          txHash = outcome.txHash;
+        } else {
+          this.logger?.("debug", "[x402] X-Payment-Response reports an unsettled payment", {
+            ...outcome.reason !== void 0 ? { reason: outcome.reason } : {}
+          });
+        }
+      } catch (err) {
+        this.logger?.("debug", "[x402] X-Payment-Response header present but undecodable", {
+          error: err
+        });
       }
     }
     let data;
@@ -1334,33 +1746,28 @@ var MppChargeClient = class {
   keypair;
   network;
   retryPolicy;
-  async pay(url, manifest) {
+  async pay(url, manifest, request) {
     const pricing = manifest.pricing["mpp-charge"];
     if (!pricing) {
       throw new RouteDockManifestError("manifest.pricing.mpp-charge missing");
     }
     const caip2 = this.network === "mainnet" ? "stellar:pubnet" : "stellar:testnet";
-    let txHash = null;
+    const prepared = await prepareRequest(request);
     let signedAmount;
     let credential;
-    const mppx = client$2.Mppx.create({
+    const mppx = client$1.Mppx.create({
       polyfill: false,
       methods: [
-        client$3.stellar.charge({
+        client$2.stellar.charge({
           keypair: this.keypair,
-          mode: "pull",
-          onProgress(event) {
-            if (event.type === "paid") {
-              txHash = event.hash;
-            }
-          }
+          mode: "pull"
         })
       ],
       onChallenge: async (challenge, { createCredential }) => {
-        const request = challenge.request;
-        const rejection = checkChargeChallenge(request, manifest, caip2, pricing.amount);
+        const request2 = challenge.request;
+        const rejection = checkChargeChallenge(request2, manifest, caip2, pricing.amount);
         if (rejection) throw rejection;
-        const amount = request["amount"];
+        const amount = request2["amount"];
         if (typeof amount !== "string") {
           throw new RouteDockPolicyRejectError("challenge_amount_invalid");
         }
@@ -1372,7 +1779,7 @@ var MppChargeClient = class {
     return withRetry(async () => {
       let response;
       try {
-        response = credential ? await mppx.rawFetch(url, { headers: { Authorization: credential } }) : await mppx.fetch(url);
+        response = credential ? await mppx.rawFetch(url, toRequestInit(prepared, { Authorization: credential })) : await mppx.fetch(url, toRequestInit(prepared));
       } catch (err) {
         throw wrapMppError(err, "MPP charge request");
       }
@@ -1384,8 +1791,9 @@ var MppChargeClient = class {
             response
           );
         }
-        throw new RouteDockManifestError(`MPP charge failed: HTTP ${response.status}`);
+        throw await paymentRejectedError("MPP charge failed", response.status, response);
       }
+      const txHash = readSettlementHash(response);
       let data;
       try {
         data = await response.json();
@@ -1405,8 +1813,40 @@ var MppChargeClient = class {
     }, this.retryPolicy);
   }
 };
+function readSettlementHash(response) {
+  try {
+    return mppx.Receipt.fromResponse(response).reference;
+  } catch {
+    return null;
+  }
+}
 var MIN_REFUND_WAITING_PERIOD = 17280;
 var STREAM_CLEANUP_TIMEOUT_MS = 3e3;
+var TX_CONFIRM_INTERVAL_MS = 1e3;
+var TX_CONFIRM_TIMEOUT_MS = 3e4;
+async function confirmTransaction(server, hash, label, timeoutMs = TX_CONFIRM_TIMEOUT_MS, intervalMs = TX_CONFIRM_INTERVAL_MS) {
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    const txResponse = await server.getTransaction(hash);
+    const status = txResponse?.status;
+    if (status === "SUCCESS") {
+      return hash;
+    }
+    if (status === "FAILED") {
+      throw new RouteDockDisputeError(
+        `${label} transaction failed on-chain: status FAILED (resultXdr: ${txResponse.resultXdr.toXDR("base64")})`
+      );
+    }
+    if (Date.now() >= deadline) {
+      break;
+    }
+    const remaining = deadline - Date.now();
+    await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, Math.max(1, remaining))));
+  }
+  throw new RouteDockDisputeError(
+    `${label} transaction confirmation timed out after ${timeoutMs}ms (hash: ${hash})`
+  );
+}
 var WS_CONNECTING = 0;
 var WS_OPEN = 1;
 function defaultWebSocketFactory(url, init, handlers) {
@@ -1420,9 +1860,9 @@ function defaultWebSocketFactory(url, init, handlers) {
     if (typeof data === "string") {
       handlers.onMessage(data);
     } else if (data instanceof ArrayBuffer) {
-      handlers.onMessage(Buffer.from(data).toString("utf8"));
+      handlers.onMessage(bytesToUtf8(new Uint8Array(data)));
     } else {
-      void data.arrayBuffer().then((buffer) => handlers.onMessage(Buffer.from(buffer).toString("utf8"))).catch(() => {
+      void data.arrayBuffer().then((buffer) => handlers.onMessage(bytesToUtf8(new Uint8Array(buffer)))).catch(() => {
       });
     }
   };
@@ -1575,11 +2015,11 @@ var MppSessionClient = class {
         throw err;
       }
     };
-    const streamWs = (u, m, createCredential, onSigned) => this.streamWebSocket(u, m, createCredential, onSigned);
-    const mppx = client$2.Mppx.create({
+    const streamWs = (u, m, createCredential, onSigned, request) => this.streamWebSocket(u, m, createCredential, onSigned, request);
+    const mppx = client$1.Mppx.create({
       polyfill: false,
       methods: [
-        client$4.stellar.channel({
+        client$3.stellar.channel({
           commitmentKey,
           sourceAccount: this.keypair.publicKey(),
           ...store ? { store } : {},
@@ -1647,6 +2087,7 @@ var MppSessionClient = class {
         };
       },
       async *stream(options2) {
+        const prepared = await prepareRequest(options2?.request);
         const checkSpend = () => {
           if (!onSpend) return Promise.resolve();
           return onSpend(pricing.rate);
@@ -1656,7 +2097,13 @@ var MppSessionClient = class {
           const onSigned = () => {
             vouchersIssued++;
           };
-          for await (const item of streamWs(url, mppx, createGuardedCredential, onSigned)) {
+          for await (const item of streamWs(
+            url,
+            mppx,
+            createGuardedCredential,
+            onSigned,
+            prepared
+          )) {
             yield item;
           }
           return;
@@ -1671,7 +2118,10 @@ var MppSessionClient = class {
         const doFetch = () => withRetry(async () => {
           let resp;
           try {
-            resp = await mppx.fetch(url, { signal: abortController.signal });
+            resp = await mppx.fetch(url, {
+              ...toRequestInit(prepared),
+              signal: abortController.signal
+            });
           } catch (err) {
             if (abortController.signal.aborted) {
               throw err;
@@ -1756,10 +2206,10 @@ var MppSessionClient = class {
       async close() {
         clearSessionTimer();
         closed = true;
-        const { rpc: rpcMod, Contract: Contract2, nativeToScVal: nativeToScVal2, TransactionBuilder: TransactionBuilder2, BASE_FEE: BASE_FEE2 } = await import('@stellar/stellar-sdk');
+        const { rpc: rpcMod, Contract: Contract2, nativeToScVal: nativeToScVal3, TransactionBuilder: TransactionBuilder2, BASE_FEE: BASE_FEE2 } = await import('@stellar/stellar-sdk');
         const rpcUrl = network === "testnet" ? "https://soroban-testnet.stellar.org" : "https://soroban.stellar.org";
         const server = new rpcMod.Server(rpcUrl);
-        const contract = new Contract2(channelFactory);
+        const contract2 = new Contract2(channelFactory);
         const passphrase = network === "mainnet" ? stellarSdk.Networks.PUBLIC : stellarSdk.Networks.TESTNET;
         const account = await withRetry(async () => {
           try {
@@ -1774,9 +2224,9 @@ var MppSessionClient = class {
               fee: BASE_FEE2,
               networkPassphrase: passphrase
             }).addOperation(
-              contract.call(
+              contract2.call(
                 "prepare_commitment",
-                nativeToScVal2(currentCumulative, { type: "i128" })
+                nativeToScVal3(currentCumulative, { type: "i128" })
               )
             ).setTimeout(30).build();
             return await server.simulateTransaction(simTx);
@@ -1795,7 +2245,7 @@ var MppSessionClient = class {
         }
         let signature;
         try {
-          signature = commitmentKey.sign(Buffer.from(commitmentBytes));
+          signature = commitmentKey.sign(commitmentBytes);
         } catch (err) {
           throw new RouteDockSignatureError("Channel close commitment signing failed", {
             cause: err
@@ -1809,7 +2259,7 @@ var MppSessionClient = class {
               headers: { "Content-Type": "application/json" },
               body: JSON.stringify({
                 amount: currentCumulative.toString(),
-                signature: Buffer.from(signature).toString("hex")
+                signature: bytesToHex(signature)
               })
             });
           } catch (err) {
@@ -1851,15 +2301,19 @@ var MppSessionClient = class {
           vouchersIssued
         };
       },
-      async requestRefund() {
+      /**
+       * Request refund from the channel contract (initiates dispute).
+       * Returns the transaction hash only after on-chain confirmation (SUCCESS).
+       */
+      async requestRefund(options2) {
         const { rpc: rpcMod, Contract: Contract2, TransactionBuilder: TransactionBuilder2, BASE_FEE: BASE_FEE2 } = await import('@stellar/stellar-sdk');
         const rpcUrl = network === "testnet" ? "https://soroban-testnet.stellar.org" : "https://soroban.stellar.org";
         const server = new rpcMod.Server(rpcUrl);
-        const contract = new Contract2(channelFactory);
+        const contract2 = new Contract2(channelFactory);
         const passphrase = network === "mainnet" ? stellarSdk.Networks.PUBLIC : stellarSdk.Networks.TESTNET;
         try {
           const account = await server.getAccount(agentPublicKey);
-          const tx = new TransactionBuilder2(account, { fee: BASE_FEE2, networkPassphrase: passphrase }).addOperation(contract.call("request_refund")).setTimeout(30).build();
+          const tx = new TransactionBuilder2(account, { fee: BASE_FEE2, networkPassphrase: passphrase }).addOperation(contract2.call("request_refund")).setTimeout(30).build();
           const simResult = await server.simulateTransaction(tx);
           if (rpcMod.Api.isSimulationError(simResult)) {
             throw new RouteDockDisputeError(`request_refund simulation failed: ${simResult.error}`);
@@ -1871,37 +2325,50 @@ var MppSessionClient = class {
             const errDetail = result.errorResult ? JSON.stringify(result.errorResult) : "status ERROR";
             throw new RouteDockDisputeError(`Refund request transaction failed: ${errDetail}`);
           }
+          if (result.status === "TRY_AGAIN_LATER") {
+            throw new RouteDockDisputeError("Refund request transaction rejected with TRY_AGAIN_LATER: transaction not queued");
+          }
           if (!result.hash) {
             throw new RouteDockDisputeError("Refund request transaction not sent");
           }
-          return result.hash;
+          return await confirmTransaction(
+            server,
+            result.hash,
+            "Refund request",
+            options2?.timeoutMs,
+            options2?.intervalMs
+          );
         } catch (err) {
           if (err instanceof RouteDockDisputeError) throw err;
           throw new RouteDockDisputeError(`Failed to request refund: ${err instanceof Error ? err.message : String(err)}`);
         }
       },
-      async settleWithLatestVoucher() {
-        const { rpc: rpcMod, Contract: Contract2, nativeToScVal: nativeToScVal2, TransactionBuilder: TransactionBuilder2, BASE_FEE: BASE_FEE2 } = await import('@stellar/stellar-sdk');
+      /**
+       * Server-side counter-mechanism to settle with latest voucher before refund window expires.
+       * Returns the transaction hash only after on-chain confirmation (SUCCESS).
+       */
+      async settleWithLatestVoucher(options2) {
+        const { rpc: rpcMod, Contract: Contract2, nativeToScVal: nativeToScVal3, TransactionBuilder: TransactionBuilder2, BASE_FEE: BASE_FEE2 } = await import('@stellar/stellar-sdk');
         const rpcUrl = network === "testnet" ? "https://soroban-testnet.stellar.org" : "https://soroban.stellar.org";
         const server = new rpcMod.Server(rpcUrl);
-        const contract = new Contract2(channelFactory);
+        const contract2 = new Contract2(channelFactory);
         const passphrase = network === "mainnet" ? stellarSdk.Networks.PUBLIC : stellarSdk.Networks.TESTNET;
         try {
           const account = await server.getAccount(agentPublicKey);
-          const simTx = new TransactionBuilder2(account, { fee: BASE_FEE2, networkPassphrase: passphrase }).addOperation(contract.call("prepare_commitment", nativeToScVal2(currentCumulative, { type: "i128" }))).setTimeout(30).build();
+          const simTx = new TransactionBuilder2(account, { fee: BASE_FEE2, networkPassphrase: passphrase }).addOperation(contract2.call("prepare_commitment", nativeToScVal3(currentCumulative, { type: "i128" }))).setTimeout(30).build();
           const simResult = await server.simulateTransaction(simTx);
           if (rpcMod.Api.isSimulationError(simResult)) {
             throw new RouteDockDisputeError(`prepare_commitment simulation failed: ${simResult.error}`);
           }
           const commitmentBytes = simResult.result?.retval?.bytes();
           if (!commitmentBytes) throw new RouteDockDisputeError("prepare_commitment returned no bytes");
-          const signature = commitmentKey.sign(Buffer.from(commitmentBytes));
+          const signature = commitmentKey.sign(commitmentBytes);
           const settleAccount = await server.getAccount(agentPublicKey);
           const settleTx = new TransactionBuilder2(settleAccount, { fee: BASE_FEE2, networkPassphrase: passphrase }).addOperation(
-            contract.call(
+            contract2.call(
               "settle_with_signature",
-              nativeToScVal2(currentCumulative, { type: "i128" }),
-              nativeToScVal2(Buffer.from(signature))
+              nativeToScVal3(currentCumulative, { type: "i128" }),
+              nativeToScVal3(signature)
             )
           ).setTimeout(30).build();
           const preparedSettleTx = await server.prepareTransaction(settleTx);
@@ -1911,10 +2378,19 @@ var MppSessionClient = class {
             const errDetail = settleResult.errorResult ? JSON.stringify(settleResult.errorResult) : "status ERROR";
             throw new RouteDockDisputeError(`Settlement transaction failed: ${errDetail}`);
           }
+          if (settleResult.status === "TRY_AGAIN_LATER") {
+            throw new RouteDockDisputeError("Settlement transaction rejected with TRY_AGAIN_LATER: transaction not queued");
+          }
           if (!settleResult.hash) {
             throw new RouteDockDisputeError("Settlement transaction not sent");
           }
-          return settleResult.hash;
+          return await confirmTransaction(
+            server,
+            settleResult.hash,
+            "Settlement",
+            options2?.timeoutMs,
+            options2?.intervalMs
+          );
         } catch (err) {
           if (err instanceof RouteDockDisputeError) throw err;
           throw new RouteDockDisputeError(`Failed to settle with latest voucher: ${err instanceof Error ? err.message : String(err)}`);
@@ -1924,11 +2400,11 @@ var MppSessionClient = class {
         const { rpc: rpcMod, Contract: Contract2, TransactionBuilder: TransactionBuilder2, BASE_FEE: BASE_FEE2 } = await import('@stellar/stellar-sdk');
         const rpcUrl = network === "testnet" ? "https://soroban-testnet.stellar.org" : "https://soroban.stellar.org";
         const server = new rpcMod.Server(rpcUrl);
-        const contract = new Contract2(channelFactory);
+        const contract2 = new Contract2(channelFactory);
         const passphrase = network === "mainnet" ? stellarSdk.Networks.PUBLIC : stellarSdk.Networks.TESTNET;
         try {
           const account = await server.getAccount(agentPublicKey);
-          const tx = new TransactionBuilder2(account, { fee: BASE_FEE2, networkPassphrase: passphrase }).addOperation(contract.call("get_channel_state")).setTimeout(30).build();
+          const tx = new TransactionBuilder2(account, { fee: BASE_FEE2, networkPassphrase: passphrase }).addOperation(contract2.call("get_channel_state")).setTimeout(30).build();
           const simResult = await server.simulateTransaction(tx);
           if (rpcMod.Api.isSimulationError(simResult)) {
             throw new RouteDockChannelStateError(`Failed to query channel state: ${simResult.error}`);
@@ -1994,11 +2470,11 @@ var MppSessionClient = class {
    * close code (1000/1001); abnormal closes and connection failures surface as
    * RouteDockChannelStateError.
    */
-  async *streamWebSocket(url, mppx$1, createCredential, onSigned) {
-    const request = { method: "GET" };
+  async *streamWebSocket(url, mppx$1, createCredential, onSigned, request) {
+    const probeInit = toRequestInit(request);
     let probe;
     try {
-      probe = await mppx$1.rawFetch(url, request);
+      probe = await mppx$1.rawFetch(url, probeInit);
     } catch (err) {
       throw wrapFetchError(err, "Voucher request");
     }
@@ -2102,235 +2578,19 @@ var MppSessionClient = class {
     }
   }
 };
-var NulthPolicyError = class extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "NulthPolicyError";
-    this.code = code;
-  }
-};
-function sha256Hex(data) {
-  const buf = typeof data === "string" ? Buffer.from(data, "utf8") : data;
-  return crypto$1.createHash("sha256").update(buf).digest("hex");
-}
-function commitDailyCap(dailyCapStroops, witnessSecret) {
-  return sha256Hex(`${witnessSecret}:cap:${dailyCapStroops.toString()}`);
-}
-function commitAllowlist(payees, witnessSecret) {
-  const sorted = [...payees].sort().join(",");
-  return sha256Hex(`${witnessSecret}:allowlist:${sorted}`);
-}
-function hashPayee(payee) {
-  return sha256Hex(`payee:${payee}`);
-}
-function dayBucketFromLedger(ledgerSequence) {
-  return Math.floor(ledgerSequence / 17280);
-}
-function authDigestFromEntry(authEntryBase64) {
-  const entryHash = stellarSdk.hash(Buffer.from(authEntryBase64, "base64"));
-  return sha256Hex(entryHash);
-}
-function assertAuthEntryMatchesContext(authEntry, from, ctx) {
-  let preimage;
+function createNulthSigner(config) {
+  const sharedConfig = { ...config, logger: resolveLogger(config.logger) };
+  Object.defineProperty(sharedConfig, "paymentContext", {
+    get: () => config.paymentContext
+  });
   try {
-    preimage = stellarSdk.xdr.HashIdPreimage.fromXDR(authEntry, "base64");
-  } catch {
-    throw new NulthPolicyError("auth_entry_mismatch", "authEntry does not decode as a HashIdPreimage");
-  }
-  if (preimage.switch() !== stellarSdk.xdr.EnvelopeType.envelopeTypeSorobanAuthorization()) {
-    throw new NulthPolicyError(
-      "auth_entry_mismatch",
-      "authEntry is not a Soroban authorization preimage"
-    );
-  }
-  const inv = preimage.sorobanAuthorization().invocation();
-  if (inv.subInvocations().length !== 0) {
-    throw new NulthPolicyError("auth_entry_mismatch", "authEntry has unexpected sub-invocations");
-  }
-  if (inv.function().switch() !== stellarSdk.xdr.SorobanAuthorizedFunctionType.sorobanAuthorizedFunctionTypeContractFn()) {
-    throw new NulthPolicyError("auth_entry_mismatch", "authEntry does not invoke a contract function");
-  }
-  const fn = inv.function().contractFn();
-  const contractAddress = stellarSdk.Address.fromScAddress(fn.contractAddress()).toString();
-  if (contractAddress !== ctx.assetContract) {
-    throw new NulthPolicyError(
-      "auth_entry_mismatch",
-      `authEntry contract ${contractAddress} does not match assetContract ${ctx.assetContract}`
-    );
-  }
-  const functionName = fn.functionName().toString();
-  if (functionName !== "transfer") {
-    throw new NulthPolicyError(
-      "auth_entry_mismatch",
-      `authEntry function ${functionName} does not match expected transfer`
-    );
-  }
-  const args = fn.args();
-  if (args.length !== 3) {
-    throw new NulthPolicyError("auth_entry_mismatch", `authEntry transfer has ${args.length} args, expected 3`);
-  }
-  const entryFrom = stellarSdk.scValToNative(args[0]);
-  if (entryFrom !== from) {
-    throw new NulthPolicyError(
-      "auth_entry_mismatch",
-      `authEntry from ${entryFrom} does not match nulthAccount ${from}`
-    );
-  }
-  const entryTo = stellarSdk.scValToNative(args[1]);
-  if (entryTo !== ctx.payee) {
-    throw new NulthPolicyError(
-      "auth_entry_mismatch",
-      `authEntry to ${entryTo} does not match paymentContext.payee ${ctx.payee}`
-    );
-  }
-  const entryAmount = stellarSdk.scValToNative(args[2]);
-  if (entryAmount !== ctx.amountStroops) {
-    throw new NulthPolicyError(
-      "auth_entry_mismatch",
-      `authEntry amount ${entryAmount} does not match paymentContext.amountStroops ${ctx.amountStroops}`
-    );
-  }
-}
-function insecureMockProof(preimage) {
-  return crypto$1.createHash("sha512").update(`nulth:${preimage}`).digest("base64");
-}
-function encodeAuthSignature(proof) {
-  const payload = { nulth: "zk-v1", proof };
-  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
-}
-function usdcToStroops2(amount) {
-  const [whole = "0", frac = ""] = amount.split(".");
-  const padded = (frac + "0000000").slice(0, 7);
-  return BigInt(whole) * 10000000n + BigInt(padded);
-}
-var NulthClient = class {
-  constructor(config) {
-    this.config = config;
-    this.policy = { ...config.policy };
-    this.prover = config.prover ?? "mock";
-    if (this.prover !== "mock") {
-      throw new RouteDockManifestError(
-        `NulthClient: unknown prover backend ${String(config.prover)}; only 'mock' is implemented`
-      );
-    }
-    if (config.network !== "testnet") {
-      throw new RouteDockManifestError(
-        `NulthClient cannot use the insecure mock prover on mainnet; a production prover is required (network must be 'testnet', got ${String(config.network)})`
-      );
-    }
-    resolveLogger(config.logger)(
-      "warn",
-      "NulthClient is using the insecure mock prover; proofs are not cryptographically sound"
-    );
-  }
-  config;
-  policy;
-  prover;
-  get proverBackend() {
-    return this.prover;
-  }
-  get nulthAccount() {
-    return this.config.nulthAccount;
-  }
-  get allowlistCommitment() {
-    return this.policy.allowlistCommitment;
-  }
-  get capCommitment() {
-    return commitDailyCap(this.policy.dailyCapStroops, this.policy.witnessSecret);
-  }
-  buildPaymentAuthProof(context) {
-    this.enforcePolicy(context);
-    const bucket = dayBucketFromLedger(context.ledgerSequence);
-    if (bucket !== this.policy.dayBucket) {
-      this.policy.dayBucket = bucket;
-      this.policy.dailySpendStroops = 0n;
-    }
-    const authDigest = authDigestFromEntry(context.authEntry);
-    const capCommitment = this.capCommitment;
-    const payeeHash = hashPayee(context.payee);
-    const preimage = [
-      authDigest,
-      this.policy.allowlistCommitment,
-      capCommitment,
-      payeeHash,
-      context.amountStroops.toString(),
-      bucket.toString(),
-      this.config.nulthAccount
-    ].join("|");
-    const proof = {
-      version: 1,
-      proof: insecureMockProof(preimage),
-      publicInputs: {
-        authDigest,
-        allowlistCommitment: this.policy.allowlistCommitment,
-        capCommitment,
-        payeeHash,
-        amountStroops: context.amountStroops.toString(),
-        dayBucket: bucket.toString()
-      }
-    };
-    this.policy.dailySpendStroops += context.amountStroops;
-    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");
-    }
-    if (!this.policy.allowedPayees.includes(context.payee)) {
-      throw new NulthPolicyError("payee_not_allowed", `Payee ${context.payee} not in off-chain allowlist`);
-    }
-    const bucket = dayBucketFromLedger(context.ledgerSequence);
-    const spend = bucket === this.policy.dayBucket ? this.policy.dailySpendStroops : 0n;
-    if (spend + context.amountStroops > this.policy.dailyCapStroops) {
-      throw new NulthPolicyError("daily_cap_exceeded", "Nulth daily cap exceeded");
+    return nulthSdk.createNulthSigner(sharedConfig);
+  } catch (error) {
+    if (error instanceof nulthSdk.NulthConfigError) {
+      throw new RouteDockManifestError(error.message, { cause: error });
     }
+    throw error;
   }
-};
-function createNulthSigner(config) {
-  const client = new NulthClient(config);
-  const nulthAccount = config.nulthAccount;
-  return {
-    address: nulthAccount,
-    signAuthEntry: async (authEntry) => {
-      const ctx = config.paymentContext;
-      if (!ctx) throw new Error("Nulth paymentContext must be set before signing");
-      assertAuthEntryMatchesContext(authEntry, nulthAccount, ctx);
-      const proof = client.buildPaymentAuthProof({ authEntry, ...ctx });
-      return { signedAuthEntry: encodeAuthSignature(proof), signerAddress: nulthAccount };
-    }
-  };
-}
-function setNulthPaymentContext(config, context) {
-  config.paymentContext = context;
-}
-function paymentContextFromManifest(manifest, mode, ledgerSequence) {
-  const pricing = manifest.pricing[mode];
-  if (!pricing) throw new Error(`manifest.pricing.${mode} missing`);
-  return {
-    payee: manifest.payee,
-    amountStroops: usdcToStroops2(pricing.amount),
-    assetContract: manifest.asset_contract,
-    ledgerSequence
-  };
-}
-function createPolicyState(input) {
-  const dailyCapStroops = usdcToStroops2(input.dailyCapUsdc);
-  return {
-    dailyCapStroops,
-    allowlistCommitment: commitAllowlist(input.allowedPayees, input.witnessSecret),
-    allowedPayees: input.allowedPayees,
-    dailySpendStroops: 0n,
-    dayBucket: dayBucketFromLedger(input.ledgerSequence ?? 0),
-    witnessSecret: input.witnessSecret,
-    ...input.expiryLedger !== void 0 ? { expiryLedger: input.expiryLedger } : {}
-  };
 }
 function assertNulthVaultManifest(manifest, nulthAccount) {
   if (manifest.vault !== void 0 && manifest.vault !== "nulth") {
@@ -2354,69 +2614,29 @@ async function prepareNulthSigner(vault, manifest, mode, network, ledgerSequence
       "nulth vault uses the insecure mock prover and cannot be used on mainnet"
     );
   }
-  const ledgerSequence = ledgerSequenceOverride ?? await fetchLedgerSequence(network);
-  const policy = createPolicyState({
-    dailyCapUsdc: vault.dailyCapUsdc,
-    allowedPayees: vault.allowedPayees,
-    witnessSecret: vault.witnessSecret,
-    ledgerSequence,
-    ...vault.expiryLedger !== void 0 ? { expiryLedger: vault.expiryLedger } : {}
-  });
-  const config = {
-    nulthAccount: vault.nulthAccount,
-    network,
-    prover,
-    policy,
-    ...vault.verifierContract !== void 0 ? { verifierContract: vault.verifierContract } : {}
-  };
-  if (mode === "x402" || mode === "mpp-charge") {
-    setNulthPaymentContext(config, paymentContextFromManifest(manifest, mode, ledgerSequence));
-  } else {
-    throw new RouteDockManifestError(`Nulth ZK vault does not support payment mode: ${mode}`);
-  }
-  const signer = createNulthSigner(config);
-  return { signer, config };
-}
-function decodeAuthSignature(encoded) {
-  const raw = JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
-  if (typeof raw !== "object" || raw === null || raw.nulth !== "zk-v1") {
-    throw new Error("Invalid Nulth ZK auth signature");
-  }
-  return raw;
-}
-var FileSpendStore = class {
-  filePath;
-  constructor(filePath) {
-    this.filePath = filePath;
-  }
-  async read() {
-    let data;
-    try {
-      data = await fs__default.default.readFile(this.filePath, "utf-8");
-    } catch (err) {
-      if (err.code === "ENOENT") {
-        return null;
-      }
-      throw new Error(
-        `[FileSpendStore] Failed to read spend file at ${this.filePath}: ${err.message}`
-      );
-    }
-    try {
-      return JSON.parse(data);
-    } catch {
-      throw new Error(
-        `[FileSpendStore] Spend file at ${this.filePath} contains invalid JSON. Delete or repair it before resuming. Raw content: ${data.slice(0, 120)}`
-      );
-    }
-  }
-  async write(state) {
-    const dir = path__default.default.dirname(this.filePath);
-    await fs__default.default.mkdir(dir, { recursive: true });
-    const tmpPath = `${this.filePath}.tmp`;
-    await fs__default.default.writeFile(tmpPath, JSON.stringify(state, null, 2), "utf-8");
-    await fs__default.default.rename(tmpPath, this.filePath);
+  const ledgerSequence = ledgerSequenceOverride ?? await fetchLedgerSequence(network);
+  const policy = nulthSdk.createPolicyState({
+    dailyCapUsdc: vault.dailyCapUsdc,
+    allowedPayees: vault.allowedPayees,
+    witnessSecret: vault.witnessSecret,
+    ledgerSequence,
+    ...vault.expiryLedger !== void 0 ? { expiryLedger: vault.expiryLedger } : {}
+  });
+  const config = {
+    nulthAccount: vault.nulthAccount,
+    network,
+    prover,
+    policy,
+    ...vault.verifierContract !== void 0 ? { verifierContract: vault.verifierContract } : {}
+  };
+  if (mode === "x402" || mode === "mpp-charge") {
+    nulthSdk.setNulthPaymentContext(config, nulthSdk.paymentContextFromManifest(manifest, mode, ledgerSequence));
+  } else {
+    throw new RouteDockManifestError(`Nulth ZK vault does not support payment mode: ${mode}`);
   }
-};
+  const signer = createNulthSigner(config);
+  return { signer, config };
+}
 
 // src/store/SpendStore.ts
 var InMemorySpendStore = class {
@@ -2530,7 +2750,7 @@ var RouteDockClient = class _RouteDockClient {
     }
     const secretKey = this.keypair.secret();
     const retryPolicy = this.logger ? { ...this.retryPolicy, logger: this.logger } : this.retryPolicy;
-    this.x402 = new X402Client(secretKey, this.network, retryPolicy);
+    this.x402 = new X402Client(secretKey, this.network, retryPolicy, config.preSignHook, this.logger);
     this.charge = new MppChargeClient(this.keypair, this.network, retryPolicy);
     this.session = new MppSessionClient(this.keypair, this.network, retryPolicy, void 0, this.logger);
   }
@@ -2538,7 +2758,7 @@ var RouteDockClient = class _RouteDockClient {
   async _resolveManifest(url, options) {
     const baseUrl = new URL(url).origin;
     const manifest = await fetchManifest(baseUrl, this.retryPolicy, this.manifestTimeoutMs, this.expectedPayee);
-    assertEndpointActive(manifest, url, this.logger);
+    assertEndpointActive(manifest, url, this.logger, options?.request?.method);
     const mode = selectMode(manifest, options);
     return { manifest, mode };
   }
@@ -2555,13 +2775,9 @@ var RouteDockClient = class _RouteDockClient {
     });
     return next;
   }
-  /**
-   * Check that the payer has a trustline for the payment asset and surface
-   * manifest metadata (regions, latency hints, capabilities). Safe to
-   * call before committing to a payment — for approval gates and manual
-   * trustline remediation.
-   */
-  async preflight(manifest, mode, endpoint) {
+  async preflight(target, mode, endpoint) {
+    if (typeof target === "string") return this._preflightUrl(target);
+    const manifest = target;
     assertManifestValid(manifest);
     const selectedAsset = mode ? selectAsset(manifest, mode, endpoint).asset : manifest.asset;
     await this._checkTrustline(manifest, selectedAsset);
@@ -2574,6 +2790,42 @@ var RouteDockClient = class _RouteDockClient {
       ...manifest.capabilities && { capabilities: manifest.capabilities }
     };
   }
+  /** Manifest-only preflight for a URL — no trustline check, no payment. */
+  async _preflightUrl(url) {
+    const baseUrl = new URL(url).origin;
+    const manifest = await fetchManifest(baseUrl, this.retryPolicy, this.manifestTimeoutMs, this.expectedPayee);
+    assertEndpointActive(manifest, url);
+    const costs = manifest.modes.map((mode) => {
+      const asset = selectAsset(manifest, mode, url).asset;
+      switch (mode) {
+        case "x402":
+        case "mpp-charge": {
+          const pricing = manifest.pricing[mode];
+          return { mode, amount: pricing.amount, per: "request", asset };
+        }
+        case "mpp-session":
+        case "mpp-session-ws": {
+          const pricing = manifest.pricing[mode];
+          return { mode, amount: pricing.rate, per: "voucher", asset, min_deposit: pricing.min_deposit };
+        }
+        default:
+          throw new RouteDockManifestError(`Unknown payment mode: ${mode}`);
+      }
+    });
+    const pathname = new URL(url).pathname;
+    const matches = Object.values(manifest.endpoints).filter((descriptor) => descriptor.path === pathname);
+    const endpointSunsets = matches.map((descriptor) => descriptor.sunset_at).filter((value) => typeof value === "string").sort((a, b) => Date.parse(a) - Date.parse(b));
+    return {
+      modes: manifest.modes,
+      costs,
+      compliance: {
+        deprecated_modes: manifest.deprecated_modes ?? [],
+        ...manifest.sunset_at && { sunset_at: manifest.sunset_at },
+        endpoint_deprecated: matches.some((descriptor) => descriptor.deprecated === true),
+        ...endpointSunsets[0] && { endpoint_sunset_at: endpointSunsets[0] }
+      }
+    };
+  }
   /**
    * Verify via Horizon that the payer account has a trustline for the
    * payment asset declared in the manifest. Throws RouteDockTrustlineError
@@ -2585,8 +2837,7 @@ var RouteDockClient = class _RouteDockClient {
     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";
-    const server = new stellarSdk.Horizon.Server(horizonUrl);
+    const server = new stellarSdk.Horizon.Server(HORIZON_URLS[this.network]);
     try {
       const account = await server.loadAccount(this.keypair.publicKey());
       const balances = account.balances;
@@ -2622,9 +2873,11 @@ var RouteDockClient = class _RouteDockClient {
   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 request = options?.request;
+    assertEndpointActive(manifest, url, this.logger, request?.method);
     const mode = selectMode(manifest, { ...options, ...this.logger && { logger: this.logger } });
     const selectedAsset = selectAsset(manifest, mode, url).asset;
+    this._assertCapAsset(selectedAsset);
     await this._checkTrustline(manifest, selectedAsset);
     let amount;
     switch (mode) {
@@ -2642,18 +2895,18 @@ var RouteDockClient = class _RouteDockClient {
       default:
         throw new RouteDockManifestError(`Unknown payment mode: ${mode}`);
     }
-    const reserveId = await this._checkAndReserveSpend(amount, baseUrl);
+    const reserveId = await this._checkAndReserveSpend(amount, baseUrl, selectedAsset);
     let result;
     try {
       if (this.vault?.mode === "nulth") {
-        result = await this._payWithNulthVault(url, manifest, mode);
+        result = await this._payWithNulthVault(url, manifest, mode, request);
       } else {
         switch (mode) {
           case "x402":
-            result = await this.x402.pay(url, manifest);
+            result = await this.x402.pay(url, manifest, request);
             break;
           case "mpp-charge":
-            result = await this.charge.pay(url, manifest);
+            result = await this.charge.pay(url, manifest, request);
             break;
           default:
             throw new RouteDockManifestError(`Unknown payment mode: ${mode}`);
@@ -2672,7 +2925,7 @@ var RouteDockClient = class _RouteDockClient {
     return result;
   }
   /** Nulth ZK vault path — proof built off-chain, attached as auth signature */
-  async _payWithNulthVault(url, manifest, mode) {
+  async _payWithNulthVault(url, manifest, mode, request) {
     const prover = this.vault?.prover ?? "mock";
     if (this.network === "mainnet" && prover === "mock") {
       throw new RouteDockManifestError("nulth vault uses a MOCK Groth16 prover and cannot be used on mainnet");
@@ -2685,10 +2938,10 @@ var RouteDockClient = class _RouteDockClient {
     try {
       const { signer } = await prepareNulthSigner(this.vault, manifest, mode, this.network);
       const x402 = this.x402.withSigner(signer);
-      const result = await x402.pay(url, manifest);
+      const result = await x402.pay(url, manifest, request);
       return result;
     } catch (err) {
-      if (err instanceof NulthPolicyError) {
+      if (err instanceof nulthSdk.NulthPolicyError) {
         throw new RouteDockPolicyRejectError(err.code);
       }
       throw err;
@@ -2754,17 +3007,35 @@ var RouteDockClient = class _RouteDockClient {
       );
     }
     const endpointKey = new URL(url).origin;
-    const onSpend = this.spendCap ? (amount) => this._recordSessionSpend(amount, endpointKey) : void 0;
+    let onSpend;
+    if (this.spendCap) {
+      const sessionAsset = selectAsset(manifest, mode, url).asset;
+      this._assertCapAsset(sessionAsset);
+      onSpend = (amount) => this._recordSessionSpend(amount, endpointKey, sessionAsset);
+    }
     return this.session.openSession(url, manifest, secret, options, onSpend);
   }
+  /**
+   * The local cap accumulates one USDC total. Refuse to count any other asset
+   * against it (or let it through uncounted) when a cap is configured.
+   */
+  _assertCapAsset(asset) {
+    if (this.spendCap && asset !== this.spendCap.asset) {
+      throw new RouteDockPolicyRejectError("local_cap_asset_mismatch", {
+        cause: new Error(
+          `spendCap is denominated in ${this.spendCap.asset} but the selected payment asset is ${asset}`
+        )
+      });
+    }
+  }
   /**
    * Record spend for an MPP session voucher. Called before each voucher
    * fetch in stream(). Enforces the same local daily and per-endpoint caps
    * as discrete pay() calls. Returns a commit function to clean up the
    * reservation after the voucher fetch succeeds.
    */
-  async _recordSessionSpend(amount, endpointKey) {
-    const reserveId = await this._checkAndReserveSpend(amount, endpointKey);
+  async _recordSessionSpend(amount, endpointKey, asset) {
+    const reserveId = await this._checkAndReserveSpend(amount, endpointKey, asset);
     if (reserveId) {
       await this._commitSpend(reserveId);
     }
@@ -2803,15 +3074,16 @@ var RouteDockClient = class _RouteDockClient {
    * Both limits are independent: a payment is only reserved after **both** pass.
    * All spend (regardless of endpoint) counts toward the global accumulator.
    */
-  async _checkAndReserveSpend(amount, endpointKey) {
+  async _checkAndReserveSpend(amount, endpointKey, asset) {
     if (!this.spendCap) return "";
-    return this._withSpendMutex(async () => {
+    this._assertCapAsset(asset);
+    const spendCap = this.spendCap;
+    const amountMicros = nulthSdk.usdcToStroops(amount);
+    const reserve = (prev) => {
       const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-      const persisted = await this.spendStore.read();
-      const current = persisted && persisted.date === today ? persisted : { date: today, totalMicros: "0", endpoints: {} };
-      const amountMicros = nulthSdk.usdcToStroops(amount);
+      const current = prev && prev.date === today ? { ...prev, endpoints: { ...prev.endpoints } } : { date: today, totalMicros: "0", endpoints: {} };
       const total = BigInt(current.totalMicros);
-      const endpointCapStr = this.spendCap.endpointCaps?.[endpointKey];
+      const endpointCapStr = spendCap.endpointCaps?.[endpointKey];
       if (endpointCapStr !== void 0) {
         const endpointCapMicros = nulthSdk.usdcToStroops(endpointCapStr);
         const endpointTotal = BigInt(current.endpoints[endpointKey] ?? "0");
@@ -2819,17 +3091,25 @@ var RouteDockClient = class _RouteDockClient {
           throw new RouteDockPolicyRejectError("local_endpoint_cap_exceeded");
         }
       }
-      const globalCapMicros = nulthSdk.usdcToStroops(this.spendCap.daily);
+      const globalCapMicros = nulthSdk.usdcToStroops(spendCap.daily);
       if (total + amountMicros > globalCapMicros) {
         throw new RouteDockPolicyRejectError("local_daily_cap_exceeded");
       }
-      const reserveId = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
-      this._pendingReserves.set(reserveId, { endpointKey, amountMicros });
       current.totalMicros = (total + amountMicros).toString();
       if (endpointCapStr !== void 0) {
         current.endpoints[endpointKey] = (BigInt(current.endpoints[endpointKey] ?? "0") + amountMicros).toString();
       }
-      await this.spendStore.write(current);
+      return current;
+    };
+    return this._withSpendMutex(async () => {
+      const store = this.spendStore;
+      if (store.update) {
+        await store.update(reserve);
+      } else {
+        await store.write(reserve(await store.read()));
+      }
+      const reserveId = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+      this._pendingReserves.set(reserveId, { endpointKey, amountMicros });
       return reserveId;
     });
   }
@@ -2851,22 +3131,29 @@ var RouteDockClient = class _RouteDockClient {
     if (!reserve) return;
     this._pendingReserves.delete(reserveId);
     const { endpointKey, amountMicros } = reserve;
-    await this._withSpendMutex(async () => {
+    const release = (prev) => {
       const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-      const persisted = await this.spendStore.read();
-      if (!persisted || persisted.date !== today) return;
-      const currentTotal = BigInt(persisted.totalMicros);
-      persisted.totalMicros = (currentTotal - amountMicros).toString();
+      if (!prev || prev.date !== today) return void 0;
+      const persisted = { ...prev, endpoints: { ...prev.endpoints } };
+      persisted.totalMicros = (BigInt(persisted.totalMicros) - amountMicros).toString();
       if (persisted.endpoints[endpointKey]) {
-        const endpointTotal = BigInt(persisted.endpoints[endpointKey]);
-        const newEndpointTotal = endpointTotal - amountMicros;
+        const newEndpointTotal = BigInt(persisted.endpoints[endpointKey]) - amountMicros;
         if (newEndpointTotal <= 0n) {
           delete persisted.endpoints[endpointKey];
         } else {
           persisted.endpoints[endpointKey] = newEndpointTotal.toString();
         }
       }
-      await this.spendStore.write(persisted);
+      return persisted;
+    };
+    await this._withSpendMutex(async () => {
+      const store = this.spendStore;
+      if (store.update) {
+        await store.update(release);
+      } else {
+        const next = release(await store.read());
+        if (next) await store.write(next);
+      }
     });
   }
 };
@@ -2950,6 +3237,158 @@ var SupabaseSessionStore = class {
     await this.setStatus(channelId, "closed");
   }
 };
+var DEFAULT_LOCK_STALE_MS = 1e4;
+var DEFAULT_LOCK_TIMEOUT_MS = 15e3;
+var sleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var FileSpendStore = class {
+  filePath;
+  lockPath;
+  lockStaleMs;
+  lockTimeoutMs;
+  constructor(filePath, options = {}) {
+    this.filePath = filePath;
+    this.lockPath = `${filePath}.lock`;
+    this.lockStaleMs = options.lockStaleMs ?? DEFAULT_LOCK_STALE_MS;
+    this.lockTimeoutMs = options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+  }
+  async read() {
+    let data;
+    try {
+      data = await fs__default.default.readFile(this.filePath, "utf-8");
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return null;
+      }
+      throw new Error(
+        `[FileSpendStore] Failed to read spend file at ${this.filePath}: ${err.message}`
+      );
+    }
+    try {
+      return JSON.parse(data);
+    } catch {
+      throw new Error(
+        `[FileSpendStore] Spend file at ${this.filePath} contains invalid JSON. Delete or repair it before resuming. Raw content: ${data.slice(0, 120)}`
+      );
+    }
+  }
+  async write(state) {
+    await this.withLock(async (assertHeld) => {
+      await this.writeFile(state, assertHeld);
+    });
+  }
+  /**
+   * Atomically read-modify-write the accumulator under the cross-process lock.
+   * `fn` receives the current state (or null) and returns the state to persist,
+   * or `undefined` to leave the file untouched. If `fn` throws, nothing is
+   * written and the lock is released.
+   */
+  async update(fn) {
+    return this.withLock(async (assertHeld) => {
+      const prev = await this.read();
+      const next = fn(prev);
+      if (next === void 0) return prev;
+      await this.writeFile(next, assertHeld);
+      return next;
+    });
+  }
+  // ── internals ──────────────────────────────────────────────────────────────
+  async writeFile(state, assertHeld) {
+    const tmpPath = `${this.filePath}.${process.pid}.${crypto$1.randomBytes(6).toString("hex")}.tmp`;
+    try {
+      await fs__default.default.writeFile(tmpPath, JSON.stringify(state, null, 2), "utf-8");
+      await assertHeld();
+      await fs__default.default.rename(tmpPath, this.filePath);
+    } catch (err) {
+      await fs__default.default.rm(tmpPath, { force: true }).catch(() => {
+      });
+      throw err;
+    }
+  }
+  /** Run `fn` while holding the lock file; always releases it. */
+  async withLock(fn) {
+    await fs__default.default.mkdir(path__default.default.dirname(this.filePath), { recursive: true });
+    const token = `${process.pid}:${crypto$1.randomBytes(8).toString("hex")}`;
+    await this.acquireLock(token);
+    const heartbeat = setInterval(() => {
+      const now = /* @__PURE__ */ new Date();
+      fs__default.default.utimes(this.lockPath, now, now).catch(() => {
+      });
+    }, Math.max(10, Math.floor(this.lockStaleMs / 3)));
+    heartbeat.unref();
+    const assertHeld = async () => {
+      let current;
+      try {
+        current = await fs__default.default.readFile(this.lockPath, "utf-8");
+      } catch {
+        current = "";
+      }
+      if (current !== token) {
+        throw new Error(
+          `[FileSpendStore] Lost the lock on ${this.lockPath} before committing; refusing to overwrite the spend file. Retry the operation.`
+        );
+      }
+    };
+    try {
+      return await fn(assertHeld);
+    } finally {
+      clearInterval(heartbeat);
+      await this.releaseLock(token);
+    }
+  }
+  async acquireLock(token) {
+    const deadline = Date.now() + this.lockTimeoutMs;
+    let delay2 = 5;
+    for (; ; ) {
+      try {
+        const handle = await fs__default.default.open(this.lockPath, "wx");
+        try {
+          await handle.writeFile(token, "utf-8");
+        } finally {
+          await handle.close();
+        }
+        return;
+      } catch (err) {
+        if (err.code !== "EEXIST") {
+          throw new Error(
+            `[FileSpendStore] Failed to create lock file ${this.lockPath}: ${err.message}`
+          );
+        }
+      }
+      await this.breakIfStale();
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `[FileSpendStore] Timed out after ${this.lockTimeoutMs}ms waiting for ${this.lockPath}. Another process is holding the spend file lock; if none is running, delete the lock file.`
+        );
+      }
+      await sleep2(delay2 + Math.floor(Math.random() * delay2));
+      delay2 = Math.min(delay2 * 2, 50);
+    }
+  }
+  /** Remove the lock if its holder stopped refreshing it (crashed process). */
+  async breakIfStale() {
+    let before;
+    try {
+      before = await fs__default.default.stat(this.lockPath);
+    } catch {
+      return;
+    }
+    if (Date.now() - before.mtimeMs <= this.lockStaleMs) return;
+    try {
+      const after = await fs__default.default.stat(this.lockPath);
+      if (after.ino !== before.ino || after.mtimeMs !== before.mtimeMs) return;
+      await fs__default.default.unlink(this.lockPath);
+    } catch {
+    }
+  }
+  async releaseLock(token) {
+    try {
+      if (await fs__default.default.readFile(this.lockPath, "utf-8") === token) {
+        await fs__default.default.unlink(this.lockPath);
+      }
+    } catch {
+    }
+  }
+};
 
 // src/store/SupabaseSeenTxStore.ts
 var SupabaseSeenTxStore = class {
@@ -3001,6 +3440,107 @@ var SupabaseSeenTxStore = class {
     return data;
   }
 };
+var FLAT_MODES = ["x402", "mpp-charge"];
+var SESSION_MODES = ["mpp-session", "mpp-session-ws"];
+function sameAmount(adapter, label, optionValue, manifestValue) {
+  const parse = (where, value) => {
+    try {
+      return nulthSdk.usdcToStroops(value);
+    } catch {
+      throw new RouteDockManifestError(
+        `${adapter}: ${label} has an unparseable ${where} amount "${value}"`
+      );
+    }
+  };
+  return parse("option", optionValue) === parse("manifest", manifestValue);
+}
+function assertProviderConfig(opts, adapterName) {
+  const { manifest } = opts;
+  if (manifest === null || typeof manifest !== "object") {
+    throw new RouteDockManifestError(`${adapterName}: opts.manifest is required and must be an object`);
+  }
+  try {
+    validateManifestSchema(manifest);
+    assertManifestValid(manifest);
+  } catch (err) {
+    if (err instanceof RouteDockManifestError) {
+      throw new RouteDockManifestError(`${adapterName}: ${err.message}`, { cause: err });
+    }
+    throw err;
+  }
+  const served = new Set(opts.modes.filter((mode) => Boolean(opts.pricing[mode])));
+  const advertised = new Set(manifest.modes);
+  const notAdvertised = [...served].filter((mode) => !advertised.has(mode));
+  const notServed = [...advertised].filter((mode) => !served.has(mode));
+  if (notAdvertised.length > 0 || notServed.length > 0) {
+    const parts = [];
+    if (notAdvertised.length > 0) parts.push(`served but not in manifest.modes: ${notAdvertised.join(", ")}`);
+    if (notServed.length > 0) parts.push(`in manifest.modes but not served (missing from modes or pricing): ${notServed.join(", ")}`);
+    throw new RouteDockManifestError(`${adapterName}: modes do not match manifest.modes (${parts.join("; ")})`);
+  }
+  for (const mode of FLAT_MODES) {
+    if (!served.has(mode)) continue;
+    const optionValue = opts.pricing[mode];
+    const manifestValue = manifest.pricing[mode]?.amount;
+    if (manifestValue === void 0) {
+      throw new RouteDockManifestError(`${adapterName}: manifest.pricing.${mode}.amount is missing but ${mode} is served`);
+    }
+    if (!sameAmount(adapterName, `pricing.${mode}`, optionValue, manifestValue)) {
+      throw new RouteDockManifestError(
+        `${adapterName}: pricing.${mode} "${optionValue}" does not match manifest.pricing.${mode}.amount "${manifestValue}"`
+      );
+    }
+  }
+  for (const mode of SESSION_MODES) {
+    if (!served.has(mode)) continue;
+    const optionValue = opts.pricing[mode];
+    const manifestValue = manifest.pricing[mode];
+    if (!manifestValue) {
+      throw new RouteDockManifestError(`${adapterName}: manifest.pricing.${mode} is missing but ${mode} is served`);
+    }
+    if (!sameAmount(adapterName, `pricing.${mode}.rate`, optionValue.rate, manifestValue.rate)) {
+      throw new RouteDockManifestError(
+        `${adapterName}: pricing.${mode}.rate "${optionValue.rate}" does not match manifest.pricing.${mode}.rate "${manifestValue.rate}"`
+      );
+    }
+    if (optionValue.channelFactory !== manifestValue.channel_factory) {
+      throw new RouteDockManifestError(
+        `${adapterName}: pricing.${mode}.channelFactory "${optionValue.channelFactory}" does not match manifest.pricing.${mode}.channel_factory "${manifestValue.channel_factory}"`
+      );
+    }
+  }
+  if (opts.assetContract !== void 0 && opts.assetContract !== manifest.asset_contract) {
+    throw new RouteDockManifestError(
+      `${adapterName}: assetContract "${opts.assetContract}" does not match manifest.asset_contract "${manifest.asset_contract}"`
+    );
+  }
+  if (opts.asset !== void 0 && opts.asset !== manifest.asset) {
+    throw new RouteDockManifestError(
+      `${adapterName}: asset "${opts.asset}" does not match manifest.asset "${manifest.asset}"`
+    );
+  }
+  if (opts.network !== manifest.network) {
+    throw new RouteDockManifestError(
+      `${adapterName}: network "${opts.network}" does not match manifest.network "${manifest.network}"`
+    );
+  }
+  let signerPublicKey;
+  try {
+    signerPublicKey = stellarSdk.Keypair.fromSecret(opts.payeeSecretKey).publicKey();
+  } catch (err) {
+    throw new RouteDockManifestError(`${adapterName}: payeeSecretKey is not a valid Stellar secret key`, { cause: err });
+  }
+  if (signerPublicKey !== manifest.payee) {
+    throw new RouteDockManifestError(
+      `${adapterName}: payeeSecretKey belongs to ${signerPublicKey}, not manifest.payee ${manifest.payee}; clients would reject the signed manifest`
+    );
+  }
+  if (opts.payee !== manifest.payee) {
+    throw new RouteDockManifestError(
+      `${adapterName}: payee "${opts.payee}" does not match manifest.payee "${manifest.payee}"`
+    );
+  }
+}
 function extractPayerAddress(key) {
   if (typeof key !== "string") return null;
   return stellarSdk.StrKey.isValidEd25519PublicKey(key) || stellarSdk.StrKey.isValidMed25519PublicKey(key) ? key : null;
@@ -3009,6 +3549,18 @@ function extractPayerAddress(key) {
 // src/provider/SeenTxStore.ts
 var SETTLEMENT_REPLAY_WINDOW_MS = 6e4;
 var MAX_SETTLEMENT_REPLAYS = 1;
+async function recordSettlement(store, key, record, ctx) {
+  try {
+    await store.set(key, record);
+  } catch (err) {
+    ctx.logger("error", `${ctx.label} seenTxStore.set failed after settlement`, { error: err });
+    try {
+      ctx.onCallbackError?.(err, "seenTxStore.set");
+    } catch (cbErr) {
+      ctx.logger("error", `${ctx.label} onCallbackError threw`, { error: cbErr });
+    }
+  }
+}
 async function checkSettlementReplay(store, key, now = Date.now()) {
   const record = await store.get(key);
   if (!record) return { kind: "miss" };
@@ -3063,7 +3615,7 @@ var InMemorySeenTxStore = class {
     return next;
   }
 };
-async function sha256Hex2(input) {
+async function sha256Hex(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("");
@@ -3071,22 +3623,11 @@ async function sha256Hex2(input) {
 async function paymentIdempotencyKey(getHeader, scope) {
   const material = getHeader("payment-signature") ?? getHeader("x-payment") ?? getHeader("authorization");
   if (!material) return null;
-  return sha256Hex2(
+  return sha256Hex(
     [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
 var CAIP22 = {
   testnet: "stellar:testnet",
@@ -3226,10 +3767,10 @@ function createX402Handler(opts) {
           requirements
         );
         if (!verifyResult.isValid) {
-          res.status(401).json({
-            error: "Payment verification failed",
-            reason: verifyResult.invalidReason
-          });
+          await respondPaymentRequired(
+            "Payment verification failed",
+            verifyResult.invalidReason
+          );
           return;
         }
         const settleResult = await localFacilitator.settle(
@@ -3255,7 +3796,12 @@ function createX402Handler(opts) {
         if (typeof paymentResponse === "string") {
           headers["X-Payment-Response"] = paymentResponse;
         }
-        await seenTxStore.set(idempotencyKey, { txHash, headers, createdAt: Date.now() });
+        await recordSettlement(
+          seenTxStore,
+          idempotencyKey,
+          { txHash, headers, createdAt: Date.now() },
+          { logger, label: "[x402]", onCallbackError: opts.onCallbackError }
+        );
       }
       if (txHash && opts.onSettled) {
         Promise.resolve().then(() => opts.onSettled(txHash, opts.amount, "x402", payerAddress)).catch((err) => {
@@ -3285,21 +3831,21 @@ function createMppChargeHandler(opts) {
   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);
+  function getMppx(contract2) {
+    let instance = mppxInstances.get(contract2);
     if (!instance) {
       instance = server$2.Mppx.create({
         secretKey: opts.payeeSecretKey,
         methods: [
           server$4.stellar.charge({
             recipient,
-            currency: contract,
+            currency: contract2,
             network: networkId,
             feePayer: { envelopeSigner: opts.payeeSecretKey }
           })
         ]
       });
-      mppxInstances.set(contract, instance);
+      mppxInstances.set(contract2, instance);
     }
     return instance;
   }
@@ -3320,7 +3866,7 @@ function createMppChargeHandler(opts) {
           const credPart = authHeader.replace(/^Payment\s+/, "").split(",").find((p) => p.trim().startsWith("credential="));
           if (credPart) {
             const b64 = credPart.split("=").slice(1).join("=").replace(/^"|"$/g, "");
-            const credJson = Buffer.from(b64, "base64").toString("utf8");
+            const credJson = base64ToUtf8(b64);
             const cred = JSON.parse(credJson);
             const key = cred.sender ?? cred.payload?.sender ?? cred.payload?.from;
             payerAddress = extractPayerAddress(key);
@@ -3382,18 +3928,19 @@ function createMppChargeHandler(opts) {
       if (receiptHeader) {
         try {
           const parsed = JSON.parse(
-            Buffer.from(receiptHeader, "base64").toString("utf8")
+            base64ToUtf8(receiptHeader)
           );
           reference = parsed.reference;
         } catch {
         }
       }
       if (idempotencyKey) {
-        await seenTxStore.set(idempotencyKey, {
-          txHash: reference ?? null,
-          headers: receiptHeaders,
-          createdAt: Date.now()
-        });
+        await recordSettlement(
+          seenTxStore,
+          idempotencyKey,
+          { txHash: reference ?? null, headers: receiptHeaders, createdAt: Date.now() },
+          { logger, label: "[mpp-charge]", onCallbackError: opts.onCallbackError }
+        );
       }
       if (reference && opts.onSettled) {
         Promise.resolve().then(() => opts.onSettled(reference, opts.amount, "mpp-charge", payerAddress)).catch((err) => {
@@ -3407,6 +3954,14 @@ function createMppChargeHandler(opts) {
     }
   };
 }
+
+// src/provider/internal/vaultRpc.ts
+async function createSorobanRpcServer(rpcUrl) {
+  const { Server } = await import('@stellar/stellar-sdk/rpc');
+  return new Server(rpcUrl);
+}
+
+// src/provider/internal/vaultSettlement.ts
 function resolveVaultSettlementAddresses(payer, payee) {
   if (!payer) return null;
   return { payer, payee };
@@ -3426,6 +3981,111 @@ function buildSessionSettlementTransaction(source, vaultContractId, channelId, a
     networkPassphrase
   }).addOperation(op).setTimeout(30).build();
 }
+var DEFAULT_RPC_URLS = {
+  testnet: "https://soroban-testnet.stellar.org",
+  mainnet: "https://mainnet.sorobanrpc.com"
+};
+var CONFIRM_TIMEOUT_MS = 12e4;
+var CONFIRM_POLL_MS = 1e3;
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function describeSendError(sent) {
+  const errorResult = sent.errorResult;
+  try {
+    const name = errorResult?.result?.().switch?.().name;
+    if (name) return `sendTransaction returned ERROR: ${name}`;
+  } catch {
+  }
+  return `sendTransaction returned status ${sent.status}`;
+}
+async function waitForConfirmation(server, txHash) {
+  const deadline = Date.now() + CONFIRM_TIMEOUT_MS;
+  for (; ; ) {
+    const tx = await server.getTransaction(txHash);
+    if (tx.status === "SUCCESS") return "success";
+    if (tx.status === "FAILED") return "failed";
+    if (Date.now() >= deadline) return "timeout";
+    await delay(CONFIRM_POLL_MS);
+  }
+}
+async function recordSessionSettlement(request, { logger, onCallbackError }) {
+  const reportFailure = (fields) => {
+    logger("error", "[vault] failed to record session_settled", {
+      channelId: request.channelId,
+      ...fields.txHash ? { txHash: fields.txHash } : {},
+      reason: fields.reason,
+      ...fields.error !== void 0 ? { error: fields.error } : {}
+    });
+    if (onCallbackError) {
+      const err = fields.error ?? new Error(`session_settled vault record failed: ${fields.reason}`);
+      onCallbackError(err, "vaultSettlement");
+    }
+    return { ok: false, reason: fields.reason, ...fields.txHash ? { txHash: fields.txHash } : {} };
+  };
+  try {
+    const payeeKeypair = stellarSdk.Keypair.fromSecret(request.payeeSecretKey);
+    const addresses = resolveVaultSettlementAddresses(request.payer, payeeKeypair.publicKey());
+    if (!addresses) {
+      logger("warn", "[vault] skipped session_settled record: payer address unavailable", {
+        channelId: request.channelId
+      });
+      return { ok: false, reason: "payer address unavailable" };
+    }
+    const networkPassphrase = request.network === "mainnet" ? stellarSdk.Networks.PUBLIC : stellarSdk.Networks.TESTNET;
+    const rpcUrl = request.config.rpcUrl ?? DEFAULT_RPC_URLS[request.network];
+    const server = await createSorobanRpcServer(rpcUrl);
+    const sourceAccount = await server.getAccount(payeeKeypair.publicKey());
+    const tx = buildSessionSettlementTransaction(
+      sourceAccount,
+      request.config.contract,
+      request.channelId,
+      addresses,
+      request.amount,
+      request.voucherCount,
+      networkPassphrase
+    );
+    const preparedTx = await server.prepareTransaction(tx);
+    preparedTx.sign(payeeKeypair);
+    const sent = await server.sendTransaction(preparedTx);
+    if (sent.status === "ERROR") {
+      return reportFailure({
+        txHash: sent.hash || preparedTx.hash().toString("hex"),
+        reason: describeSendError(sent)
+      });
+    }
+    const txHash = sent.hash || preparedTx.hash().toString("hex");
+    const confirmation = await waitForConfirmation(server, txHash);
+    if (confirmation === "success") {
+      logger("debug", "[vault] recorded session_settled", {
+        channelId: request.channelId,
+        txHash
+      });
+      return { ok: true, txHash };
+    }
+    return reportFailure({
+      txHash,
+      reason: confirmation === "failed" ? "transaction failed on-chain" : `confirmation timed out after ${CONFIRM_TIMEOUT_MS}ms`
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return reportFailure({ reason, error: err });
+  }
+}
+
+// src/internal/vaultConfig.ts
+function resolveVaultSettlementConfig(option, logger) {
+  if (option) return option;
+  if (typeof process === "undefined") return void 0;
+  const fromEnv = process.env.AGENT_VAULT_CONTRACT ?? process.env.AGENT_VAULT_CONTRACT_ID;
+  if (!fromEnv) return void 0;
+  logger(
+    "warn",
+    "[vault] configuring the vault contract via the AGENT_VAULT_CONTRACT/AGENT_VAULT_CONTRACT_ID environment variables is deprecated and will be removed in the next minor release \u2014 pass the vaultSettlement option instead",
+    {}
+  );
+  return { contract: fromEnv };
+}
 function channelAuthorizer(envelopeSigner) {
   return { envelopeSigner };
 }
@@ -3504,6 +4164,7 @@ function createMppSessionHandler(opts) {
   let record = null;
   let voucherCount = 0;
   let sessionOpened = false;
+  let orphanFlagged = false;
   let idleTimer = null;
   let settledCleanly = false;
   let closeListenerArmed = false;
@@ -3529,6 +4190,14 @@ function createMppSessionHandler(opts) {
         return null;
       }
       record = { amount: BigInt(stored.amount), signature: stored.signature, payer: stored.payer ?? null };
+      if (typeof stored.voucherCount === "number") {
+        voucherCount = stored.voucherCount;
+      }
+      if (typeof stored.sessionOpened === "boolean") {
+        sessionOpened = stored.sessionOpened;
+      } else if (record !== null) {
+        sessionOpened = true;
+      }
     } catch {
       return null;
     }
@@ -3536,8 +4205,8 @@ function createMppSessionHandler(opts) {
   }
   async function flagOrphan(reason) {
     await loadPersistedRecord();
-    if (!sessionOpened || settledCleanly) return;
-    sessionOpened = false;
+    if (!sessionOpened || settledCleanly || orphanFlagged) return;
+    orphanFlagged = true;
     closeListenerArmed = false;
     clearIdleTimer();
     const cumulativeAmount = record ? (Number(record.amount) / 1e7).toFixed(7) : "0.0000000";
@@ -3585,16 +4254,20 @@ function createMppSessionHandler(opts) {
     if (record && amount < record.amount) return;
     const payer = record?.payer ?? extractPayerAddress(credential.source);
     record = { amount, signature: payload.signature, payer };
+    voucherCount++;
+    settledCleanly = false;
+    orphanFlagged = false;
+    armIdleTimer();
+    const wasOpened = sessionOpened;
+    sessionOpened = true;
     await innerStore.put(voucherRecordKey, {
       amount: record.amount.toString(),
       signature: record.signature,
-      payer: record.payer
+      payer: record.payer,
+      voucherCount,
+      sessionOpened: true
     });
-    voucherCount++;
-    settledCleanly = false;
-    armIdleTimer();
-    if (!sessionOpened) {
-      sessionOpened = true;
+    if (!wasOpened) {
       if (opts.onSessionOpen) {
         Promise.resolve().then(() => opts.onSessionOpen(opts.channelFactory, record.payer)).catch((err) => {
           logger("error", "[mpp-session] onSessionOpen callback error", { error: err });
@@ -3646,10 +4319,11 @@ function createMppSessionHandler(opts) {
         }
         if (closeAmount > 0n && closeSig) {
           const closePayer = record?.payer ?? null;
+          const vouchersClosed = voucherCount;
           const closeTxHash = await server$3.close({
             channel: opts.channelFactory,
             amount: closeAmount,
-            signature: Buffer.from(closeSig, "hex"),
+            signature: hexToBytes(closeSig),
             feePayer: channelAuthorizer(payeeKeypair),
             network: networkId
           });
@@ -3662,46 +4336,28 @@ function createMppSessionHandler(opts) {
               opts.onCallbackError?.(err, "onSettled");
             });
           }
-          const vaultContract = process.env.AGENT_VAULT_CONTRACT;
-          if (vaultContract) {
-            const settlementAddresses = resolveVaultSettlementAddresses(
-              closePayer,
-              payeeKeypair.publicKey()
+          res.json({ closeTxHash });
+          const vaultConfig = resolveVaultSettlementConfig(opts.vaultSettlement, logger);
+          if (vaultConfig) {
+            await recordSessionSettlement(
+              {
+                config: vaultConfig,
+                network: opts.network,
+                payeeSecretKey: opts.payeeSecretKey,
+                channelId: opts.channelFactory,
+                payer: closePayer,
+                amount: closeAmount,
+                voucherCount: vouchersClosed
+              },
+              { logger, onCallbackError: opts.onCallbackError }
             );
-            if (!settlementAddresses) {
-              logger("warn", "[mpp-session] skipped session_settled vault record: payer address unavailable");
-            } else {
-              try {
-                const { Networks: Networks2 } = await import('@stellar/stellar-sdk');
-                const { Server } = await import('@stellar/stellar-sdk/rpc');
-                const networkPassphrase = opts.network === "mainnet" ? Networks2.PUBLIC : Networks2.TESTNET;
-                const rpcUrl = opts.network === "mainnet" ? "https://mainnet.sorobanrpc.com" : "https://soroban-testnet.stellar.org";
-                const server = new Server(rpcUrl);
-                const payeePublicKey = payeeKeypair.publicKey();
-                const sourceAccount = await server.getAccount(payeePublicKey);
-                const tx = buildSessionSettlementTransaction(
-                  sourceAccount,
-                  vaultContract,
-                  opts.channelFactory,
-                  settlementAddresses,
-                  closeAmount,
-                  voucherCount,
-                  networkPassphrase
-                );
-                const preparedTx = await server.prepareTransaction(tx);
-                preparedTx.sign(payeeKeypair);
-                await server.sendTransaction(preparedTx);
-              } catch (recordErr) {
-                logger("error", "[mpp-session] failed to record session_settled on vault", { error: recordErr });
-              }
-            }
           }
-          res.json({ closeTxHash });
         } else {
           res.json({ closeTxHash: null, message: "no vouchers received" });
         }
         sessionOpened = false;
         voucherCount = 0;
+        orphanFlagged = false;
         record = null;
         await innerStore.delete(voucherRecordKey);
         closeListenerArmed = false;
@@ -3738,6 +4394,7 @@ function createMppSessionHandler(opts) {
 var MPP_MODES = ["mpp-session", "mpp-charge"];
 function routedock(opts) {
   const startTime = Date.now();
+  assertProviderConfig(opts, "routedock");
   const signedManifest = signManifest(opts.manifest, opts.payeeSecretKey);
   const handlerMap = /* @__PURE__ */ new Map();
   if (opts.modes.includes("x402")) {
@@ -3801,7 +4458,8 @@ function routedock(opts) {
           ...opts.onCallbackError ? { onCallbackError: opts.onCallbackError } : {},
           ...opts.onOrphaned ? { onOrphaned: opts.onOrphaned } : {},
           ...opts.idleTimeoutMs != null ? { idleTimeoutMs: opts.idleTimeoutMs } : {},
-          ...opts.logger ? { logger: opts.logger } : {}
+          ...opts.logger ? { logger: opts.logger } : {},
+          ...opts.vaultSettlement ? { vaultSettlement: opts.vaultSettlement } : {}
         })
       );
     }
@@ -3891,6 +4549,8 @@ var MPP_NETWORK3 = {
   testnet: "stellar:testnet",
   mainnet: "stellar:pubnet"
 };
+var DEFAULT_MAX_RECONCILE_ATTEMPTS = 5;
+var ALREADY_CLOSED_PATTERN = /channel has been closed|channel is closed|already closed|finalized/i;
 function decimalToStroops(amountStr) {
   return nulthSdk.usdcToStroops(amountStr);
 }
@@ -3900,12 +4560,15 @@ async function reconcileAbandonedSessions(opts) {
     recoveredCount: 0,
     skippedCount: 0,
     failedCount: 0,
+    alreadyClosedCount: 0,
+    terminalCount: 0,
     errors: []
   };
+  const maxAttempts = opts.maxReconcileAttempts ?? DEFAULT_MAX_RECONCILE_ATTEMPTS;
   const payeeKeypair = stellarSdk.Keypair.fromSecret(opts.payeeSecretKey);
   const networkId = MPP_NETWORK3[opts.network];
   try {
-    const { data: closingSessions, error } = await opts.supabase.from("sessions").select("channel_id, channel_contract, cumulative_amount, last_signature, settlement_tx_hash").eq("status", "closing").eq("network", opts.network).eq("payee", payeeKeypair.publicKey()).is("settlement_tx_hash", null).not("last_signature", "is", null).order("updated_at", { ascending: true }).limit(100);
+    const { data: closingSessions, error } = await opts.supabase.from("sessions").select("channel_id, channel_contract, cumulative_amount, last_signature, settlement_tx_hash, reconcile_attempts").eq("status", "closing").eq("network", opts.network).eq("payee", payeeKeypair.publicKey()).is("settlement_tx_hash", null).not("last_signature", "is", null).order("updated_at", { ascending: true }).limit(100);
     if (error) {
       throw new Error(`Failed to query sessions: ${error.message}`);
     }
@@ -3927,7 +4590,7 @@ async function reconcileAbandonedSessions(opts) {
           continue;
         }
         const closeAmount = decimalToStroops(cumulative_amount);
-        const closeSig = Buffer.from(last_signature, "hex");
+        const closeSig = hexToBytes(last_signature);
         const closeFn = opts.channelClose ?? (await import('@stellar/mpp/channel/server')).close;
         const closeTxHash = await closeFn({
           channel: channelId,
@@ -3950,11 +4613,36 @@ async function reconcileAbandonedSessions(opts) {
           await opts.onRecovered(channelId, closeTxHash, totalPaid);
         }
       } catch (err) {
+        const reason = formatMppError(err);
+        if (ALREADY_CLOSED_PATTERN.test(reason)) {
+          const { error: closeError } = await opts.supabase.from("sessions").update({
+            status: "closed",
+            last_reconcile_error: `channel already closed on-chain: ${reason}`,
+            updated_at: (/* @__PURE__ */ new Date()).toISOString()
+          }).eq("channel_id", session.channel_id);
+          if (!closeError) {
+            stats.alreadyClosedCount++;
+            continue;
+          }
+        }
         stats.failedCount++;
-        stats.errors.push({
-          channelId: session.channel_id,
-          reason: formatMppError(err)
-        });
+        stats.errors.push({ channelId: session.channel_id, reason });
+        const attempts = (Number(session.reconcile_attempts) || 0) + 1;
+        const terminal = attempts >= maxAttempts;
+        const { error: bookkeepingError } = await opts.supabase.from("sessions").update({
+          reconcile_attempts: attempts,
+          last_reconcile_error: reason,
+          updated_at: (/* @__PURE__ */ new Date()).toISOString(),
+          ...terminal ? { status: "failed" } : {}
+        }).eq("channel_id", session.channel_id);
+        if (bookkeepingError) {
+          stats.errors.push({
+            channelId: session.channel_id,
+            reason: `Failed to record reconcile failure: ${bookkeepingError.message}`
+          });
+        } else if (terminal) {
+          stats.terminalCount++;
+        }
       }
     }
     return stats;
@@ -3975,7 +4663,7 @@ async function runStartupReconciliation(opts, logger) {
     }
     log(
       "info",
-      `[SessionReconciler] Found ${stats.orphanedCount} orphaned session(s). Recovered: ${stats.recoveredCount}, Skipped: ${stats.skippedCount}, Failed: ${stats.failedCount}`
+      `[SessionReconciler] Found ${stats.orphanedCount} orphaned session(s). Recovered: ${stats.recoveredCount}, Skipped: ${stats.skippedCount}, Failed: ${stats.failedCount}, Already closed: ${stats.alreadyClosedCount}, Moved to failed: ${stats.terminalCount}`
     );
     if (stats.errors.length > 0) {
       log("warn", "[SessionReconciler] Reconciliation errors:");
@@ -3992,7 +4680,7 @@ function tryDecodeBase64(value) {
     return value;
   }
   try {
-    const decoded = typeof Buffer !== "undefined" ? Buffer.from(value, "base64").toString("utf-8") : atob(value);
+    const decoded = base64ToUtf8(value);
     if (decoded.length > 0 && decoded !== value) return decoded;
   } catch {
   }
@@ -4129,10 +4817,30 @@ var ProviderRegistry = class {
   }
 };
 
+Object.defineProperty(exports, "NulthPolicyError", {
+  enumerable: true,
+  get: function () { return nulthSdk.NulthPolicyError; }
+});
 Object.defineProperty(exports, "USDC_DECIMALS", {
   enumerable: true,
   get: function () { return nulthSdk.USDC_DECIMALS; }
 });
+Object.defineProperty(exports, "createPolicyState", {
+  enumerable: true,
+  get: function () { return nulthSdk.createPolicyState; }
+});
+Object.defineProperty(exports, "decodeAuthSignature", {
+  enumerable: true,
+  get: function () { return nulthSdk.decodeAuthSignature; }
+});
+Object.defineProperty(exports, "paymentContextFromManifest", {
+  enumerable: true,
+  get: function () { return nulthSdk.paymentContextFromManifest; }
+});
+Object.defineProperty(exports, "setNulthPaymentContext", {
+  enumerable: true,
+  get: function () { return nulthSdk.setNulthPaymentContext; }
+});
 Object.defineProperty(exports, "usdcToStroops", {
   enumerable: true,
   get: function () { return nulthSdk.usdcToStroops; }
@@ -4142,7 +4850,6 @@ exports.DEFAULT_RETRY_POLICY = DEFAULT_RETRY_POLICY;
 exports.FileSpendStore = FileSpendStore;
 exports.InMemorySpendStore = InMemorySpendStore;
 exports.MppChargeClient = MppChargeClient;
-exports.NulthPolicyError = NulthPolicyError;
 exports.OnChainRegistry = OnChainRegistry;
 exports.ProviderRegistry = ProviderRegistry;
 exports.RouteDockChannelStateError = RouteDockChannelStateError;
@@ -4156,6 +4863,7 @@ exports.RouteDockManifestSunsetError = RouteDockManifestSunsetError;
 exports.RouteDockManifestTimeoutError = RouteDockManifestTimeoutError;
 exports.RouteDockNetworkError = RouteDockNetworkError;
 exports.RouteDockNoSupportedModeError = RouteDockNoSupportedModeError;
+exports.RouteDockPaymentRejectedError = RouteDockPaymentRejectedError;
 exports.RouteDockPolicyRejectError = RouteDockPolicyRejectError;
 exports.RouteDockPolicyRejectedError = RouteDockPolicyRejectedError;
 exports.RouteDockRefundWindowError = RouteDockRefundWindowError;
@@ -4174,9 +4882,7 @@ 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;
@@ -4187,7 +4893,7 @@ exports.manifestDigest = manifestDigest;
 exports.noopLogger = noopLogger;
 exports.normalizeManifestAssets = normalizeManifestAssets;
 exports.parseRetryAfterMs = parseRetryAfterMs;
-exports.paymentContextFromManifest = paymentContextFromManifest;
+exports.paymentRejectedError = paymentRejectedError;
 exports.prepareNulthSigner = prepareNulthSigner;
 exports.rankProvidersByLatency = rankProvidersByLatency;
 exports.reconcileAbandonedSessions = reconcileAbandonedSessions;
@@ -4198,7 +4904,6 @@ exports.routedock = routedock;
 exports.runStartupReconciliation = runStartupReconciliation;
 exports.selectAsset = selectAsset;
 exports.selectMode = selectMode;
-exports.setNulthPaymentContext = setNulthPaymentContext;
 exports.signManifest = signManifest;
 exports.usdcToMicros = usdcToMicros;
 exports.usdcToUnits = usdcToUnits;