@routedock/routedock 0.1.2 → 0.3.0

package/dist/index.js

@@ -1,57 +1,331 @@
-import { Keypair } from '@stellar/stellar-sdk';
-import Ajv from 'ajv';
+import { usdcToStroops, stroopsToUsdc } from '@routedock/nulth-sdk';
+export { USDC_DECIMALS, usdcToStroops } from '@routedock/nulth-sdk';
+import { Keypair, rpc, Horizon, xdr, Address, scValToNative, hash, Networks, StrKey, Contract, nativeToScVal, TransactionBuilder, BASE_FEE } from '@stellar/stellar-sdk';
+import { Validator } from '@cfworker/json-schema';
+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, encodePaymentRequiredHeader, decodePaymentSignatureHeader, encodePaymentResponseHeader } 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, Errors } from 'mppx';
+import fs from 'fs/promises';
+import path from 'path';
 import { ExactStellarScheme as ExactStellarScheme$1 } from '@x402/stellar/exact/facilitator';
 import { ExactStellarScheme as ExactStellarScheme$2 } from '@x402/stellar/exact/server';
 import { HTTPFacilitatorClient, x402ResourceServer } from '@x402/core/server';
-import { stellar as stellar$2 } from '@stellar/mpp/charge/server';
-import { Mppx as Mppx$1, Request } from 'mppx/server';
-import { Store, stellar as stellar$3, close } from '@stellar/mpp/channel/server';
+import { stellar as stellar$3 } from '@stellar/mpp/charge/server';
+import { Request, Mppx as Mppx$1 } from 'mppx/server';
+import { Store, stellar as stellar$2, close } from '@stellar/mpp/channel/server';
 
-// src/types.ts
+// src/errors.ts
 var RouteDockError = class extends Error {
-  constructor(message) {
-    super(message);
+  code;
+  retryable;
+  retryAfterMs;
+  constructor(message, code, retryable, options = {}) {
+    super(message, { cause: options.cause });
     this.name = "RouteDockError";
+    this.code = code;
+    this.retryable = retryable;
+    if (options.retryAfterMs !== void 0) {
+      this.retryAfterMs = options.retryAfterMs;
+    }
   }
 };
 var RouteDockManifestError = class extends RouteDockError {
-  constructor(message) {
-    super(message);
+  constructor(message, options = {}) {
+    super(message, "MANIFEST", false, options);
     this.name = "RouteDockManifestError";
   }
 };
+var RouteDockManifestTimeoutError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "MANIFEST_TIMEOUT", true, options);
+    this.name = "RouteDockManifestTimeoutError";
+  }
+};
+var RouteDockManifestSunsetError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "MANIFEST_SUNSET", false, options);
+    this.name = "RouteDockManifestSunsetError";
+  }
+};
 var RouteDockNoSupportedModeError = class extends RouteDockError {
-  constructor(message) {
-    super(message);
+  constructor(message, options = {}) {
+    super(message, "NO_SUPPORTED_MODE", false, options);
     this.name = "RouteDockNoSupportedModeError";
   }
 };
-var RouteDockSessionError = class extends RouteDockError {
-  constructor(message) {
-    super(message);
-    this.name = "RouteDockSessionError";
+var RouteDockClientVersionError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "CLIENT_VERSION_TOO_OLD", false, options);
+    this.name = "RouteDockClientVersionError";
+  }
+};
+var RouteDockTrustlineError = class extends RouteDockError {
+  asset;
+  issuer;
+  remediation;
+  constructor(asset, issuer, remediation, options = {}) {
+    super(
+      `Missing trustline for ${asset} (issuer: ${issuer}). ${remediation}`,
+      "TRUSTLINE",
+      false,
+      options
+    );
+    this.name = "RouteDockTrustlineError";
+    this.asset = asset;
+    this.issuer = issuer;
+    this.remediation = remediation;
+  }
+};
+var RouteDockFacilitatorError = class extends RouteDockError {
+  status;
+  constructor(message, status, options = {}) {
+    super(message, "FACILITATOR", true, options);
+    this.name = "RouteDockFacilitatorError";
+    this.status = status;
+  }
+};
+var RouteDockNetworkError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "NETWORK", true, options);
+    this.name = "RouteDockNetworkError";
+  }
+};
+var RouteDockSignatureError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "SIGNATURE", false, options);
+    this.name = "RouteDockSignatureError";
+  }
+};
+var RouteDockVoucherMonotonicityError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "VOUCHER_MONOTONICITY", false, options);
+    this.name = "RouteDockVoucherMonotonicityError";
   }
 };
-var RouteDockPolicyRejectedError = class extends RouteDockError {
+var RouteDockPolicyRejectError = class extends RouteDockError {
   reason;
-  constructor(reason) {
-    super(`Payment rejected by policy: ${reason}`);
-    this.name = "RouteDockPolicyRejectedError";
+  constructor(reason, options = {}) {
+    super(`Payment rejected by policy: ${reason}`, "POLICY_REJECT", false, options);
+    this.name = "RouteDockPolicyRejectError";
     this.reason = reason;
   }
 };
+var RouteDockChannelStateError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "CHANNEL_STATE", false, options);
+    this.name = "RouteDockChannelStateError";
+  }
+};
+var RouteDockDisputeError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "DISPUTE", false, options);
+    this.name = "RouteDockDisputeError";
+  }
+};
+var RouteDockRefundWindowError = class extends RouteDockError {
+  constructor(message, options = {}) {
+    super(message, "REFUND_WINDOW", false, options);
+    this.name = "RouteDockRefundWindowError";
+  }
+};
+var RouteDockPolicyRejectedError = RouteDockPolicyRejectError;
+var RouteDockSessionError = RouteDockVoucherMonotonicityError;
+function parseRetryAfterMs(response) {
+  const header = response.headers.get("Retry-After");
+  if (!header) return void 0;
+  const seconds = Number(header);
+  if (!Number.isNaN(seconds) && seconds >= 0) {
+    return seconds * 1e3;
+  }
+  const date = Date.parse(header);
+  if (!Number.isNaN(date)) {
+    return Math.max(0, date - Date.now());
+  }
+  return void 0;
+}
+function httpStatusToError(message, status, response) {
+  const retryAfterMs = response ? parseRetryAfterMs(response) : void 0;
+  const opts = retryAfterMs !== void 0 ? { retryAfterMs } : {};
+  if (status === 429 || status === 503 || status >= 500 && status < 600) {
+    return new RouteDockFacilitatorError(message, status, opts);
+  }
+  if (status >= 400) {
+    return new RouteDockManifestError(message, opts);
+  }
+  return new RouteDockNetworkError(message, opts);
+}
+function wrapFetchError(err, context) {
+  if (err instanceof RouteDockError) return err;
+  return new RouteDockNetworkError(`${context}: ${String(err)}`, { cause: err });
+}
+function wrapMppError(err, context) {
+  if (err instanceof RouteDockError) return err;
+  if (err instanceof TypeError || err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError")) {
+    return new RouteDockNetworkError(`${context}: ${String(err)}`, { cause: err });
+  }
+  return new RouteDockSignatureError(`${context}: ${String(err)}`, { cause: err });
+}
+
+// src/types.ts
+var DEFAULT_MAX_SESSION_DURATION_MS = 36e5;
+
+// src/internal/logger.ts
+function createConsoleLogger() {
+  return (level, message, fields) => {
+    const values = fields ? Object.values(fields) : [];
+    if (values.length > 0) {
+      console[level](message, ...values);
+    } else {
+      console[level](message);
+    }
+  };
+}
+var consoleLogger = createConsoleLogger();
+var noopLogger = () => {
+};
+function resolveLogger(logger, fallback = consoleLogger) {
+  return logger ?? fallback;
+}
+
+// src/internal/retry.ts
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 4,
+  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, logger } = {
+    ...DEFAULT_RETRY_POLICY,
+    ...policy
+  };
+  const log = resolveLogger(logger);
+  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) {
+          log("error", "[withRetry] onRetry callback threw:", { error: cbErr });
+        }
+      }
+      await sleep(delay);
+    }
+  }
+  throw lastError ?? new RouteDockError("Retry exhausted", "NETWORK", false);
+}
+var USDC_ISSUERS = {
+  testnet: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
+  mainnet: "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
+};
+var usdcToUnits = usdcToStroops;
+
+// src/internal/assetUtils.ts
+function normalizeManifestAssets(manifest) {
+  if (manifest.assets && manifest.assets.length > 0) {
+    return manifest.assets;
+  }
+  if (manifest.asset && manifest.asset_contract) {
+    return [
+      {
+        asset: manifest.asset,
+        asset_contract: manifest.asset_contract
+      }
+    ];
+  }
+  throw new RouteDockManifestError(
+    "Manifest must define either assets[] or root asset/asset_contract fields"
+  );
+}
+function getEligibleAssets(manifest, mode, endpoint) {
+  const assets = normalizeManifestAssets(manifest);
+  return assets.filter((asset) => {
+    if (asset.modes && !asset.modes.includes(mode)) {
+      return false;
+    }
+    if (endpoint && asset.endpoints && asset.endpoints.length > 0) {
+      const trimmedEndpoint = endpoint.replace(/^\//, "");
+      if (asset.endpoints.includes(endpoint) || asset.endpoints.includes(trimmedEndpoint)) {
+        return true;
+      }
+      if (manifest.endpoints) {
+        let pathname = endpoint;
+        if (endpoint.startsWith("http://") || endpoint.startsWith("https://")) {
+          try {
+            pathname = new URL(endpoint).pathname;
+          } catch {
+          }
+        }
+        const trimmedPathname = pathname.replace(/^\//, "");
+        const matchesEndpoint = Object.entries(manifest.endpoints).some(([key, desc]) => {
+          const pathMatches = desc.path === pathname || desc.path === endpoint || desc.path.replace(/\/+$/, "") === pathname.replace(/\/+$/, "") || desc.path.replace(/^\//, "") === trimmedPathname;
+          const keyMatches = key === endpoint || key === trimmedEndpoint;
+          if (pathMatches || keyMatches) {
+            return asset.endpoints.includes(key) || asset.endpoints.includes(desc.path) || asset.endpoints.includes(desc.path.replace(/^\//, ""));
+          }
+          return false;
+        });
+        if (!matchesEndpoint) {
+          return false;
+        }
+      } else {
+        return false;
+      }
+    }
+    return true;
+  });
+}
+function resolveAssetContract(manifest, mode, endpoint, explicitContract) {
+  if (manifest.assets && manifest.assets.length > 0) {
+    return selectAsset(manifest, mode, endpoint).asset_contract;
+  }
+  return explicitContract ?? selectAsset(manifest, mode, endpoint).asset_contract;
+}
+function selectAsset(manifest, mode, endpoint) {
+  const eligible = getEligibleAssets(manifest, mode, endpoint);
+  if (eligible.length === 0) {
+    const endpointMsg = endpoint ? ` for endpoint '${endpoint}'` : "";
+    throw new RouteDockManifestError(
+      `No eligible assets found for mode '${mode}'${endpointMsg}`
+    );
+  }
+  return eligible[0];
+}
+function isAssetEligible(manifest, assetIdentifier, mode, endpoint) {
+  const eligible = getEligibleAssets(manifest, mode, endpoint);
+  return eligible.some(
+    (asset) => asset.asset === assetIdentifier || asset.asset_contract === assetIdentifier
+  );
+}
 
 // src/schemas/routedock.schema.json
 var routedock_schema_default = {
   $schema: "http://json-schema.org/draft-07/schema#",
-  $id: "https://routedock.dev/schemas/routedock.schema.json",
+  $id: "https://routedock.xyz/schemas/routedock.schema.json",
   title: "RouteDock Manifest",
   description: "Discovery manifest served at /.well-known/routedock.json on every RouteDock provider endpoint",
   type: "object",
@@ -72,8 +346,26 @@ var routedock_schema_default = {
   properties: {
     routedock: {
       type: "string",
-      const: "1.0",
-      description: "Manifest schema version. Always '1.0' for this version."
+      pattern: "^[0-9]+\\.[0-9]+$",
+      description: "Manifest schema version, e.g. '1.0', '1.1', '2.0'."
+    },
+    min_client_version: {
+      type: "string",
+      pattern: "^[0-9]+\\.[0-9]+$",
+      description: "Minimum SDK client version (major.minor) required to use this manifest. Clients below this version must refuse to pay."
+    },
+    deprecated_modes: {
+      type: "array",
+      items: {
+        $ref: "#/definitions/PaymentMode"
+      },
+      uniqueItems: true,
+      description: "Payment modes still listed in 'modes' for backwards compatibility but deprecated for new integrations."
+    },
+    sunset_at: {
+      type: "string",
+      format: "date-time",
+      description: "ISO 8601 timestamp after which this manifest version is no longer supported by the provider."
     },
     name: {
       type: "string",
@@ -109,6 +401,14 @@ var routedock_schema_default = {
       type: "string",
       description: "Stellar Asset Contract (SAC) address for the payment asset"
     },
+    assets: {
+      type: "array",
+      minItems: 1,
+      items: {
+        $ref: "#/definitions/AssetConfig"
+      },
+      description: "Payment assets accepted by this provider. Each asset can be scoped to specific modes and endpoints. When present, assets[0] must match the root-level asset and asset_contract."
+    },
     payee: {
       type: "string",
       description: "Stellar address (G...) that receives payments"
@@ -126,18 +426,25 @@ var routedock_schema_default = {
         },
         "mpp-session": {
           $ref: "#/definitions/SessionPricingConfig"
+        },
+        "mpp-session-ws": {
+          $ref: "#/definitions/SessionPricingConfig",
+          description: "WebSocket transport variant of mpp-session: channel opened and first voucher negotiated over HTTP, then the connection upgrades to WebSocket for push-based streaming."
         }
       },
       minProperties: 1
     },
     endpoints: {
       type: "object",
-      description: "Map of endpoint name to HTTP method + path (e.g. { 'price': 'GET /price' })",
+      description: "Map of endpoint name to endpoint descriptors",
       additionalProperties: {
-        type: "string"
+        $ref: "#/definitions/EndpointDescriptor"
       },
       minProperties: 1
     },
+    sla: {
+      $ref: "#/definitions/SLAConfig"
+    },
     tags: {
       type: "array",
       items: {
@@ -147,14 +454,125 @@ var routedock_schema_default = {
       },
       uniqueItems: true,
       description: "Capability tags indexed with trigram search in the provider registry"
+    },
+    vault: {
+      $ref: "#/definitions/VaultMode"
+    },
+    nulth_account: {
+      type: "string",
+      description: "Optional Nulth smart account address associated with this provider"
+    },
+    capabilities: {
+      type: "object",
+      description: "Optional protocol features this provider supports",
+      properties: {
+        streaming: {
+          type: "array",
+          items: {
+            type: "string",
+            enum: ["sse", "websocket"]
+          },
+          description: "Supported streaming transports"
+        },
+        webhooks: {
+          type: "boolean",
+          description: "Whether webhook callbacks are supported"
+        },
+        idempotency_keys: {
+          type: "boolean",
+          description: "Whether idempotency keys are supported"
+        },
+        content_types: {
+          type: "array",
+          items: {
+            type: "string"
+          },
+          description: "Supported content types for request/response"
+        }
+      },
+      additionalProperties: false
+    },
+    regions: {
+      type: "array",
+      items: {
+        type: "string",
+        minLength: 2,
+        maxLength: 10
+      },
+      uniqueItems: true,
+      description: "IATA airport codes or UN/LOCODE identifiers for regions where this provider has infrastructure (e.g. ['IAD', 'AMS']). Used by agents to select the nearest provider."
+    },
+    latency_hints: {
+      type: "object",
+      additionalProperties: {
+        type: "number",
+        minimum: 0
+      },
+      description: "Provider-declared p50 latency in milliseconds per region code. Keys must be a subset of 'regions'. Example: { 'IAD': 14, 'AMS': 22 }."
+    },
+    signature: {
+      type: "string",
+      description: "Base64 Ed25519 signature (payee keypair) over the SHA-256 hash of this manifest with the signature field omitted. Clients must verify before trusting any routing field."
+    },
+    signature_version: {
+      type: "string",
+      const: "2",
+      description: "Manifest signature format. Version 2 recursively includes every nested manifest field in the signed digest."
+    },
+    categories: {
+      type: "array",
+      items: {
+        type: "string",
+        minLength: 1,
+        maxLength: 128
+      },
+      uniqueItems: true,
+      description: "Optional hierarchical categories from a published taxonomy (e.g. data/price/crypto)"
     }
   },
   definitions: {
+    VaultMode: {
+      type: "string",
+      enum: ["local-key", "agent-vault", "nulth"],
+      description: "Agent vault / custody mode for payments from this provider"
+    },
     PaymentMode: {
       type: "string",
-      enum: ["x402", "mpp-charge", "mpp-session"],
+      enum: ["x402", "mpp-charge", "mpp-session", "mpp-session-ws"],
       description: "A supported RouteDock payment mode"
     },
+    AssetConfig: {
+      type: "object",
+      description: "Payment asset configuration with optional mode and endpoint scoping",
+      required: ["asset", "asset_contract"],
+      additionalProperties: false,
+      properties: {
+        asset: {
+          type: "string",
+          description: "Asset ticker symbol (e.g. 'USDC' or 'XLM')"
+        },
+        asset_contract: {
+          type: "string",
+          description: "Stellar Asset Contract (SAC) address for the payment asset"
+        },
+        modes: {
+          type: "array",
+          items: {
+            $ref: "#/definitions/PaymentMode"
+          },
+          uniqueItems: true,
+          description: "Optional: restrict this asset to specific payment modes. If omitted, available for all modes."
+        },
+        endpoints: {
+          type: "array",
+          items: {
+            type: "string"
+          },
+          uniqueItems: true,
+          description: "Optional: restrict this asset to specific endpoints (by name). If omitted, available for all endpoints."
+        }
+      }
+    },
     PricingConfig: {
       type: "object",
       description: "Per-request pricing for x402 or mpp-charge modes",
@@ -173,13 +591,17 @@ var routedock_schema_default = {
         facilitator: {
           type: "string",
           description: "x402 facilitator URL (required for x402 mode). OpenZeppelin Channels endpoint."
+        },
+        payee: {
+          type: "string",
+          description: "Optional per-mode payee override (Stellar G... address). Directs settlements for this mode to a separate account for treasury separation. Falls back to the top-level 'payee' when omitted."
         }
       }
     },
     SessionPricingConfig: {
       type: "object",
       description: "Per-voucher pricing for mpp-session (one-way-channel) mode",
-      required: ["rate", "per", "channel_contract", "min_deposit", "refund_waiting_period_ledgers"],
+      required: ["rate", "per", "channel_factory", "min_deposit", "refund_waiting_period_ledgers"],
       additionalProperties: false,
       properties: {
         rate: {
@@ -191,9 +613,9 @@ var routedock_schema_default = {
           const: "voucher",
           description: "Billing unit \u2014 always 'voucher' for session mode"
         },
-        channel_contract: {
+        channel_factory: {
           type: "string",
-          description: "Soroban contract address (C...) for the one-way-channel contract"
+          description: "Stable Soroban factory address (C...) used to deploy a per-session channel"
         },
         min_deposit: {
           type: "string",
@@ -205,112 +627,680 @@ var routedock_schema_default = {
           description: "Ledgers the server has to settle before the funder can reclaim. Default: 17280 (~24h). Do not reduce in production."
         }
       }
+    },
+    SLAConfig: {
+      type: "object",
+      description: "Service Level Agreement for the provider",
+      required: ["uptime_30d_percent", "p95_latency_ms"],
+      additionalProperties: false,
+      properties: {
+        uptime_30d_percent: {
+          type: "number",
+          description: "Uptime percentage over the last 30 days"
+        },
+        p95_latency_ms: {
+          type: "number",
+          description: "P95 latency in milliseconds"
+        },
+        maintenance_windows: {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["cron", "duration_minutes"],
+            additionalProperties: false,
+            properties: {
+              cron: {
+                type: "string",
+                description: "Cron expression for the maintenance window"
+              },
+              duration_minutes: {
+                type: "number",
+                description: "Duration of the maintenance window in minutes"
+              }
+            }
+          }
+        }
+      }
+    },
+    EndpointDescriptor: {
+      type: "object",
+      description: "Descriptor for a provider endpoint",
+      required: ["method", "path"],
+      additionalProperties: false,
+      properties: {
+        method: {
+          type: "string",
+          description: "HTTP method for the endpoint"
+        },
+        path: {
+          type: "string",
+          description: "Path for the endpoint"
+        },
+        deprecated: {
+          type: "boolean",
+          description: "Whether this endpoint is retained only for backwards compatibility"
+        },
+        sunset_at: {
+          type: "string",
+          format: "date-time",
+          description: "ISO 8601 timestamp after which callers should stop using this endpoint"
+        },
+        headers: {
+          type: "object",
+          additionalProperties: {
+            type: "string"
+          },
+          description: "Expected request headers"
+        },
+        request_schema: {
+          description: "JSON schema for the request body"
+        },
+        response_schema: {
+          description: "JSON schema for the response body"
+        },
+        rate_limit: {
+          type: "object",
+          required: ["requests", "window_seconds"],
+          additionalProperties: false,
+          properties: {
+            requests: {
+              type: "number"
+            },
+            window_seconds: {
+              type: "number"
+            }
+          }
+        }
+      }
     }
   }
 };
 
-// src/client/ModeRouter.ts
-var ajv = new Ajv();
-var validateManifest = ajv.compile(routedock_schema_default);
-var CACHE_TTL_MS = 6e4;
-var manifestCache = /* @__PURE__ */ new Map();
-async function fetchManifest(baseUrl) {
-  const cached = manifestCache.get(baseUrl);
-  if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
-    return cached.manifest;
+// package.json
+var package_default = {
+  version: "0.3.0"};
+var MANIFEST_SIGNATURE_VERSION = "2";
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
   }
-  const url = baseUrl.replace(/\/$/, "") + "/.well-known/routedock.json";
-  let raw;
+  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 signManifest(manifest, payeeSecretKey) {
+  const keypair = Keypair.fromSecret(payeeSecretKey);
+  const versionedManifest = {
+    ...manifest,
+    signature_version: MANIFEST_SIGNATURE_VERSION
+  };
+  const digest = manifestDigest(versionedManifest);
+  const sig = keypair.sign(digest);
+  return { ...versionedManifest, signature: Buffer.from(sig).toString("base64") };
+}
+function verifyManifestSignature(manifest, expectedPayee) {
+  if (!manifest.signature) {
+    throw new RouteDockSignatureError(
+      "Manifest is missing a signature field \u2014 cannot verify payee authenticity"
+    );
+  }
+  if (manifest.signature_version !== MANIFEST_SIGNATURE_VERSION) {
+    throw new RouteDockSignatureError(
+      `Manifest signature version must be ${MANIFEST_SIGNATURE_VERSION}; legacy signatures are not safe because nested fields were excluded from their digest`
+    );
+  }
+  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 {
-    const resp = await fetch(url);
-    if (!resp.ok) {
-      throw new RouteDockManifestError(`Manifest fetch failed: HTTP ${resp.status} from ${url}`);
-    }
-    raw = await resp.json();
-  } catch (err) {
-    if (err instanceof RouteDockManifestError) throw err;
-    throw new RouteDockManifestError(`Manifest fetch error: ${String(err)}`);
+    sigBytes = Buffer.from(manifest.signature, "base64");
+  } catch {
+    throw new RouteDockSignatureError("Manifest signature is not valid base64");
   }
-  if (!validateManifest(raw)) {
-    const msgs = ajv.errorsText(validateManifest.errors);
-    throw new RouteDockManifestError(`Invalid manifest at ${url}: ${msgs}`);
+  let valid = false;
+  try {
+    valid = keypair.verify(digest, sigBytes);
+  } catch {
+    throw new RouteDockSignatureError(
+      `Manifest signature verification failed for payee ${manifest.payee}`
+    );
   }
-  const manifest = raw;
-  manifestCache.set(baseUrl, { manifest, fetchedAt: Date.now() });
-  return manifest;
-}
-function selectMode(manifest, options = {}) {
-  const modes = manifest.modes;
-  if (options.forceMode) {
-    if (!modes.includes(options.forceMode)) {
-      throw new RouteDockNoSupportedModeError(
-        `Provider does not support forced mode: ${options.forceMode} (available: ${modes.join(", ")})`
-      );
-    }
-    console.log(`[RouteDock] ${manifest.name} \u2192 ${options.forceMode} (forced)`);
-    return options.forceMode;
+  if (!valid) {
+    throw new RouteDockSignatureError(
+      `Manifest signature verification failed for payee ${manifest.payee}`
+    );
   }
-  if ((options.sustained || options.session) && modes.includes("mpp-session")) {
-    const mode = "mpp-session";
-    console.log(`[RouteDock] ${manifest.name} \u2192 ${mode}`);
-    return mode;
+}
+
+// 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.`
+    );
   }
-  if (modes.includes("mpp-charge")) {
-    const mode = "mpp-charge";
-    console.log(`[RouteDock] ${manifest.name} \u2192 ${mode}`);
-    return mode;
+}
+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 (modes.includes("x402")) {
-    const mode = "x402";
-    console.log(`[RouteDock] ${manifest.name} \u2192 ${mode}`);
-    return mode;
+  if (sunsetTime <= Date.now()) {
+    throw new RouteDockManifestSunsetError(
+      `Manifest for provider at ${baseUrl} sunset at ${sunsetAt} and can no longer be used`
+    );
   }
-  throw new RouteDockNoSupportedModeError(
-    `No supported payment mode found in manifest (modes: ${modes.join(", ")})`
-  );
 }
-var CAIP2 = {
-  testnet: "stellar:testnet",
-  mainnet: "stellar:pubnet"
-};
-var X402Client = class {
-  constructor(secretKey, network) {
-    this.secretKey = secretKey;
-    this.network = network;
-    const caip2 = CAIP2[network];
-    const signer = createEd25519Signer(secretKey, caip2);
-    const scheme = new ExactStellarScheme(signer);
-    const core = new x402Client();
-    core.register(caip2, scheme);
-    this.httpClient = new x402HTTPClient(core);
+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`
+    );
   }
-  secretKey;
-  network;
-  httpClient;
-  async pay(url, manifest) {
-    const pricing = manifest.pricing.x402;
-    if (!pricing) {
-      throw new RouteDockManifestError("manifest.pricing.x402 missing");
+  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(
+      "warn",
+      `[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`
+      );
     }
-    if (!pricing.facilitator) {
-      throw new RouteDockManifestError("manifest.pricing.x402.facilitator missing");
+    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(", ")})`
+        );
+      }
     }
-    const init = await fetch(url, { headers: { "X-Preferred-Mode": "x402" } });
-    if (init.status !== 402) {
-      const data2 = await init.json();
-      return { data: data2, txHash: null, mode: "x402", amount: pricing.amount, timestamp: Date.now() };
+  }
+  if (manifest.assets !== void 0) {
+    if (!Array.isArray(manifest.assets) || manifest.assets.length === 0) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: assets must be a non-empty array when defined`
+      );
     }
-    const reqHeader = init.headers.get("X-Payment-Requirements");
+    for (let i = 0; i < manifest.assets.length; i++) {
+      const a = manifest.assets[i];
+      if (!a || typeof a.asset !== "string" || typeof a.asset_contract !== "string") {
+        throw new RouteDockManifestError(
+          `Invalid manifest${context}: assets[${i}] must define asset and asset_contract strings`
+        );
+      }
+    }
+    const first = manifest.assets[0];
+    if (first.asset !== manifest.asset || first.asset_contract !== manifest.asset_contract) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: assets[0] (${first.asset}:${first.asset_contract}) must match root asset fields (${manifest.asset}:${manifest.asset_contract})`
+      );
+    }
+  }
+}
+var CACHE_TTL_MS = 6e4;
+var DEFAULT_MANIFEST_CACHE_MAX_SIZE = 512;
+var DEFAULT_MANIFEST_TIMEOUT_MS = 5e3;
+var LruCache = class {
+  constructor(maxSize) {
+    this.maxSize = maxSize;
+  }
+  maxSize;
+  map = /* @__PURE__ */ new Map();
+  get(key) {
+    if (!this.map.has(key)) return void 0;
+    const value = this.map.get(key);
+    this.map.delete(key);
+    this.map.set(key, value);
+    return value;
+  }
+  set(key, value) {
+    if (this.map.has(key)) {
+      this.map.delete(key);
+    } else if (this.map.size >= this.maxSize) {
+      const oldestKey = this.map.keys().next().value;
+      if (oldestKey !== void 0) {
+        this.map.delete(oldestKey);
+      }
+    }
+    this.map.set(key, value);
+  }
+  setMaxSize(maxSize) {
+    this.maxSize = maxSize;
+    while (this.map.size > this.maxSize) {
+      const oldestKey = this.map.keys().next().value;
+      if (oldestKey === void 0) break;
+      this.map.delete(oldestKey);
+    }
+  }
+  delete(key) {
+    this.map.delete(key);
+  }
+};
+var manifestCache = new LruCache(DEFAULT_MANIFEST_CACHE_MAX_SIZE);
+function configureManifestCache(maxSize) {
+  if (!Number.isInteger(maxSize) || maxSize <= 0) {
+    throw new RouteDockManifestError("Invalid manifest cache size: " + maxSize);
+  }
+  manifestCache.setMaxSize(maxSize);
+}
+function invalidateManifest(baseUrl) {
+  manifestCache.delete(baseUrl);
+}
+function ttlFromHeaders(headers, now) {
+  const cacheControl = headers.get("cache-control");
+  if (cacheControl) {
+    const directives = cacheControl.split(",").map((directive) => directive.trim().toLowerCase());
+    if (directives.includes("no-store") || directives.includes("no-cache")) {
+      return 0;
+    }
+    const maxAge = /max-age=(\d+)/i.exec(cacheControl);
+    if (maxAge) {
+      return Number.parseInt(maxAge[1], 10) * 1e3;
+    }
+  }
+  const expires = headers.get("expires");
+  if (expires) {
+    const expiresTime = Date.parse(expires);
+    if (Number.isFinite(expiresTime)) {
+      return expiresTime - now;
+    }
+  }
+  return CACHE_TTL_MS;
+}
+async function fetchManifest(baseUrl, retryPolicy, manifestTimeoutMs = DEFAULT_MANIFEST_TIMEOUT_MS, expectedPayee) {
+  const cached = manifestCache.get(baseUrl);
+  if (cached && Date.now() < cached.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(
+      "warn",
+      `[RouteDock] WARNING: ${manifest.name} \u2192 ${selection.mode}${reason}; selected deprecated mode because no active supported mode is available`
+    );
+    return;
+  }
+  log("info", `[RouteDock] ${manifest.name} \u2192 ${selection.mode}${reason}`);
+}
+function selectMode(manifest, options = {}) {
+  const modes = manifest.modes;
+  const log = options.logger ?? noopLogger;
+  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(
+        "warn",
+        `[RouteDock] WARNING: ${manifest.name} \u2192 ${options.forceMode} (forced); selected mode is deprecated`
+      );
+    } else {
+      log("info", `[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(", ")})`
+  );
+}
+function rankProvidersByLatency(manifests, targetRegion) {
+  return [...manifests].sort((a, b) => {
+    const latA = a.latency_hints?.[targetRegion];
+    const latB = b.latency_hints?.[targetRegion];
+    const inRegionsA = a.regions?.includes(targetRegion) ?? false;
+    const inRegionsB = b.regions?.includes(targetRegion) ?? false;
+    if (latA !== void 0 && latB !== void 0) {
+      return latA - latB;
+    }
+    if (latA !== void 0) return -1;
+    if (latB !== void 0) return 1;
+    if (inRegionsA && !inRegionsB) return -1;
+    if (!inRegionsA && inRegionsB) return 1;
+    return 0;
+  });
+}
+
+// src/internal/payee.ts
+function resolvePayee(manifest, mode) {
+  const override = manifest.pricing[mode]?.payee;
+  return override ?? manifest.payee;
+}
+
+// src/client/challenge.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isPositiveIntegerString(value) {
+  return typeof value === "string" && /^[1-9]\d*$/.test(value);
+}
+function checkAmount(amount, maxAmount) {
+  if (!isPositiveIntegerString(amount)) {
+    return new RouteDockPolicyRejectError("challenge_amount_invalid");
+  }
+  let max;
+  try {
+    max = usdcToStroops(maxAmount);
+  } catch {
+    return new RouteDockPolicyRejectError("challenge_amount_invalid");
+  }
+  if (BigInt(amount) > max) {
+    return new RouteDockPolicyRejectError("challenge_amount_exceeds_manifest");
+  }
+  return null;
+}
+function checkX402Accept(accept, manifest, network, maxAmount) {
+  if (accept.network !== network) {
+    return new RouteDockPolicyRejectError("challenge_network_mismatch");
+  }
+  if (accept.payTo !== resolvePayee(manifest, "x402")) {
+    return new RouteDockPolicyRejectError("challenge_payee_mismatch");
+  }
+  if (accept.asset !== manifest.asset_contract) {
+    return new RouteDockPolicyRejectError("challenge_asset_mismatch");
+  }
+  return checkAmount(accept.amount, maxAmount);
+}
+function filterX402Accepts(accepts, manifest, network, maxAmount) {
+  return accepts.filter((accept) => checkX402Accept(accept, manifest, network, maxAmount) === null);
+}
+function checkChargeChallenge(request, manifest, network, maxAmount) {
+  const methodDetails = request["methodDetails"];
+  const rawNetwork = isRecord(methodDetails) ? methodDetails["network"] : void 0;
+  const challengeNetwork = rawNetwork === void 0 ? "stellar:testnet" : rawNetwork;
+  if (challengeNetwork !== network) {
+    return new RouteDockPolicyRejectError("challenge_network_mismatch");
+  }
+  const recipient = request["recipient"];
+  if (typeof recipient !== "string" || recipient !== resolvePayee(manifest, "mpp-charge")) {
+    return new RouteDockPolicyRejectError("challenge_payee_mismatch");
+  }
+  const currency = request["currency"];
+  if (typeof currency !== "string" || currency !== manifest.asset_contract) {
+    return new RouteDockPolicyRejectError("challenge_asset_mismatch");
+  }
+  return checkAmount(request["amount"], maxAmount);
+}
+
+// src/client/x402Client.ts
+var CAIP2 = {
+  testnet: "stellar:testnet",
+  mainnet: "stellar:pubnet"
+};
+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");
+    }
+    const caip2 = CAIP2[this.network];
+    const probe = await withRetry(async () => {
+      let init2;
+      try {
+        init2 = await fetch(url, { headers: { "X-Preferred-Mode": "x402" } });
+      } catch (err) {
+        throw wrapFetchError(err, "x402 initial request");
+      }
+      if (init2.status !== 402) {
+        if (!init2.ok) {
+          throw httpStatusToError(
+            `x402 initial request failed: HTTP ${init2.status}`,
+            init2.status,
+            init2
+          );
+        }
+        let data2;
+        try {
+          data2 = await init2.json();
+        } catch {
+          throw new RouteDockManifestError(
+            `Failed to parse JSON from non-402 response (HTTP ${init2.status})`
+          );
+        }
+        return { kind: "free", data: data2 };
+      }
+      return { kind: "payment-required", init: init2 };
+    }, this.retryPolicy);
+    if (probe.kind === "free") {
+      return { data: probe.data, txHash: null, mode: "x402", amount: "0", timestamp: Date.now() };
+    }
+    const init = probe.init;
+    const reqHeader = init.headers.get("X-Payment-Requirements");
     if (!reqHeader) {
       throw new RouteDockManifestError("402 response missing X-Payment-Requirements header");
     }
-    const paymentRequired = decodePaymentRequiredHeader(reqHeader);
-    const paymentPayload = await this.httpClient.createPaymentPayload(paymentRequired);
-    const paymentHeaders = this.httpClient.encodePaymentSignatureHeader(paymentPayload);
-    const settled = await fetch(url, { headers: paymentHeaders });
-    if (!settled.ok) {
-      throw new RouteDockManifestError(`x402 payment failed: HTTP ${settled.status}`);
+    let paymentRequired;
+    try {
+      paymentRequired = decodePaymentRequiredHeader(reqHeader);
+    } catch (err) {
+      throw new RouteDockManifestError("402 X-Payment-Requirements header is malformed", {
+        cause: err
+      });
+    }
+    const firstAccept = paymentRequired.accepts[0];
+    if (!firstAccept) {
+      throw new RouteDockManifestError("402 response carries no payment accepts");
+    }
+    const allowed = filterX402Accepts(paymentRequired.accepts, manifest, caip2, pricing.amount);
+    if (allowed.length === 0) {
+      throw checkX402Accept(firstAccept, manifest, caip2, pricing.amount);
+    }
+    let paymentPayload;
+    try {
+      paymentPayload = await this.httpClient.createPaymentPayload({
+        ...paymentRequired,
+        accepts: allowed
+      });
+    } catch (err) {
+      throw new RouteDockSignatureError(`x402 payment signing failed: ${String(err)}`, {
+        cause: err
+      });
     }
+    const paymentHeaders = this.httpClient.encodePaymentSignatureHeader(paymentPayload);
+    const signedAmount = stroopsToUsdc(BigInt(paymentPayload.accepted.amount));
+    const settled = await withRetry(async () => {
+      let response;
+      try {
+        response = await fetch(url, { headers: paymentHeaders });
+      } catch (err) {
+        throw wrapFetchError(err, "x402 settlement request");
+      }
+      if (!response.ok) {
+        if (response.status >= 500 || response.status === 429 || response.status === 503) {
+          throw httpStatusToError(
+            `x402 payment failed: HTTP ${response.status}`,
+            response.status,
+            response
+          );
+        }
+        throw new RouteDockManifestError(`x402 payment failed: HTTP ${response.status}`);
+      }
+      return response;
+    }, this.retryPolicy);
     let txHash = null;
     const responseHeader = settled.headers.get("X-Payment-Response");
     if (responseHeader) {
@@ -320,225 +1310,1558 @@ var X402Client = class {
       } catch {
       }
     }
-    const data = await settled.json();
-    return { data, txHash, mode: "x402", amount: pricing.amount, timestamp: Date.now() };
+    let data;
+    try {
+      data = await settled.json();
+    } catch {
+      throw new RouteDockManifestError("Failed to parse JSON from settled response");
+    }
+    return { data, txHash, mode: "x402", amount: signedAmount, timestamp: Date.now() };
+  }
+};
+var MppChargeClient = class {
+  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");
+    }
+    const caip2 = this.network === "mainnet" ? "stellar:pubnet" : "stellar:testnet";
+    let txHash = null;
+    let signedAmount;
+    let credential;
+    const mppx = Mppx.create({
+      polyfill: false,
+      methods: [
+        stellar.charge({
+          keypair: this.keypair,
+          mode: "pull",
+          onProgress(event) {
+            if (event.type === "paid") {
+              txHash = event.hash;
+            }
+          }
+        })
+      ],
+      onChallenge: async (challenge, { createCredential }) => {
+        const request = challenge.request;
+        const rejection = checkChargeChallenge(request, manifest, caip2, pricing.amount);
+        if (rejection) throw rejection;
+        const amount = request["amount"];
+        if (typeof amount !== "string") {
+          throw new RouteDockPolicyRejectError("challenge_amount_invalid");
+        }
+        signedAmount = stroopsToUsdc(BigInt(amount));
+        credential ??= await createCredential();
+        return credential;
+      }
+    });
+    return withRetry(async () => {
+      let response;
+      try {
+        response = credential ? await mppx.rawFetch(url, { headers: { Authorization: credential } }) : await mppx.fetch(url);
+      } catch (err) {
+        throw wrapMppError(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: signedAmount ?? pricing.amount,
+        timestamp: Date.now()
+      };
+    }, this.retryPolicy);
+  }
+};
+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, logger = consoleLogger) {
+    this.keypair = keypair;
+    this.network = network;
+    this.retryPolicy = retryPolicy;
+    this.webSocketFactory = webSocketFactory;
+    this.logger = logger;
+  }
+  keypair;
+  network;
+  retryPolicy;
+  webSocketFactory;
+  logger;
+  async openSession(url, manifest, commitmentSecret, options, onSpend) {
+    const mode = options?.mode ?? "mpp-session";
+    const pricing = manifest.pricing[mode];
+    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 wrapMppError(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: Contract2, nativeToScVal: nativeToScVal2, TransactionBuilder: TransactionBuilder2, BASE_FEE: BASE_FEE2 } = await import('@stellar/stellar-sdk');
+        const rpcUrl = network === "testnet" ? "https://soroban-testnet.stellar.org" : "https://soroban.stellar.org";
+        const server = new rpcMod.Server(rpcUrl);
+        const contract = new Contract2(channelFactory);
+        const 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 TransactionBuilder2(account, {
+              fee: BASE_FEE2,
+              networkPassphrase: passphrase
+            }).addOperation(
+              contract.call(
+                "prepare_commitment",
+                nativeToScVal2(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: Contract2, TransactionBuilder: TransactionBuilder2, BASE_FEE: BASE_FEE2 } = await import('@stellar/stellar-sdk');
+        const rpcUrl = network === "testnet" ? "https://soroban-testnet.stellar.org" : "https://soroban.stellar.org";
+        const server = new rpcMod.Server(rpcUrl);
+        const contract = new Contract2(channelFactory);
+        const passphrase = network === "mainnet" ? Networks.PUBLIC : Networks.TESTNET;
+        try {
+          const account = await server.getAccount(agentPublicKey);
+          const tx = new TransactionBuilder2(account, { fee: BASE_FEE2, networkPassphrase: passphrase }).addOperation(contract.call("request_refund")).setTimeout(30).build();
+          const 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: Contract2, nativeToScVal: nativeToScVal2, TransactionBuilder: TransactionBuilder2, BASE_FEE: BASE_FEE2 } = await import('@stellar/stellar-sdk');
+        const rpcUrl = network === "testnet" ? "https://soroban-testnet.stellar.org" : "https://soroban.stellar.org";
+        const server = new rpcMod.Server(rpcUrl);
+        const contract = new Contract2(channelFactory);
+        const passphrase = network === "mainnet" ? Networks.PUBLIC : Networks.TESTNET;
+        try {
+          const account = await server.getAccount(agentPublicKey);
+          const simTx = new TransactionBuilder2(account, { fee: BASE_FEE2, networkPassphrase: passphrase }).addOperation(contract.call("prepare_commitment", nativeToScVal2(currentCumulative, { type: "i128" }))).setTimeout(30).build();
+          const 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 TransactionBuilder2(settleAccount, { fee: BASE_FEE2, networkPassphrase: passphrase }).addOperation(
+            contract.call(
+              "settle_with_signature",
+              nativeToScVal2(currentCumulative, { type: "i128" }),
+              nativeToScVal2(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: Contract2, TransactionBuilder: TransactionBuilder2, BASE_FEE: BASE_FEE2 } = await import('@stellar/stellar-sdk');
+        const rpcUrl = network === "testnet" ? "https://soroban-testnet.stellar.org" : "https://soroban.stellar.org";
+        const server = new rpcMod.Server(rpcUrl);
+        const contract = new Contract2(channelFactory);
+        const passphrase = network === "mainnet" ? Networks.PUBLIC : Networks.TESTNET;
+        try {
+          const account = await server.getAccount(agentPublicKey);
+          const tx = new TransactionBuilder2(account, { fee: BASE_FEE2, networkPassphrase: passphrase }).addOperation(contract.call("get_channel_state")).setTimeout(30).build();
+          const 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 });
+          this.logger(
+            "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 wrapMppError(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)})`
+      );
+    }
+    resolveLogger(config.logger)(
+      "warn",
+      "NulthClient is using the insecure mock prover; proofs are not cryptographically sound"
+    );
+  }
+  config;
+  policy;
+  prover;
+  get proverBackend() {
+    return this.prover;
+  }
+  get nulthAccount() {
+    return this.config.nulthAccount;
+  }
+  get allowlistCommitment() {
+    return this.policy.allowlistCommitment;
+  }
+  get capCommitment() {
+    return commitDailyCap(this.policy.dailyCapStroops, this.policy.witnessSecret);
+  }
+  buildPaymentAuthProof(context) {
+    this.enforcePolicy(context);
+    const bucket = dayBucketFromLedger(context.ledgerSequence);
+    if (bucket !== this.policy.dayBucket) {
+      this.policy.dayBucket = bucket;
+      this.policy.dailySpendStroops = 0n;
+    }
+    const authDigest = authDigestFromEntry(context.authEntry);
+    const capCommitment = this.capCommitment;
+    const payeeHash = hashPayee(context.payee);
+    const preimage = [
+      authDigest,
+      this.policy.allowlistCommitment,
+      capCommitment,
+      payeeHash,
+      context.amountStroops.toString(),
+      bucket.toString(),
+      this.config.nulthAccount
+    ].join("|");
+    const proof = {
+      version: 1,
+      proof: insecureMockProof(preimage),
+      publicInputs: {
+        authDigest,
+        allowlistCommitment: this.policy.allowlistCommitment,
+        capCommitment,
+        payeeHash,
+        amountStroops: context.amountStroops.toString(),
+        dayBucket: bucket.toString()
+      }
+    };
+    this.policy.dailySpendStroops += context.amountStroops;
+    return proof;
+  }
+  enforcePolicy(context) {
+    if (context.amountStroops < 0n) {
+      throw new RangeError(`Invalid amountStroops: ${context.amountStroops}`);
+    }
+    if (!Number.isSafeInteger(context.ledgerSequence) || context.ledgerSequence < 0) {
+      throw new RangeError(`Invalid ledgerSequence: ${context.ledgerSequence}`);
+    }
+    if (this.policy.expiryLedger !== void 0 && context.ledgerSequence > this.policy.expiryLedger) {
+      throw new NulthPolicyError("session_expired", "Nulth session expired");
+    }
+    if (!this.policy.allowedPayees.includes(context.payee)) {
+      throw new NulthPolicyError("payee_not_allowed", `Payee ${context.payee} not in off-chain allowlist`);
+    }
+    const bucket = dayBucketFromLedger(context.ledgerSequence);
+    const spend = bucket === this.policy.dayBucket ? this.policy.dailySpendStroops : 0n;
+    if (spend + context.amountStroops > this.policy.dailyCapStroops) {
+      throw new NulthPolicyError("daily_cap_exceeded", "Nulth daily cap exceeded");
+    }
   }
 };
-var MppChargeClient = class {
-  constructor(keypair, network) {
-    this.keypair = keypair;
-    this.network = network;
+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`);
   }
-  keypair;
-  network;
-  async pay(url, manifest) {
-    const pricing = manifest.pricing["mpp-charge"];
-    if (!pricing) {
-      throw new RouteDockManifestError("manifest.pricing.mpp-charge missing");
+  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 = ledgerSequenceOverride ?? await fetchLedgerSequence(network);
+  const policy = createPolicyState({
+    dailyCapUsdc: vault.dailyCapUsdc,
+    allowedPayees: vault.allowedPayees,
+    witnessSecret: vault.witnessSecret,
+    ledgerSequence,
+    ...vault.expiryLedger !== void 0 ? { expiryLedger: vault.expiryLedger } : {}
+  });
+  const config = {
+    nulthAccount: vault.nulthAccount,
+    network,
+    prover,
+    policy,
+    ...vault.verifierContract !== void 0 ? { verifierContract: vault.verifierContract } : {}
+  };
+  if (mode === "x402" || mode === "mpp-charge") {
+    setNulthPaymentContext(config, paymentContextFromManifest(manifest, mode, ledgerSequence));
+  } else {
+    throw new RouteDockManifestError(`Nulth ZK vault does not support payment mode: ${mode}`);
+  }
+  const signer = createNulthSigner(config);
+  return { signer, config };
+}
+function decodeAuthSignature(encoded) {
+  const raw = JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
+  if (typeof raw !== "object" || raw === null || raw.nulth !== "zk-v1") {
+    throw new Error("Invalid Nulth ZK auth signature");
+  }
+  return raw;
+}
+var FileSpendStore = class {
+  filePath;
+  constructor(filePath) {
+    this.filePath = filePath;
+  }
+  async read() {
+    let data;
+    try {
+      data = await fs.readFile(this.filePath, "utf-8");
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return null;
+      }
+      throw new Error(
+        `[FileSpendStore] Failed to read spend file at ${this.filePath}: ${err.message}`
+      );
     }
-    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;
-            }
-          }
-        })
-      ]
-    });
-    const response = await mppx.fetch(url);
-    if (!response.ok) {
-      throw new RouteDockManifestError(`MPP charge failed: HTTP ${response.status}`);
+    try {
+      return JSON.parse(data);
+    } catch {
+      throw new Error(
+        `[FileSpendStore] Spend file at ${this.filePath} contains invalid JSON. Delete or repair it before resuming. Raw content: ${data.slice(0, 120)}`
+      );
     }
-    const data = await response.json();
-    return { data, txHash, mode: "mpp-charge", amount: pricing.amount, timestamp: Date.now() };
+  }
+  async write(state) {
+    const dir = path.dirname(this.filePath);
+    await fs.mkdir(dir, { recursive: true });
+    const tmpPath = `${this.filePath}.tmp`;
+    await fs.writeFile(tmpPath, JSON.stringify(state, null, 2), "utf-8");
+    await fs.rename(tmpPath, this.filePath);
   }
 };
-var MIN_REFUND_WAITING_PERIOD = 17280;
-var MppSessionClient = class {
-  constructor(keypair, network) {
-    this.keypair = keypair;
-    this.network = network;
+
+// src/store/SpendStore.ts
+var InMemorySpendStore = class {
+  state = null;
+  constructor(options = {}) {
+    if (options.warn !== false) {
+      resolveLogger(options.logger)(
+        "warn",
+        "[RouteDock] Using in-memory SpendStore: the daily spend cap is NOT durable and resets on every process restart. Inject a persistent SpendStore via RouteDockClientConfig.spendStore for production safety."
+      );
+    }
   }
-  keypair;
-  network;
-  async openSession(url, manifest, commitmentSecret) {
-    const pricing = manifest.pricing["mpp-session"];
-    if (!pricing) {
-      throw new RouteDockManifestError("manifest.pricing.mpp-session missing");
+  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"`
+      );
     }
-    const refundPeriod = pricing.refund_waiting_period_ledgers;
-    if (refundPeriod < MIN_REFUND_WAITING_PERIOD) {
+    if (url.pathname !== "/" || url.search !== "" || url.hash !== "") {
       throw new RouteDockManifestError(
-        `refund_waiting_period_ledgers ${refundPeriod} < minimum ${MIN_REFUND_WAITING_PERIOD}`
+        `spendCap.endpointCaps key "${key}" must be an origin only (no path, query, or hash) \u2014 use "${url.origin}"`
       );
     }
-    const commitmentKey = Keypair.fromSecret(commitmentSecret);
-    const channelContract = pricing.channel_contract;
-    const agentPublicKey = this.keypair.publicKey();
-    let currentCumulative = 0n;
-    let vouchersIssued = 0;
-    const mppx = Mppx.create({
-      polyfill: false,
-      methods: [
-        stellar$1.channel({
-          commitmentKey,
-          sourceAccount: this.keypair.publicKey(),
-          onProgress(event) {
-            if (event.type === "signed") {
-              currentCumulative = BigInt(event.cumulativeAmount);
-            }
-          }
-        })
-      ]
-    });
-    const openTxHash = channelContract;
-    const handle = {
-      channelId: channelContract,
-      openTxHash,
-      async *stream() {
-        while (true) {
-          let resp = null;
-          for (let attempt = 0; attempt < 3; attempt++) {
-            try {
-              resp = await mppx.fetch(url);
-              if (resp.ok) break;
-              resp = null;
-            } catch {
-              if (attempt === 2) throw new RouteDockSessionError("Voucher request failed after 3 retries");
-              await new Promise((r) => setTimeout(r, 1e3 * (attempt + 1)));
-            }
-          }
-          if (!resp || !resp.ok) {
-            throw new RouteDockSessionError(`Voucher request failed: HTTP ${resp?.status ?? "unknown"}`);
-          }
-          vouchersIssued++;
-          yield await resp.json();
-        }
-      },
-      async close() {
-        const { rpc: rpcMod, Contract, nativeToScVal, TransactionBuilder, BASE_FEE } = await import('@stellar/stellar-sdk');
-        const rpcUrl = "https://soroban-testnet.stellar.org";
-        const server = new rpcMod.Server(rpcUrl);
-        const contract = new Contract(channelContract);
-        const passphrase = "Test SDF Network ; September 2015";
-        const account = await server.getAccount(agentPublicKey);
-        const simTx = new TransactionBuilder(account, { fee: BASE_FEE, networkPassphrase: passphrase }).addOperation(contract.call("prepare_commitment", nativeToScVal(currentCumulative, { type: "i128" }))).setTimeout(30).build();
-        const simResult = await server.simulateTransaction(simTx);
-        if (rpcMod.Api.isSimulationError(simResult)) {
-          throw new RouteDockSessionError(`prepare_commitment simulation failed: ${simResult.error}`);
-        }
-        const commitmentBytes = simResult.result?.retval?.bytes();
-        if (!commitmentBytes) throw new RouteDockSessionError("prepare_commitment returned no bytes");
-        const signature = commitmentKey.sign(Buffer.from(commitmentBytes));
-        const closeResp = await fetch(url, {
-          method: "DELETE",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({
-            amount: currentCumulative.toString(),
-            signature: Buffer.from(signature).toString("hex")
-          })
-        });
-        if (!closeResp.ok) {
-          throw new RouteDockSessionError(`Channel close failed: HTTP ${closeResp.status}`);
-        }
-        const closeData = await closeResp.json();
-        const closeTxHash = closeData.closeTxHash ?? null;
-        if (!closeTxHash) {
-          throw new RouteDockSessionError("Channel close response missing closeTxHash");
-        }
-        const totalPaid = (Number(currentCumulative) / 1e7).toFixed(7);
-        return { closeTxHash, totalPaid, vouchersIssued };
-      }
-    };
-    return handle;
+    const origin = url.origin;
+    if (Object.prototype.hasOwnProperty.call(normalized, origin)) {
+      throw new RouteDockManifestError(
+        `spendCap.endpointCaps has two keys that both normalize to origin "${origin}" \u2014 remove the duplicate`
+      );
+    }
+    normalized[origin] = value;
   }
+  return normalized;
+}
+function normalizeSpendCap(spendCap) {
+  const endpointCaps = normalizeEndpointCaps(spendCap.endpointCaps);
+  return endpointCaps === void 0 ? spendCap : { ...spendCap, endpointCaps };
+}
+var usdcToMicros = usdcToStroops;
+var ASSET_ISSUERS = {
+  USDC: USDC_ISSUERS
 };
-
-// src/client/RouteDockClient.ts
-var RouteDockClient = class {
+function getAssetIssuer(asset, network) {
+  return ASSET_ISSUERS[asset]?.[network] ?? "";
+}
+var TRUSTLINE_CACHE_TTL_MS = 3e5;
+var RouteDockClient = class _RouteDockClient {
+  /** Per-(account,asset) trustline existence cache keyed by `${network}:${pubkey}:${asset}` */
+  static _trustlineCache = /* @__PURE__ */ new Map();
   keypair;
   network;
   spendCap;
-  commitmentSecret;
-  /** Local daily accumulator keyed by YYYY-MM-DD */
-  dailySpend = { date: "", total: 0 };
+  retryPolicy;
+  logger;
+  manifestTimeoutMs;
+  expectedPayee;
+  vault;
+  /**
+   * Durable backing store for the local daily spend accumulator (keyed by
+   * YYYY-MM-DD). Totals are persisted as decimal strings of microUSDC
+   * (1 USDC = 10^7) so stores stay JSON-safe with no precision loss.
+   */
+  spendStore;
   x402;
   charge;
   session;
+  /**
+   * Promise-chain mutex for serializing read-modify-write on the spend
+   * accumulator. Each pay() call awaits the previous one, preventing
+   * concurrent read-modify-write races that could overrun the cap.
+   */
+  _spendMutex = Promise.resolve();
+  /**
+   * Pending spend reservations keyed by reserveId. Used by _rollbackSpend
+   * to revert the accumulator when a payment fails after reservation.
+   */
+  _pendingReserves = /* @__PURE__ */ new Map();
   constructor(config) {
     this.keypair = typeof config.wallet === "string" ? Keypair.fromSecret(config.wallet) : config.wallet;
     this.network = config.network;
-    this.spendCap = config.spendCap;
-    this.commitmentSecret = config.commitmentSecret;
+    this.spendCap = config.spendCap ? normalizeSpendCap(config.spendCap) : void 0;
+    this.retryPolicy = config.retryPolicy;
+    this.spendStore = config.spendStore ?? new InMemorySpendStore({
+      warn: !!config.spendCap,
+      ...config.logger && { logger: config.logger }
+    });
+    this.logger = config.logger;
+    this.manifestTimeoutMs = config.manifestTimeoutMs;
+    this.expectedPayee = config.expectedPayee;
+    if (config.commitmentSecret) {
+      _secrets.set(this, config.commitmentSecret);
+    }
+    this.vault = config.vault;
+    if (config.commitmentSecret) {
+      _secrets.set(this, config.commitmentSecret);
+    }
     const secretKey = this.keypair.secret();
-    this.x402 = new X402Client(secretKey, this.network);
-    this.charge = new MppChargeClient(this.keypair, this.network);
-    this.session = new MppSessionClient(this.keypair, this.network);
+    const retryPolicy = this.logger ? { ...this.retryPolicy, logger: this.logger } : this.retryPolicy;
+    this.x402 = new X402Client(secretKey, this.network, retryPolicy);
+    this.charge = new MppChargeClient(this.keypair, this.network, retryPolicy);
+    this.session = new MppSessionClient(this.keypair, this.network, retryPolicy, void 0, this.logger);
+  }
+  /** Fetch manifest and select mode — shared by pay() and estimateCost(). */
+  async _resolveManifest(url, options) {
+    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, mode, endpoint) {
+    assertManifestValid(manifest);
+    const selectedAsset = mode ? selectAsset(manifest, mode, endpoint).asset : manifest.asset;
+    await this._checkTrustline(manifest, selectedAsset);
+    return {
+      hasTrustline: true,
+      asset: selectedAsset,
+      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, targetAsset = manifest.asset) {
+    const cacheKey = `${this.network}:${this.keypair.publicKey()}:${targetAsset}`;
+    const cached = _RouteDockClient._trustlineCache.get(cacheKey);
+    if (cached && Date.now() < cached.expiresAt) return;
+    const horizonUrl = this.network === "testnet" ? "https://horizon-testnet.stellar.org" : "https://horizon.stellar.org";
+    const server = new Horizon.Server(horizonUrl);
+    try {
+      const account = await server.loadAccount(this.keypair.publicKey());
+      const balances = account.balances;
+      const expectedIssuer = getAssetIssuer(targetAsset, this.network);
+      const hasTrustline = balances.some(
+        (b) => typeof b === "object" && b !== null && (targetAsset === "XLM" && b.asset_type === "native" || "asset_code" in b && b.asset_code === targetAsset && (!expectedIssuer || b.asset_issuer === expectedIssuer))
+      );
+      if (!hasTrustline) {
+        const remediation = expectedIssuer ? `Run: stellar tx new --source ${this.keypair.publicKey()} --network ${this.network} change-trust --asset ${targetAsset}:${expectedIssuer} --limit 100000` : `Establish a trustline for ${targetAsset} with the appropriate issuer on ${this.network}`;
+        throw new RouteDockTrustlineError(targetAsset, expectedIssuer || "unknown", remediation);
+      }
+      _RouteDockClient._trustlineCache.set(cacheKey, {
+        exists: true,
+        expiresAt: Date.now() + TRUSTLINE_CACHE_TTL_MS
+      });
+    } catch (err) {
+      if (err instanceof RouteDockTrustlineError) throw err;
+      this.logger?.(
+        "warn",
+        `[RouteDock] Trustline preflight: could not verify trustline for ${targetAsset} \u2014 continuing`
+      );
+    }
   }
   /**
    * Pay for one request at `url`. Fetches manifest, selects payment mode,
-   * checks local spend cap, executes payment, returns result.
+   * runs trustline preflight, reserves local spend cap BEFORE executing the
+   * payment, then commits the spend record on success. Rolls back the
+   * reservation if the on-chain payment fails, and also when the call
+   * completes without paying anything (an x402 endpoint answering a plain
+   * 200 with no challenge). Concurrent pay() calls are serialized through a
+   * per-instance mutex to prevent spend-cap overrun.
    */
   async pay(url, options) {
     const baseUrl = new URL(url).origin;
-    const manifest = await fetchManifest(baseUrl);
-    const mode = selectMode(manifest, options);
-    let result;
+    const manifest = await fetchManifest(baseUrl, this.retryPolicy, this.manifestTimeoutMs, this.expectedPayee);
+    assertEndpointActive(manifest, url, this.logger);
+    const mode = selectMode(manifest, { ...options, ...this.logger && { logger: this.logger } });
+    const selectedAsset = selectAsset(manifest, mode, url).asset;
+    await this._checkTrustline(manifest, selectedAsset);
+    let amount;
     switch (mode) {
       case "x402":
-        result = await this.x402.pay(url, manifest);
+        amount = manifest.pricing.x402.amount;
         break;
       case "mpp-charge":
-        result = await this.charge.pay(url, manifest);
+        amount = manifest.pricing["mpp-charge"].amount;
         break;
       case "mpp-session":
+      case "mpp-session-ws":
         throw new RouteDockManifestError(
-          "Use client.openSession() for mpp-session mode \u2014 client.pay() only handles discrete payments"
+          `Use client.openSession() for ${mode} mode \u2014 client.pay() only handles discrete payments`
         );
       default:
         throw new RouteDockManifestError(`Unknown payment mode: ${mode}`);
     }
-    this._checkAndRecordSpend(result.amount);
+    const reserveId = await this._checkAndReserveSpend(amount, baseUrl);
+    let result;
+    try {
+      if (this.vault?.mode === "nulth") {
+        result = await this._payWithNulthVault(url, manifest, mode);
+      } else {
+        switch (mode) {
+          case "x402":
+            result = await this.x402.pay(url, manifest);
+            break;
+          case "mpp-charge":
+            result = await this.charge.pay(url, manifest);
+            break;
+          default:
+            throw new RouteDockManifestError(`Unknown payment mode: ${mode}`);
+        }
+      }
+    } catch (err) {
+      await this._rollbackSpend(reserveId).catch(() => {
+      });
+      throw err;
+    }
+    if (result.txHash === null && result.amount === "0") {
+      await this._rollbackSpend(reserveId);
+    } else {
+      await this._commitSpend(reserveId);
+    }
     return result;
   }
+  /** Nulth ZK vault path — proof built off-chain, attached as auth signature */
+  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}`);
+    }
+    const selectedAsset = selectAsset(manifest, mode, url).asset;
+    return {
+      amount,
+      asset: selectedAsset,
+      mode,
+      manifest,
+      ...manifest.regions && { regions: manifest.regions },
+      ...manifest.latency_hints && { latency_hints: manifest.latency_hints },
+      ...manifest.capabilities && { capabilities: manifest.capabilities }
+    };
+  }
   /**
    * Open a sustained MPP session at `url`. Verifies mpp-session is supported
    * before opening a channel. Returns a SessionHandle for streaming + closing.
+   *
+   * By default the session auto-closes after a wall-clock timeout (1h) so an
+   * orphaned channel cannot keep collateral locked on-chain — override or
+   * disable via `options.maxDurationMs`.
    */
-  async openSession(url) {
+  async openSession(url, options) {
     const baseUrl = new URL(url).origin;
-    const manifest = await fetchManifest(baseUrl);
-    if (!manifest.modes.includes("mpp-session")) {
+    const manifest = await fetchManifest(baseUrl, this.retryPolicy, this.manifestTimeoutMs, this.expectedPayee);
+    assertEndpointActive(manifest, url, this.logger);
+    const mode = options?.mode ?? "mpp-session";
+    if (!manifest.modes.includes(mode)) {
       throw new RouteDockManifestError(
-        `Provider at ${baseUrl} does not support mpp-session mode`
+        `Provider at ${baseUrl} does not support ${mode} mode`
       );
     }
-    if (!this.commitmentSecret) {
+    const secret = _secrets.get(this);
+    if (!secret) {
       throw new RouteDockManifestError(
         "commitmentSecret is required in RouteDockClientConfig for mpp-session mode"
       );
     }
-    return this.session.openSession(url, manifest, this.commitmentSecret);
+    const endpointKey = new URL(url).origin;
+    const onSpend = this.spendCap ? (amount) => this._recordSessionSpend(amount, endpointKey) : void 0;
+    return this.session.openSession(url, manifest, secret, options, onSpend);
   }
-  /** Check local daily cap and record the spend. Throws if cap exceeded. */
-  _checkAndRecordSpend(amount) {
-    if (!this.spendCap) return;
-    const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-    if (this.dailySpend.date !== today) {
-      this.dailySpend = { date: today, total: 0 };
-    }
-    const amountNum = parseFloat(amount);
-    const capNum = parseFloat(this.spendCap.daily);
-    if (this.dailySpend.total + amountNum > capNum) {
-      throw new RouteDockPolicyRejectedError("local_daily_cap_exceeded");
+  /**
+   * Record spend for an MPP session voucher. Called before each voucher
+   * fetch in stream(). Enforces the same local daily and per-endpoint caps
+   * as discrete pay() calls. Returns a commit function to clean up the
+   * reservation after the voucher fetch succeeds.
+   */
+  async _recordSessionSpend(amount, endpointKey) {
+    const reserveId = await this._checkAndReserveSpend(amount, endpointKey);
+    if (reserveId) {
+      await this._commitSpend(reserveId);
     }
-    this.dailySpend.total += amountNum;
+  }
+  /**
+   * Remove the commitment secret from memory and make it eligible for GC.
+   * Call when this client instance is no longer needed — particularly in
+   * long-lived processes or Worker threads.
+   */
+  dispose() {
+    _secrets.delete(this);
+  }
+  /**
+   * Evict the cached manifest for `url` immediately, so the next pay() /
+   * estimateCost() / openSession() call re-fetches it instead of routing on
+   * the stale cached copy. Use when a provider signals their manifest
+   * changed (e.g. after a config update) and the change must take effect
+   * before the cache TTL expires.
+   */
+  invalidateManifest(url) {
+    invalidateManifest(new URL(url).origin);
+  }
+  /**
+   * Reserve spend against local daily caps BEFORE dispatching payment.
+   * Returns a reserveId that must be passed to _commitSpend() on success
+   * or _rollbackSpend() on failure.
+   *
+   * The entire read-check-write is serialized through the per-instance
+   * mutex (_withSpendMutex) so concurrent pay() calls cannot interleave
+   * and overrun the cap.
+   *
+   * Enforcement order:
+   *   1. Per-endpoint cap (if `endpointCaps[endpointKey]` is set) — checked first.
+   *   2. Global daily cap — checked second.
+   *
+   * Both limits are independent: a payment is only reserved after **both** pass.
+   * All spend (regardless of endpoint) counts toward the global accumulator.
+   */
+  async _checkAndReserveSpend(amount, endpointKey) {
+    if (!this.spendCap) return "";
+    return this._withSpendMutex(async () => {
+      const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+      const persisted = await this.spendStore.read();
+      const current = persisted && persisted.date === today ? persisted : { date: today, totalMicros: "0", endpoints: {} };
+      const amountMicros = 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);
+    });
   }
 };
 
@@ -550,12 +2873,16 @@ var SupabaseSessionStore = class {
   supabase;
   async get(channelId) {
     const { data, error } = await this.supabase.from("sessions").select("*").eq("channel_id", channelId).maybeSingle();
-    if (error) throw new RouteDockSessionError(`SessionStore.get failed: ${error.message}`);
+    if (error) {
+      throw new RouteDockNetworkError(`SessionStore.get failed: ${error.message}`);
+    }
     if (!data) return null;
     return {
       channel_id: data.channel_id,
       payee: data.payee,
       payer: data.payer,
+      channel_contract: data.channel_contract,
+      network: data.network,
       cumulative_amount: String(data.cumulative_amount),
       last_signature: data.last_signature,
       status: data.status,
@@ -570,39 +2897,191 @@ var SupabaseSessionStore = class {
       const prev = parseFloat(existing.cumulative_amount);
       const next = parseFloat(state.cumulative_amount);
       if (next <= prev) {
-        throw new RouteDockSessionError(
+        throw new RouteDockVoucherMonotonicityError(
           `cumulative_amount must be strictly increasing: ${next} <= ${prev}`
         );
       }
     }
-    const { error } = await this.supabase.from("sessions").upsert(
+    const { error } = await this.supabase.from("sessions").upsert(
+      {
+        channel_id: state.channel_id,
+        payee: state.payee,
+        payer: state.payer,
+        channel_contract: state.channel_contract,
+        network: state.network,
+        cumulative_amount: state.cumulative_amount,
+        last_signature: state.last_signature,
+        status: state.status,
+        opened_at: state.opened_at,
+        updated_at: (/* @__PURE__ */ new Date()).toISOString(),
+        settlement_tx_hash: state.settlement_tx_hash
+      },
+      { onConflict: "channel_id" }
+    );
+    if (error) {
+      if (error.message.includes("strictly increasing")) {
+        throw new RouteDockVoucherMonotonicityError(
+          `cumulative_amount must be strictly increasing (DB): ${error.message}`
+        );
+      }
+      throw new RouteDockNetworkError(`SessionStore.upsert failed: ${error.message}`);
+    }
+  }
+  async setStatus(channelId, status, settlementTxHash) {
+    const payload = {
+      status,
+      updated_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (settlementTxHash !== void 0) {
+      payload.settlement_tx_hash = settlementTxHash;
+    }
+    const { error } = await this.supabase.from("sessions").update(payload).eq("channel_id", channelId);
+    if (error) {
+      throw new RouteDockNetworkError(`SessionStore.setStatus failed: ${error.message}`);
+    }
+  }
+  async close(channelId) {
+    await this.setStatus(channelId, "closed");
+  }
+};
+
+// src/store/SupabaseSeenTxStore.ts
+var SupabaseSeenTxStore = class {
+  constructor(supabase) {
+    this.supabase = supabase;
+  }
+  supabase;
+  async get(key) {
+    const { data, error } = await this.supabase.from("settlements").select("tx_hash, headers, created_at").eq("key", key).maybeSingle();
+    if (error) {
+      throw new RouteDockNetworkError(`SupabaseSeenTxStore.get failed: ${error.message}`);
+    }
+    if (!data) return void 0;
+    const headers = data.headers;
+    return {
+      txHash: data.tx_hash ?? null,
+      ...headers ? { headers } : {},
+      createdAt: Date.parse(data.created_at)
+    };
+  }
+  async set(key, record) {
+    const { error } = await this.supabase.from("settlements").upsert(
       {
-        channel_id: state.channel_id,
-        payee: state.payee,
-        payer: state.payer,
-        cumulative_amount: state.cumulative_amount,
-        last_signature: state.last_signature,
-        status: state.status,
-        opened_at: state.opened_at,
-        updated_at: (/* @__PURE__ */ new Date()).toISOString(),
-        settlement_tx_hash: state.settlement_tx_hash
+        key,
+        tx_hash: record.txHash,
+        headers: record.headers ?? null,
+        created_at: new Date(record.createdAt ?? Date.now()).toISOString()
       },
-      { onConflict: "channel_id" }
+      { onConflict: "key" }
     );
     if (error) {
-      if (error.message.includes("strictly increasing")) {
-        throw new RouteDockSessionError(
-          `cumulative_amount must be strictly increasing (DB): ${error.message}`
+      throw new RouteDockNetworkError(`SupabaseSeenTxStore.set failed: ${error.message}`);
+    }
+  }
+  /**
+   * Atomically increment the settlement's replay counter through the
+   * `claim_settlement_replay` Postgres function (migration 006). The UPDATE's
+   * row lock gives concurrent claims distinct counts. Returns `Infinity` when
+   * the key no longer exists, so the caller treats it as spent.
+   */
+  async claimReplay(key) {
+    const { data, error } = await this.supabase.rpc("claim_settlement_replay", {
+      p_key: key
+    });
+    if (error) {
+      throw new RouteDockNetworkError(`SupabaseSeenTxStore.claimReplay failed: ${error.message}`);
+    }
+    if (data == null) return Number.POSITIVE_INFINITY;
+    return data;
+  }
+};
+function extractPayerAddress(key) {
+  if (typeof key !== "string") return null;
+  return StrKey.isValidEd25519PublicKey(key) || StrKey.isValidMed25519PublicKey(key) ? key : null;
+}
+
+// src/provider/SeenTxStore.ts
+var SETTLEMENT_REPLAY_WINDOW_MS = 6e4;
+var MAX_SETTLEMENT_REPLAYS = 1;
+async function checkSettlementReplay(store, key, now = Date.now()) {
+  const record = await store.get(key);
+  if (!record) return { kind: "miss" };
+  const { createdAt } = record;
+  if (createdAt !== void 0 && now - createdAt > SETTLEMENT_REPLAY_WINDOW_MS) {
+    return { kind: "spent" };
+  }
+  if (store.claimReplay) {
+    const replayed = await store.claimReplay(key);
+    if (replayed > MAX_SETTLEMENT_REPLAYS) return { kind: "spent" };
+  }
+  return { kind: "replay", record };
+}
+var InMemorySeenTxStore = class {
+  map = /* @__PURE__ */ new Map();
+  replayCounts = /* @__PURE__ */ new Map();
+  order = [];
+  constructor(maxEntriesOrOptions = 1e4) {
+    const options = typeof maxEntriesOrOptions === "number" ? { maxEntries: maxEntriesOrOptions } : maxEntriesOrOptions;
+    this.maxEntries = options.maxEntries ?? 1e4;
+    if (options.warn !== false) {
+      const isServerless = typeof globalThis.navigator !== "undefined" && globalThis.navigator.userAgent === "Cloudflare-Workers";
+      if (isServerless) {
+        resolveLogger(options.logger)(
+          "warn",
+          "[RouteDock] Using in-memory SeenTxStore: settlement deduplication is NOT durable and resets on every isolate restart. Supply a SupabaseSeenTxStore (or other durable SeenTxStore) for production safety."
         );
       }
-      throw new RouteDockSessionError(`SessionStore.upsert failed: ${error.message}`);
     }
   }
-  async close(channelId) {
-    const { error } = await this.supabase.from("sessions").update({ status: "closed", updated_at: (/* @__PURE__ */ new Date()).toISOString() }).eq("channel_id", channelId);
-    if (error) throw new RouteDockSessionError(`SessionStore.close failed: ${error.message}`);
+  maxEntries;
+  get(key) {
+    return this.map.get(key);
+  }
+  set(key, record) {
+    if (!this.map.has(key)) {
+      this.order.push(key);
+      if (this.order.length > this.maxEntries) {
+        const evicted = this.order.shift();
+        if (evicted !== void 0) {
+          this.map.delete(evicted);
+          this.replayCounts.delete(evicted);
+        }
+      }
+    }
+    this.map.set(key, record);
+  }
+  claimReplay(key) {
+    if (!this.map.has(key)) return Number.POSITIVE_INFINITY;
+    const next = (this.replayCounts.get(key) ?? 0) + 1;
+    this.replayCounts.set(key, next);
+    return next;
   }
 };
+async function sha256Hex2(input) {
+  const buf = new TextEncoder().encode(input);
+  const digest = await crypto.subtle.digest("SHA-256", buf);
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function paymentIdempotencyKey(getHeader, scope) {
+  const material = getHeader("payment-signature") ?? getHeader("x-payment") ?? getHeader("authorization");
+  if (!material) return null;
+  return sha256Hex2(
+    [scope.method, scope.path, scope.amount, scope.payTo, material].join("\n")
+  );
+}
+
+// src/provider/settleResult.ts
+function readSettleResult(result) {
+  const settle = result;
+  const failed = (reason) => reason ? { ok: false, reason } : { ok: false };
+  if (!settle || settle.success !== true) return failed(settle?.errorReason);
+  if (typeof settle.transaction !== "string" || settle.transaction.length === 0) {
+    return failed(settle.errorReason);
+  }
+  return { ok: true, txHash: settle.transaction };
+}
+
+// src/provider/x402Handler.ts
 var CAIP22 = {
   testnet: "stellar:testnet",
   mainnet: "stellar:pubnet"
@@ -612,6 +3091,8 @@ function createX402Handler(opts) {
   const caip2 = CAIP22[opts.network];
   const payeeKeypair = Keypair.fromSecret(opts.payeeSecretKey);
   const signer = createEd25519Signer(opts.payeeSecretKey, caip2);
+  const logger = resolveLogger(opts.logger);
+  const seenTxStore = opts.seenTxStore ?? new InMemorySeenTxStore({ logger });
   const useOzFacilitator = opts.network === "mainnet" && opts.facilitatorApiKey;
   const localFacilitator = new ExactStellarScheme$1([signer], {
     areFeesSponsored: true
@@ -630,23 +3111,31 @@ function createX402Handler(opts) {
     ozServer = new x402ResourceServer(facilitator);
     ozServer.register(caip2, new ExactStellarScheme$2());
   }
-  const amountInBaseUnits = String(Math.round(parseFloat(opts.amount) * 1e7));
-  const requirements = {
-    scheme: "exact",
-    network: caip2,
-    asset: opts.assetContract,
-    amount: amountInBaseUnits,
-    payTo: opts.manifest.payee,
-    maxTimeoutSeconds: 60,
-    extra: {
-      areFeesSponsored: true,
-      ...useOzFacilitator ? {} : { facilitatorAddresses: [payeeKeypair.publicKey()] }
-    }
-  };
+  const amountInBaseUnits = String(usdcToUnits(opts.amount));
+  const payTo = resolvePayee(opts.manifest, "x402");
   return async (req, res, next) => {
     try {
-      const paymentHeader = req.headers["payment-signature"] ?? req.headers["x-payment"];
-      if (!paymentHeader) {
+      const endpoint = req.path || req.originalUrl;
+      const assetContract = resolveAssetContract(
+        opts.manifest,
+        "x402",
+        endpoint,
+        opts.assetContract
+      );
+      const requirements = {
+        scheme: "exact",
+        network: caip2,
+        asset: assetContract,
+        amount: amountInBaseUnits,
+        payTo,
+        maxTimeoutSeconds: 60,
+        extra: {
+          areFeesSponsored: true,
+          ...useOzFacilitator ? {} : { facilitatorAddresses: [payeeKeypair.publicKey()] }
+        }
+      };
+      const respondPaymentRequired = async (error, reason) => {
+        const body = { error, ...reason ? { reason } : {} };
         if (ozServer) {
           const resourceInfo = {
             url: `${req.protocol}://${req.get("host") ?? ""}${req.originalUrl}`,
@@ -656,7 +3145,7 @@ function createX402Handler(opts) {
             [requirements],
             resourceInfo
           );
-          res.status(402).setHeader("Content-Type", "application/json").setHeader("X-Payment-Requirements", encodePaymentRequiredHeader(paymentRequired)).json({ error: "Payment Required" });
+          res.status(402).setHeader("Content-Type", "application/json").setHeader("X-Payment-Requirements", encodePaymentRequiredHeader(paymentRequired)).json(body);
         } else {
           const x402Response = {
             x402Version: 2,
@@ -666,23 +3155,65 @@ function createX402Handler(opts) {
             },
             accepts: [requirements]
           };
-          res.status(402).setHeader("Content-Type", "application/json").setHeader("X-Payment-Requirements", encodePaymentRequiredHeader(x402Response)).json({ error: "Payment Required" });
+          res.status(402).setHeader("Content-Type", "application/json").setHeader("X-Payment-Requirements", encodePaymentRequiredHeader(x402Response)).json(body);
         }
+      };
+      const paymentHeader = req.headers["payment-signature"] ?? req.headers["x-payment"];
+      if (!paymentHeader) {
+        await respondPaymentRequired("Payment Required");
         return;
       }
+      const idempotencyKey = await paymentIdempotencyKey(
+        (name) => {
+          const v = req.headers[name.toLowerCase()];
+          return Array.isArray(v) ? v[0] : v;
+        },
+        {
+          method: req.method,
+          path: req.originalUrl.split("?")[0],
+          amount: requirements.amount,
+          payTo: requirements.payTo
+        }
+      );
+      if (idempotencyKey) {
+        const replayCheck = await checkSettlementReplay(seenTxStore, idempotencyKey);
+        if (replayCheck.kind === "spent") {
+          res.status(402).json({ error: "Payment already used" });
+          return;
+        }
+        if (replayCheck.kind === "replay") {
+          if (replayCheck.record.headers) {
+            for (const [k, val] of Object.entries(replayCheck.record.headers)) {
+              res.setHeader(k, val);
+            }
+          }
+          next();
+          return;
+        }
+      }
       const payload = decodePaymentSignatureHeader(paymentHeader);
       let txHash = null;
+      let payerAddress = null;
+      try {
+        const creds = payload.authorization?.credentials;
+        const key = Array.isArray(creds) ? creds[0]?.publicKey : void 0;
+        payerAddress = extractPayerAddress(key);
+      } catch {
+      }
       if (ozServer) {
         const settleResult = await ozServer.settlePayment(payload, requirements);
-        txHash = settleResult.transaction ?? null;
-        if (settleResult) {
-          res.setHeader(
-            "X-Payment-Response",
-            encodePaymentResponseHeader(
-              settleResult
-            )
-          );
+        const outcome = readSettleResult(settleResult);
+        if (!outcome.ok) {
+          await respondPaymentRequired("Payment settlement failed", outcome.reason);
+          return;
         }
+        txHash = outcome.txHash;
+        res.setHeader(
+          "X-Payment-Response",
+          encodePaymentResponseHeader(
+            settleResult
+          )
+        );
       } else {
         const verifyResult = await localFacilitator.verify(
           payload,
@@ -699,22 +3230,40 @@ function createX402Handler(opts) {
           payload,
           requirements
         );
-        txHash = settleResult.transaction ?? null;
-        if (settleResult) {
-          res.setHeader(
-            "X-Payment-Response",
-            encodePaymentResponseHeader(
-              settleResult
-            )
-          );
+        const outcome = readSettleResult(settleResult);
+        if (!outcome.ok) {
+          await respondPaymentRequired("Payment settlement failed", outcome.reason);
+          return;
+        }
+        txHash = outcome.txHash;
+        res.setHeader(
+          "X-Payment-Response",
+          encodePaymentResponseHeader(
+            settleResult
+          )
+        );
+      }
+      if (idempotencyKey) {
+        const headers = {};
+        const paymentResponse = res.getHeader("X-Payment-Response");
+        if (typeof paymentResponse === "string") {
+          headers["X-Payment-Response"] = paymentResponse;
         }
+        await seenTxStore.set(idempotencyKey, { txHash, headers, createdAt: Date.now() });
       }
       if (txHash && opts.onSettled) {
-        await opts.onSettled(txHash, opts.amount, "x402");
+        Promise.resolve().then(() => opts.onSettled(txHash, opts.amount, "x402", payerAddress)).catch((err) => {
+          logger("error", "[x402] onSettled callback error", { error: err });
+          opts.onCallbackError?.(err, "onSettled");
+        });
       }
       next();
     } catch (err) {
-      console.error("[x402] Settlement error:", err);
+      if (err instanceof RouteDockManifestError) {
+        next(err);
+        return;
+      }
+      logger("error", "[x402] Settlement error", { error: err });
       res.status(500).json({ error: "Payment settlement failed" });
     }
   };
@@ -726,25 +3275,87 @@ var MPP_NETWORK = {
 function createMppChargeHandler(opts) {
   const networkId = MPP_NETWORK[opts.network];
   const amountHumanReadable = opts.amount;
-  const mppx = Mppx$1.create({
-    secretKey: opts.payeeSecretKey,
-    methods: [
-      stellar$2.charge({
-        recipient: opts.manifest.payee,
-        currency: opts.assetContract,
-        network: networkId,
-        feePayer: { envelopeSigner: opts.payeeSecretKey }
-      })
-    ]
-  });
+  const recipient = resolvePayee(opts.manifest, "mpp-charge");
+  const logger = resolveLogger(opts.logger);
+  const seenTxStore = opts.seenTxStore ?? new InMemorySeenTxStore({ logger });
+  const mppxInstances = /* @__PURE__ */ new Map();
+  function getMppx(contract) {
+    let instance = mppxInstances.get(contract);
+    if (!instance) {
+      instance = Mppx$1.create({
+        secretKey: opts.payeeSecretKey,
+        methods: [
+          stellar$3.charge({
+            recipient,
+            currency: contract,
+            network: networkId,
+            feePayer: { envelopeSigner: opts.payeeSecretKey }
+          })
+        ]
+      });
+      mppxInstances.set(contract, instance);
+    }
+    return instance;
+  }
   return async (req, res, next) => {
     try {
+      const endpoint = req.path || req.originalUrl;
+      const assetContract = resolveAssetContract(
+        opts.manifest,
+        "mpp-charge",
+        endpoint,
+        opts.assetContract
+      );
+      const mppx = getMppx(assetContract);
+      let payerAddress = null;
+      try {
+        const authHeader = req.headers["authorization"];
+        if (typeof authHeader === "string" && authHeader.startsWith("Payment ")) {
+          const credPart = authHeader.replace(/^Payment\s+/, "").split(",").find((p) => p.trim().startsWith("credential="));
+          if (credPart) {
+            const b64 = credPart.split("=").slice(1).join("=").replace(/^"|"$/g, "");
+            const credJson = Buffer.from(b64, "base64").toString("utf8");
+            const cred = JSON.parse(credJson);
+            const key = cred.sender ?? cred.payload?.sender ?? cred.payload?.from;
+            payerAddress = extractPayerAddress(key);
+          }
+        }
+      } catch {
+      }
+      const idempotencyKey = await paymentIdempotencyKey(
+        (name) => {
+          const v = req.headers[name.toLowerCase()];
+          return Array.isArray(v) ? v[0] : v;
+        },
+        {
+          method: req.method,
+          path: req.originalUrl.split("?")[0],
+          amount: amountHumanReadable,
+          payTo: recipient
+        }
+      );
+      if (idempotencyKey) {
+        const replayCheck = await checkSettlementReplay(seenTxStore, idempotencyKey);
+        if (replayCheck.kind === "spent") {
+          res.status(402).json({ error: "Payment already used" });
+          return;
+        }
+        if (replayCheck.kind === "replay") {
+          if (replayCheck.record.headers) {
+            for (const [k, val] of Object.entries(replayCheck.record.headers)) {
+              res.setHeader(k, val);
+            }
+          }
+          next();
+          return;
+        }
+      }
       const fetchReq = Request.fromNodeListener(req, res);
       const handler = mppx["stellar/charge"];
       const result = await handler({
         amount: amountHumanReadable,
-        currency: opts.assetContract,
-        recipient: opts.manifest.payee,
+        currency: assetContract,
+        recipient,
         description: opts.manifest.name
       })(fetchReq);
       if (result.status === 402) {
@@ -755,25 +3366,124 @@ function createMppChargeHandler(opts) {
         return;
       }
       const receipt = result.withReceipt(new Response(""));
-      receipt.headers.forEach((v, k) => res.setHeader(k, v));
+      const receiptHeaders = {};
+      receipt.headers.forEach((v, k) => {
+        res.setHeader(k, v);
+        receiptHeaders[k] = v;
+      });
       const receiptHeader = receipt.headers.get("payment-receipt");
-      if (receiptHeader && opts.onSettled) {
+      let reference;
+      if (receiptHeader) {
         try {
           const parsed = JSON.parse(
             Buffer.from(receiptHeader, "base64").toString("utf8")
           );
-          if (parsed.reference) {
-            await opts.onSettled(parsed.reference, opts.amount, "mpp-charge");
-          }
+          reference = parsed.reference;
         } catch {
         }
       }
+      if (idempotencyKey) {
+        await seenTxStore.set(idempotencyKey, {
+          txHash: reference ?? null,
+          headers: receiptHeaders,
+          createdAt: Date.now()
+        });
+      }
+      if (reference && opts.onSettled) {
+        Promise.resolve().then(() => opts.onSettled(reference, opts.amount, "mpp-charge", payerAddress)).catch((err) => {
+          logger("error", "[mpp-charge] onSettled callback error", { error: err });
+          opts.onCallbackError?.(err, "onSettled");
+        });
+      }
       next();
     } catch (err) {
       next(err);
     }
   };
 }
+function resolveVaultSettlementAddresses(payer, payee) {
+  if (!payer) return null;
+  return { payer, payee };
+}
+function buildSessionSettlementTransaction(source, vaultContractId, channelId, addresses, amount, voucherCount, networkPassphrase) {
+  const vault = new Contract(vaultContractId);
+  const op = vault.call(
+    "record_session_settlement",
+    nativeToScVal(channelId, { type: "address" }),
+    nativeToScVal(addresses.payer, { type: "address" }),
+    nativeToScVal(addresses.payee, { type: "address" }),
+    nativeToScVal(amount, { type: "i128" }),
+    nativeToScVal(voucherCount, { type: "u32" })
+  );
+  return new TransactionBuilder(source, {
+    fee: BASE_FEE,
+    networkPassphrase
+  }).addOperation(op).setTimeout(30).build();
+}
+function channelAuthorizer(envelopeSigner) {
+  return { envelopeSigner };
+}
+function formatMppError(error) {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  try {
+    const serialized = JSON.stringify(error);
+    return serialized === void 0 ? String(error) : serialized;
+  } catch {
+    return String(error);
+  }
+}
+function withTypedChannelErrors(method) {
+  return {
+    ...method,
+    async verify(parameters) {
+      try {
+        return await method.verify(parameters);
+      } catch (error) {
+        throw mapChannelError(error);
+      }
+    }
+  };
+}
+function onVerifiedCredential(method, commit) {
+  return {
+    ...method,
+    async verify(parameters) {
+      const receipt = await method.verify(parameters);
+      await commit(parameters.credential);
+      return receipt;
+    }
+  };
+}
+function mapChannelError(error) {
+  const message = formatMppError(error);
+  const details = error && typeof error === "object" && "details" in error ? error.details : void 0;
+  const reason = details && Object.keys(details).length > 0 ? `${message} (${JSON.stringify(details)})` : message;
+  if (/signer mismatch|authori[sz]er|unauthori[sz]ed/i.test(message)) {
+    return new Errors.SignerMismatchError({ reason });
+  }
+  if (/already used|replay|challenge/i.test(message)) {
+    return new Errors.InvalidChallengeError({ reason });
+  }
+  if (/channel has been closed|channel is closed|finalized/i.test(message)) {
+    return new Errors.ChannelClosedError({ reason });
+  }
+  if (/exceeds channel balance|exceeds.*deposit/i.test(message)) {
+    return new Errors.AmountExceedsDepositError({ reason });
+  }
+  if (/channel not found|no channel/i.test(message)) {
+    return new Errors.ChannelNotFoundError({ reason });
+  }
+  if (/must be greater|does not cover|below.*minimum/i.test(message)) {
+    return new Errors.DeltaTooSmallError({ reason });
+  }
+  if (/signature/i.test(message)) {
+    return new Errors.InvalidSignatureError({ reason });
+  }
+  return new Errors.VerificationFailedError({ reason });
+}
+
+// src/provider/MppSessionHandler.ts
 var MPP_NETWORK2 = {
   testnet: "stellar:testnet",
   mainnet: "stellar:pubnet"
@@ -782,67 +3492,203 @@ function createMppSessionHandler(opts) {
   const networkId = MPP_NETWORK2[opts.network];
   const rateHuman = opts.rate;
   const payeeKeypair = Keypair.fromSecret(opts.payeeSecretKey);
-  const cumulativeKey = `stellar:channel:cumulative:${opts.channelContract}`;
+  const logger = resolveLogger(opts.logger);
+  const voucherRecordKey = `routedock:session:voucher:${opts.channelFactory}`;
   const innerStore = Store.memory();
-  let lastCumulativeAmount = 0n;
+  let record = null;
   let voucherCount = 0;
   let sessionOpened = false;
+  let idleTimer = null;
+  let settledCleanly = false;
+  let closeListenerArmed = false;
+  function clearIdleTimer() {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+  }
+  function armIdleTimer() {
+    if (!opts.idleTimeoutMs) return;
+    clearIdleTimer();
+    idleTimer = setTimeout(() => {
+      void flagOrphan("idle-timeout");
+    }, opts.idleTimeoutMs);
+    if (typeof idleTimer.unref === "function") idleTimer.unref();
+  }
+  async function loadPersistedRecord() {
+    if (record) return record;
+    try {
+      const stored = await innerStore.get(voucherRecordKey);
+      if (!stored || typeof stored.amount !== "string" || typeof stored.signature !== "string") {
+        return null;
+      }
+      record = { amount: BigInt(stored.amount), signature: stored.signature, payer: stored.payer ?? null };
+    } catch {
+      return null;
+    }
+    return record;
+  }
+  async function flagOrphan(reason) {
+    await loadPersistedRecord();
+    if (!sessionOpened || settledCleanly) return;
+    sessionOpened = false;
+    closeListenerArmed = false;
+    clearIdleTimer();
+    const cumulativeAmount = record ? (Number(record.amount) / 1e7).toFixed(7) : "0.0000000";
+    if (opts.onOrphaned) {
+      try {
+        await opts.onOrphaned(opts.channelFactory, {
+          cumulativeAmount,
+          lastSignature: record?.signature ?? "",
+          voucherCount,
+          reason
+        });
+      } catch (err) {
+        logger("error", "[mpp-session] onOrphaned handler failed", { error: err });
+      }
+    }
+  }
   const wrappedStore = {
     async get(key) {
       return innerStore.get(key);
     },
     async put(key, value) {
-      await innerStore.put(key, value);
-      if (key === cumulativeKey && value && typeof value === "object" && "amount" in value) {
-        lastCumulativeAmount = BigInt(value.amount);
-        voucherCount++;
-        if (!sessionOpened) {
-          sessionOpened = true;
-          if (opts.onSessionOpen) {
-            await opts.onSessionOpen(opts.channelContract);
-          }
-        }
-        if (opts.onVoucher) {
-          const humanAmount = (Number(lastCumulativeAmount) / 1e7).toFixed(7);
-          await opts.onVoucher(voucherCount, humanAmount);
-        }
-      }
+      return innerStore.put(key, value);
     },
     async delete(key) {
       return innerStore.delete(key);
+    },
+    async update(key, fn) {
+      const storeWithUpdate = innerStore;
+      if (typeof storeWithUpdate.update === "function") {
+        return storeWithUpdate.update(key, fn);
+      }
+      throw new Error("Store does not support atomic update operations");
     }
   };
+  async function commit(credential) {
+    await loadPersistedRecord();
+    const payload = credential.payload;
+    if (typeof payload?.amount !== "string" || typeof payload.signature !== "string") return;
+    let amount;
+    try {
+      amount = BigInt(payload.amount);
+    } catch {
+      return;
+    }
+    if (record && amount < record.amount) return;
+    const payer = record?.payer ?? extractPayerAddress(credential.source);
+    record = { amount, signature: payload.signature, payer };
+    await innerStore.put(voucherRecordKey, {
+      amount: record.amount.toString(),
+      signature: record.signature,
+      payer: record.payer
+    });
+    voucherCount++;
+    settledCleanly = false;
+    armIdleTimer();
+    if (!sessionOpened) {
+      sessionOpened = true;
+      if (opts.onSessionOpen) {
+        Promise.resolve().then(() => opts.onSessionOpen(opts.channelFactory, record.payer)).catch((err) => {
+          logger("error", "[mpp-session] onSessionOpen callback error", { error: err });
+          opts.onCallbackError?.(err, "onSessionOpen");
+        });
+      }
+    }
+    if (opts.onVoucher) {
+      const humanAmount = (Number(record.amount) / 1e7).toFixed(7);
+      Promise.resolve().then(() => opts.onVoucher(opts.channelFactory, voucherCount, humanAmount, record.signature)).catch((err) => {
+        logger("error", "[mpp-session] onVoucher callback error", { error: err });
+        opts.onCallbackError?.(err, "onVoucher");
+      });
+    }
+  }
   const mppx = Mppx$1.create({
     secretKey: opts.payeeSecretKey,
     methods: [
-      stellar$3.channel({
-        channel: opts.channelContract,
-        commitmentKey: opts.commitmentPublicKey,
-        network: networkId,
-        store: wrappedStore,
-        sourceAccount: payeeKeypair.publicKey(),
-        feePayer: { envelopeSigner: payeeKeypair }
-      })
+      withTypedChannelErrors(
+        onVerifiedCredential(
+          stellar$2.channel({
+            channel: opts.channelFactory,
+            commitmentKey: opts.commitmentPublicKey,
+            network: networkId,
+            store: wrappedStore,
+            sourceAccount: payeeKeypair.publicKey(),
+            feePayer: channelAuthorizer(payeeKeypair)
+          }),
+          commit
+        )
+      )
     ]
   });
-  let lastSignatureHex = "";
   return async (req, res, next) => {
     try {
       if (req.method === "DELETE") {
+        await loadPersistedRecord();
         const body = req.body;
-        const closeAmount = body?.amount ? BigInt(body.amount) : lastCumulativeAmount;
-        const closeSig = body?.signature ?? lastSignatureHex;
+        const bodyAmount = body?.amount ? BigInt(body.amount) : 0n;
+        const recordAmount = record?.amount ?? 0n;
+        let closeAmount;
+        let closeSig;
+        if (bodyAmount > recordAmount) {
+          closeAmount = bodyAmount;
+          closeSig = body?.signature ?? record?.signature ?? "";
+        } else {
+          closeAmount = recordAmount;
+          closeSig = record?.signature ?? "";
+        }
         if (closeAmount > 0n && closeSig) {
+          const closePayer = record?.payer ?? null;
           const closeTxHash = await close({
-            channel: opts.channelContract,
+            channel: opts.channelFactory,
             amount: closeAmount,
             signature: Buffer.from(closeSig, "hex"),
-            feePayer: { envelopeSigner: payeeKeypair },
+            feePayer: channelAuthorizer(payeeKeypair),
             network: networkId
           });
+          settledCleanly = true;
+          clearIdleTimer();
           if (opts.onSettled) {
-            const totalPaid = (Number(lastCumulativeAmount) / 1e7).toFixed(7);
-            await opts.onSettled(closeTxHash, totalPaid, "mpp-session");
+            const totalPaid = (Number(closeAmount) / 1e7).toFixed(7);
+            Promise.resolve().then(() => opts.onSettled(closeTxHash, totalPaid, "mpp-session", closePayer)).catch((err) => {
+              logger("error", "[mpp-session] onSettled callback error", { error: err });
+              opts.onCallbackError?.(err, "onSettled");
+            });
+          }
+          const vaultContract = process.env.AGENT_VAULT_CONTRACT;
+          if (vaultContract) {
+            const settlementAddresses = resolveVaultSettlementAddresses(
+              closePayer,
+              payeeKeypair.publicKey()
+            );
+            if (!settlementAddresses) {
+              logger("warn", "[mpp-session] skipped session_settled vault record: payer address unavailable");
+            } else {
+              try {
+                const { Networks: Networks2 } = await import('@stellar/stellar-sdk');
+                const { Server } = await import('@stellar/stellar-sdk/rpc');
+                const networkPassphrase = opts.network === "mainnet" ? Networks2.PUBLIC : Networks2.TESTNET;
+                const rpcUrl = opts.network === "mainnet" ? "https://mainnet.sorobanrpc.com" : "https://soroban-testnet.stellar.org";
+                const server = new Server(rpcUrl);
+                const payeePublicKey = payeeKeypair.publicKey();
+                const sourceAccount = await server.getAccount(payeePublicKey);
+                const tx = buildSessionSettlementTransaction(
+                  sourceAccount,
+                  vaultContract,
+                  opts.channelFactory,
+                  settlementAddresses,
+                  closeAmount,
+                  voucherCount,
+                  networkPassphrase
+                );
+                const preparedTx = await server.prepareTransaction(tx);
+                preparedTx.sign(payeeKeypair);
+                await server.sendTransaction(preparedTx);
+              } catch (recordErr) {
+                logger("error", "[mpp-session] failed to record session_settled on vault", { error: recordErr });
+              }
+            }
           }
           res.json({ closeTxHash });
         } else {
@@ -850,23 +3696,12 @@ function createMppSessionHandler(opts) {
         }
         sessionOpened = false;
         voucherCount = 0;
-        lastCumulativeAmount = 0n;
+        record = null;
+        await innerStore.delete(voucherRecordKey);
+        closeListenerArmed = false;
+        clearIdleTimer();
         return;
       }
-      const authHeader = req.headers["authorization"];
-      if (typeof authHeader === "string" && authHeader.startsWith("Payment ")) {
-        try {
-          const credB64 = authHeader.replace(/^Payment\s+/, "").split(",").find((p) => p.trim().startsWith("credential="));
-          if (credB64) {
-            const credJson = Buffer.from(credB64.split("=").slice(1).join("=").replace(/^"|"$/g, ""), "base64").toString("utf8");
-            const cred = JSON.parse(credJson);
-            if (cred.payload?.signature) {
-              lastSignatureHex = cred.payload.signature;
-            }
-          }
-        } catch {
-        }
-      }
       const fetchReq = Request.fromNodeListener(req, res);
       const result = await mppx.channel({
         amount: rateHuman,
@@ -880,6 +3715,12 @@ function createMppSessionHandler(opts) {
         res.send(body);
         return;
       }
+      if (!closeListenerArmed) {
+        closeListenerArmed = true;
+        req.on("close", () => {
+          void flagOrphan("connection-closed");
+        });
+      }
       next();
     } catch (err) {
       next(err);
@@ -888,20 +3729,27 @@ function createMppSessionHandler(opts) {
 }
 
 // src/provider/routedockMiddleware.ts
+var MPP_MODES = ["mpp-session", "mpp-charge"];
 function routedock(opts) {
-  const handlers = [];
+  const startTime = Date.now();
+  const signedManifest = signManifest(opts.manifest, opts.payeeSecretKey);
+  const handlerMap = /* @__PURE__ */ new Map();
   if (opts.modes.includes("x402")) {
     const x402Price = opts.pricing.x402;
     if (x402Price) {
-      handlers.push(
+      handlerMap.set(
+        "x402",
         createX402Handler({
           payeeSecretKey: opts.payeeSecretKey,
           network: opts.network,
           amount: x402Price,
-          assetContract: opts.assetContract,
+          ...opts.assetContract ? { assetContract: opts.assetContract } : {},
           ...opts.facilitatorApiKey ? { facilitatorApiKey: opts.facilitatorApiKey } : {},
-          manifest: opts.manifest,
-          ...opts.onSettled ? { onSettled: opts.onSettled } : {}
+          manifest: signedManifest,
+          ...opts.onSettled ? { onSettled: opts.onSettled } : {},
+          ...opts.onCallbackError ? { onCallbackError: opts.onCallbackError } : {},
+          ...opts.seenTxStore ? { seenTxStore: opts.seenTxStore } : {},
+          ...opts.logger ? { logger: opts.logger } : {}
         })
       );
     }
@@ -909,14 +3757,18 @@ function routedock(opts) {
   if (opts.modes.includes("mpp-charge")) {
     const chargePrice = opts.pricing["mpp-charge"];
     if (chargePrice) {
-      handlers.push(
+      handlerMap.set(
+        "mpp-charge",
         createMppChargeHandler({
           payeeSecretKey: opts.payeeSecretKey,
           network: opts.network,
           amount: chargePrice,
-          assetContract: opts.assetContract,
-          manifest: opts.manifest,
-          ...opts.onSettled ? { onSettled: opts.onSettled } : {}
+          ...opts.assetContract ? { assetContract: opts.assetContract } : {},
+          manifest: signedManifest,
+          ...opts.onSettled ? { onSettled: opts.onSettled } : {},
+          ...opts.onCallbackError ? { onCallbackError: opts.onCallbackError } : {},
+          ...opts.seenTxStore ? { seenTxStore: opts.seenTxStore } : {},
+          ...opts.logger ? { logger: opts.logger } : {}
         })
       );
     }
@@ -927,39 +3779,53 @@ function routedock(opts) {
       if (!opts.commitmentPublicKey) {
         throw new Error("routedock: mpp-session mode requires commitmentPublicKey");
       }
-      handlers.push(
+      handlerMap.set(
+        "mpp-session",
         createMppSessionHandler({
           payeeSecretKey: opts.payeeSecretKey,
           network: opts.network,
-          channelContract: sessionPricing.channelContract,
+          channelFactory: sessionPricing.channelFactory,
           rate: sessionPricing.rate,
-          assetContract: opts.assetContract,
-          manifest: opts.manifest,
+          ...opts.assetContract ? { assetContract: opts.assetContract } : {},
+          manifest: signedManifest,
           commitmentPublicKey: opts.commitmentPublicKey,
           ...opts.onSettled ? { onSettled: opts.onSettled } : {},
           ...opts.onSessionOpen ? { onSessionOpen: opts.onSessionOpen } : {},
-          ...opts.onVoucher ? { onVoucher: opts.onVoucher } : {}
+          ...opts.onVoucher ? { onVoucher: opts.onVoucher } : {},
+          ...opts.onCallbackError ? { onCallbackError: opts.onCallbackError } : {},
+          ...opts.onOrphaned ? { onOrphaned: opts.onOrphaned } : {},
+          ...opts.idleTimeoutMs != null ? { idleTimeoutMs: opts.idleTimeoutMs } : {},
+          ...opts.logger ? { logger: opts.logger } : {}
         })
       );
     }
   }
+  const defaultMode = MPP_MODES.find((mode) => handlerMap.has(mode)) ?? (handlerMap.has("x402") ? "x402" : void 0);
   return (req, res, next) => {
     if (req.path === "/.well-known/routedock.json") {
-      res.json(opts.manifest);
+      res.json(signedManifest);
+      return;
+    }
+    if (req.path === "/health") {
+      res.json({
+        status: "ok",
+        routedock: opts.manifest.routedock,
+        network: opts.network,
+        payee: opts.payee,
+        modesActive: opts.modes,
+        uptime: Math.floor((Date.now() - startTime) / 1e3)
+      });
       return;
     }
-    if (handlers.length === 0) {
+    if (handlerMap.size === 0) {
       next();
       return;
     }
     const hasX402Header = !!(req.headers["payment-signature"] || req.headers["x-payment"]);
     const prefersX402 = req.headers["x-preferred-mode"] === "x402";
-    let handler;
-    if (hasX402Header || prefersX402) {
-      handler = handlers[0];
-    } else {
-      handler = handlers[handlers.length - 1];
-    }
+    const x402Handler = handlerMap.get("x402");
+    const defaultHandler = defaultMode ? handlerMap.get(defaultMode) : void 0;
+    const handler = hasX402Header || prefersX402 ? x402Handler ?? defaultHandler : defaultHandler;
     if (!handler) {
       next();
       return;
@@ -973,4 +3839,288 @@ function routedock(opts) {
   };
 }
 
-export { MppChargeClient, MppSessionClient, RouteDockClient, RouteDockError, RouteDockManifestError, RouteDockNoSupportedModeError, RouteDockPolicyRejectedError, RouteDockSessionError, SupabaseSessionStore, X402Client, fetchManifest, routedock, selectMode };
+// src/provider/registerProvider.ts
+async function registerProvider(optionsOrSupabase, manifestArg, baseUrlArg, verifiedArg) {
+  let supabase;
+  let manifest;
+  let baseUrl;
+  let verified;
+  if ("supabase" in optionsOrSupabase) {
+    supabase = optionsOrSupabase.supabase;
+    manifest = optionsOrSupabase.manifest;
+    baseUrl = optionsOrSupabase.baseUrl;
+    verified = optionsOrSupabase.verified ?? true;
+  } else {
+    supabase = optionsOrSupabase;
+    if (!manifestArg || !baseUrlArg) {
+      throw new RouteDockManifestError("manifest and baseUrl are required for registerProvider");
+    }
+    manifest = manifestArg;
+    baseUrl = baseUrlArg;
+    verified = verifiedArg ?? true;
+  }
+  verifyManifestSignature(manifest);
+  const normalizedBaseUrl = baseUrl.replace(/\/$/, "");
+  const { error } = await supabase.from("providers").upsert(
+    {
+      name: manifest.name,
+      description: manifest.description ?? null,
+      base_url: normalizedBaseUrl,
+      modes: manifest.modes,
+      tags: manifest.tags ?? [],
+      categories: manifest.categories ?? [],
+      network: manifest.network,
+      payee: manifest.payee,
+      manifest,
+      verified,
+      registered_at: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    { onConflict: "base_url" }
+  );
+  if (error) {
+    throw new Error(`Failed to register provider in Supabase: ${error.message}`);
+  }
+}
+var MPP_NETWORK3 = {
+  testnet: "stellar:testnet",
+  mainnet: "stellar:pubnet"
+};
+function decimalToStroops(amountStr) {
+  return usdcToStroops(amountStr);
+}
+async function reconcileAbandonedSessions(opts) {
+  const stats = {
+    orphanedCount: 0,
+    recoveredCount: 0,
+    skippedCount: 0,
+    failedCount: 0,
+    errors: []
+  };
+  const payeeKeypair = Keypair.fromSecret(opts.payeeSecretKey);
+  const networkId = MPP_NETWORK3[opts.network];
+  try {
+    const { data: closingSessions, error } = await opts.supabase.from("sessions").select("channel_id, channel_contract, cumulative_amount, last_signature, settlement_tx_hash").eq("status", "closing").eq("network", opts.network).eq("payee", payeeKeypair.publicKey()).is("settlement_tx_hash", null).not("last_signature", "is", null).order("updated_at", { ascending: true }).limit(100);
+    if (error) {
+      throw new Error(`Failed to query sessions: ${error.message}`);
+    }
+    stats.orphanedCount = closingSessions?.length ?? 0;
+    if (!closingSessions || closingSessions.length === 0) {
+      return stats;
+    }
+    for (const session of closingSessions) {
+      try {
+        const {
+          channel_id: sessionId,
+          channel_contract: channelContract,
+          cumulative_amount,
+          last_signature
+        } = session;
+        const channelId = channelContract || sessionId;
+        if (!channelId || !cumulative_amount || !last_signature) {
+          stats.skippedCount++;
+          continue;
+        }
+        const closeAmount = decimalToStroops(cumulative_amount);
+        const closeSig = Buffer.from(last_signature, "hex");
+        const closeFn = opts.channelClose ?? (await import('@stellar/mpp/channel/server')).close;
+        const closeTxHash = await closeFn({
+          channel: channelId,
+          amount: closeAmount,
+          signature: closeSig,
+          feePayer: channelAuthorizer(payeeKeypair),
+          network: networkId
+        });
+        const totalPaid = (Number(closeAmount) / 1e7).toFixed(7);
+        const { error: updateError } = await opts.supabase.from("sessions").update({
+          status: "closed",
+          settlement_tx_hash: closeTxHash,
+          updated_at: (/* @__PURE__ */ new Date()).toISOString()
+        }).eq("channel_id", sessionId);
+        if (updateError) {
+          throw new Error(`Failed to update session: ${updateError.message}`);
+        }
+        stats.recoveredCount++;
+        if (opts.onRecovered) {
+          await opts.onRecovered(channelId, closeTxHash, totalPaid);
+        }
+      } catch (err) {
+        stats.failedCount++;
+        stats.errors.push({
+          channelId: session.channel_id,
+          reason: formatMppError(err)
+        });
+      }
+    }
+    return stats;
+  } catch (err) {
+    throw new Error(
+      `Session reconciliation failed: ${formatMppError(err)}`
+    );
+  }
+}
+async function runStartupReconciliation(opts, logger) {
+  const log = resolveLogger(logger);
+  log("info", "[SessionReconciler] Running startup reconciliation...");
+  try {
+    const stats = await reconcileAbandonedSessions(opts);
+    if (stats.orphanedCount === 0) {
+      log("info", "[SessionReconciler] No orphaned sessions found");
+      return;
+    }
+    log(
+      "info",
+      `[SessionReconciler] Found ${stats.orphanedCount} orphaned session(s). Recovered: ${stats.recoveredCount}, Skipped: ${stats.skippedCount}, Failed: ${stats.failedCount}`
+    );
+    if (stats.errors.length > 0) {
+      log("warn", "[SessionReconciler] Reconciliation errors:");
+      for (const err of stats.errors) {
+        log("warn", `  - ${err.channelId}: ${err.reason}`);
+      }
+    }
+  } catch (err) {
+    log("error", `[SessionReconciler] Startup reconciliation failed: ${formatMppError(err)}`);
+  }
+}
+function tryDecodeBase64(value) {
+  if (value.startsWith("http://") || value.startsWith("https://") || value.startsWith("/") || value.startsWith("[")) {
+    return value;
+  }
+  try {
+    const decoded = typeof Buffer !== "undefined" ? Buffer.from(value, "base64").toString("utf-8") : atob(value);
+    if (decoded.length > 0 && decoded !== value) return decoded;
+  } catch {
+  }
+  return value;
+}
+var OnChainRegistry = class {
+  horizon;
+  knownAccounts;
+  timeoutMs;
+  constructor(options) {
+    this.horizon = new Horizon.Server(options.horizonUrl);
+    this.knownAccounts = options.knownAccounts;
+    this.timeoutMs = options.timeoutMs ?? 1e4;
+  }
+  /**
+   * stellar-sdk 14.6.1 has no way to cancel the underlying Horizon request, so
+   * we stop waiting on it instead: the promise returned here rejects once
+   * `timeoutMs` elapses, even though the request may still be in flight. The
+   * timer is always cleared, including on the error path.
+   */
+  loadAccountWithTimeout(accountId) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(
+        () => reject(new Error(`Horizon loadAccount timed out after ${this.timeoutMs}ms`)),
+        this.timeoutMs
+      );
+    });
+    return Promise.race([this.horizon.loadAccount(accountId), timeout]).finally(() => {
+      if (timer !== void 0) clearTimeout(timer);
+    });
+  }
+  async listProviders() {
+    const settled = await Promise.allSettled(
+      this.knownAccounts.map((accountId) => this.loadAccountWithTimeout(accountId))
+    );
+    const results = [];
+    for (let i = 0; i < settled.length; i++) {
+      const outcome = settled[i];
+      if (outcome.status !== "fulfilled") continue;
+      const accountId = this.knownAccounts[i];
+      const account = outcome.value;
+      const dataEntries = account.data_attr;
+      if (!dataEntries) continue;
+      const rawEndpoint = dataEntries["routedock_endpoint"];
+      if (!rawEndpoint) continue;
+      const endpoint = tryDecodeBase64(rawEndpoint);
+      if (!endpoint.startsWith("http://") && !endpoint.startsWith("https://")) continue;
+      let tags = [];
+      const rawTags = dataEntries["routedock_tags"];
+      if (rawTags) {
+        const decoded = tryDecodeBase64(rawTags);
+        try {
+          const parsed = JSON.parse(decoded);
+          if (Array.isArray(parsed)) tags = parsed;
+        } catch {
+          tags = decoded.split(",").map((t) => t.trim()).filter(Boolean);
+        }
+      }
+      results.push({ account: accountId, endpoint, tags });
+    }
+    return results;
+  }
+};
+
+// src/registry/ProviderRegistry.ts
+function deriveNetwork(horizonUrl) {
+  return horizonUrl.includes("testnet") ? "testnet" : "mainnet";
+}
+var ProviderRegistry = class {
+  supabase;
+  onChain;
+  network;
+  constructor(config) {
+    this.supabase = config.supabase;
+    this.network = config.onChain.network ?? deriveNetwork(config.onChain.horizonUrl);
+    this.onChain = new OnChainRegistry({
+      horizonUrl: config.onChain.horizonUrl,
+      knownAccounts: config.onChain.knownAccounts,
+      ...config.onChain.timeoutMs !== void 0 ? { timeoutMs: config.onChain.timeoutMs } : {}
+    });
+  }
+  async listProviders() {
+    const supabaseProviders = await this.trySupabase();
+    if (supabaseProviders.length > 0) return supabaseProviders;
+    return this.tryOnChain();
+  }
+  async trySupabase() {
+    if (!this.supabase) return [];
+    try {
+      const { data, error } = await this.supabase.from("providers").select("*").eq("verified", true).eq("network", this.network).limit(100);
+      if (error) return [];
+      if (!data || data.length === 0) return [];
+      return data.map((r) => ({
+        name: r.name,
+        description: r.description ?? void 0,
+        base_url: r.base_url,
+        modes: r.modes,
+        tags: r.tags,
+        network: r.network,
+        payee: r.payee,
+        source: "supabase",
+        verified: r.verified === true
+      }));
+    } catch {
+      return [];
+    }
+  }
+  async tryOnChain() {
+    const providers = await this.onChain.listProviders();
+    return providers.map((p) => ({
+      name: `On-chain provider (${p.account.slice(0, 8)}...)`,
+      description: `Provider registered on Stellar account ${p.account}`,
+      base_url: p.endpoint,
+      modes: [],
+      tags: p.tags,
+      network: this.network,
+      payee: p.account,
+      source: "onchain",
+      verified: true
+    }));
+  }
+  /**
+   * Fetch a provider's manifest bound to the record's payee. The record's
+   * `payee` (from supabase `verified` rows or the on-chain registry account)
+   * is the out-of-band trust anchor: the fetched manifest's `payee` must
+   * equal it, otherwise `RouteDockSignatureError` is thrown. This closes the
+   * gap where the registry never cross-checked the on-chain payee against
+   * the manifest payee.
+   */
+  async fetchProviderManifest(record) {
+    const baseUrl = new URL(record.base_url).origin;
+    return fetchManifest(baseUrl, void 0, void 0, record.payee);
+  }
+};
+
+export { DEFAULT_MAX_SESSION_DURATION_MS, DEFAULT_RETRY_POLICY, FileSpendStore, InMemorySpendStore, MppChargeClient, NulthPolicyError, OnChainRegistry, ProviderRegistry, RouteDockChannelStateError, RouteDockClient, RouteDockClientVersionError, RouteDockDisputeError, RouteDockError, RouteDockFacilitatorError, RouteDockManifestError, RouteDockManifestSunsetError, RouteDockManifestTimeoutError, RouteDockNetworkError, RouteDockNoSupportedModeError, RouteDockPolicyRejectError, RouteDockPolicyRejectedError, RouteDockRefundWindowError, RouteDockSessionError, RouteDockSignatureError, RouteDockTrustlineError, RouteDockVoucherMonotonicityError, SupabaseSeenTxStore, SupabaseSessionStore, X402Client, assertEndpointActive, assertManifestValid, assertNulthVaultManifest, backoffDelayMs, configureManifestCache, consoleLogger, createConsoleLogger, createNulthSigner, createPolicyState, decimalToStroops, decodeAuthSignature, fetchLedgerSequence, fetchManifest, getEligibleAssets, httpStatusToError, invalidateManifest, isAssetEligible, manifestDigest, noopLogger, normalizeManifestAssets, parseRetryAfterMs, paymentContextFromManifest, prepareNulthSigner, rankProvidersByLatency, reconcileAbandonedSessions, registerProvider, resolveAssetContract, resolveLogger, routedock, runStartupReconciliation, selectAsset, selectMode, setNulthPaymentContext, signManifest, usdcToMicros, usdcToUnits, verifyManifestSignature, withRetry, wrapFetchError, wrapMppError };