@routedock/routedock 0.3.0 → 0.4.0

package/dist/provider/fastify.js

@@ -1,17 +1,18 @@
-import { Keypair, StrKey, Contract, nativeToScVal, TransactionBuilder, BASE_FEE } from '@stellar/stellar-sdk';
+import { Keypair, StrKey, Networks, Contract, nativeToScVal, TransactionBuilder, BASE_FEE } from '@stellar/stellar-sdk';
+import { usdcToStroops } from '@routedock/nulth-sdk';
+import { Validator } from '@cfworker/json-schema';
 import { ExactStellarScheme } from '@x402/stellar/exact/facilitator';
 import { ExactStellarScheme as ExactStellarScheme$1 } from '@x402/stellar/exact/server';
 import { HTTPFacilitatorClient, x402ResourceServer } from '@x402/core/server';
 import { createEd25519Signer } from '@x402/stellar';
 import { encodePaymentRequiredHeader, decodePaymentSignatureHeader, encodePaymentResponseHeader } from '@x402/core/http';
-import { usdcToStroops } from '@routedock/nulth-sdk';
 import { stellar as stellar$1 } from '@stellar/mpp/charge/server';
 import { Request, Mppx } from 'mppx/server';
 import { Store, stellar, close } from '@stellar/mpp/channel/server';
 import { Errors } from 'mppx';
-import { createHash } from 'crypto';
+import { sha256 as sha256$1 } from '@noble/hashes/sha2.js';
 
-// src/provider/x402Handler.ts
+// src/provider/internal/assertProviderConfig.ts
 
 // src/errors.ts
 var RouteDockError = class extends Error {
@@ -34,13 +35,618 @@ var RouteDockManifestError = class extends RouteDockError {
     this.name = "RouteDockManifestError";
   }
 };
+var usdcToUnits = usdcToStroops;
+
+// src/schemas/routedock.schema.json
+var routedock_schema_default = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://routedock.xyz/schemas/routedock.schema.json",
+  title: "RouteDock Manifest",
+  description: "Discovery manifest served at /.well-known/routedock.json on every RouteDock provider endpoint",
+  type: "object",
+  required: [
+    "routedock",
+    "name",
+    "description",
+    "modes",
+    "network",
+    "asset",
+    "asset_contract",
+    "payee",
+    "pricing",
+    "endpoints",
+    "tags"
+  ],
+  additionalProperties: false,
+  properties: {
+    routedock: {
+      type: "string",
+      pattern: "^[0-9]+\\.[0-9]+$",
+      description: "Manifest schema version, e.g. '1.0', '1.1', '2.0'."
+    },
+    min_client_version: {
+      type: "string",
+      pattern: "^[0-9]+\\.[0-9]+$",
+      description: "Minimum SDK client version (major.minor) required to use this manifest. Clients below this version must refuse to pay."
+    },
+    deprecated_modes: {
+      type: "array",
+      items: {
+        $ref: "#/definitions/PaymentMode"
+      },
+      uniqueItems: true,
+      description: "Payment modes still listed in 'modes' for backwards compatibility but deprecated for new integrations."
+    },
+    sunset_at: {
+      type: "string",
+      format: "date-time",
+      description: "ISO 8601 timestamp after which this manifest version is no longer supported by the provider."
+    },
+    name: {
+      type: "string",
+      minLength: 1,
+      maxLength: 120,
+      description: "Human-readable provider name"
+    },
+    description: {
+      type: "string",
+      minLength: 1,
+      maxLength: 500,
+      description: "Human-readable description of the provider's data or service"
+    },
+    modes: {
+      type: "array",
+      minItems: 1,
+      uniqueItems: true,
+      items: {
+        $ref: "#/definitions/PaymentMode"
+      },
+      description: "Payment modes supported by this provider"
+    },
+    network: {
+      type: "string",
+      enum: ["testnet", "mainnet"],
+      description: "Stellar network this provider operates on"
+    },
+    asset: {
+      type: "string",
+      description: "Asset ticker symbol (e.g. 'USDC')"
+    },
+    asset_contract: {
+      type: "string",
+      pattern: "^C[A-Z2-7]{55}$",
+      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",
+      pattern: "^G[A-Z2-7]{55}$",
+      description: "Stellar address (G...) that receives payments"
+    },
+    pricing: {
+      type: "object",
+      description: "Pricing configuration per supported payment mode",
+      additionalProperties: false,
+      properties: {
+        x402: {
+          $ref: "#/definitions/PricingConfig"
+        },
+        "mpp-charge": {
+          $ref: "#/definitions/PricingConfig"
+        },
+        "mpp-session": {
+          $ref: "#/definitions/SessionPricingConfig"
+        },
+        "mpp-session-ws": {
+          $ref: "#/definitions/SessionPricingConfig",
+          description: "WebSocket transport variant of mpp-session: channel opened and first voucher negotiated over HTTP, then the connection upgrades to WebSocket for push-based streaming."
+        }
+      },
+      minProperties: 1
+    },
+    endpoints: {
+      type: "object",
+      description: "Map of endpoint name to endpoint descriptors",
+      additionalProperties: {
+        $ref: "#/definitions/EndpointDescriptor"
+      },
+      minProperties: 1
+    },
+    sla: {
+      $ref: "#/definitions/SLAConfig"
+    },
+    tags: {
+      type: "array",
+      items: {
+        type: "string",
+        minLength: 1,
+        maxLength: 64
+      },
+      uniqueItems: true,
+      description: "Capability tags indexed with trigram search in the provider registry"
+    },
+    vault: {
+      $ref: "#/definitions/VaultMode"
+    },
+    nulth_account: {
+      type: "string",
+      description: "Optional Nulth smart account address associated with this provider"
+    },
+    capabilities: {
+      type: "object",
+      description: "Optional protocol features this provider supports",
+      properties: {
+        streaming: {
+          type: "array",
+          items: {
+            type: "string",
+            enum: ["sse", "websocket"]
+          },
+          description: "Supported streaming transports"
+        },
+        webhooks: {
+          type: "boolean",
+          description: "Whether webhook callbacks are supported"
+        },
+        idempotency_keys: {
+          type: "boolean",
+          description: "Whether idempotency keys are supported"
+        },
+        content_types: {
+          type: "array",
+          items: {
+            type: "string"
+          },
+          description: "Supported content types for request/response"
+        }
+      },
+      additionalProperties: false
+    },
+    regions: {
+      type: "array",
+      items: {
+        type: "string",
+        minLength: 2,
+        maxLength: 10
+      },
+      uniqueItems: true,
+      description: "IATA airport codes or UN/LOCODE identifiers for regions where this provider has infrastructure (e.g. ['IAD', 'AMS']). Used by agents to select the nearest provider."
+    },
+    latency_hints: {
+      type: "object",
+      additionalProperties: {
+        type: "number",
+        minimum: 0
+      },
+      description: "Provider-declared p50 latency in milliseconds per region code. Keys must be a subset of 'regions'. Example: { 'IAD': 14, 'AMS': 22 }."
+    },
+    signature: {
+      type: "string",
+      description: "Base64 Ed25519 signature (payee keypair) over the SHA-256 hash of this manifest with the signature field omitted. Clients must verify before trusting any routing field."
+    },
+    signature_version: {
+      type: "string",
+      const: "2",
+      description: "Manifest signature format. Version 2 recursively includes every nested manifest field in the signed digest."
+    },
+    categories: {
+      type: "array",
+      items: {
+        type: "string",
+        minLength: 1,
+        maxLength: 128
+      },
+      uniqueItems: true,
+      description: "Optional hierarchical categories from a published taxonomy (e.g. data/price/crypto)"
+    }
+  },
+  definitions: {
+    VaultMode: {
+      type: "string",
+      enum: ["local-key", "agent-vault", "nulth"],
+      description: "Agent vault / custody mode for payments from this provider"
+    },
+    PaymentMode: {
+      type: "string",
+      enum: ["x402", "mpp-charge", "mpp-session", "mpp-session-ws"],
+      description: "A supported RouteDock payment mode"
+    },
+    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",
+      required: ["amount", "per"],
+      additionalProperties: false,
+      properties: {
+        amount: {
+          type: "string",
+          pattern: "^[0-9]+(\\.[0-9]{1,7})?$",
+          description: "Cost per request in the payment asset (decimal string, e.g. '0.001')"
+        },
+        per: {
+          type: "string",
+          const: "request",
+          description: "Billing unit \u2014 always 'request' for non-session modes"
+        },
+        facilitator: {
+          type: "string",
+          description: "x402 facilitator URL (required for x402 mode). OpenZeppelin Channels endpoint."
+        },
+        payee: {
+          type: "string",
+          pattern: "^G[A-Z2-7]{55}$",
+          description: "Optional per-mode payee override (Stellar G... address). Directs settlements for this mode to a separate account for treasury separation. Falls back to the top-level 'payee' when omitted."
+        }
+      }
+    },
+    SessionPricingConfig: {
+      type: "object",
+      description: "Per-voucher pricing for mpp-session (one-way-channel) mode",
+      required: ["rate", "per", "channel_factory", "min_deposit", "refund_waiting_period_ledgers"],
+      additionalProperties: false,
+      properties: {
+        rate: {
+          type: "string",
+          pattern: "^[0-9]+(\\.[0-9]{1,7})?$",
+          description: "Cost per voucher in the payment asset (decimal string, e.g. '0.0001')"
+        },
+        per: {
+          type: "string",
+          const: "voucher",
+          description: "Billing unit \u2014 always 'voucher' for session mode"
+        },
+        channel_factory: {
+          type: "string",
+          pattern: "^C[A-Z2-7]{55}$",
+          description: "Stable Soroban factory address (C...) used to deploy a per-session channel"
+        },
+        min_deposit: {
+          type: "string",
+          pattern: "^[0-9]+(\\.[0-9]{1,7})?$",
+          description: "Minimum initial deposit to open a channel (decimal string)"
+        },
+        refund_waiting_period_ledgers: {
+          type: "integer",
+          minimum: 1,
+          description: "Ledgers the server has to settle before the funder can reclaim. Default: 17280 (~24h). Do not reduce in production."
+        }
+      }
+    },
+    SLAConfig: {
+      type: "object",
+      description: "Service Level Agreement for the provider",
+      required: ["uptime_30d_percent", "p95_latency_ms"],
+      additionalProperties: false,
+      properties: {
+        uptime_30d_percent: {
+          type: "number",
+          description: "Uptime percentage over the last 30 days"
+        },
+        p95_latency_ms: {
+          type: "number",
+          description: "P95 latency in milliseconds"
+        },
+        maintenance_windows: {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["cron", "duration_minutes"],
+            additionalProperties: false,
+            properties: {
+              cron: {
+                type: "string",
+                description: "Cron expression for the maintenance window"
+              },
+              duration_minutes: {
+                type: "number",
+                description: "Duration of the maintenance window in minutes"
+              }
+            }
+          }
+        }
+      }
+    },
+    EndpointDescriptor: {
+      type: "object",
+      description: "Descriptor for a provider endpoint",
+      required: ["method", "path"],
+      additionalProperties: false,
+      properties: {
+        method: {
+          type: "string",
+          description: "HTTP method for the endpoint"
+        },
+        path: {
+          type: "string",
+          description: "Path for the endpoint"
+        },
+        deprecated: {
+          type: "boolean",
+          description: "Whether this endpoint is retained only for backwards compatibility"
+        },
+        sunset_at: {
+          type: "string",
+          format: "date-time",
+          description: "ISO 8601 timestamp after which callers should stop using this endpoint"
+        },
+        headers: {
+          type: "object",
+          additionalProperties: {
+            type: "string"
+          },
+          description: "Expected request headers"
+        },
+        request_schema: {
+          description: "JSON schema for the request body"
+        },
+        response_schema: {
+          description: "JSON schema for the response body"
+        },
+        rate_limit: {
+          type: "object",
+          required: ["requests", "window_seconds"],
+          additionalProperties: false,
+          properties: {
+            requests: {
+              type: "number"
+            },
+            window_seconds: {
+              type: "number"
+            }
+          }
+        }
+      }
+    }
+  }
+};
+
+// src/manifest/validate.ts
+var validator = new Validator(routedock_schema_default, "7");
+function validateManifestSchema(manifest, source) {
+  const result = validator.validate(manifest);
+  if (!result.valid) {
+    const msgs = result.errors.map((err) => err.error).join("; ");
+    throw new RouteDockManifestError(`Invalid manifest${""}: ${msgs}`);
+  }
+}
+function assertManifestValid(manifest, baseUrl) {
+  const context = "";
+  if (manifest.latency_hints !== void 0) {
+    if (!Array.isArray(manifest.regions) || manifest.regions.length === 0) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: latency_hints defined without declaring regions`
+      );
+    }
+    const regionSet = new Set(manifest.regions);
+    for (const region of Object.keys(manifest.latency_hints)) {
+      if (!regionSet.has(region)) {
+        throw new RouteDockManifestError(
+          `Invalid manifest${context}: latency_hints key '${region}' is not declared in regions (${manifest.regions.join(", ")})`
+        );
+      }
+    }
+  }
+  if (manifest.assets !== void 0) {
+    if (!Array.isArray(manifest.assets) || manifest.assets.length === 0) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: assets must be a non-empty array when defined`
+      );
+    }
+    for (let i = 0; i < manifest.assets.length; i++) {
+      const a = manifest.assets[i];
+      if (!a || typeof a.asset !== "string" || typeof a.asset_contract !== "string") {
+        throw new RouteDockManifestError(
+          `Invalid manifest${context}: assets[${i}] must define asset and asset_contract strings`
+        );
+      }
+    }
+    const first = manifest.assets[0];
+    if (first.asset !== manifest.asset || first.asset_contract !== manifest.asset_contract) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: assets[0] (${first.asset}:${first.asset_contract}) must match root asset fields (${manifest.asset}:${manifest.asset_contract})`
+      );
+    }
+  }
+  assertPricingMatchesModes(manifest, context);
+  assertDeprecatedModesListed(manifest, context);
+  assertPricesParse(manifest, context);
+}
+function assertPricingMatchesModes(manifest, context) {
+  const pricing = manifest.pricing ?? {};
+  for (const mode of manifest.modes ?? []) {
+    if (pricing[mode] === void 0 || pricing[mode] === null) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: mode '${mode}' is listed in modes but pricing.${mode} is missing`
+      );
+    }
+  }
+}
+function assertDeprecatedModesListed(manifest, context) {
+  if (manifest.deprecated_modes === void 0) return;
+  const modes = new Set(manifest.modes ?? []);
+  for (const mode of manifest.deprecated_modes) {
+    if (!modes.has(mode)) {
+      throw new RouteDockManifestError(
+        `Invalid manifest${context}: deprecated_modes entry '${mode}' is not listed in modes`
+      );
+    }
+  }
+}
+var PRICE_FIELDS = {
+  x402: ["amount"],
+  "mpp-charge": ["amount"],
+  "mpp-session": ["rate", "min_deposit"],
+  "mpp-session-ws": ["rate", "min_deposit"]
+};
+function assertPricesParse(manifest, context) {
+  const pricing = manifest.pricing ?? {};
+  for (const [mode, fields] of Object.entries(PRICE_FIELDS)) {
+    const entry = pricing[mode];
+    if (entry === void 0 || entry === null) continue;
+    for (const field of fields) {
+      const value = entry[field];
+      try {
+        if (typeof value !== "string") {
+          throw new RangeError(`expected a decimal string, got ${typeof value}`);
+        }
+        usdcToStroops(value);
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new RouteDockManifestError(
+          `Invalid manifest${context}: pricing.${mode}.${field} ${JSON.stringify(value)} is not a valid amount (${detail})`,
+          { cause: err }
+        );
+      }
+    }
+  }
+}
+
+// src/provider/internal/assertProviderConfig.ts
+var FLAT_MODES = ["x402", "mpp-charge"];
+var SESSION_MODES = ["mpp-session", "mpp-session-ws"];
+function sameAmount(adapter, label, optionValue, manifestValue) {
+  const parse = (where, value) => {
+    try {
+      return usdcToStroops(value);
+    } catch {
+      throw new RouteDockManifestError(
+        `${adapter}: ${label} has an unparseable ${where} amount "${value}"`
+      );
+    }
+  };
+  return parse("option", optionValue) === parse("manifest", manifestValue);
+}
+function assertProviderConfig(opts, adapterName) {
+  const { manifest } = opts;
+  if (manifest === null || typeof manifest !== "object") {
+    throw new RouteDockManifestError(`${adapterName}: opts.manifest is required and must be an object`);
+  }
+  try {
+    validateManifestSchema(manifest);
+    assertManifestValid(manifest);
+  } catch (err) {
+    if (err instanceof RouteDockManifestError) {
+      throw new RouteDockManifestError(`${adapterName}: ${err.message}`, { cause: err });
+    }
+    throw err;
+  }
+  const served = new Set(opts.modes.filter((mode) => Boolean(opts.pricing[mode])));
+  const advertised = new Set(manifest.modes);
+  const notAdvertised = [...served].filter((mode) => !advertised.has(mode));
+  const notServed = [...advertised].filter((mode) => !served.has(mode));
+  if (notAdvertised.length > 0 || notServed.length > 0) {
+    const parts = [];
+    if (notAdvertised.length > 0) parts.push(`served but not in manifest.modes: ${notAdvertised.join(", ")}`);
+    if (notServed.length > 0) parts.push(`in manifest.modes but not served (missing from modes or pricing): ${notServed.join(", ")}`);
+    throw new RouteDockManifestError(`${adapterName}: modes do not match manifest.modes (${parts.join("; ")})`);
+  }
+  for (const mode of FLAT_MODES) {
+    if (!served.has(mode)) continue;
+    const optionValue = opts.pricing[mode];
+    const manifestValue = manifest.pricing[mode]?.amount;
+    if (manifestValue === void 0) {
+      throw new RouteDockManifestError(`${adapterName}: manifest.pricing.${mode}.amount is missing but ${mode} is served`);
+    }
+    if (!sameAmount(adapterName, `pricing.${mode}`, optionValue, manifestValue)) {
+      throw new RouteDockManifestError(
+        `${adapterName}: pricing.${mode} "${optionValue}" does not match manifest.pricing.${mode}.amount "${manifestValue}"`
+      );
+    }
+  }
+  for (const mode of SESSION_MODES) {
+    if (!served.has(mode)) continue;
+    const optionValue = opts.pricing[mode];
+    const manifestValue = manifest.pricing[mode];
+    if (!manifestValue) {
+      throw new RouteDockManifestError(`${adapterName}: manifest.pricing.${mode} is missing but ${mode} is served`);
+    }
+    if (!sameAmount(adapterName, `pricing.${mode}.rate`, optionValue.rate, manifestValue.rate)) {
+      throw new RouteDockManifestError(
+        `${adapterName}: pricing.${mode}.rate "${optionValue.rate}" does not match manifest.pricing.${mode}.rate "${manifestValue.rate}"`
+      );
+    }
+    if (optionValue.channelFactory !== manifestValue.channel_factory) {
+      throw new RouteDockManifestError(
+        `${adapterName}: pricing.${mode}.channelFactory "${optionValue.channelFactory}" does not match manifest.pricing.${mode}.channel_factory "${manifestValue.channel_factory}"`
+      );
+    }
+  }
+  if (opts.assetContract !== void 0 && opts.assetContract !== manifest.asset_contract) {
+    throw new RouteDockManifestError(
+      `${adapterName}: assetContract "${opts.assetContract}" does not match manifest.asset_contract "${manifest.asset_contract}"`
+    );
+  }
+  if (opts.asset !== void 0 && opts.asset !== manifest.asset) {
+    throw new RouteDockManifestError(
+      `${adapterName}: asset "${opts.asset}" does not match manifest.asset "${manifest.asset}"`
+    );
+  }
+  if (opts.network !== manifest.network) {
+    throw new RouteDockManifestError(
+      `${adapterName}: network "${opts.network}" does not match manifest.network "${manifest.network}"`
+    );
+  }
+  let signerPublicKey;
+  try {
+    signerPublicKey = Keypair.fromSecret(opts.payeeSecretKey).publicKey();
+  } catch (err) {
+    throw new RouteDockManifestError(`${adapterName}: payeeSecretKey is not a valid Stellar secret key`, { cause: err });
+  }
+  if (signerPublicKey !== manifest.payee) {
+    throw new RouteDockManifestError(
+      `${adapterName}: payeeSecretKey belongs to ${signerPublicKey}, not manifest.payee ${manifest.payee}; clients would reject the signed manifest`
+    );
+  }
+  if (opts.payee !== manifest.payee) {
+    throw new RouteDockManifestError(
+      `${adapterName}: payee "${opts.payee}" does not match manifest.payee "${manifest.payee}"`
+    );
+  }
+}
 
 // src/internal/payee.ts
 function resolvePayee(manifest, mode) {
   const override = manifest.pricing[mode]?.payee;
   return override ?? manifest.payee;
 }
-var usdcToUnits = usdcToStroops;
 function extractPayerAddress(key) {
   if (typeof key !== "string") return null;
   return StrKey.isValidEd25519PublicKey(key) || StrKey.isValidMed25519PublicKey(key) ? key : null;
@@ -137,6 +743,18 @@ function resolveLogger(logger, fallback = consoleLogger) {
 // src/provider/SeenTxStore.ts
 var SETTLEMENT_REPLAY_WINDOW_MS = 6e4;
 var MAX_SETTLEMENT_REPLAYS = 1;
+async function recordSettlement(store, key, record, ctx) {
+  try {
+    await store.set(key, record);
+  } catch (err) {
+    ctx.logger("error", `${ctx.label} seenTxStore.set failed after settlement`, { error: err });
+    try {
+      ctx.onCallbackError?.(err, "seenTxStore.set");
+    } catch (cbErr) {
+      ctx.logger("error", `${ctx.label} onCallbackError threw`, { error: cbErr });
+    }
+  }
+}
 async function checkSettlementReplay(store, key, now = Date.now()) {
   const record = await store.get(key);
   if (!record) return { kind: "miss" };
@@ -204,7 +822,7 @@ async function paymentIdempotencyKey(getHeader, scope) {
   );
 }
 
-// src/provider/settleResult.ts
+// src/internal/settleResult.ts
 function readSettleResult(result) {
   const settle = result;
   const failed = (reason) => reason ? { ok: false, reason } : { ok: false };
@@ -354,10 +972,10 @@ function createX402Handler(opts) {
           requirements
         );
         if (!verifyResult.isValid) {
-          res.status(401).json({
-            error: "Payment verification failed",
-            reason: verifyResult.invalidReason
-          });
+          await respondPaymentRequired(
+            "Payment verification failed",
+            verifyResult.invalidReason
+          );
           return;
         }
         const settleResult = await localFacilitator.settle(
@@ -383,7 +1001,12 @@ function createX402Handler(opts) {
         if (typeof paymentResponse === "string") {
           headers["X-Payment-Response"] = paymentResponse;
         }
-        await seenTxStore.set(idempotencyKey, { txHash, headers, createdAt: Date.now() });
+        await recordSettlement(
+          seenTxStore,
+          idempotencyKey,
+          { txHash, headers, createdAt: Date.now() },
+          { logger, label: "[x402]", onCallbackError: opts.onCallbackError }
+        );
       }
       if (txHash && opts.onSettled) {
         Promise.resolve().then(() => opts.onSettled(txHash, opts.amount, "x402", payerAddress)).catch((err) => {
@@ -402,6 +1025,51 @@ function createX402Handler(opts) {
     }
   };
 }
+
+// src/internal/encoding.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function utf8ToBytes(text) {
+  return encoder.encode(text);
+}
+function bytesToUtf8(bytes) {
+  return decoder.decode(bytes);
+}
+function bytesToBase64(bytes) {
+  const chunk = 32768;
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+  }
+  return btoa(binary);
+}
+function base64ToBytes(b64) {
+  const end = b64.indexOf("=");
+  let clean = (end === -1 ? b64 : b64.slice(0, end)).replace(/-/g, "+").replace(/_/g, "/").replace(/[^A-Za-z0-9+/]/g, "");
+  if (clean.length % 4 === 1) clean = clean.slice(0, -1);
+  const binary = atob(clean);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+function base64ToUtf8(b64) {
+  return bytesToUtf8(base64ToBytes(b64));
+}
+function hexToBytes(hex) {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  if (clean.length % 2 !== 0) {
+    throw new Error("hexToBytes: hex string must have an even length");
+  }
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+// src/provider/MppChargeHandler.ts
 var MPP_NETWORK = {
   testnet: "stellar:testnet",
   mainnet: "stellar:pubnet"
@@ -448,7 +1116,7 @@ function createMppChargeHandler(opts) {
           const credPart = authHeader.replace(/^Payment\s+/, "").split(",").find((p) => p.trim().startsWith("credential="));
           if (credPart) {
             const b64 = credPart.split("=").slice(1).join("=").replace(/^"|"$/g, "");
-            const credJson = Buffer.from(b64, "base64").toString("utf8");
+            const credJson = base64ToUtf8(b64);
             const cred = JSON.parse(credJson);
             const key = cred.sender ?? cred.payload?.sender ?? cred.payload?.from;
             payerAddress = extractPayerAddress(key);
@@ -510,18 +1178,19 @@ function createMppChargeHandler(opts) {
       if (receiptHeader) {
         try {
           const parsed = JSON.parse(
-            Buffer.from(receiptHeader, "base64").toString("utf8")
+            base64ToUtf8(receiptHeader)
           );
           reference = parsed.reference;
         } catch {
         }
       }
       if (idempotencyKey) {
-        await seenTxStore.set(idempotencyKey, {
-          txHash: reference ?? null,
-          headers: receiptHeaders,
-          createdAt: Date.now()
-        });
+        await recordSettlement(
+          seenTxStore,
+          idempotencyKey,
+          { txHash: reference ?? null, headers: receiptHeaders, createdAt: Date.now() },
+          { logger, label: "[mpp-charge]", onCallbackError: opts.onCallbackError }
+        );
       }
       if (reference && opts.onSettled) {
         Promise.resolve().then(() => opts.onSettled(reference, opts.amount, "mpp-charge", payerAddress)).catch((err) => {
@@ -535,6 +1204,14 @@ function createMppChargeHandler(opts) {
     }
   };
 }
+
+// src/provider/internal/vaultRpc.ts
+async function createSorobanRpcServer(rpcUrl) {
+  const { Server } = await import('@stellar/stellar-sdk/rpc');
+  return new Server(rpcUrl);
+}
+
+// src/provider/internal/vaultSettlement.ts
 function resolveVaultSettlementAddresses(payer, payee) {
   if (!payer) return null;
   return { payer, payee };
@@ -554,6 +1231,111 @@ function buildSessionSettlementTransaction(source, vaultContractId, channelId, a
     networkPassphrase
   }).addOperation(op).setTimeout(30).build();
 }
+var DEFAULT_RPC_URLS = {
+  testnet: "https://soroban-testnet.stellar.org",
+  mainnet: "https://mainnet.sorobanrpc.com"
+};
+var CONFIRM_TIMEOUT_MS = 12e4;
+var CONFIRM_POLL_MS = 1e3;
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function describeSendError(sent) {
+  const errorResult = sent.errorResult;
+  try {
+    const name = errorResult?.result?.().switch?.().name;
+    if (name) return `sendTransaction returned ERROR: ${name}`;
+  } catch {
+  }
+  return `sendTransaction returned status ${sent.status}`;
+}
+async function waitForConfirmation(server, txHash) {
+  const deadline = Date.now() + CONFIRM_TIMEOUT_MS;
+  for (; ; ) {
+    const tx = await server.getTransaction(txHash);
+    if (tx.status === "SUCCESS") return "success";
+    if (tx.status === "FAILED") return "failed";
+    if (Date.now() >= deadline) return "timeout";
+    await delay(CONFIRM_POLL_MS);
+  }
+}
+async function recordSessionSettlement(request, { logger, onCallbackError }) {
+  const reportFailure = (fields) => {
+    logger("error", "[vault] failed to record session_settled", {
+      channelId: request.channelId,
+      ...fields.txHash ? { txHash: fields.txHash } : {},
+      reason: fields.reason,
+      ...fields.error !== void 0 ? { error: fields.error } : {}
+    });
+    if (onCallbackError) {
+      const err = fields.error ?? new Error(`session_settled vault record failed: ${fields.reason}`);
+      onCallbackError(err, "vaultSettlement");
+    }
+    return { ok: false, reason: fields.reason, ...fields.txHash ? { txHash: fields.txHash } : {} };
+  };
+  try {
+    const payeeKeypair = Keypair.fromSecret(request.payeeSecretKey);
+    const addresses = resolveVaultSettlementAddresses(request.payer, payeeKeypair.publicKey());
+    if (!addresses) {
+      logger("warn", "[vault] skipped session_settled record: payer address unavailable", {
+        channelId: request.channelId
+      });
+      return { ok: false, reason: "payer address unavailable" };
+    }
+    const networkPassphrase = request.network === "mainnet" ? Networks.PUBLIC : Networks.TESTNET;
+    const rpcUrl = request.config.rpcUrl ?? DEFAULT_RPC_URLS[request.network];
+    const server = await createSorobanRpcServer(rpcUrl);
+    const sourceAccount = await server.getAccount(payeeKeypair.publicKey());
+    const tx = buildSessionSettlementTransaction(
+      sourceAccount,
+      request.config.contract,
+      request.channelId,
+      addresses,
+      request.amount,
+      request.voucherCount,
+      networkPassphrase
+    );
+    const preparedTx = await server.prepareTransaction(tx);
+    preparedTx.sign(payeeKeypair);
+    const sent = await server.sendTransaction(preparedTx);
+    if (sent.status === "ERROR") {
+      return reportFailure({
+        txHash: sent.hash || preparedTx.hash().toString("hex"),
+        reason: describeSendError(sent)
+      });
+    }
+    const txHash = sent.hash || preparedTx.hash().toString("hex");
+    const confirmation = await waitForConfirmation(server, txHash);
+    if (confirmation === "success") {
+      logger("debug", "[vault] recorded session_settled", {
+        channelId: request.channelId,
+        txHash
+      });
+      return { ok: true, txHash };
+    }
+    return reportFailure({
+      txHash,
+      reason: confirmation === "failed" ? "transaction failed on-chain" : `confirmation timed out after ${CONFIRM_TIMEOUT_MS}ms`
+    });
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return reportFailure({ reason, error: err });
+  }
+}
+
+// src/internal/vaultConfig.ts
+function resolveVaultSettlementConfig(option, logger) {
+  if (option) return option;
+  if (typeof process === "undefined") return void 0;
+  const fromEnv = process.env.AGENT_VAULT_CONTRACT ?? process.env.AGENT_VAULT_CONTRACT_ID;
+  if (!fromEnv) return void 0;
+  logger(
+    "warn",
+    "[vault] configuring the vault contract via the AGENT_VAULT_CONTRACT/AGENT_VAULT_CONTRACT_ID environment variables is deprecated and will be removed in the next minor release \u2014 pass the vaultSettlement option instead",
+    {}
+  );
+  return { contract: fromEnv };
+}
 function channelAuthorizer(envelopeSigner) {
   return { envelopeSigner };
 }
@@ -632,6 +1414,7 @@ function createMppSessionHandler(opts) {
   let record = null;
   let voucherCount = 0;
   let sessionOpened = false;
+  let orphanFlagged = false;
   let idleTimer = null;
   let settledCleanly = false;
   let closeListenerArmed = false;
@@ -657,6 +1440,14 @@ function createMppSessionHandler(opts) {
         return null;
       }
       record = { amount: BigInt(stored.amount), signature: stored.signature, payer: stored.payer ?? null };
+      if (typeof stored.voucherCount === "number") {
+        voucherCount = stored.voucherCount;
+      }
+      if (typeof stored.sessionOpened === "boolean") {
+        sessionOpened = stored.sessionOpened;
+      } else if (record !== null) {
+        sessionOpened = true;
+      }
     } catch {
       return null;
     }
@@ -664,8 +1455,8 @@ function createMppSessionHandler(opts) {
   }
   async function flagOrphan(reason) {
     await loadPersistedRecord();
-    if (!sessionOpened || settledCleanly) return;
-    sessionOpened = false;
+    if (!sessionOpened || settledCleanly || orphanFlagged) return;
+    orphanFlagged = true;
     closeListenerArmed = false;
     clearIdleTimer();
     const cumulativeAmount = record ? (Number(record.amount) / 1e7).toFixed(7) : "0.0000000";
@@ -713,16 +1504,20 @@ function createMppSessionHandler(opts) {
     if (record && amount < record.amount) return;
     const payer = record?.payer ?? extractPayerAddress(credential.source);
     record = { amount, signature: payload.signature, payer };
+    voucherCount++;
+    settledCleanly = false;
+    orphanFlagged = false;
+    armIdleTimer();
+    const wasOpened = sessionOpened;
+    sessionOpened = true;
     await innerStore.put(voucherRecordKey, {
       amount: record.amount.toString(),
       signature: record.signature,
-      payer: record.payer
+      payer: record.payer,
+      voucherCount,
+      sessionOpened: true
     });
-    voucherCount++;
-    settledCleanly = false;
-    armIdleTimer();
-    if (!sessionOpened) {
-      sessionOpened = true;
+    if (!wasOpened) {
       if (opts.onSessionOpen) {
         Promise.resolve().then(() => opts.onSessionOpen(opts.channelFactory, record.payer)).catch((err) => {
           logger("error", "[mpp-session] onSessionOpen callback error", { error: err });
@@ -774,10 +1569,11 @@ function createMppSessionHandler(opts) {
         }
         if (closeAmount > 0n && closeSig) {
           const closePayer = record?.payer ?? null;
+          const vouchersClosed = voucherCount;
           const closeTxHash = await close({
             channel: opts.channelFactory,
             amount: closeAmount,
-            signature: Buffer.from(closeSig, "hex"),
+            signature: hexToBytes(closeSig),
             feePayer: channelAuthorizer(payeeKeypair),
             network: networkId
           });
@@ -790,46 +1586,28 @@ function createMppSessionHandler(opts) {
               opts.onCallbackError?.(err, "onSettled");
             });
           }
-          const vaultContract = process.env.AGENT_VAULT_CONTRACT;
-          if (vaultContract) {
-            const settlementAddresses = resolveVaultSettlementAddresses(
-              closePayer,
-              payeeKeypair.publicKey()
+          res.json({ closeTxHash });
+          const vaultConfig = resolveVaultSettlementConfig(opts.vaultSettlement, logger);
+          if (vaultConfig) {
+            await recordSessionSettlement(
+              {
+                config: vaultConfig,
+                network: opts.network,
+                payeeSecretKey: opts.payeeSecretKey,
+                channelId: opts.channelFactory,
+                payer: closePayer,
+                amount: closeAmount,
+                voucherCount: vouchersClosed
+              },
+              { logger, onCallbackError: opts.onCallbackError }
             );
-            if (!settlementAddresses) {
-              logger("warn", "[mpp-session] skipped session_settled vault record: payer address unavailable");
-            } else {
-              try {
-                const { Networks } = await import('@stellar/stellar-sdk');
-                const { Server } = await import('@stellar/stellar-sdk/rpc');
-                const networkPassphrase = opts.network === "mainnet" ? Networks.PUBLIC : Networks.TESTNET;
-                const rpcUrl = opts.network === "mainnet" ? "https://mainnet.sorobanrpc.com" : "https://soroban-testnet.stellar.org";
-                const server = new Server(rpcUrl);
-                const payeePublicKey = payeeKeypair.publicKey();
-                const sourceAccount = await server.getAccount(payeePublicKey);
-                const tx = buildSessionSettlementTransaction(
-                  sourceAccount,
-                  vaultContract,
-                  opts.channelFactory,
-                  settlementAddresses,
-                  closeAmount,
-                  voucherCount,
-                  networkPassphrase
-                );
-                const preparedTx = await server.prepareTransaction(tx);
-                preparedTx.sign(payeeKeypair);
-                await server.sendTransaction(preparedTx);
-              } catch (recordErr) {
-                logger("error", "[mpp-session] failed to record session_settled on vault", { error: recordErr });
-              }
-            }
           }
-          res.json({ closeTxHash });
         } else {
           res.json({ closeTxHash: null, message: "no vouchers received" });
         }
         sessionOpened = false;
         voucherCount = 0;
+        orphanFlagged = false;
         record = null;
         await innerStore.delete(voucherRecordKey);
         closeListenerArmed = false;
@@ -861,6 +1639,11 @@ function createMppSessionHandler(opts) {
     }
   };
 }
+function sha256(data) {
+  return sha256$1(typeof data === "string" ? utf8ToBytes(data) : data);
+}
+
+// src/manifest/sign.ts
 var MANIFEST_SIGNATURE_VERSION = "2";
 function canonicalize(value) {
   if (Array.isArray(value)) {
@@ -876,7 +1659,7 @@ function canonicalize(value) {
 function manifestDigest(manifest) {
   const { signature: _omit, ...rest } = manifest;
   const canonical = JSON.stringify(canonicalize(rest));
-  return createHash("sha256").update(canonical, "utf8").digest();
+  return sha256(utf8ToBytes(canonical));
 }
 function signManifest(manifest, payeeSecretKey) {
   const keypair = Keypair.fromSecret(payeeSecretKey);
@@ -886,7 +1669,7 @@ function signManifest(manifest, payeeSecretKey) {
   };
   const digest = manifestDigest(versionedManifest);
   const sig = keypair.sign(digest);
-  return { ...versionedManifest, signature: Buffer.from(sig).toString("base64") };
+  return { ...versionedManifest, signature: bytesToBase64(sig) };
 }
 
 // src/provider/fastify.ts
@@ -1002,6 +1785,7 @@ function runExpressHandler(handler, fastifyRequest, fastifyReply) {
 }
 var MPP_MODES = ["mpp-session", "mpp-charge"];
 function routedockFastify(opts) {
+  assertProviderConfig(opts, "routedockFastify");
   const signedManifest = signManifest(opts.manifest, opts.payeeSecretKey);
   const handlerMap = /* @__PURE__ */ new Map();
   if (opts.modes.includes("x402")) {
@@ -1065,7 +1849,8 @@ function routedockFastify(opts) {
           ...opts.onCallbackError ? { onCallbackError: opts.onCallbackError } : {},
           ...opts.onOrphaned ? { onOrphaned: opts.onOrphaned } : {},
           ...opts.idleTimeoutMs != null ? { idleTimeoutMs: opts.idleTimeoutMs } : {},
-          ...opts.logger ? { logger: opts.logger } : {}
+          ...opts.logger ? { logger: opts.logger } : {},
+          ...opts.vaultSettlement ? { vaultSettlement: opts.vaultSettlement } : {}
         })
       );
     }