@routedock/routedock 0.1.1 → 0.2.0

package/dist/react.js

@@ -0,0 +1,2634 @@
+import { createContext, useContext, useMemo, useEffect, useState, useRef, useCallback } from 'react';
+import { jsx } from 'react/jsx-runtime';
+import { Keypair, Horizon, Networks, rpc, xdr, Address, scValToNative, hash } from '@stellar/stellar-sdk';
+import { Validator } from '@cfworker/json-schema';
+import { usdcToStroops } from '@routedock/nulth-sdk';
+import { createHash } from 'crypto';
+import { createEd25519Signer } from '@x402/stellar';
+import { ExactStellarScheme } from '@x402/stellar/exact/client';
+import { x402Client, x402HTTPClient } from '@x402/core/client';
+import { decodePaymentRequiredHeader, decodePaymentResponseHeader } from '@x402/core/http';
+import { stellar } from '@stellar/mpp/charge/client';
+import { Mppx } from 'mppx/client';
+import { STELLAR_PUBNET, STELLAR_TESTNET } from '@stellar/mpp';
+import { stellar as stellar$1 } from '@stellar/mpp/channel/client';
+import { Challenge } from 'mppx';
+import 'fs/promises';
+import 'path';
+
+// src/react/context.tsx
+var RouteDockContext = createContext(null);
+function RouteDockProvider(props) {
+  const { children, client, supabase } = props;
+  const value = supabase ? { client, supabase } : { client };
+  return /* @__PURE__ */ jsx(RouteDockContext.Provider, { value, children });
+}
+function useRouteDockContext() {
+  const ctx = useContext(RouteDockContext);
+  if (!ctx) {
+    throw new Error("useRouteDockContext must be used inside <RouteDockProvider>");
+  }
+  return ctx;
+}
+
+// src/errors.ts
+var RouteDockError = class extends Error {
+  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, 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, options = {}) {
+    super(message, "NO_SUPPORTED_MODE", false, options);
+    this.name = "RouteDockNoSupportedModeError";
+  }
+};
+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 RouteDockPolicyRejectError = class extends RouteDockError {
+  reason;
+  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";
+  }
+};
+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/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"
+};
+
+// src/schemas/routedock.schema.json
+var routedock_schema_default = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $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",
+  required: [
+    "routedock",
+    "name",
+    "description",
+    "modes",
+    "network",
+    "asset",
+    "asset_contract",
+    "payee",
+    "pricing",
+    "endpoints",
+    "tags"
+  ],
+  additionalProperties: false,
+  properties: {
+    routedock: {
+      type: "string",
+      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",
+      minLength: 1,
+      maxLength: 120,
+      description: "Human-readable provider name"
+    },
+    description: {
+      type: "string",
+      minLength: 1,
+      maxLength: 500,
+      description: "Human-readable description of the provider's data or service"
+    },
+    modes: {
+      type: "array",
+      minItems: 1,
+      uniqueItems: true,
+      items: {
+        $ref: "#/definitions/PaymentMode"
+      },
+      description: "Payment modes supported by this provider"
+    },
+    network: {
+      type: "string",
+      enum: ["testnet", "mainnet"],
+      description: "Stellar network this provider operates on"
+    },
+    asset: {
+      type: "string",
+      description: "Asset ticker symbol (e.g. 'USDC')"
+    },
+    asset_contract: {
+      type: "string",
+      description: "Stellar Asset Contract (SAC) address for the payment asset"
+    },
+    payee: {
+      type: "string",
+      description: "Stellar address (G...) that receives payments"
+    },
+    pricing: {
+      type: "object",
+      description: "Pricing configuration per supported payment mode",
+      additionalProperties: false,
+      properties: {
+        x402: {
+          $ref: "#/definitions/PricingConfig"
+        },
+        "mpp-charge": {
+          $ref: "#/definitions/PricingConfig"
+        },
+        "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 endpoint descriptors",
+      additionalProperties: {
+        $ref: "#/definitions/EndpointDescriptor"
+      },
+      minProperties: 1
+    },
+    sla: {
+      $ref: "#/definitions/SLAConfig"
+    },
+    tags: {
+      type: "array",
+      items: {
+        type: "string",
+        minLength: 1,
+        maxLength: 64
+      },
+      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", "mpp-session-ws"],
+      description: "A supported RouteDock payment mode"
+    },
+    PricingConfig: {
+      type: "object",
+      description: "Per-request pricing for x402 or mpp-charge modes",
+      required: ["amount", "per"],
+      additionalProperties: false,
+      properties: {
+        amount: {
+          type: "string",
+          description: "Cost per request in the payment asset (decimal string, e.g. '0.001')"
+        },
+        per: {
+          type: "string",
+          const: "request",
+          description: "Billing unit \u2014 always 'request' for non-session modes"
+        },
+        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_factory", "min_deposit", "refund_waiting_period_ledgers"],
+      additionalProperties: false,
+      properties: {
+        rate: {
+          type: "string",
+          description: "Cost per voucher in the payment asset (decimal string, e.g. '0.0001')"
+        },
+        per: {
+          type: "string",
+          const: "voucher",
+          description: "Billing unit \u2014 always 'voucher' for session mode"
+        },
+        channel_factory: {
+          type: "string",
+          description: "Stable Soroban factory address (C...) used to deploy a per-session channel"
+        },
+        min_deposit: {
+          type: "string",
+          description: "Minimum initial deposit to open a channel (decimal string)"
+        },
+        refund_waiting_period_ledgers: {
+          type: "integer",
+          minimum: 1,
+          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 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 = 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 validator = new 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 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 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.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";
+  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 = 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: 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");
+      }
+    }
+  }
+  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;
+  }
+  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(", ")})`
+      );
+    }
+    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;
+  }
+  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;
+  }
+  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(", ")})`
+  );
+}
+var CAIP2 = {
+  testnet: "stellar:testnet",
+  mainnet: "stellar:pubnet"
+};
+var X402Client = class _X402Client {
+  constructor(secretKeyOrSigner, network, retryPolicy) {
+    this.network = network;
+    this.retryPolicy = retryPolicy;
+    const caip2 = CAIP2[network];
+    this.signer = typeof secretKeyOrSigner === "string" ? createEd25519Signer(secretKeyOrSigner, caip2) : secretKeyOrSigner;
+    const scheme = new ExactStellarScheme(this.signer);
+    const core = new x402Client();
+    core.register(caip2, scheme);
+    this.httpClient = new x402HTTPClient(core);
+  }
+  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) {
+      throw new RouteDockManifestError("manifest.pricing.x402 missing");
+    }
+    if (!pricing.facilitator) {
+      throw new RouteDockManifestError("manifest.pricing.x402.facilitator missing");
+    }
+    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 {
+        paymentRequired = 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 = 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");
+      }
+      return { data, txHash, mode: "x402", amount: pricing.amount, timestamp: Date.now() };
+    }, this.retryPolicy);
+  }
+};
+var MppChargeClient = class {
+  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");
+    }
+    return withRetry(async () => {
+      let txHash = null;
+      const mppx = Mppx.create({
+        polyfill: false,
+        methods: [
+          stellar.charge({
+            keypair: this.keypair,
+            mode: "pull",
+            onProgress(event) {
+              if (event.type === "paid") {
+                txHash = event.hash;
+              }
+            }
+          })
+        ]
+      });
+      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);
+  }
+};
+
+// src/types.ts
+var DEFAULT_MAX_SESSION_DURATION_MS = 36e5;
+
+// src/client/MppSessionClient.ts
+var MIN_REFUND_WAITING_PERIOD = 17280;
+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 === STELLAR_PUBNET ? STELLAR_PUBNET : 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;
+  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.${mode} missing`);
+    }
+    const refundPeriod = pricing.refund_waiting_period_ledgers;
+    if (refundPeriod < MIN_REFUND_WAITING_PERIOD) {
+      throw new RouteDockManifestError(
+        `refund_waiting_period_ledgers ${refundPeriod} < minimum ${MIN_REFUND_WAITING_PERIOD}`
+      );
+    }
+    const commitmentKey = Keypair.fromSecret(commitmentSecret);
+    const channelFactory = pricing.channel_factory;
+    const agentPublicKey = this.keypair.publicKey();
+    const agentKeypair = this.keypair;
+    let currentCumulative = 0n;
+    let vouchersIssued = 0;
+    let rateStroops;
+    try {
+      rateStroops = 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 = Mppx.create({
+      polyfill: false,
+      methods: [
+        stellar$1.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 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: 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}`
+            );
+          }
+          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;
+          }
+        }
+      },
+      async close() {
+        clearSessionTimer();
+        closed = true;
+        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" ? Networks.PUBLIC : 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 RouteDockChannelStateError(
+            `prepare_commitment simulation failed: ${simResult.error}`
+          );
+        }
+        const commitmentBytes = simResult.result?.retval?.bytes();
+        if (!commitmentBytes) {
+          throw new RouteDockChannelStateError("prepare_commitment returned no bytes");
+        }
+        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: 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" ? Networks.PUBLIC : 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" ? Networks.PUBLIC : 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" ? Networks.PUBLIC : 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, createCredential, onSigned) {
+    const request = { method: "GET" };
+    let probe;
+    try {
+      probe = await mppx.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(
+        Challenge.fromResponse(probe),
+        (cumulativeAmount) => mppx.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 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 = hash(Buffer.from(authEntryBase64, "base64"));
+  return sha256Hex(entryHash);
+}
+function assertAuthEntryMatchesContext(authEntry, from, ctx) {
+  let preimage;
+  try {
+    preimage = xdr.HashIdPreimage.fromXDR(authEntry, "base64");
+  } catch {
+    throw new NulthPolicyError("auth_entry_mismatch", "authEntry does not decode as a HashIdPreimage");
+  }
+  if (preimage.switch() !== 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() !== xdr.SorobanAuthorizedFunctionType.sorobanAuthorizedFunctionTypeContractFn()) {
+    throw new NulthPolicyError("auth_entry_mismatch", "authEntry does not invoke a contract function");
+  }
+  const fn = inv.function().contractFn();
+  const contractAddress = 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 = scValToNative(args[0]);
+  if (entryFrom !== from) {
+    throw new NulthPolicyError(
+      "auth_entry_mismatch",
+      `authEntry from ${entryFrom} does not match nulthAccount ${from}`
+    );
+  }
+  const entryTo = 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 = 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 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 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 = 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 };
+}
+
+// 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 _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 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;
+  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" ? Keypair.fromSecret(config.wallet) : config.wallet;
+    this.network = config.network;
+    this.spendCap = config.spendCap ? normalizeSpendCap(config.spendCap) : void 0;
+    this.retryPolicy = config.retryPolicy;
+    this.spendStore = config.spendStore ?? new InMemorySpendStore({ warn: !!config.spendCap });
+    this.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.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 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,
+   * 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, 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":
+        amount = manifest.pricing.x402.amount;
+        break;
+      case "mpp-charge":
+        amount = manifest.pricing["mpp-charge"].amount;
+        break;
+      case "mpp-session":
+      case "mpp-session-ws":
+        throw new RouteDockManifestError(
+          `Use client.openSession() for ${mode} mode \u2014 client.pay() only handles discrete payments`
+        );
+      default:
+        throw new RouteDockManifestError(`Unknown payment mode: ${mode}`);
+    }
+    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, 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 = options?.mode ?? "mpp-session";
+    if (!manifest.modes.includes(mode)) {
+      throw new RouteDockManifestError(
+        `Provider at ${baseUrl} does not support ${mode} mode`
+      );
+    }
+    const secret = _secrets.get(this);
+    if (!secret) {
+      throw new RouteDockManifestError(
+        "commitmentSecret is required in RouteDockClientConfig for mpp-session mode"
+      );
+    }
+    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);
+  }
+  /**
+   * 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);
+    }
+  }
+  /**
+   * 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 = usdcToStroops(amount);
+      const total = BigInt(current.totalMicros);
+      const endpointCapStr = this.spendCap.endpointCaps?.[endpointKey];
+      if (endpointCapStr !== void 0) {
+        const endpointCapMicros = usdcToStroops(endpointCapStr);
+        const endpointTotal = BigInt(current.endpoints[endpointKey] ?? "0");
+        if (endpointTotal + amountMicros > endpointCapMicros) {
+          throw new RouteDockPolicyRejectError("local_endpoint_cap_exceeded");
+        }
+      }
+      const globalCapMicros = 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);
+    });
+  }
+};
+
+// src/react/useRouteDockClient.ts
+function useRouteDockClient(config) {
+  const walletKey = typeof config.wallet === "string" ? config.wallet : config.wallet.secret();
+  const spendCapKey = config.spendCap ? `${config.spendCap.daily}|${config.spendCap.asset}` : "";
+  const retryKey = config.retryPolicy ? `${config.retryPolicy.maxAttempts}|${config.retryPolicy.baseDelayMs}` : "";
+  const client = useMemo(
+    () => new RouteDockClient(config),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [walletKey, config.network, spendCapKey, config.commitmentSecret, retryKey]
+  );
+  useEffect(() => () => client.dispose(), [client]);
+  return client;
+}
+function usePay(url, options) {
+  const { client } = useRouteDockContext();
+  const [result, setResult] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const mountedRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  const pay = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const r = await client.pay(url, options);
+      if (mountedRef.current) {
+        setResult(r);
+        setLoading(false);
+      }
+      return r;
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      if (mountedRef.current) {
+        setError(e);
+        setLoading(false);
+      }
+      return null;
+    }
+  }, [client, url, options]);
+  return { pay, result, loading, error };
+}
+function useSession(url) {
+  const { client } = useRouteDockContext();
+  const [session, setSession] = useState(null);
+  const [status, setStatus] = useState("idle");
+  const [vouchers, setVouchers] = useState(0);
+  const [cumulative, setCumulative] = useState("0");
+  const [error, setError] = useState(null);
+  const mountedRef = useRef(true);
+  const sessionRef = useRef(null);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      const s = sessionRef.current;
+      if (s) {
+        s.close().catch(() => {
+        });
+        sessionRef.current = null;
+      }
+    };
+  }, []);
+  const open = useCallback(async () => {
+    setStatus("opening");
+    setError(null);
+    try {
+      const s = await client.openSession(url);
+      sessionRef.current = s;
+      if (mountedRef.current) {
+        setSession(s);
+        setStatus("open");
+      }
+      return s;
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      if (mountedRef.current) {
+        setError(e);
+        setStatus("error");
+      }
+      return null;
+    }
+  }, [client, url]);
+  const close = useCallback(async () => {
+    const s = sessionRef.current;
+    if (!s) return null;
+    setStatus("closing");
+    try {
+      const r = await s.close();
+      sessionRef.current = null;
+      if (mountedRef.current) {
+        setSession(null);
+        setStatus("closed");
+        setVouchers(r.vouchersIssued);
+        setCumulative(r.totalPaid);
+      }
+      return r;
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      if (mountedRef.current) {
+        setError(e);
+        setStatus("error");
+      }
+      return null;
+    }
+  }, []);
+  return { session, status, vouchers, cumulative, error, open, close };
+}
+function useTxLog(filter) {
+  const { supabase } = useRouteDockContext();
+  const [rows, setRows] = useState([]);
+  useEffect(() => {
+    if (!supabase) return;
+    let cancelled = false;
+    const fetchInitial = async () => {
+      let query = supabase.from("tx_log").select("*").order("created_at", { ascending: false }).limit(filter?.limit ?? 100);
+      if (filter?.channelId) query = query.eq("channel_id", filter.channelId);
+      if (filter?.mode) query = query.eq("mode", filter.mode);
+      const { data } = await query;
+      if (!cancelled && data) setRows(data);
+    };
+    fetchInitial();
+    const channel = supabase.channel(`tx_log:${filter?.channelId ?? "all"}`).on(
+      "postgres_changes",
+      { event: "INSERT", schema: "public", table: "tx_log" },
+      (payload) => {
+        const row = payload.new;
+        if (filter?.channelId && row.channel_id !== filter.channelId) return;
+        if (filter?.mode && row.mode !== filter.mode) return;
+        setRows((prev) => [row, ...prev].slice(0, filter?.limit ?? 100));
+      }
+    ).subscribe();
+    return () => {
+      cancelled = true;
+      void supabase.removeChannel(channel);
+    };
+  }, [supabase, filter?.channelId, filter?.mode, filter?.limit]);
+  return rows;
+}
+
+export { RouteDockProvider, usePay, useRouteDockClient, useRouteDockContext, useSession, useTxLog };