@routedock/routedock 0.1.1 → 0.2.0

package/dist/client.cjs

@@ -1,57 +1,227 @@
 'use strict';
 
+var nulthSdk = require('@routedock/nulth-sdk');
 var stellarSdk = require('@stellar/stellar-sdk');
-var Ajv = require('ajv');
+var jsonSchema = require('@cfworker/json-schema');
+var crypto = require('crypto');
 var stellar = require('@x402/stellar');
 var client = require('@x402/stellar/exact/client');
 var client$1 = 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 mppx = require('mppx');
+var fs = require('fs/promises');
+var path = require('path');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
-var Ajv__default = /*#__PURE__*/_interopDefault(Ajv);
+var fs__default = /*#__PURE__*/_interopDefault(fs);
+var path__default = /*#__PURE__*/_interopDefault(path);
 
-// src/types.ts
+// src/errors.ts
 var RouteDockError = class extends Error {
-  constructor(message) {
-    super(message);
+  code;
+  retryable;
+  retryAfterMs;
+  constructor(message, code, retryable, options = {}) {
+    super(message, { cause: options.cause });
     this.name = "RouteDockError";
+    this.code = code;
+    this.retryable = retryable;
+    if (options.retryAfterMs !== void 0) {
+      this.retryAfterMs = options.retryAfterMs;
+    }
   }
 };
 var RouteDockManifestError = class extends RouteDockError {
-  constructor(message) {
-    super(message);
+  constructor(message, options = {}) {
+    super(message, "MANIFEST", false, options);
     this.name = "RouteDockManifestError";
   }
 };
+var RouteDockManifestTimeoutError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "MANIFEST_TIMEOUT", true, options);
+    this.name = "RouteDockManifestTimeoutError";
+  }
+};
+var RouteDockManifestSunsetError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "MANIFEST_SUNSET", false, options);
+    this.name = "RouteDockManifestSunsetError";
+  }
+};
 var RouteDockNoSupportedModeError = class extends RouteDockError {
-  constructor(message) {
-    super(message);
+  constructor(message, options = {}) {
+    super(message, "NO_SUPPORTED_MODE", false, options);
     this.name = "RouteDockNoSupportedModeError";
   }
 };
-var RouteDockSessionError = class extends RouteDockError {
-  constructor(message) {
-    super(message);
-    this.name = "RouteDockSessionError";
+var RouteDockClientVersionError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "CLIENT_VERSION_TOO_OLD", false, options);
+    this.name = "RouteDockClientVersionError";
+  }
+};
+var RouteDockTrustlineError = class extends RouteDockError {
+  asset;
+  issuer;
+  remediation;
+  constructor(asset, issuer, remediation, options = {}) {
+    super(
+      `Missing trustline for ${asset} (issuer: ${issuer}). ${remediation}`,
+      "TRUSTLINE",
+      false,
+      options
+    );
+    this.name = "RouteDockTrustlineError";
+    this.asset = asset;
+    this.issuer = issuer;
+    this.remediation = remediation;
+  }
+};
+var RouteDockFacilitatorError = class extends RouteDockError {
+  status;
+  constructor(message, status, options = {}) {
+    super(message, "FACILITATOR", true, options);
+    this.name = "RouteDockFacilitatorError";
+    this.status = status;
+  }
+};
+var RouteDockNetworkError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "NETWORK", true, options);
+    this.name = "RouteDockNetworkError";
+  }
+};
+var RouteDockSignatureError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "SIGNATURE", false, options);
+    this.name = "RouteDockSignatureError";
+  }
+};
+var RouteDockVoucherMonotonicityError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "VOUCHER_MONOTONICITY", false, options);
+    this.name = "RouteDockVoucherMonotonicityError";
   }
 };
-var RouteDockPolicyRejectedError = class extends RouteDockError {
+var RouteDockPolicyRejectError = class extends RouteDockError {
   reason;
-  constructor(reason) {
-    super(`Payment rejected by policy: ${reason}`);
-    this.name = "RouteDockPolicyRejectedError";
+  constructor(reason, options = {}) {
+    super(`Payment rejected by policy: ${reason}`, "POLICY_REJECT", false, options);
+    this.name = "RouteDockPolicyRejectError";
     this.reason = reason;
   }
 };
+var RouteDockChannelStateError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "CHANNEL_STATE", false, options);
+    this.name = "RouteDockChannelStateError";
+  }
+};
+var RouteDockDisputeError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "DISPUTE", false, options);
+    this.name = "RouteDockDisputeError";
+  }
+};
+var RouteDockRefundWindowError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "REFUND_WINDOW", false, options);
+    this.name = "RouteDockRefundWindowError";
+  }
+};
+var RouteDockPolicyRejectedError = RouteDockPolicyRejectError;
+var RouteDockSessionError = RouteDockVoucherMonotonicityError;
+function parseRetryAfterMs(response) {
+  const header = response.headers.get("Retry-After");
+  if (!header) return void 0;
+  const seconds = Number(header);
+  if (!Number.isNaN(seconds) && seconds >= 0) {
+    return seconds * 1e3;
+  }
+  const date = Date.parse(header);
+  if (!Number.isNaN(date)) {
+    return Math.max(0, date - Date.now());
+  }
+  return void 0;
+}
+function httpStatusToError(message, status, response) {
+  const retryAfterMs = response ? parseRetryAfterMs(response) : void 0;
+  const opts = retryAfterMs !== void 0 ? { retryAfterMs } : {};
+  if (status === 429 || status === 503 || status >= 500 && status < 600) {
+    return new RouteDockFacilitatorError(message, status, opts);
+  }
+  if (status >= 400) {
+    return new RouteDockManifestError(message, opts);
+  }
+  return new RouteDockNetworkError(message, opts);
+}
+function wrapFetchError(err, context) {
+  if (err instanceof RouteDockError) return err;
+  return new RouteDockNetworkError(`${context}: ${String(err)}`, { cause: err });
+}
+
+// src/types.ts
+var DEFAULT_MAX_SESSION_DURATION_MS = 36e5;
+
+// src/internal/retry.ts
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 4,
+  baseDelayMs: 250,
+  maxDelayMs: 3e4
+};
+function backoffDelayMs(attempt, baseDelayMs, maxDelayMs = DEFAULT_RETRY_POLICY.maxDelayMs) {
+  const cappedDelay = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+  return Math.floor(Math.random() * (cappedDelay + 1));
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withRetry(fn, policy = {}) {
+  const { maxAttempts, baseDelayMs, maxDelayMs, onRetry } = {
+    ...DEFAULT_RETRY_POLICY,
+    ...policy
+  };
+  let lastError;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (!(err instanceof RouteDockError)) {
+        throw err;
+      }
+      lastError = err;
+      if (!err.retryable || attempt >= maxAttempts - 1) {
+        throw err;
+      }
+      const delay = err.retryAfterMs !== void 0 ? err.retryAfterMs : backoffDelayMs(attempt, baseDelayMs, maxDelayMs);
+      if (onRetry) {
+        try {
+          await onRetry(attempt, err, delay);
+        } catch (cbErr) {
+          console.error("[withRetry] onRetry callback threw:", cbErr);
+        }
+      }
+      await sleep(delay);
+    }
+  }
+  throw lastError ?? new RouteDockError("Retry exhausted", "NETWORK", false);
+}
+var USDC_ISSUERS = {
+  testnet: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
+  mainnet: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
+};
+var usdcToUnits = nulthSdk.usdcToStroops;
 
 // src/schemas/routedock.schema.json
 var routedock_schema_default = {
   $schema: "http://json-schema.org/draft-07/schema#",
-  $id: "https://routedock.dev/schemas/routedock.schema.json",
+  $id: "https://routedock.xyz/schemas/routedock.schema.json",
   title: "RouteDock Manifest",
   description: "Discovery manifest served at /.well-known/routedock.json on every RouteDock provider endpoint",
   type: "object",
@@ -72,8 +242,26 @@ var routedock_schema_default = {
   properties: {
     routedock: {
       type: "string",
-      const: "1.0",
-      description: "Manifest schema version. Always '1.0' for this version."
+      pattern: "^[0-9]+\\.[0-9]+$",
+      description: "Manifest schema version, e.g. '1.0', '1.1', '2.0'."
+    },
+    min_client_version: {
+      type: "string",
+      pattern: "^[0-9]+\\.[0-9]+$",
+      description: "Minimum SDK client version (major.minor) required to use this manifest. Clients below this version must refuse to pay."
+    },
+    deprecated_modes: {
+      type: "array",
+      items: {
+        $ref: "#/definitions/PaymentMode"
+      },
+      uniqueItems: true,
+      description: "Payment modes still listed in 'modes' for backwards compatibility but deprecated for new integrations."
+    },
+    sunset_at: {
+      type: "string",
+      format: "date-time",
+      description: "ISO 8601 timestamp after which this manifest version is no longer supported by the provider."
     },
     name: {
       type: "string",
@@ -126,18 +314,25 @@ var routedock_schema_default = {
         },
         "mpp-session": {
           $ref: "#/definitions/SessionPricingConfig"
+        },
+        "mpp-session-ws": {
+          $ref: "#/definitions/SessionPricingConfig",
+          description: "WebSocket transport variant of mpp-session: channel opened and first voucher negotiated over HTTP, then the connection upgrades to WebSocket for push-based streaming."
         }
       },
       minProperties: 1
     },
     endpoints: {
       type: "object",
-      description: "Map of endpoint name to HTTP method + path (e.g. { 'price': 'GET /price' })",
+      description: "Map of endpoint name to endpoint descriptors",
       additionalProperties: {
-        type: "string"
+        $ref: "#/definitions/EndpointDescriptor"
       },
       minProperties: 1
     },
+    sla: {
+      $ref: "#/definitions/SLAConfig"
+    },
     tags: {
       type: "array",
       items: {
@@ -147,12 +342,91 @@ var routedock_schema_default = {
       },
       uniqueItems: true,
       description: "Capability tags indexed with trigram search in the provider registry"
+    },
+    vault: {
+      $ref: "#/definitions/VaultMode"
+    },
+    nulth_account: {
+      type: "string",
+      description: "Optional Nulth smart account address associated with this provider"
+    },
+    capabilities: {
+      type: "object",
+      description: "Optional protocol features this provider supports",
+      properties: {
+        streaming: {
+          type: "array",
+          items: {
+            type: "string",
+            enum: ["sse", "websocket"]
+          },
+          description: "Supported streaming transports"
+        },
+        webhooks: {
+          type: "boolean",
+          description: "Whether webhook callbacks are supported"
+        },
+        idempotency_keys: {
+          type: "boolean",
+          description: "Whether idempotency keys are supported"
+        },
+        content_types: {
+          type: "array",
+          items: {
+            type: "string"
+          },
+          description: "Supported content types for request/response"
+        }
+      },
+      additionalProperties: false
+    },
+    regions: {
+      type: "array",
+      items: {
+        type: "string",
+        minLength: 2,
+        maxLength: 10
+      },
+      uniqueItems: true,
+      description: "IATA airport codes or UN/LOCODE identifiers for regions where this provider has infrastructure (e.g. ['IAD', 'AMS']). Used by agents to select the nearest provider."
+    },
+    latency_hints: {
+      type: "object",
+      additionalProperties: {
+        type: "number",
+        minimum: 0
+      },
+      description: "Provider-declared p50 latency in milliseconds per region code. Keys must be a subset of 'regions'. Example: { 'IAD': 14, 'AMS': 22 }."
+    },
+    signature: {
+      type: "string",
+      description: "Base64 Ed25519 signature (payee keypair) over the SHA-256 hash of this manifest with the signature field omitted. Clients must verify before trusting any routing field."
+    },
+    signature_version: {
+      type: "string",
+      const: "2",
+      description: "Manifest signature format. Version 2 recursively includes every nested manifest field in the signed digest."
+    },
+    categories: {
+      type: "array",
+      items: {
+        type: "string",
+        minLength: 1,
+        maxLength: 128
+      },
+      uniqueItems: true,
+      description: "Optional hierarchical categories from a published taxonomy (e.g. data/price/crypto)"
     }
   },
   definitions: {
+    VaultMode: {
+      type: "string",
+      enum: ["local-key", "agent-vault", "nulth"],
+      description: "Agent vault / custody mode for payments from this provider"
+    },
     PaymentMode: {
       type: "string",
-      enum: ["x402", "mpp-charge", "mpp-session"],
+      enum: ["x402", "mpp-charge", "mpp-session", "mpp-session-ws"],
       description: "A supported RouteDock payment mode"
     },
     PricingConfig: {
@@ -173,13 +447,17 @@ var routedock_schema_default = {
         facilitator: {
           type: "string",
           description: "x402 facilitator URL (required for x402 mode). OpenZeppelin Channels endpoint."
+        },
+        payee: {
+          type: "string",
+          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."
         }
       }
     },
     SessionPricingConfig: {
       type: "object",
       description: "Per-voucher pricing for mpp-session (one-way-channel) mode",
-      required: ["rate", "per", "channel_contract", "min_deposit", "refund_waiting_period_ledgers"],
+      required: ["rate", "per", "channel_factory", "min_deposit", "refund_waiting_period_ledgers"],
       additionalProperties: false,
       properties: {
         rate: {
@@ -191,9 +469,9 @@ var routedock_schema_default = {
           const: "voucher",
           description: "Billing unit \u2014 always 'voucher' for session mode"
         },
-        channel_contract: {
+        channel_factory: {
           type: "string",
-          description: "Soroban contract address (C...) for the one-way-channel contract"
+          description: "Stable Soroban factory address (C...) used to deploy a per-session channel"
         },
         min_deposit: {
           type: "string",
@@ -205,88 +483,492 @@ var routedock_schema_default = {
           description: "Ledgers the server has to settle before the funder can reclaim. Default: 17280 (~24h). Do not reduce in production."
         }
       }
+    },
+    SLAConfig: {
+      type: "object",
+      description: "Service Level Agreement for the provider",
+      required: ["uptime_30d_percent", "p95_latency_ms"],
+      additionalProperties: false,
+      properties: {
+        uptime_30d_percent: {
+          type: "number",
+          description: "Uptime percentage over the last 30 days"
+        },
+        p95_latency_ms: {
+          type: "number",
+          description: "P95 latency in milliseconds"
+        },
+        maintenance_windows: {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["cron", "duration_minutes"],
+            additionalProperties: false,
+            properties: {
+              cron: {
+                type: "string",
+                description: "Cron expression for the maintenance window"
+              },
+              duration_minutes: {
+                type: "number",
+                description: "Duration of the maintenance window in minutes"
+              }
+            }
+          }
+        }
+      }
+    },
+    EndpointDescriptor: {
+      type: "object",
+      description: "Descriptor for a provider endpoint",
+      required: ["method", "path"],
+      additionalProperties: false,
+      properties: {
+        method: {
+          type: "string",
+          description: "HTTP method for the endpoint"
+        },
+        path: {
+          type: "string",
+          description: "Path for the endpoint"
+        },
+        deprecated: {
+          type: "boolean",
+          description: "Whether this endpoint is retained only for backwards compatibility"
+        },
+        sunset_at: {
+          type: "string",
+          format: "date-time",
+          description: "ISO 8601 timestamp after which callers should stop using this endpoint"
+        },
+        headers: {
+          type: "object",
+          additionalProperties: {
+            type: "string"
+          },
+          description: "Expected request headers"
+        },
+        request_schema: {
+          description: "JSON schema for the request body"
+        },
+        response_schema: {
+          description: "JSON schema for the response body"
+        },
+        rate_limit: {
+          type: "object",
+          required: ["requests", "window_seconds"],
+          additionalProperties: false,
+          properties: {
+            requests: {
+              type: "number"
+            },
+            window_seconds: {
+              type: "number"
+            }
+          }
+        }
+      }
     }
   }
 };
 
+// package.json
+var package_default = {
+  version: "0.2.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])])
+    );
+  }
+  return value;
+}
+function manifestDigest(manifest) {
+  const { signature: _omit, ...rest } = manifest;
+  const canonical = JSON.stringify(canonicalize(rest));
+  return crypto.createHash("sha256").update(canonical, "utf8").digest();
+}
+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}`
+    );
+  }
+  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");
+  }
+  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/client/ModeRouter.ts
-var ajv = new Ajv__default.default();
-var validateManifest = ajv.compile(routedock_schema_default);
+var validator = new jsonSchema.Validator(routedock_schema_default, "7");
+var SDK_VERSION = package_default.version;
+function parseMajorMinor(version) {
+  const parts = version.split(".");
+  return [Number.parseInt(parts[0] ?? "0", 10), Number.parseInt(parts[1] ?? "0", 10)];
+}
+function isVersionBelow(a, b) {
+  const [aMajor, aMinor] = parseMajorMinor(a);
+  const [bMajor, bMinor] = parseMajorMinor(b);
+  return aMajor < bMajor || aMajor === bMajor && aMinor < bMinor;
+}
+function assertClientVersionSupported(manifest, baseUrl) {
+  const minVersion = manifest.min_client_version;
+  if (minVersion && isVersionBelow(SDK_VERSION, minVersion)) {
+    throw new RouteDockClientVersionError(
+      `SDK version ${SDK_VERSION} is below the minimum required version ${minVersion} for provider at ${baseUrl}. Please upgrade the SDK.`
+    );
+  }
+}
+function assertManifestActive(manifest, baseUrl) {
+  const sunsetAt = manifest.sunset_at;
+  if (!sunsetAt) return;
+  const sunsetTime = Date.parse(sunsetAt);
+  if (!Number.isFinite(sunsetTime)) {
+    throw new RouteDockManifestError(
+      `Manifest at ${baseUrl} contains an invalid sunset_at timestamp: ${sunsetAt}`
+    );
+  }
+  if (sunsetTime <= Date.now()) {
+    throw new RouteDockManifestSunsetError(
+      `Manifest for provider at ${baseUrl} sunset at ${sunsetAt} and can no longer be used`
+    );
+  }
+}
+function assertEndpointActive(manifest, url, logger) {
+  const pathname = new URL(url).pathname;
+  const matches = Object.entries(manifest.endpoints).filter(
+    ([, descriptor]) => descriptor.path === pathname
+  );
+  if (matches.length === 0) return;
+  const now = Date.now();
+  const allSunset = matches.every(([, descriptor]) => {
+    const sunsetAt = descriptor.sunset_at;
+    return typeof sunsetAt === "string" && Date.parse(sunsetAt) <= now;
+  });
+  if (allSunset) {
+    const [key, descriptor] = matches[0];
+    throw new RouteDockManifestSunsetError(
+      `Endpoint '${key}' (${pathname}) sunset at ${descriptor.sunset_at} and can no longer be used`
+    );
+  }
+  const deprecated = matches.find(([, descriptor]) => descriptor.deprecated === true);
+  if (deprecated && logger) {
+    const [key, descriptor] = deprecated;
+    const sunsetSuffix = descriptor.sunset_at ? `; sunset_at ${descriptor.sunset_at}` : "";
+    logger(
+      `[RouteDock] WARNING: ${manifest.name} \u2192 ${pathname}; endpoint '${key}' is deprecated${sunsetSuffix}`
+    );
+  }
+}
+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(", ")})`
+        );
+      }
+    }
+  }
+}
 var CACHE_TTL_MS = 6e4;
-var manifestCache = /* @__PURE__ */ new Map();
-async function fetchManifest(baseUrl) {
+var DEFAULT_MANIFEST_CACHE_MAX_SIZE = 512;
+var DEFAULT_MANIFEST_TIMEOUT_MS = 5e3;
+var LruCache = class {
+  constructor(maxSize) {
+    this.maxSize = maxSize;
+  }
+  maxSize;
+  map = /* @__PURE__ */ new Map();
+  get(key) {
+    if (!this.map.has(key)) return void 0;
+    const value = this.map.get(key);
+    this.map.delete(key);
+    this.map.set(key, value);
+    return value;
+  }
+  set(key, value) {
+    if (this.map.has(key)) {
+      this.map.delete(key);
+    } else if (this.map.size >= this.maxSize) {
+      const oldestKey = this.map.keys().next().value;
+      if (oldestKey !== void 0) {
+        this.map.delete(oldestKey);
+      }
+    }
+    this.map.set(key, value);
+  }
+  setMaxSize(maxSize) {
+    this.maxSize = maxSize;
+    while (this.map.size > this.maxSize) {
+      const oldestKey = this.map.keys().next().value;
+      if (oldestKey === void 0) break;
+      this.map.delete(oldestKey);
+    }
+  }
+  delete(key) {
+    this.map.delete(key);
+  }
+};
+var manifestCache = new LruCache(DEFAULT_MANIFEST_CACHE_MAX_SIZE);
+function configureManifestCache(maxSize) {
+  if (!Number.isInteger(maxSize) || maxSize <= 0) {
+    throw new RouteDockManifestError("Invalid manifest cache size: " + maxSize);
+  }
+  manifestCache.setMaxSize(maxSize);
+}
+function invalidateManifest(baseUrl) {
+  manifestCache.delete(baseUrl);
+}
+function ttlFromHeaders(headers, now) {
+  const cacheControl = headers.get("cache-control");
+  if (cacheControl) {
+    const directives = cacheControl.split(",").map((directive) => directive.trim().toLowerCase());
+    if (directives.includes("no-store") || directives.includes("no-cache")) {
+      return 0;
+    }
+    const maxAge = /max-age=(\d+)/i.exec(cacheControl);
+    if (maxAge) {
+      return Number.parseInt(maxAge[1], 10) * 1e3;
+    }
+  }
+  const expires = headers.get("expires");
+  if (expires) {
+    const expiresTime = Date.parse(expires);
+    if (Number.isFinite(expiresTime)) {
+      return expiresTime - now;
+    }
+  }
+  return CACHE_TTL_MS;
+}
+async function fetchManifest(baseUrl, retryPolicy, manifestTimeoutMs = DEFAULT_MANIFEST_TIMEOUT_MS, expectedPayee) {
   const cached = manifestCache.get(baseUrl);
-  if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+  if (cached && Date.now() < cached.expiresAt) {
+    verifyManifestSignature(cached.manifest, expectedPayee);
+    assertClientVersionSupported(cached.manifest, baseUrl);
+    assertManifestValid(cached.manifest, baseUrl);
+    assertManifestActive(cached.manifest, baseUrl);
     return cached.manifest;
   }
   const url = baseUrl.replace(/\/$/, "") + "/.well-known/routedock.json";
-  let raw;
-  try {
-    const resp = await fetch(url);
-    if (!resp.ok) {
-      throw new RouteDockManifestError(`Manifest fetch failed: HTTP ${resp.status} from ${url}`);
+  return withRetry(async () => {
+    let raw;
+    let resp;
+    let expiresAt = 0;
+    try {
+      resp = await fetch(url, { signal: AbortSignal.timeout(manifestTimeoutMs) });
+      if (!resp.ok) {
+        if (resp.status >= 500 || resp.status === 429 || resp.status === 503) {
+          throw httpStatusToError(
+            `Manifest fetch failed: HTTP ${resp.status} from ${url}`,
+            resp.status,
+            resp
+          );
+        }
+        throw new RouteDockManifestError(
+          `Manifest fetch failed: HTTP ${resp.status} from ${url}`
+        );
+      }
+    } catch (err) {
+      if (err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError")) {
+        throw new RouteDockManifestTimeoutError(
+          `Manifest fetch timed out after ${manifestTimeoutMs}ms from ${url}`,
+          { cause: err }
+        );
+      }
+      if (err instanceof RouteDockError) throw err;
+      throw wrapFetchError(err, `Manifest fetch error from ${url}`);
+    }
+    const now = Date.now();
+    expiresAt = now + ttlFromHeaders(resp.headers, now);
+    try {
+      raw = await resp.json();
+    } 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}`);
+    }
+    const manifest = raw;
+    assertManifestValid(manifest, baseUrl);
+    verifyManifestSignature(manifest, expectedPayee);
+    assertClientVersionSupported(manifest, baseUrl);
+    assertManifestActive(manifest, baseUrl);
+    manifestCache.set(baseUrl, { manifest, fetchedAt: Date.now(), expiresAt });
+    return manifest;
+  }, retryPolicy);
+}
+function selectFromModes(modes, manifest, options) {
+  if (options.sustained || options.session) {
+    if (options.transport === "websocket") {
+      if (modes.includes("mpp-session-ws")) return { mode: "mpp-session-ws" };
+      if (modes.includes("mpp-session")) return { mode: "mpp-session" };
+    } else {
+      if (modes.includes("mpp-session")) return { mode: "mpp-session" };
+      if (modes.includes("mpp-session-ws")) return { mode: "mpp-session-ws" };
+    }
+  }
+  if (options.optimize === "cost") {
+    let budgetStroops = null;
+    if (options.budget_per_request !== void 0) {
+      try {
+        budgetStroops = nulthSdk.usdcToStroops(options.budget_per_request);
+      } catch {
+        throw new RouteDockPolicyRejectError("invalid_budget_per_request");
+      }
+    }
+    const candidates = ["x402", "mpp-charge"].filter((mode) => modes.includes(mode)).flatMap((mode) => {
+      const amount = manifest.pricing[mode]?.amount;
+      if (typeof amount !== "string") return [];
+      try {
+        return [{ mode, amountStroops: nulthSdk.usdcToStroops(amount) }];
+      } catch {
+        return [];
+      }
+    });
+    if (candidates.length > 0) {
+      const affordableCandidates = budgetStroops === null ? candidates : candidates.filter((candidate) => candidate.amountStroops <= budgetStroops);
+      const cheapestCandidate = [...affordableCandidates].sort(
+        (a, b) => a.amountStroops < b.amountStroops ? -1 : a.amountStroops > b.amountStroops ? 1 : 0
+      )[0];
+      if (cheapestCandidate) {
+        return { mode: cheapestCandidate.mode, reason: "cost-optimized" };
+      }
+      if (budgetStroops !== null) {
+        throw new RouteDockPolicyRejectError("budget_per_request_exceeded");
+      }
     }
-    raw = await resp.json();
-  } catch (err) {
-    if (err instanceof RouteDockManifestError) throw err;
-    throw new RouteDockManifestError(`Manifest fetch error: ${String(err)}`);
   }
-  if (!validateManifest(raw)) {
-    const msgs = ajv.errorsText(validateManifest.errors);
-    throw new RouteDockManifestError(`Invalid manifest at ${url}: ${msgs}`);
+  if (modes.includes("mpp-charge")) return { mode: "mpp-charge" };
+  if (modes.includes("x402")) return { mode: "x402" };
+  return void 0;
+}
+function logSelection(manifest, selection, log, deprecated) {
+  const reason = selection.reason ? ` (${selection.reason})` : "";
+  if (deprecated) {
+    log(
+      `[RouteDock] WARNING: ${manifest.name} \u2192 ${selection.mode}${reason}; selected deprecated mode because no active supported mode is available`
+    );
+    return;
   }
-  const manifest = raw;
-  manifestCache.set(baseUrl, { manifest, fetchedAt: Date.now() });
-  return manifest;
+  log(`[RouteDock] ${manifest.name} \u2192 ${selection.mode}${reason}`);
 }
 function selectMode(manifest, options = {}) {
   const modes = manifest.modes;
+  const log = options.logger ?? (() => {
+  });
+  const deprecatedSet = new Set(manifest.deprecated_modes ?? []);
   if (options.forceMode) {
     if (!modes.includes(options.forceMode)) {
       throw new RouteDockNoSupportedModeError(
         `Provider does not support forced mode: ${options.forceMode} (available: ${modes.join(", ")})`
       );
     }
-    console.log(`[RouteDock] ${manifest.name} \u2192 ${options.forceMode} (forced)`);
+    if (deprecatedSet.has(options.forceMode)) {
+      log(
+        `[RouteDock] WARNING: ${manifest.name} \u2192 ${options.forceMode} (forced); selected mode is deprecated`
+      );
+    } else {
+      log(`[RouteDock] ${manifest.name} \u2192 ${options.forceMode} (forced)`);
+    }
     return options.forceMode;
   }
-  if ((options.sustained || options.session) && modes.includes("mpp-session")) {
-    const mode = "mpp-session";
-    console.log(`[RouteDock] ${manifest.name} \u2192 ${mode}`);
-    return mode;
+  const activeModes = modes.filter((mode) => !deprecatedSet.has(mode));
+  const deprecatedModes = modes.filter((mode) => deprecatedSet.has(mode));
+  const activeSelection = selectFromModes(activeModes, manifest, options);
+  if (activeSelection) {
+    logSelection(manifest, activeSelection, log, false);
+    return activeSelection.mode;
   }
-  if (modes.includes("mpp-charge")) {
-    const mode = "mpp-charge";
-    console.log(`[RouteDock] ${manifest.name} \u2192 ${mode}`);
-    return mode;
-  }
-  if (modes.includes("x402")) {
-    const mode = "x402";
-    console.log(`[RouteDock] ${manifest.name} \u2192 ${mode}`);
-    return mode;
+  const deprecatedSelection = selectFromModes(deprecatedModes, manifest, options);
+  if (deprecatedSelection) {
+    logSelection(manifest, deprecatedSelection, log, true);
+    return deprecatedSelection.mode;
   }
   throw new RouteDockNoSupportedModeError(
     `No supported payment mode found in manifest (modes: ${modes.join(", ")})`
   );
 }
+function rankProvidersByLatency(manifests, targetRegion) {
+  return [...manifests].sort((a, b) => {
+    const latA = a.latency_hints?.[targetRegion];
+    const latB = b.latency_hints?.[targetRegion];
+    const inRegionsA = a.regions?.includes(targetRegion) ?? false;
+    const inRegionsB = b.regions?.includes(targetRegion) ?? false;
+    if (latA !== void 0 && latB !== void 0) {
+      return latA - latB;
+    }
+    if (latA !== void 0) return -1;
+    if (latB !== void 0) return 1;
+    if (inRegionsA && !inRegionsB) return -1;
+    if (!inRegionsA && inRegionsB) return 1;
+    return 0;
+  });
+}
 var CAIP2 = {
   testnet: "stellar:testnet",
   mainnet: "stellar:pubnet"
 };
-var X402Client = class {
-  constructor(secretKey, network) {
-    this.secretKey = secretKey;
+var X402Client = class _X402Client {
+  constructor(secretKeyOrSigner, network, retryPolicy) {
     this.network = network;
+    this.retryPolicy = retryPolicy;
     const caip2 = CAIP2[network];
-    const signer = stellar.createEd25519Signer(secretKey, caip2);
-    const scheme = new client.ExactStellarScheme(signer);
+    this.signer = typeof secretKeyOrSigner === "string" ? stellar.createEd25519Signer(secretKeyOrSigner, caip2) : secretKeyOrSigner;
+    const scheme = new client.ExactStellarScheme(this.signer);
     const core = new client$1.x402Client();
     core.register(caip2, scheme);
     this.httpClient = new client$1.x402HTTPClient(core);
   }
-  secretKey;
   network;
+  retryPolicy;
   httpClient;
+  signer;
+  /** Replace signer (e.g. swap to Nulth ZK account payer before pay) */
+  withSigner(signer) {
+    return new _X402Client(signer, this.network, this.retryPolicy);
+  }
   async pay(url, manifest) {
     const pricing = manifest.pricing.x402;
     if (!pricing) {
@@ -295,82 +977,194 @@ var X402Client = class {
     if (!pricing.facilitator) {
       throw new RouteDockManifestError("manifest.pricing.x402.facilitator missing");
     }
-    const init = await fetch(url, { headers: { "X-Preferred-Mode": "x402" } });
-    if (init.status !== 402) {
-      const data2 = await init.json();
-      return { data: data2, txHash: null, mode: "x402", amount: pricing.amount, timestamp: Date.now() };
-    }
-    const reqHeader = init.headers.get("X-Payment-Requirements");
-    if (!reqHeader) {
-      throw new RouteDockManifestError("402 response missing X-Payment-Requirements header");
-    }
-    const paymentRequired = http.decodePaymentRequiredHeader(reqHeader);
-    const paymentPayload = await this.httpClient.createPaymentPayload(paymentRequired);
-    const paymentHeaders = this.httpClient.encodePaymentSignatureHeader(paymentPayload);
-    const settled = await fetch(url, { headers: paymentHeaders });
-    if (!settled.ok) {
-      throw new RouteDockManifestError(`x402 payment failed: HTTP ${settled.status}`);
-    }
-    let txHash = null;
-    const responseHeader = settled.headers.get("X-Payment-Response");
-    if (responseHeader) {
+    return withRetry(async () => {
+      let init;
+      try {
+        init = await fetch(url, { headers: { "X-Preferred-Mode": "x402" } });
+      } catch (err) {
+        throw wrapFetchError(err, "x402 initial request");
+      }
+      if (init.status !== 402) {
+        if (!init.ok) {
+          throw httpStatusToError(
+            `x402 initial request failed: HTTP ${init.status}`,
+            init.status,
+            init
+          );
+        }
+        let data2;
+        try {
+          data2 = await init.json();
+        } catch {
+          throw new RouteDockManifestError(`Failed to parse JSON from non-402 response (HTTP ${init.status})`);
+        }
+        return { data: data2, txHash: null, mode: "x402", amount: "0", timestamp: Date.now() };
+      }
+      const reqHeader = init.headers.get("X-Payment-Requirements");
+      if (!reqHeader) {
+        throw new RouteDockManifestError("402 response missing X-Payment-Requirements header");
+      }
+      let paymentRequired;
       try {
-        const settleResponse = http.decodePaymentResponseHeader(responseHeader);
-        txHash = settleResponse.transaction ?? null;
+        paymentRequired = http.decodePaymentRequiredHeader(reqHeader);
+      } catch (err) {
+        throw new RouteDockManifestError("402 X-Payment-Requirements header is malformed", {
+          cause: err
+        });
+      }
+      let paymentPayload;
+      try {
+        paymentPayload = await this.httpClient.createPaymentPayload(paymentRequired);
+      } catch (err) {
+        throw new RouteDockSignatureError(`x402 payment signing failed: ${String(err)}`, {
+          cause: err
+        });
+      }
+      const paymentHeaders = this.httpClient.encodePaymentSignatureHeader(paymentPayload);
+      let settled;
+      try {
+        settled = await fetch(url, { headers: paymentHeaders });
+      } catch (err) {
+        throw wrapFetchError(err, "x402 settlement request");
+      }
+      if (!settled.ok) {
+        if (settled.status >= 500 || settled.status === 429 || settled.status === 503) {
+          throw httpStatusToError(
+            `x402 payment failed: HTTP ${settled.status}`,
+            settled.status,
+            settled
+          );
+        }
+        throw new RouteDockManifestError(`x402 payment failed: HTTP ${settled.status}`);
+      }
+      let txHash = null;
+      const responseHeader = settled.headers.get("X-Payment-Response");
+      if (responseHeader) {
+        try {
+          const settleResponse = http.decodePaymentResponseHeader(responseHeader);
+          txHash = settleResponse.transaction ?? null;
+        } catch {
+        }
+      }
+      let data;
+      try {
+        data = await settled.json();
       } catch {
+        throw new RouteDockManifestError("Failed to parse JSON from settled response");
       }
-    }
-    const data = await settled.json();
-    return { data, txHash, mode: "x402", amount: pricing.amount, timestamp: Date.now() };
+      return { data, txHash, mode: "x402", amount: pricing.amount, timestamp: Date.now() };
+    }, this.retryPolicy);
   }
 };
 var MppChargeClient = class {
-  constructor(keypair, network) {
+  constructor(keypair, network, retryPolicy) {
     this.keypair = keypair;
     this.network = network;
+    this.retryPolicy = retryPolicy;
   }
   keypair;
   network;
+  retryPolicy;
   async pay(url, manifest) {
     const pricing = manifest.pricing["mpp-charge"];
     if (!pricing) {
       throw new RouteDockManifestError("manifest.pricing.mpp-charge missing");
     }
-    let txHash = null;
-    const mppx = client$2.Mppx.create({
-      polyfill: false,
-      methods: [
-        client$3.stellar.charge({
-          keypair: this.keypair,
-          mode: "pull",
-          onProgress(event) {
-            if (event.type === "paid") {
-              txHash = event.hash;
+    return withRetry(async () => {
+      let txHash = null;
+      const mppx = client$2.Mppx.create({
+        polyfill: false,
+        methods: [
+          client$3.stellar.charge({
+            keypair: this.keypair,
+            mode: "pull",
+            onProgress(event) {
+              if (event.type === "paid") {
+                txHash = event.hash;
+              }
             }
-          }
-        })
-      ]
-    });
-    const response = await mppx.fetch(url);
-    if (!response.ok) {
-      throw new RouteDockManifestError(`MPP charge failed: HTTP ${response.status}`);
-    }
-    const data = await response.json();
-    return { data, txHash, mode: "mpp-charge", amount: pricing.amount, timestamp: Date.now() };
+          })
+        ]
+      });
+      let response;
+      try {
+        response = await mppx.fetch(url);
+      } catch (err) {
+        throw wrapFetchError(err, "MPP charge request");
+      }
+      if (!response.ok) {
+        if (response.status >= 500 || response.status === 429 || response.status === 503) {
+          throw httpStatusToError(
+            `MPP charge failed: HTTP ${response.status}`,
+            response.status,
+            response
+          );
+        }
+        throw new RouteDockManifestError(`MPP charge failed: HTTP ${response.status}`);
+      }
+      let data;
+      try {
+        data = await response.json();
+      } catch (cause) {
+        throw new RouteDockManifestError(
+          `Failed to parse JSON from response (HTTP ${response.status})`,
+          { cause }
+        );
+      }
+      return { data, txHash, mode: "mpp-charge", amount: pricing.amount, timestamp: Date.now() };
+    }, this.retryPolicy);
   }
 };
 var MIN_REFUND_WAITING_PERIOD = 17280;
-var MppSessionClient = class {
-  constructor(keypair, network) {
-    this.keypair = keypair;
+var STREAM_CLEANUP_TIMEOUT_MS = 3e3;
+var WS_CONNECTING = 0;
+var WS_OPEN = 1;
+function defaultWebSocketFactory(url, init, handlers) {
+  const socket = new WebSocket(
+    url,
+    { headers: init.headers }
+  );
+  socket.onopen = () => handlers.onOpen();
+  socket.onmessage = (event) => {
+    const data = event.data;
+    if (typeof data === "string") {
+      handlers.onMessage(data);
+    } else if (data instanceof ArrayBuffer) {
+      handlers.onMessage(Buffer.from(data).toString("utf8"));
+    } else {
+      void data.arrayBuffer().then((buffer) => handlers.onMessage(Buffer.from(buffer).toString("utf8"))).catch(() => {
+      });
+    }
+  };
+  socket.onclose = (event) => handlers.onClose(event.code, event.reason);
+  socket.onerror = () => handlers.onError();
+  return socket;
+}
+function parseIntegerString(value) {
+  return /^\d+$/.test(value) ? BigInt(value) : null;
+}
+function clientCumulativeStoreKey(networkId, channel) {
+  return `stellar:channel:client:${networkId}:${channel}:cumulative`;
+}
+function resolveStoreNetworkId(network) {
+  return network === mpp.STELLAR_PUBNET ? mpp.STELLAR_PUBNET : mpp.STELLAR_TESTNET;
+}
+var MppSessionClient = class {
+  constructor(keypair, network, retryPolicy, webSocketFactory = defaultWebSocketFactory) {
+    this.keypair = keypair;
     this.network = network;
+    this.retryPolicy = retryPolicy;
+    this.webSocketFactory = webSocketFactory;
   }
   keypair;
   network;
-  async openSession(url, manifest, commitmentSecret) {
-    const pricing = manifest.pricing["mpp-session"];
+  retryPolicy;
+  webSocketFactory;
+  async openSession(url, manifest, commitmentSecret, options, onSpend) {
+    const mode = options?.mode ?? "mpp-session";
+    const pricing = manifest.pricing[mode];
     if (!pricing) {
-      throw new RouteDockManifestError("manifest.pricing.mpp-session missing");
+      throw new RouteDockManifestError(`manifest.pricing.${mode} missing`);
     }
     const refundPeriod = pricing.refund_waiting_period_ledgers;
     if (refundPeriod < MIN_REFUND_WAITING_PERIOD) {
@@ -379,166 +1173,1383 @@ var MppSessionClient = class {
       );
     }
     const commitmentKey = stellarSdk.Keypair.fromSecret(commitmentSecret);
-    const channelContract = pricing.channel_contract;
+    const channelFactory = pricing.channel_factory;
     const agentPublicKey = this.keypair.publicKey();
+    const agentKeypair = this.keypair;
     let currentCumulative = 0n;
     let vouchersIssued = 0;
+    let rateStroops;
+    try {
+      rateStroops = nulthSdk.usdcToStroops(pricing.rate);
+    } catch (err) {
+      throw new RouteDockManifestError(
+        `manifest.pricing.${mode}.rate is not a valid USDC amount: "${pricing.rate}"`,
+        { cause: err }
+      );
+    }
+    const store = options?.store;
+    let reservedCumulative = null;
+    let storeSeed;
+    const seedFromStore = (networkId, channel) => {
+      storeSeed ??= Promise.resolve(
+        store.get(clientCumulativeStoreKey(networkId, channel))
+      ).then((stored) => {
+        if (stored && typeof stored === "object" && "amount" in stored) {
+          const raw = stored.amount;
+          const amount = typeof raw === "string" ? parseIntegerString(raw) : null;
+          if (amount === null) {
+            throw new RouteDockChannelStateError(
+              `Stored cumulative for channel ${channel} is not an integer string: ${JSON.stringify(raw)}`
+            );
+          }
+          return amount;
+        }
+        return 0n;
+      });
+      return storeSeed;
+    };
+    const reserveNextCumulative = async (challenge) => {
+      const request = challenge.request;
+      const channelValue = request["channel"];
+      if (typeof channelValue !== "string" || channelValue !== channelFactory) {
+        throw new RouteDockChannelStateError(
+          `Challenge names channel ${String(channelValue)}, but the manifest channel_factory is ${channelFactory}`
+        );
+      }
+      const amountValue = request["amount"];
+      const amount = typeof amountValue === "string" ? parseIntegerString(amountValue) : null;
+      if (amount === null) {
+        throw new RouteDockChannelStateError(
+          `Challenge request.amount is not a base-10 integer string: ${JSON.stringify(amountValue)}`
+        );
+      }
+      if (amount !== rateStroops) {
+        throw new RouteDockChannelStateError(
+          `Challenge request.amount ${amount} does not match the manifest rate ${rateStroops} stroops per voucher`
+        );
+      }
+      const methodDetailsValue = request["methodDetails"];
+      const methodDetails = methodDetailsValue !== null && typeof methodDetailsValue === "object" ? methodDetailsValue : void 0;
+      let serverReported = 0n;
+      if (methodDetails && "cumulativeAmount" in methodDetails) {
+        const rawCumulative = methodDetails["cumulativeAmount"];
+        const parsed = typeof rawCumulative === "string" ? parseIntegerString(rawCumulative) : null;
+        if (parsed === null) {
+          throw new RouteDockChannelStateError(
+            `Challenge methodDetails.cumulativeAmount is not a base-10 integer string: ${JSON.stringify(rawCumulative)}`
+          );
+        }
+        serverReported = parsed;
+      }
+      let baseline = reservedCumulative;
+      if (baseline === null) {
+        if (store) {
+          const challengedNetwork = methodDetails?.["network"];
+          const seeded = await seedFromStore(
+            resolveStoreNetworkId(
+              typeof challengedNetwork === "string" ? challengedNetwork : void 0
+            ),
+            channelValue
+          );
+          baseline = reservedCumulative ?? seeded;
+        } else if (serverReported === 0n) {
+          baseline = 0n;
+        } else {
+          throw new RouteDockChannelStateError(
+            `Challenge reports cumulative ${serverReported} for a channel this client has no baseline for. Pass a \`store\` in SessionOptions so the signed cumulative survives restarts, or close the channel before reusing it.`
+          );
+        }
+      }
+      if (serverReported > baseline) {
+        throw new RouteDockChannelStateError(
+          `Challenge reports cumulative ${serverReported}, above the locally reserved baseline ${baseline}`
+        );
+      }
+      const next = baseline + rateStroops;
+      reservedCumulative = next;
+      return next;
+    };
+    const releaseReservation = (reserved) => {
+      if (reservedCumulative === reserved) {
+        reservedCumulative = reserved - rateStroops;
+      }
+    };
+    const createGuardedCredential = async (challenge, create) => {
+      const next = await reserveNextCumulative(challenge);
+      try {
+        return await create(next.toString());
+      } catch (err) {
+        releaseReservation(next);
+        throw err;
+      }
+    };
+    const streamWs = (u, m, createCredential, onSigned) => this.streamWebSocket(u, m, createCredential, onSigned);
     const mppx = client$2.Mppx.create({
       polyfill: false,
       methods: [
         client$4.stellar.channel({
           commitmentKey,
           sourceAccount: this.keypair.publicKey(),
+          ...store ? { store } : {},
           onProgress(event) {
             if (event.type === "signed") {
               currentCumulative = BigInt(event.cumulativeAmount);
             }
           }
         })
-      ]
+      ],
+      // mppx runs onChallenge on the HTTP path only (createCredential skips it),
+      // so the WebSocket path runs the same guard inside streamWebSocket.
+      onChallenge: (challenge, helpers) => createGuardedCredential(
+        challenge,
+        (cumulativeAmount) => helpers.createCredential({ cumulativeAmount })
+      )
     });
-    const openTxHash = channelContract;
+    const retryPolicy = this.retryPolicy;
+    const maxDurationMs = options?.maxDurationMs ?? DEFAULT_MAX_SESSION_DURATION_MS;
+    const listeners = /* @__PURE__ */ new Map();
+    let timeoutId;
+    let closed = false;
+    const emit = (event, payload) => {
+      const set = listeners.get(event);
+      if (!set) return;
+      for (const listener of set) {
+        try {
+          const returned = listener(payload);
+          if (returned && typeof returned.then === "function") {
+            void Promise.resolve(returned).catch(() => {
+            });
+          }
+        } catch {
+        }
+      }
+    };
+    const clearSessionTimer = () => {
+      if (timeoutId !== void 0) {
+        clearTimeout(timeoutId);
+        timeoutId = void 0;
+      }
+    };
+    const network = this.network;
     const handle = {
-      channelId: channelContract,
-      openTxHash,
-      async *stream() {
-        while (true) {
-          let resp = null;
-          for (let attempt = 0; attempt < 3; attempt++) {
-            try {
-              resp = await mppx.fetch(url);
-              if (resp.ok) break;
-              resp = null;
-            } catch {
-              if (attempt === 2) throw new RouteDockSessionError("Voucher request failed after 3 retries");
-              await new Promise((r) => setTimeout(r, 1e3 * (attempt + 1)));
+      channelId: channelFactory,
+      // The channel is pre-deployed and funded before the agent runs, so the
+      // client never issues the channel-open transaction and has no hash for
+      // it. Report null rather than the contract address (a non-transaction
+      // identifier that produces broken explorer links downstream).
+      openTxHash: null,
+      /**
+       * Live session snapshot. vouchersIssued increments once per signed voucher
+       * and currentCumulative is updated by the channel client's onProgress when
+       * a voucher is signed, so a stats() call immediately after a yield always
+       * reflects everything consumed so far.
+       */
+      stats() {
+        return {
+          vouchersIssued,
+          // Same conversion as SessionCloseResult.totalPaid so a per-session
+          // sub-cap can be compared against stats().currentCumulative directly.
+          currentCumulative: (Number(currentCumulative) / 1e7).toFixed(7),
+          channelId: channelFactory,
+          openTxHash: null
+        };
+      },
+      async *stream(options2) {
+        const checkSpend = () => {
+          if (!onSpend) return Promise.resolve();
+          return onSpend(pricing.rate);
+        };
+        if (mode === "mpp-session-ws") {
+          await checkSpend();
+          const onSigned = () => {
+            vouchersIssued++;
+          };
+          for await (const item of streamWs(url, mppx, createGuardedCredential, onSigned)) {
+            yield item;
+          }
+          return;
+        }
+        const concurrency = Math.max(1, options2?.concurrency ?? 1);
+        const assertOpen = () => {
+          if (closed) {
+            throw new RouteDockChannelStateError("session closed");
+          }
+        };
+        const abortController = new AbortController();
+        const doFetch = () => withRetry(async () => {
+          let resp;
+          try {
+            resp = await mppx.fetch(url, { signal: abortController.signal });
+          } catch (err) {
+            if (abortController.signal.aborted) {
+              throw err;
+            }
+            throw wrapFetchError(err, "Voucher request");
+          }
+          if (!resp.ok) {
+            if (resp.status >= 500 || resp.status === 429 || resp.status === 503) {
+              throw httpStatusToError(
+                `Voucher request failed: HTTP ${resp.status}`,
+                resp.status,
+                resp
+              );
             }
+            throw new RouteDockChannelStateError(
+              `Voucher request failed: HTTP ${resp.status}`
+            );
           }
-          if (!resp || !resp.ok) {
-            throw new RouteDockSessionError(`Voucher request failed: HTTP ${resp?.status ?? "unknown"}`);
+          try {
+            return await resp.json();
+          } catch (cause) {
+            throw new RouteDockChannelStateError(
+              `Voucher response was not valid JSON (HTTP ${resp.status})`,
+              { cause }
+            );
+          }
+        }, retryPolicy);
+        if (concurrency === 1) {
+          try {
+            while (true) {
+              assertOpen();
+              await checkSpend();
+              const data = await doFetch();
+              vouchersIssued++;
+              yield data;
+            }
+          } finally {
+            abortController.abort();
+          }
+        } else {
+          const queue = [];
+          try {
+            for (let i = 0; i < concurrency; i++) {
+              assertOpen();
+              await checkSpend();
+              const p = doFetch();
+              p.catch(() => {
+              });
+              queue.push(p);
+            }
+            while (true) {
+              assertOpen();
+              const data = await queue.shift();
+              await checkSpend();
+              const p = doFetch();
+              p.catch(() => {
+              });
+              queue.push(p);
+              vouchersIssued++;
+              yield data;
+            }
+          } finally {
+            abortController.abort();
+            let timer;
+            try {
+              await Promise.race([
+                Promise.allSettled(queue),
+                new Promise((resolve) => {
+                  timer = setTimeout(resolve, STREAM_CLEANUP_TIMEOUT_MS);
+                  timer.unref?.();
+                })
+              ]);
+            } finally {
+              if (timer) {
+                clearTimeout(timer);
+              }
+            }
+            queue.length = 0;
           }
-          vouchersIssued++;
-          yield await resp.json();
         }
       },
       async close() {
+        clearSessionTimer();
+        closed = true;
         const { rpc: rpcMod, Contract, nativeToScVal, TransactionBuilder, BASE_FEE } = await import('@stellar/stellar-sdk');
-        const rpcUrl = "https://soroban-testnet.stellar.org";
+        const rpcUrl = network === "testnet" ? "https://soroban-testnet.stellar.org" : "https://soroban.stellar.org";
         const server = new rpcMod.Server(rpcUrl);
-        const contract = new Contract(channelContract);
-        const passphrase = "Test SDF Network ; September 2015";
-        const account = await server.getAccount(agentPublicKey);
-        const simTx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase: passphrase }).addOperation(contract.call("prepare_commitment", nativeToScVal(currentCumulative, { type: "i128" }))).setTimeout(30).build();
-        const simResult = await server.simulateTransaction(simTx);
+        const contract = new Contract(channelFactory);
+        const passphrase = network === "mainnet" ? stellarSdk.Networks.PUBLIC : stellarSdk.Networks.TESTNET;
+        const account = await withRetry(async () => {
+          try {
+            return await server.getAccount(agentPublicKey);
+          } catch (err) {
+            throw wrapFetchError(err, "Horizon getAccount");
+          }
+        }, retryPolicy);
+        const simResult = await withRetry(async () => {
+          try {
+            const simTx = new TransactionBuilder(account, {
+              fee: BASE_FEE,
+              networkPassphrase: passphrase
+            }).addOperation(
+              contract.call(
+                "prepare_commitment",
+                nativeToScVal(currentCumulative, { type: "i128" })
+              )
+            ).setTimeout(30).build();
+            return await server.simulateTransaction(simTx);
+          } catch (err) {
+            throw wrapFetchError(err, "prepare_commitment RPC");
+          }
+        }, retryPolicy);
         if (rpcMod.Api.isSimulationError(simResult)) {
-          throw new RouteDockSessionError(`prepare_commitment simulation failed: ${simResult.error}`);
+          throw new RouteDockChannelStateError(
+            `prepare_commitment simulation failed: ${simResult.error}`
+          );
         }
         const commitmentBytes = simResult.result?.retval?.bytes();
-        if (!commitmentBytes) throw new RouteDockSessionError("prepare_commitment returned no bytes");
-        const signature = commitmentKey.sign(Buffer.from(commitmentBytes));
-        const closeResp = await fetch(url, {
-          method: "DELETE",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({
-            amount: currentCumulative.toString(),
-            signature: Buffer.from(signature).toString("hex")
-          })
-        });
-        if (!closeResp.ok) {
-          throw new RouteDockSessionError(`Channel close failed: HTTP ${closeResp.status}`);
+        if (!commitmentBytes) {
+          throw new RouteDockChannelStateError("prepare_commitment returned no bytes");
         }
-        const closeData = await closeResp.json();
-        const closeTxHash = closeData.closeTxHash ?? null;
-        if (!closeTxHash) {
-          throw new RouteDockSessionError("Channel close response missing closeTxHash");
+        let signature;
+        try {
+          signature = commitmentKey.sign(Buffer.from(commitmentBytes));
+        } catch (err) {
+          throw new RouteDockSignatureError("Channel close commitment signing failed", {
+            cause: err
+          });
         }
+        const closeData = await withRetry(async () => {
+          let closeResp;
+          try {
+            closeResp = await fetch(url, {
+              method: "DELETE",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({
+                amount: currentCumulative.toString(),
+                signature: Buffer.from(signature).toString("hex")
+              })
+            });
+          } catch (err) {
+            throw wrapFetchError(err, "Channel close request");
+          }
+          if (!closeResp.ok) {
+            if (closeResp.status >= 500 || closeResp.status === 429 || closeResp.status === 503) {
+              throw httpStatusToError(
+                `Channel close failed: HTTP ${closeResp.status}`,
+                closeResp.status,
+                closeResp
+              );
+            }
+            throw new RouteDockChannelStateError(
+              `Channel close failed: HTTP ${closeResp.status}`
+            );
+          }
+          let body;
+          try {
+            body = await closeResp.json();
+          } catch (cause) {
+            throw new RouteDockChannelStateError(
+              `Channel close response was not valid JSON (HTTP ${closeResp.status})`,
+              { cause }
+            );
+          }
+          const closeTxHash = body.closeTxHash ?? null;
+          if (!closeTxHash) {
+            throw new RouteDockChannelStateError(
+              "Channel close response missing closeTxHash"
+            );
+          }
+          return { closeTxHash, body };
+        }, retryPolicy);
         const totalPaid = (Number(currentCumulative) / 1e7).toFixed(7);
-        return { closeTxHash, totalPaid, vouchersIssued };
+        return {
+          closeTxHash: closeData.closeTxHash,
+          totalPaid,
+          vouchersIssued
+        };
+      },
+      async requestRefund() {
+        const { rpc: rpcMod, Contract, TransactionBuilder, BASE_FEE } = 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 Contract(channelFactory);
+        const passphrase = network === "mainnet" ? stellarSdk.Networks.PUBLIC : stellarSdk.Networks.TESTNET;
+        try {
+          const account = await server.getAccount(agentPublicKey);
+          const tx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase: passphrase }).addOperation(contract.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}`);
+          }
+          const preparedTx = await server.prepareTransaction(tx);
+          preparedTx.sign(agentKeypair);
+          const result = await server.sendTransaction(preparedTx);
+          if (result.status === "ERROR") {
+            const errDetail = result.errorResult ? JSON.stringify(result.errorResult) : "status ERROR";
+            throw new RouteDockDisputeError(`Refund request transaction failed: ${errDetail}`);
+          }
+          if (!result.hash) {
+            throw new RouteDockDisputeError("Refund request transaction not sent");
+          }
+          return result.hash;
+        } 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, nativeToScVal, TransactionBuilder, BASE_FEE } = 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 Contract(channelFactory);
+        const passphrase = network === "mainnet" ? stellarSdk.Networks.PUBLIC : stellarSdk.Networks.TESTNET;
+        try {
+          const account = await server.getAccount(agentPublicKey);
+          const simTx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase: passphrase }).addOperation(contract.call("prepare_commitment", nativeToScVal(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 settleAccount = await server.getAccount(agentPublicKey);
+          const settleTx = new TransactionBuilder(settleAccount, { fee: BASE_FEE, networkPassphrase: passphrase }).addOperation(
+            contract.call(
+              "settle_with_signature",
+              nativeToScVal(currentCumulative, { type: "i128" }),
+              nativeToScVal(Buffer.from(signature))
+            )
+          ).setTimeout(30).build();
+          const preparedSettleTx = await server.prepareTransaction(settleTx);
+          preparedSettleTx.sign(agentKeypair);
+          const settleResult = await server.sendTransaction(preparedSettleTx);
+          if (settleResult.status === "ERROR") {
+            const errDetail = settleResult.errorResult ? JSON.stringify(settleResult.errorResult) : "status ERROR";
+            throw new RouteDockDisputeError(`Settlement transaction failed: ${errDetail}`);
+          }
+          if (!settleResult.hash) {
+            throw new RouteDockDisputeError("Settlement transaction not sent");
+          }
+          return settleResult.hash;
+        } catch (err) {
+          if (err instanceof RouteDockDisputeError) throw err;
+          throw new RouteDockDisputeError(`Failed to settle with latest voucher: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      },
+      async getDisputeStatus() {
+        const { rpc: rpcMod, Contract, TransactionBuilder, BASE_FEE } = 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 Contract(channelFactory);
+        const passphrase = network === "mainnet" ? stellarSdk.Networks.PUBLIC : stellarSdk.Networks.TESTNET;
+        try {
+          const account = await server.getAccount(agentPublicKey);
+          const tx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase: passphrase }).addOperation(contract.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}`);
+          }
+          const retval = simResult.result?.retval;
+          if (!retval) {
+            throw new RouteDockChannelStateError("No channel state returned");
+          }
+          if (typeof retval === "object" && retval !== null) {
+            const status = retval.status;
+            if (status === "open") return "open";
+            if (status === "in_refund_window") return "in-refund-window";
+            if (status === "refundable") return "refundable";
+            if (status === "settled") return "settled";
+          }
+          return "open";
+        } catch (err) {
+          if (err instanceof RouteDockChannelStateError) throw err;
+          throw new RouteDockChannelStateError(`Failed to get dispute status: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      },
+      on(event, listener) {
+        let set = listeners.get(event);
+        if (!set) {
+          set = /* @__PURE__ */ new Set();
+          listeners.set(event, set);
+        }
+        const stored = listener;
+        set.add(stored);
+        return () => {
+          set?.delete(stored);
+        };
       }
     };
+    if (Number.isFinite(maxDurationMs) && maxDurationMs > 0) {
+      timeoutId = setTimeout(() => {
+        if (closed) return;
+        emit("session:timeout", { maxDurationMs });
+        void handle.close().catch((error) => {
+          emit("session:close-failed", { maxDurationMs, error });
+          console.warn(
+            `RouteDock: maxDuration auto-close failed after ${maxDurationMs}ms \u2014 the channel may still hold collateral; retry close() or call requestRefund().`,
+            error
+          );
+        });
+      }, maxDurationMs);
+      timeoutId.unref?.();
+    }
     return handle;
   }
+  /**
+   * mpp-session-ws streaming transport.
+   *
+   * Mirrors the issue's three-step sequence:
+   *   1. open the channel — probe the provider URL over HTTP;
+   *   2. negotiate the voucher — sign the mppx 402 challenge into a credential;
+   *   3. upgrade the HTTP connection to WebSocket — hand the signed voucher to
+   *      the provider as the Authorization header of the WebSocket handshake.
+   *
+   * Each server frame is yielded (JSON frames parsed; raw strings yielded
+   * as-is). The stream ends when the server closes the socket with a normal
+   * close code (1000/1001); abnormal closes and connection failures surface as
+   * RouteDockChannelStateError.
+   */
+  async *streamWebSocket(url, mppx$1, createCredential, onSigned) {
+    const request = { method: "GET" };
+    let probe;
+    try {
+      probe = await mppx$1.rawFetch(url, request);
+    } catch (err) {
+      throw wrapFetchError(err, "Voucher request");
+    }
+    if (probe.status !== 402) {
+      if (probe.status >= 500 || probe.status === 429 || probe.status === 503) {
+        throw httpStatusToError(
+          `Voucher request failed: HTTP ${probe.status}`,
+          probe.status,
+          probe
+        );
+      }
+      throw new RouteDockChannelStateError(
+        `Voucher request failed: expected HTTP 402 challenge, got HTTP ${probe.status}`
+      );
+    }
+    let credential;
+    try {
+      credential = await createCredential(
+        mppx.Challenge.fromResponse(probe),
+        (cumulativeAmount) => mppx$1.createCredential(probe, { cumulativeAmount })
+      );
+      onSigned?.();
+    } catch (err) {
+      throw wrapFetchError(err, "Voucher credential");
+    }
+    const wsUrl = url.replace(/^http/, "ws");
+    const queue = [];
+    const waiters = [];
+    const drain = () => {
+      while (queue.length > 0 && waiters.length > 0) {
+        const waiter = waiters.shift();
+        waiter(queue.shift());
+      }
+    };
+    const nextEvent = () => queue.length > 0 ? Promise.resolve(queue.shift()) : new Promise((resolve) => {
+      waiters.push(resolve);
+    });
+    const socket = this.webSocketFactory(
+      wsUrl,
+      { headers: { authorization: credential } },
+      {
+        onOpen: () => {
+          queue.push({ type: "open" });
+          drain();
+        },
+        onMessage: (data) => {
+          queue.push({ type: "message", data });
+          drain();
+        },
+        onClose: (code, reason) => {
+          queue.push({ type: "close", code, reason });
+          drain();
+        },
+        onError: () => {
+          queue.push({ type: "error" });
+          drain();
+        }
+      }
+    );
+    try {
+      for (; ; ) {
+        const event = await nextEvent();
+        if (event.type === "open") break;
+        if (event.type === "error") {
+          throw new RouteDockChannelStateError(
+            "WebSocket upgrade failed: connection error"
+          );
+        }
+        if (event.type === "close") {
+          throw new RouteDockChannelStateError(
+            `WebSocket upgrade failed: server closed the connection before upgrading (code ${event.code})`
+          );
+        }
+      }
+      for (; ; ) {
+        const event = await nextEvent();
+        if (event.type === "message") {
+          let parsed = event.data;
+          try {
+            parsed = JSON.parse(event.data);
+          } catch {
+          }
+          yield parsed;
+          continue;
+        }
+        if (event.type === "error") {
+          throw new RouteDockChannelStateError("WebSocket connection error");
+        }
+        if (event.type === "open") continue;
+        if (event.code === 1e3 || event.code === 1001) {
+          return;
+        }
+        throw new RouteDockChannelStateError(
+          `WebSocket stream ended abnormally (code ${event.code}${event.reason ? `: ${event.reason}` : ""})`
+        );
+      }
+    } finally {
+      if (socket.readyState === WS_CONNECTING || socket.readyState === WS_OPEN) {
+        socket.close(1e3, "stream ended");
+      }
+    }
+  }
+};
+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.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;
+  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.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)})`
+      );
+    }
+    console.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 (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");
+    }
+  }
+};
+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") {
+    throw new RouteDockManifestError(`Provider vault mode ${manifest.vault} does not match client nulth vault`);
+  }
+  if (manifest.nulth_account && manifest.nulth_account !== nulthAccount) {
+    throw new RouteDockManifestError(`Manifest nulth_account ${manifest.nulth_account} does not match configured ${nulthAccount}`);
+  }
+}
+async function fetchLedgerSequence(network) {
+  const rpcUrl = network === "testnet" ? "https://soroban-testnet.stellar.org" : "https://soroban.stellar.org";
+  const server = new stellarSdk.rpc.Server(rpcUrl);
+  const latest = await server.getLatestLedger();
+  return latest.sequence;
+}
+async function prepareNulthSigner(vault, manifest, mode, network, ledgerSequenceOverride) {
+  assertNulthVaultManifest(manifest, vault.nulthAccount);
+  const prover = vault.prover ?? "mock";
+  if (network === "mainnet" && prover === "mock") {
+    throw new RouteDockManifestError(
+      "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);
+  }
+};
+
+// src/store/SpendStore.ts
+var InMemorySpendStore = class {
+  state = null;
+  constructor(options = {}) {
+    if (options.warn !== false) {
+      console.warn(
+        "[RouteDock] Using in-memory SpendStore: the daily spend cap is NOT durable and resets on every process restart. Inject a persistent SpendStore via RouteDockClientConfig.spendStore for production safety."
+      );
+    }
+  }
+  async read() {
+    return this.state ? { ...this.state, endpoints: { ...this.state.endpoints } } : null;
+  }
+  async write(state) {
+    this.state = { ...state, endpoints: { ...state.endpoints } };
+  }
 };
 
 // src/client/RouteDockClient.ts
-var RouteDockClient = class {
+var _secrets = /* @__PURE__ */ new WeakMap();
+function normalizeEndpointCaps(endpointCaps) {
+  if (!endpointCaps) return void 0;
+  const normalized = {};
+  for (const [key, value] of Object.entries(endpointCaps)) {
+    let url;
+    try {
+      url = new URL(key);
+    } catch {
+      throw new RouteDockManifestError(
+        `spendCap.endpointCaps key "${key}" is not a valid URL \u2014 use an origin such as "https://api.example.com"`
+      );
+    }
+    if (url.pathname !== "/" || url.search !== "" || url.hash !== "") {
+      throw new RouteDockManifestError(
+        `spendCap.endpointCaps key "${key}" must be an origin only (no path, query, or hash) \u2014 use "${url.origin}"`
+      );
+    }
+    const origin = url.origin;
+    if (Object.prototype.hasOwnProperty.call(normalized, origin)) {
+      throw new RouteDockManifestError(
+        `spendCap.endpointCaps has two keys that both normalize to origin "${origin}" \u2014 remove the duplicate`
+      );
+    }
+    normalized[origin] = value;
+  }
+  return normalized;
+}
+function normalizeSpendCap(spendCap) {
+  const endpointCaps = normalizeEndpointCaps(spendCap.endpointCaps);
+  return endpointCaps === void 0 ? spendCap : { ...spendCap, endpointCaps };
+}
+var usdcToMicros = nulthSdk.usdcToStroops;
+var ASSET_ISSUERS = {
+  USDC: USDC_ISSUERS
+};
+function getAssetIssuer(asset, network) {
+  return ASSET_ISSUERS[asset]?.[network] ?? "";
+}
+var TRUSTLINE_CACHE_TTL_MS = 3e5;
+var RouteDockClient = class _RouteDockClient {
+  /** Per-(account,asset) trustline existence cache keyed by `${network}:${pubkey}:${asset}` */
+  static _trustlineCache = /* @__PURE__ */ new Map();
   keypair;
   network;
   spendCap;
-  commitmentSecret;
-  /** Local daily accumulator keyed by YYYY-MM-DD */
-  dailySpend = { date: "", total: 0 };
+  retryPolicy;
+  logger;
+  manifestTimeoutMs;
+  expectedPayee;
+  vault;
+  /**
+   * Durable backing store for the local daily spend accumulator (keyed by
+   * YYYY-MM-DD). Totals are persisted as decimal strings of microUSDC
+   * (1 USDC = 10^7) so stores stay JSON-safe with no precision loss.
+   */
+  spendStore;
   x402;
   charge;
   session;
+  /**
+   * Promise-chain mutex for serializing read-modify-write on the spend
+   * accumulator. Each pay() call awaits the previous one, preventing
+   * concurrent read-modify-write races that could overrun the cap.
+   */
+  _spendMutex = Promise.resolve();
+  /**
+   * Pending spend reservations keyed by reserveId. Used by _rollbackSpend
+   * to revert the accumulator when a payment fails after reservation.
+   */
+  _pendingReserves = /* @__PURE__ */ new Map();
   constructor(config) {
     this.keypair = typeof config.wallet === "string" ? stellarSdk.Keypair.fromSecret(config.wallet) : config.wallet;
     this.network = config.network;
-    this.spendCap = config.spendCap;
-    this.commitmentSecret = config.commitmentSecret;
+    this.spendCap = config.spendCap ? normalizeSpendCap(config.spendCap) : void 0;
+    this.retryPolicy = config.retryPolicy;
+    this.spendStore = config.spendStore ?? new InMemorySpendStore({ warn: !!config.spendCap });
+    this.logger = config.logger;
+    this.manifestTimeoutMs = config.manifestTimeoutMs;
+    this.expectedPayee = config.expectedPayee;
+    if (config.commitmentSecret) {
+      _secrets.set(this, config.commitmentSecret);
+    }
+    this.vault = config.vault;
+    if (config.commitmentSecret) {
+      _secrets.set(this, config.commitmentSecret);
+    }
     const secretKey = this.keypair.secret();
-    this.x402 = new X402Client(secretKey, this.network);
-    this.charge = new MppChargeClient(this.keypair, this.network);
-    this.session = new MppSessionClient(this.keypair, this.network);
+    this.x402 = new X402Client(secretKey, this.network, this.retryPolicy);
+    this.charge = new MppChargeClient(this.keypair, this.network, this.retryPolicy);
+    this.session = new MppSessionClient(this.keypair, this.network, this.retryPolicy);
+  }
+  /** Fetch manifest and select mode — shared by pay() and estimateCost(). */
+  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);
+    const mode = selectMode(manifest, options);
+    return { manifest, mode };
+  }
+  /**
+   * Serialize async work through the per-instance spend mutex so concurrent
+   * pay() calls cannot interleave read-modify-write on the accumulator.
+   */
+  _withSpendMutex(fn) {
+    const prev = this._spendMutex;
+    let next;
+    next = prev.then(fn, fn);
+    this._spendMutex = next.then(() => {
+    }, () => {
+    });
+    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) {
+    assertManifestValid(manifest);
+    await this._checkTrustline(manifest);
+    return {
+      hasTrustline: true,
+      asset: manifest.asset,
+      modes: manifest.modes,
+      ...manifest.regions && { regions: manifest.regions },
+      ...manifest.latency_hints && { latency_hints: manifest.latency_hints },
+      ...manifest.capabilities && { capabilities: manifest.capabilities }
+    };
+  }
+  /**
+   * Verify via Horizon that the payer account has a trustline for the
+   * payment asset declared in the manifest. Throws RouteDockTrustlineError
+   * with an exact Stellar CLI change-trust remediation command when the
+   * trustline is missing. Results are cached per (account, asset) so the
+   * per-payment overhead is one RPC call amortized to zero after the first.
+   */
+  async _checkTrustline(manifest) {
+    const cacheKey = `${this.network}:${this.keypair.publicKey()}:${manifest.asset}`;
+    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);
+    try {
+      const account = await server.loadAccount(this.keypair.publicKey());
+      const balances = account.balances;
+      const expectedIssuer = getAssetIssuer(manifest.asset, this.network);
+      const hasTrustline = balances.some(
+        (b) => typeof b === "object" && b !== null && "asset_code" in b && b.asset_code === manifest.asset && (!expectedIssuer || b.asset_issuer === expectedIssuer)
+      );
+      if (!hasTrustline) {
+        const remediation = expectedIssuer ? `Run: stellar tx new --source ${this.keypair.publicKey()} --network ${this.network} change-trust --asset ${manifest.asset}:${expectedIssuer} --limit 100000` : `Establish a trustline for ${manifest.asset} with the appropriate issuer on ${this.network}`;
+        throw new RouteDockTrustlineError(manifest.asset, expectedIssuer || "unknown", remediation);
+      }
+      _RouteDockClient._trustlineCache.set(cacheKey, {
+        exists: true,
+        expiresAt: Date.now() + TRUSTLINE_CACHE_TTL_MS
+      });
+    } catch (err) {
+      if (err instanceof RouteDockTrustlineError) throw err;
+      this.logger?.(
+        `[RouteDock] Trustline preflight: could not verify trustline for ${manifest.asset} \u2014 continuing`
+      );
+    }
   }
   /**
    * Pay for one request at `url`. Fetches manifest, selects payment mode,
-   * checks local spend cap, executes payment, returns result.
+   * runs trustline preflight, reserves local spend cap BEFORE executing the
+   * payment, then commits the spend record on success. Rolls back the
+   * reservation if the on-chain payment fails. Concurrent pay() calls are
+   * serialized through a per-instance mutex to prevent spend-cap overrun.
    */
   async pay(url, options) {
     const baseUrl = new URL(url).origin;
-    const manifest = await fetchManifest(baseUrl);
-    const mode = selectMode(manifest, options);
-    let result;
+    const manifest = await fetchManifest(baseUrl, this.retryPolicy, this.manifestTimeoutMs, this.expectedPayee);
+    assertEndpointActive(manifest, url, this.logger);
+    const mode = selectMode(manifest, { ...options, ...this.logger && { logger: this.logger } });
+    await this._checkTrustline(manifest);
+    if (this.vault?.mode === "nulth") {
+      return this._payWithNulthVault(url, manifest, mode);
+    }
+    let amount;
     switch (mode) {
       case "x402":
-        result = await this.x402.pay(url, manifest);
+        amount = manifest.pricing.x402.amount;
         break;
       case "mpp-charge":
-        result = await this.charge.pay(url, manifest);
+        amount = manifest.pricing["mpp-charge"].amount;
         break;
       case "mpp-session":
+      case "mpp-session-ws":
         throw new RouteDockManifestError(
-          "Use client.openSession() for mpp-session mode \u2014 client.pay() only handles discrete payments"
+          `Use client.openSession() for ${mode} mode \u2014 client.pay() only handles discrete payments`
         );
       default:
         throw new RouteDockManifestError(`Unknown payment mode: ${mode}`);
     }
-    this._checkAndRecordSpend(result.amount);
+    const reserveId = await this._checkAndReserveSpend(amount, baseUrl);
+    let result;
+    try {
+      switch (mode) {
+        case "x402":
+          result = await this.x402.pay(url, manifest);
+          break;
+        case "mpp-charge":
+          result = await this.charge.pay(url, manifest);
+          break;
+        default:
+          throw new RouteDockManifestError(`Unknown payment mode: ${mode}`);
+      }
+    } catch (err) {
+      await this._rollbackSpend(reserveId).catch(() => {
+      });
+      throw err;
+    }
+    await this._commitSpend(reserveId);
     return result;
   }
+  /** Nulth ZK vault path — proof built off-chain, attached as auth signature */
+  async _payWithNulthVault(url, manifest, mode) {
+    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");
+    }
+    if (mode !== "x402") {
+      throw new RouteDockManifestError(
+        'nulth vault currently supports x402 mode \u2014 force x402 via { forceMode: "x402" }'
+      );
+    }
+    try {
+      const { signer } = await prepareNulthSigner(this.vault, manifest, mode, this.network);
+      const x402 = this.x402.withSigner(signer);
+      const result = await x402.pay(url, manifest);
+      return result;
+    } catch (err) {
+      if (err instanceof NulthPolicyError) {
+        throw new RouteDockPolicyRejectError(err.code);
+      }
+      throw err;
+    }
+  }
+  /**
+   * Resolve manifest and compute the expected charge WITHOUT submitting any
+   * transaction. Safe to call before committing — for approval gates and
+   * budget-aware routing.
+   */
+  async estimateCost(url, options) {
+    const { manifest, mode } = await this._resolveManifest(url, options);
+    let amount;
+    switch (mode) {
+      case "x402":
+        amount = manifest.pricing.x402.amount;
+        break;
+      case "mpp-charge":
+        amount = manifest.pricing["mpp-charge"].amount;
+        break;
+      case "mpp-session":
+        amount = manifest.pricing["mpp-session"].rate;
+        break;
+      case "mpp-session-ws":
+        amount = manifest.pricing["mpp-session-ws"].rate;
+        break;
+      default:
+        throw new RouteDockManifestError(`Unknown payment mode: ${mode}`);
+    }
+    return {
+      amount,
+      asset: manifest.asset,
+      mode,
+      manifest,
+      ...manifest.regions && { regions: manifest.regions },
+      ...manifest.latency_hints && { latency_hints: manifest.latency_hints },
+      ...manifest.capabilities && { capabilities: manifest.capabilities }
+    };
+  }
   /**
    * Open a sustained MPP session at `url`. Verifies mpp-session is supported
    * before opening a channel. Returns a SessionHandle for streaming + closing.
+   *
+   * By default the session auto-closes after a wall-clock timeout (1h) so an
+   * orphaned channel cannot keep collateral locked on-chain — override or
+   * disable via `options.maxDurationMs`.
    */
-  async openSession(url) {
+  async openSession(url, options) {
     const baseUrl = new URL(url).origin;
-    const manifest = await fetchManifest(baseUrl);
-    if (!manifest.modes.includes("mpp-session")) {
+    const manifest = await fetchManifest(baseUrl, this.retryPolicy, this.manifestTimeoutMs, this.expectedPayee);
+    assertEndpointActive(manifest, url, this.logger);
+    const mode = options?.mode ?? "mpp-session";
+    if (!manifest.modes.includes(mode)) {
       throw new RouteDockManifestError(
-        `Provider at ${baseUrl} does not support mpp-session mode`
+        `Provider at ${baseUrl} does not support ${mode} mode`
       );
     }
-    if (!this.commitmentSecret) {
+    const secret = _secrets.get(this);
+    if (!secret) {
       throw new RouteDockManifestError(
         "commitmentSecret is required in RouteDockClientConfig for mpp-session mode"
       );
     }
-    return this.session.openSession(url, manifest, this.commitmentSecret);
+    const endpointKey = new URL(url).origin;
+    const onSpend = this.spendCap ? (amount) => this._recordSessionSpend(amount, endpointKey) : void 0;
+    return this.session.openSession(url, manifest, secret, options, onSpend);
   }
-  /** Check local daily cap and record the spend. Throws if cap exceeded. */
-  _checkAndRecordSpend(amount) {
-    if (!this.spendCap) return;
-    const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-    if (this.dailySpend.date !== today) {
-      this.dailySpend = { date: today, total: 0 };
-    }
-    const amountNum = parseFloat(amount);
-    const capNum = parseFloat(this.spendCap.daily);
-    if (this.dailySpend.total + amountNum > capNum) {
-      throw new RouteDockPolicyRejectedError("local_daily_cap_exceeded");
+  /**
+   * 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);
+    if (reserveId) {
+      await this._commitSpend(reserveId);
     }
-    this.dailySpend.total += amountNum;
+  }
+  /**
+   * Remove the commitment secret from memory and make it eligible for GC.
+   * Call when this client instance is no longer needed — particularly in
+   * long-lived processes or Worker threads.
+   */
+  dispose() {
+    _secrets.delete(this);
+  }
+  /**
+   * Evict the cached manifest for `url` immediately, so the next pay() /
+   * estimateCost() / openSession() call re-fetches it instead of routing on
+   * the stale cached copy. Use when a provider signals their manifest
+   * changed (e.g. after a config update) and the change must take effect
+   * before the cache TTL expires.
+   */
+  invalidateManifest(url) {
+    invalidateManifest(new URL(url).origin);
+  }
+  /**
+   * Reserve spend against local daily caps BEFORE dispatching payment.
+   * Returns a reserveId that must be passed to _commitSpend() on success
+   * or _rollbackSpend() on failure.
+   *
+   * The entire read-check-write is serialized through the per-instance
+   * mutex (_withSpendMutex) so concurrent pay() calls cannot interleave
+   * and overrun the cap.
+   *
+   * Enforcement order:
+   *   1. Per-endpoint cap (if `endpointCaps[endpointKey]` is set) — checked first.
+   *   2. Global daily cap — checked second.
+   *
+   * 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) {
+    if (!this.spendCap) return "";
+    return this._withSpendMutex(async () => {
+      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 total = BigInt(current.totalMicros);
+      const endpointCapStr = this.spendCap.endpointCaps?.[endpointKey];
+      if (endpointCapStr !== void 0) {
+        const endpointCapMicros = nulthSdk.usdcToStroops(endpointCapStr);
+        const endpointTotal = BigInt(current.endpoints[endpointKey] ?? "0");
+        if (endpointTotal + amountMicros > endpointCapMicros) {
+          throw new RouteDockPolicyRejectError("local_endpoint_cap_exceeded");
+        }
+      }
+      const globalCapMicros = nulthSdk.usdcToStroops(this.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 reserveId;
+    });
+  }
+  /**
+   * Commit a previously reserved spend after payment succeeds. For discrete
+   * pay() calls this is a no-op (the spend was already recorded by reserve).
+   * Reserved for future use if the committed amount differs from the reserved.
+   */
+  async _commitSpend(reserveId) {
+    this._pendingReserves.delete(reserveId);
+  }
+  /**
+   * Rollback a previously reserved spend when payment fails. Reverts the
+   * tentative accumulator write done by _checkAndReserveSpend.
+   */
+  async _rollbackSpend(reserveId) {
+    if (!this.spendCap || !reserveId) return;
+    const reserve = this._pendingReserves.get(reserveId);
+    if (!reserve) return;
+    this._pendingReserves.delete(reserveId);
+    const { endpointKey, amountMicros } = reserve;
+    await this._withSpendMutex(async () => {
+      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 (persisted.endpoints[endpointKey]) {
+        const endpointTotal = BigInt(persisted.endpoints[endpointKey]);
+        const newEndpointTotal = endpointTotal - amountMicros;
+        if (newEndpointTotal <= 0n) {
+          delete persisted.endpoints[endpointKey];
+        } else {
+          persisted.endpoints[endpointKey] = newEndpointTotal.toString();
+        }
+      }
+      await this.spendStore.write(persisted);
+    });
   }
 };
 
@@ -550,12 +2561,16 @@ var SupabaseSessionStore = class {
   supabase;
   async get(channelId) {
     const { data, error } = await this.supabase.from("sessions").select("*").eq("channel_id", channelId).maybeSingle();
-    if (error) throw new RouteDockSessionError(`SessionStore.get failed: ${error.message}`);
+    if (error) {
+      throw new RouteDockNetworkError(`SessionStore.get failed: ${error.message}`);
+    }
     if (!data) return null;
     return {
       channel_id: data.channel_id,
       payee: data.payee,
       payer: data.payer,
+      channel_contract: data.channel_contract,
+      network: data.network,
       cumulative_amount: String(data.cumulative_amount),
       last_signature: data.last_signature,
       status: data.status,
@@ -570,7 +2585,7 @@ var SupabaseSessionStore = class {
       const prev = parseFloat(existing.cumulative_amount);
       const next = parseFloat(state.cumulative_amount);
       if (next <= prev) {
-        throw new RouteDockSessionError(
+        throw new RouteDockVoucherMonotonicityError(
           `cumulative_amount must be strictly increasing: ${next} <= ${prev}`
         );
       }
@@ -580,6 +2595,8 @@ var SupabaseSessionStore = class {
         channel_id: state.channel_id,
         payee: state.payee,
         payer: state.payer,
+        channel_contract: state.channel_contract,
+        network: state.network,
         cumulative_amount: state.cumulative_amount,
         last_signature: state.last_signature,
         status: state.status,
@@ -591,28 +2608,228 @@ var SupabaseSessionStore = class {
     );
     if (error) {
       if (error.message.includes("strictly increasing")) {
-        throw new RouteDockSessionError(
+        throw new RouteDockVoucherMonotonicityError(
           `cumulative_amount must be strictly increasing (DB): ${error.message}`
         );
       }
-      throw new RouteDockSessionError(`SessionStore.upsert failed: ${error.message}`);
+      throw new RouteDockNetworkError(`SessionStore.upsert failed: ${error.message}`);
+    }
+  }
+  async setStatus(channelId, status, settlementTxHash) {
+    const payload = {
+      status,
+      updated_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (settlementTxHash !== void 0) {
+      payload.settlement_tx_hash = settlementTxHash;
+    }
+    const { error } = await this.supabase.from("sessions").update(payload).eq("channel_id", channelId);
+    if (error) {
+      throw new RouteDockNetworkError(`SessionStore.setStatus failed: ${error.message}`);
     }
   }
   async close(channelId) {
-    const { error } = await this.supabase.from("sessions").update({ status: "closed", updated_at: (/* @__PURE__ */ new Date()).toISOString() }).eq("channel_id", channelId);
-    if (error) throw new RouteDockSessionError(`SessionStore.close failed: ${error.message}`);
+    await this.setStatus(channelId, "closed");
+  }
+};
+function tryDecodeBase64(value) {
+  if (value.startsWith("http://") || value.startsWith("https://") || value.startsWith("/") || value.startsWith("[")) {
+    return value;
+  }
+  try {
+    const decoded = typeof Buffer !== "undefined" ? Buffer.from(value, "base64").toString("utf-8") : atob(value);
+    if (decoded.length > 0 && decoded !== value) return decoded;
+  } catch {
+  }
+  return value;
+}
+var OnChainRegistry = class {
+  horizon;
+  knownAccounts;
+  timeoutMs;
+  constructor(options) {
+    this.horizon = new stellarSdk.Horizon.Server(options.horizonUrl);
+    this.knownAccounts = options.knownAccounts;
+    this.timeoutMs = options.timeoutMs ?? 1e4;
+  }
+  /**
+   * stellar-sdk 14.6.1 has no way to cancel the underlying Horizon request, so
+   * we stop waiting on it instead: the promise returned here rejects once
+   * `timeoutMs` elapses, even though the request may still be in flight. The
+   * timer is always cleared, including on the error path.
+   */
+  loadAccountWithTimeout(accountId) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(
+        () => reject(new Error(`Horizon loadAccount timed out after ${this.timeoutMs}ms`)),
+        this.timeoutMs
+      );
+    });
+    return Promise.race([this.horizon.loadAccount(accountId), timeout]).finally(() => {
+      if (timer !== void 0) clearTimeout(timer);
+    });
+  }
+  async listProviders() {
+    const settled = await Promise.allSettled(
+      this.knownAccounts.map((accountId) => this.loadAccountWithTimeout(accountId))
+    );
+    const results = [];
+    for (let i = 0; i < settled.length; i++) {
+      const outcome = settled[i];
+      if (outcome.status !== "fulfilled") continue;
+      const accountId = this.knownAccounts[i];
+      const account = outcome.value;
+      const dataEntries = account.data_attr;
+      if (!dataEntries) continue;
+      const rawEndpoint = dataEntries["routedock_endpoint"];
+      if (!rawEndpoint) continue;
+      const endpoint = tryDecodeBase64(rawEndpoint);
+      if (!endpoint.startsWith("http://") && !endpoint.startsWith("https://")) continue;
+      let tags = [];
+      const rawTags = dataEntries["routedock_tags"];
+      if (rawTags) {
+        const decoded = tryDecodeBase64(rawTags);
+        try {
+          const parsed = JSON.parse(decoded);
+          if (Array.isArray(parsed)) tags = parsed;
+        } catch {
+          tags = decoded.split(",").map((t) => t.trim()).filter(Boolean);
+        }
+      }
+      results.push({ account: accountId, endpoint, tags });
+    }
+    return results;
+  }
+};
+
+// src/registry/ProviderRegistry.ts
+function deriveNetwork(horizonUrl) {
+  return horizonUrl.includes("testnet") ? "testnet" : "mainnet";
+}
+var ProviderRegistry = class {
+  supabase;
+  onChain;
+  network;
+  constructor(config) {
+    this.supabase = config.supabase;
+    this.network = config.onChain.network ?? deriveNetwork(config.onChain.horizonUrl);
+    this.onChain = new OnChainRegistry({
+      horizonUrl: config.onChain.horizonUrl,
+      knownAccounts: config.onChain.knownAccounts,
+      ...config.onChain.timeoutMs !== void 0 ? { timeoutMs: config.onChain.timeoutMs } : {}
+    });
+  }
+  async listProviders() {
+    const supabaseProviders = await this.trySupabase();
+    if (supabaseProviders.length > 0) return supabaseProviders;
+    return this.tryOnChain();
+  }
+  async trySupabase() {
+    if (!this.supabase) return [];
+    try {
+      const { data, error } = await this.supabase.from("providers").select("*").eq("verified", true).eq("network", this.network).limit(100);
+      if (error) return [];
+      if (!data || data.length === 0) return [];
+      return data.map((r) => ({
+        name: r.name,
+        description: r.description ?? void 0,
+        base_url: r.base_url,
+        modes: r.modes,
+        tags: r.tags,
+        network: r.network,
+        payee: r.payee,
+        source: "supabase",
+        verified: r.verified === true
+      }));
+    } catch {
+      return [];
+    }
+  }
+  async tryOnChain() {
+    const providers = await this.onChain.listProviders();
+    return providers.map((p) => ({
+      name: `On-chain provider (${p.account.slice(0, 8)}...)`,
+      description: `Provider registered on Stellar account ${p.account}`,
+      base_url: p.endpoint,
+      modes: [],
+      tags: p.tags,
+      network: this.network,
+      payee: p.account,
+      source: "onchain",
+      verified: true
+    }));
+  }
+  /**
+   * Fetch a provider's manifest bound to the record's payee. The record's
+   * `payee` (from supabase `verified` rows or the on-chain registry account)
+   * is the out-of-band trust anchor: the fetched manifest's `payee` must
+   * equal it, otherwise `RouteDockSignatureError` is thrown. This closes the
+   * gap where the registry never cross-checked the on-chain payee against
+   * the manifest payee.
+   */
+  async fetchProviderManifest(record) {
+    const baseUrl = new URL(record.base_url).origin;
+    return fetchManifest(baseUrl, void 0, void 0, record.payee);
   }
 };
 
+Object.defineProperty(exports, "USDC_DECIMALS", {
+  enumerable: true,
+  get: function () { return nulthSdk.USDC_DECIMALS; }
+});
+Object.defineProperty(exports, "usdcToStroops", {
+  enumerable: true,
+  get: function () { return nulthSdk.usdcToStroops; }
+});
+exports.DEFAULT_MAX_SESSION_DURATION_MS = DEFAULT_MAX_SESSION_DURATION_MS;
+exports.DEFAULT_RETRY_POLICY = DEFAULT_RETRY_POLICY;
+exports.FileSpendStore = FileSpendStore;
+exports.InMemorySpendStore = InMemorySpendStore;
 exports.MppChargeClient = MppChargeClient;
 exports.MppSessionClient = MppSessionClient;
+exports.NulthPolicyError = NulthPolicyError;
+exports.OnChainRegistry = OnChainRegistry;
+exports.ProviderRegistry = ProviderRegistry;
+exports.RouteDockChannelStateError = RouteDockChannelStateError;
 exports.RouteDockClient = RouteDockClient;
+exports.RouteDockClientVersionError = RouteDockClientVersionError;
+exports.RouteDockDisputeError = RouteDockDisputeError;
 exports.RouteDockError = RouteDockError;
+exports.RouteDockFacilitatorError = RouteDockFacilitatorError;
 exports.RouteDockManifestError = RouteDockManifestError;
+exports.RouteDockManifestSunsetError = RouteDockManifestSunsetError;
+exports.RouteDockManifestTimeoutError = RouteDockManifestTimeoutError;
+exports.RouteDockNetworkError = RouteDockNetworkError;
 exports.RouteDockNoSupportedModeError = RouteDockNoSupportedModeError;
+exports.RouteDockPolicyRejectError = RouteDockPolicyRejectError;
 exports.RouteDockPolicyRejectedError = RouteDockPolicyRejectedError;
+exports.RouteDockRefundWindowError = RouteDockRefundWindowError;
 exports.RouteDockSessionError = RouteDockSessionError;
+exports.RouteDockSignatureError = RouteDockSignatureError;
+exports.RouteDockTrustlineError = RouteDockTrustlineError;
+exports.RouteDockVoucherMonotonicityError = RouteDockVoucherMonotonicityError;
 exports.SupabaseSessionStore = SupabaseSessionStore;
 exports.X402Client = X402Client;
+exports.assertEndpointActive = assertEndpointActive;
+exports.assertManifestValid = assertManifestValid;
+exports.assertNulthVaultManifest = assertNulthVaultManifest;
+exports.backoffDelayMs = backoffDelayMs;
+exports.configureManifestCache = configureManifestCache;
+exports.createNulthSigner = createNulthSigner;
+exports.createPolicyState = createPolicyState;
+exports.decodeAuthSignature = decodeAuthSignature;
+exports.fetchLedgerSequence = fetchLedgerSequence;
 exports.fetchManifest = fetchManifest;
+exports.httpStatusToError = httpStatusToError;
+exports.invalidateManifest = invalidateManifest;
+exports.parseRetryAfterMs = parseRetryAfterMs;
+exports.paymentContextFromManifest = paymentContextFromManifest;
+exports.prepareNulthSigner = prepareNulthSigner;
+exports.rankProvidersByLatency = rankProvidersByLatency;
 exports.selectMode = selectMode;
+exports.setNulthPaymentContext = setNulthPaymentContext;
+exports.usdcToMicros = usdcToMicros;
+exports.usdcToUnits = usdcToUnits;
+exports.withRetry = withRetry;
+exports.wrapFetchError = wrapFetchError;