@routedock/routedock 0.1.2 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RouteDock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,17 +1,17 @@
-# @routedock/routedock
+# @routedock/sdk
 
 Unified payment execution layer for autonomous agents on Stellar. One SDK for x402, MPP charge, and MPP session — mode selected automatically from the provider's `routedock.json` manifest.
 
 ## Install
 
 ```bash
-npm install @routedock/routedock
+npm install @routedock/sdk
 ```
 
 ## Agent Usage
 
 ```ts
-import { RouteDockClient } from '@routedock/routedock/client'
+import { RouteDockClient } from '@routedock/sdk/client'
 import { Keypair } from '@stellar/stellar-sdk'
 
 const client = new RouteDockClient({
@@ -35,11 +35,40 @@ for await (const update of session.stream()) {
 await session.close() // triggers on-chain settlement
 ```
 
+### Durable spend cap
+
+The `spendCap` is enforced via a pluggable `SpendStore` (`read()` / `write()`).
+By default the client uses an in-memory store that resets on every process
+restart — and logs a startup warning — so the cap is **not** durable. For
+production, inject a persistent implementation so a crash or restart can't reset
+the accumulator and bypass the cap:
+
+```ts
+import { RouteDockClient, type SpendStore, type DailySpend } from '@routedock/sdk/client'
+
+const redisSpendStore: SpendStore = {
+  async read(): Promise<DailySpend | null> {
+    const raw = await redis.get('routedock:dailySpend')
+    return raw ? (JSON.parse(raw) as DailySpend) : null
+  },
+  async write(state: DailySpend): Promise<void> {
+    await redis.set('routedock:dailySpend', JSON.stringify(state))
+  },
+}
+
+const client = new RouteDockClient({
+  wallet: Keypair.fromSecret(process.env.AGENT_SECRET),
+  network: 'mainnet',
+  spendCap: { daily: '1.00', asset: 'USDC' },
+  spendStore: redisSpendStore,
+})
+```
+
 ## Provider Usage
 
 ```ts
 import express from 'express'
-import { routedock } from '@routedock/routedock/provider'
+import { routedock } from '@routedock/sdk/provider'
 
 const app = express()
 
@@ -107,6 +136,175 @@ app.use('/stream', routedock({
 | `onVoucher(index, cumulativeAmount)` | Each verified ed25519 commitment | No |
 | `onSettled(txHash, amount, mode)` | Channel close transaction confirmed | Yes |
 
+## React Integration
+
+> **Warning:** These hooks create a RouteDockClient in the browser, so the wallet secret and any commitmentSecret are readable by anyone who loads the page.
+>
+> Next.js inlines every `NEXT_PUBLIC_*` variable into the client bundle at build time, so never put a Stellar secret in one.
+>
+> Only use these hooks with a dedicated, low-balance testnet key, and spendCap does not protect a key that has leaked.
+>
+> For production or mainnet, keep RouteDockClient on the server (a route handler or server action) and read the key from a non-public variable such as `AGENT_SECRET`, as the Agent Usage section does.
+
+`@routedock/sdk/react` provides hooks for client construction, payments, sessions, and live tx log subscription. Wrap your app with `RouteDockProvider`:
+
+```tsx
+import { RouteDockProvider, useRouteDockClient } from '@routedock/sdk/react'
+import { createClient } from '@supabase/supabase-js'
+
+// Dedicated throwaway testnet key. Never a funded or mainnet key.
+const THROWAWAY_TESTNET_SECRET = 'S...'
+
+function App({ children }: { children: React.ReactNode }) {
+  const client = useRouteDockClient({
+    wallet: THROWAWAY_TESTNET_SECRET,
+    network: 'testnet',
+    spendCap: { daily: '1.00', asset: 'USDC' },
+  })
+  const supabase = createClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+  )
+  return (
+    <RouteDockProvider client={client} supabase={supabase}>
+      {children}
+    </RouteDockProvider>
+  )
+}
+```
+
+### Paying from the server
+
+```ts
+// app/api/price/route.ts (runs on the server only)
+import { RouteDockClient } from '@routedock/sdk/client'
+
+const client = new RouteDockClient({
+  wallet: process.env.AGENT_SECRET!,
+  network: 'testnet',
+  spendCap: { daily: '1.00', asset: 'USDC' },
+})
+
+export async function POST() {
+  const result = await client.pay('https://provider.example.com/price')
+  return Response.json({ mode: result.mode, txHash: result.txHash, data: result.data })
+}
+```
+
+### `usePay(url, options?)`
+
+```tsx
+import { usePay } from '@routedock/sdk/react'
+
+function PriceButton() {
+  const { pay, result, loading, error } = usePay('https://provider.example.com/price')
+  if (error) return <span>Error: {error.message}</span>
+  return (
+    <button onClick={pay} disabled={loading}>
+      {loading ? 'Paying…' : result ? `Paid: ${result.txHash}` : 'Pay 0.001 USDC'}
+    </button>
+  )
+}
+```
+
+### `useSession(url)`
+
+```tsx
+import { useEffect } from 'react'
+import { useSession } from '@routedock/sdk/react'
+
+function StreamingFeed() {
+  const { open, close, status, vouchers, cumulative } = useSession(
+    'https://provider.example.com/stream/orderbook',
+  )
+  useEffect(() => { void open() }, [])
+  return (
+    <div>
+      <p>Status: {status} — vouchers: {vouchers} — paid: {cumulative} USDC</p>
+      <button onClick={close} disabled={status !== 'open'}>Close & settle</button>
+    </div>
+  )
+}
+```
+
+The hook automatically fires `session.close()` in the background on unmount when status is `open` (best-effort settlement).
+
+### `useTxLog(filter?)`
+
+```tsx
+import { useTxLog } from '@routedock/sdk/react'
+
+function ActivityFeed({ channelId }: { channelId: string }) {
+  const txLog = useTxLog({ channelId, limit: 25 })
+  return (
+    <ul>
+      {txLog.map((row) => (
+        <li key={row.id}>{row.mode} — {row.amount} USDC — {row.tx_hash}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+| Hook | Returns | Requires from `RouteDockProvider` |
+|---|---|---|
+| `useRouteDockClient(config)` | Memoized `RouteDockClient` | — (creator hook) |
+| `usePay(url, options?)` | `{ pay, result, loading, error }` | `client` |
+| `useSession(url)` | `{ session, status, vouchers, cumulative, error, open, close }` | `client` (with `commitmentSecret`) |
+| `useTxLog(filter?)` | `TxLogRow[]` (newest first) | `supabase` |
+
+React is a peer dependency — install `react@^18` (or `^19`) in your app.
+
+---
+
+## Error Handling
+
+All SDK failures extend `RouteDockError` with a stable `code`, `retryable` flag, and optional `cause`. Transient failures (network timeouts, facilitator 5xx, Horizon RPC errors) are retried automatically with exponential backoff unless you disable retries.
+
+```ts
+import {
+  RouteDockClient,
+  RouteDockError,
+  RouteDockFacilitatorError,
+  RouteDockManifestError,
+  RouteDockPolicyRejectError,
+} from '@routedock/sdk/client'
+
+const client = new RouteDockClient({
+  wallet: process.env.AGENT_SECRET!,
+  network: 'testnet',
+  retryPolicy: { maxAttempts: 4, baseDelayMs: 250 },
+})
+
+try {
+  const result = await client.pay('https://provider.example.com/price')
+  console.log(result.mode, result.txHash)
+} catch (err) {
+  if (err instanceof RouteDockPolicyRejectError) {
+    console.error('Spend cap exceeded:', err.reason)
+  } else if (err instanceof RouteDockFacilitatorError) {
+    console.error(`Facilitator HTTP ${err.status} (retryable=${err.retryable})`)
+  } else if (err instanceof RouteDockManifestError) {
+    console.error('Manifest or config problem:', err.message)
+  } else if (err instanceof RouteDockError) {
+    console.error(`[${err.code}] ${err.message} (retryable=${err.retryable})`)
+  } else {
+    throw err
+  }
+}
+```
+
+| Error | `retryable` | Typical cause |
+|---|---|---|
+| `RouteDockManifestError` | no | Invalid manifest, missing pricing fields |
+| `RouteDockNoSupportedModeError` | no | Provider has no compatible payment mode |
+| `RouteDockFacilitatorError` | yes | Facilitator/provider 429 or 5xx |
+| `RouteDockNetworkError` | yes | Timeouts, connection failures |
+| `RouteDockSignatureError` | no | Signing or commitment failure |
+| `RouteDockVoucherMonotonicityError` | no | Non-increasing voucher amount |
+| `RouteDockPolicyRejectError` | no | Local spend cap exceeded |
+| `RouteDockChannelStateError` | no | Channel simulate/close invariant violation |
+
 ## Mode Selection Logic
 
 The `ModeRouter` uses this decision tree (deterministic, no randomness):
@@ -118,6 +316,31 @@ The `ModeRouter` uses this decision tree (deterministic, no randomness):
 
 Override with `{ forceMode: 'x402' }` to bypass auto-selection.
 
+## Dispute Resolution
+
+For `mpp-session` mode, the session handle exposes three methods to handle server unavailability or crashes:
+
+```ts
+const session = await client.openSession('https://provider.example.com/stream')
+
+// Check the current dispute status (open, in-refund-window, refundable, settled)
+const status = await session.getDisputeStatus()
+
+// If server is unresponsive, request a refund (starts the refund window)
+const refundTxHash = await session.requestRefund()
+
+// Server-side: settle with the latest signed voucher before refund window expires
+const settleTxHash = await session.settleWithLatestVoucher()
+```
+
+| Method | Purpose | Requires | Returns |
+|--------|---------|----------|---------|
+| `getDisputeStatus()` | Query channel state | None | `'open' \| 'in-refund-window' \| 'refundable' \| 'settled'` |
+| `requestRefund()` | Initiate refund process | Signed agent keypair | Transaction hash (string) |
+| `settleWithLatestVoucher()` | Server counter-settle | Latest voucher signature | Transaction hash (string) |
+
+Raises: `RouteDockDisputeError`, `RouteDockChannelStateError`, `RouteDockRefundWindowError`
+
 ## Security
 
 The `one-way-channel` Soroban contract wrapped by `MppSessionClient` is **unaudited** (`stellar-experimental/one-way-channel`). Safe defaults are enforced: 17280 ledger refund window, monotonic cumulative enforcement at application, database, and contract layers. Production mainnet use should await a formal audit.

package/dist/MppSessionHandler-B4TyD7Xg.d.cts

@@ -0,0 +1,121 @@
+import { RequestHandler } from 'express';
+import { Store } from 'mppx';
+import { R as RouteDockManifest } from './types-DmhmfLzP.cjs';
+
+/**
+ * Idempotency store for payment settlement.
+ *
+ * `x402Handler` and `MppChargeHandler` settle on every request carrying a
+ * payment header. An agent that retries after a post-settlement network
+ * timeout resends the *same* signed payment, which would settle a second time
+ * and invoke `onSettled` twice — double-counting in billing.
+ *
+ * Before settling, a handler derives an idempotency key from the inbound
+ * payment header(s) and checks this store. On a hit it replays the cached
+ * settlement response and skips both the on-chain settle and `onSettled`.
+ *
+ * The default {@link InMemorySeenTxStore} is per-handler and per-process. For
+ * multi-instance deployments, supply a shared implementation backed by Redis,
+ * Supabase, etc.
+ */
+/** Cached outcome of a settlement, replayed on a duplicate payment. */
+interface SettlementRecord {
+    /** On-chain transaction hash (or settlement reference), if known. */
+    txHash: string | null;
+    /** Response headers to re-apply on a replay (e.g. `X-Payment-Response`). */
+    headers?: Record<string, string>;
+}
+interface SeenTxStore {
+    /** Returns the cached settlement for a key, or `undefined` if unseen. */
+    get(key: string): Promise<SettlementRecord | undefined> | SettlementRecord | undefined;
+    /** Records the settlement outcome for a key. */
+    set(key: string, record: SettlementRecord): Promise<void> | void;
+}
+interface InMemorySeenTxStoreOptions {
+    /** Maximum number of entries before FIFO eviction. Defaults to 10,000. */
+    maxEntries?: number;
+    /** Log a startup warning about non-durability. Defaults to true. */
+    warn?: boolean;
+}
+/**
+ * Default in-memory {@link SeenTxStore}. Bounded by `maxEntries` with FIFO
+ * eviction so a long-running process cannot grow without limit.
+ *
+ * **Not durable.** On serverless/edge runtimes each request may land on a
+ * fresh isolate with an empty cache, which causes duplicate settlements.
+ * Supply a persistent implementation (Supabase, Redis, …) in production.
+ */
+declare class InMemorySeenTxStore implements SeenTxStore {
+    private readonly map;
+    private readonly order;
+    constructor(maxEntriesOrOptions?: number | InMemorySeenTxStoreOptions);
+    private readonly maxEntries;
+    get(key: string): SettlementRecord | undefined;
+    set(key: string, record: SettlementRecord): void;
+}
+/**
+ * Derive a collision-resistant idempotency key from the inbound
+ * payment-bearing headers. Uses SHA-256 instead of 32-bit FNV-1a
+ * (which has a 2^32 keyspace — birthday collisions become likely
+ * well before the 10_000-entry default store is full).
+ *
+ * x402 clients send the signed payment in `payment-signature` / `x-payment`;
+ * mppx clients send it in `authorization` (the `Payment` scheme). A retry
+ * resends byte-identical headers, so hashing the first present one yields a
+ * stable key. Returns `null` when no payment header is present (nothing to
+ * dedupe — e.g. the initial 402 challenge request).
+ */
+declare function paymentIdempotencyKey(getHeader: (name: string) => string | undefined): Promise<string | null>;
+
+/** Store shape extended with optional atomic update operation. */
+type ChannelStore = Store.Store & {
+    update?: (key: string, fn: (prev: unknown) => unknown) => Promise<unknown>;
+};
+/** Expected payload shape for voucher cumulative amount entries. */
+interface VoucherStoreValue {
+    amount: string;
+    [key: string]: unknown;
+}
+/** Validates that a stored store value is an object containing a numeric string amount. */
+declare function isVoucherStoreValue(value: unknown): value is VoucherStoreValue;
+type Network = 'testnet' | 'mainnet';
+/** Why a live session was flagged as orphaned (never cleanly closed). */
+type OrphanReason = 'connection-closed' | 'idle-timeout';
+/** Latest signed state of an orphaned session, enough for the reconciler to settle. */
+interface OrphanedSessionInfo {
+    /** Cumulative amount of the highest voucher seen (human-readable, 7 dp). */
+    cumulativeAmount: string;
+    /** Hex-encoded signature of the highest voucher seen. */
+    lastSignature: string;
+    /** Number of vouchers received before teardown. */
+    voucherCount: number;
+    /** What triggered the orphan flag. */
+    reason: OrphanReason;
+}
+interface MppSessionHandlerOptions {
+    payeeSecretKey: string;
+    network: Network;
+    channelFactory: string;
+    rate: string;
+    assetContract: string;
+    manifest: RouteDockManifest;
+    commitmentPublicKey: string;
+    onSettled?: (txHash: string, totalPaid: string, mode: string, payer: string | null) => Promise<void>;
+    onSessionOpen?: (channelId: string, payer: string | null) => Promise<void>;
+    onVoucher?: (channelId: string, voucherIndex: number, cumulativeAmount: string, signature: string) => Promise<void>;
+    onCallbackError?: (err: unknown, cb: string) => void;
+    /**
+     * Called when the client connection drops mid-session or the session goes
+     * idle, before a clean close. Persist the session as `closing` so the
+     * SessionReconciler can settle it with the latest signed voucher.
+     */
+    onOrphaned?: (channelId: string, info: OrphanedSessionInfo) => Promise<void>;
+    /**
+     * Flag the session orphaned after this many milliseconds with no voucher
+     * activity. Disabled when unset.
+     */
+    idleTimeoutMs?: number;
+}
+declare function createMppSessionHandler(opts: MppSessionHandlerOptions): RequestHandler;
+
+export { type ChannelStore as C, InMemorySeenTxStore as I, type MppSessionHandlerOptions as M, type OrphanedSessionInfo as O, type SeenTxStore as S, type VoucherStoreValue as V, type SettlementRecord as a, type InMemorySeenTxStoreOptions as b, type OrphanReason as c, createMppSessionHandler as d, isVoucherStoreValue as i, paymentIdempotencyKey as p };

package/dist/MppSessionHandler-CLB5SzgN.d.ts

@@ -0,0 +1,121 @@
+import { RequestHandler } from 'express';
+import { Store } from 'mppx';
+import { R as RouteDockManifest } from './types-DmhmfLzP.js';
+
+/**
+ * Idempotency store for payment settlement.
+ *
+ * `x402Handler` and `MppChargeHandler` settle on every request carrying a
+ * payment header. An agent that retries after a post-settlement network
+ * timeout resends the *same* signed payment, which would settle a second time
+ * and invoke `onSettled` twice — double-counting in billing.
+ *
+ * Before settling, a handler derives an idempotency key from the inbound
+ * payment header(s) and checks this store. On a hit it replays the cached
+ * settlement response and skips both the on-chain settle and `onSettled`.
+ *
+ * The default {@link InMemorySeenTxStore} is per-handler and per-process. For
+ * multi-instance deployments, supply a shared implementation backed by Redis,
+ * Supabase, etc.
+ */
+/** Cached outcome of a settlement, replayed on a duplicate payment. */
+interface SettlementRecord {
+    /** On-chain transaction hash (or settlement reference), if known. */
+    txHash: string | null;
+    /** Response headers to re-apply on a replay (e.g. `X-Payment-Response`). */
+    headers?: Record<string, string>;
+}
+interface SeenTxStore {
+    /** Returns the cached settlement for a key, or `undefined` if unseen. */
+    get(key: string): Promise<SettlementRecord | undefined> | SettlementRecord | undefined;
+    /** Records the settlement outcome for a key. */
+    set(key: string, record: SettlementRecord): Promise<void> | void;
+}
+interface InMemorySeenTxStoreOptions {
+    /** Maximum number of entries before FIFO eviction. Defaults to 10,000. */
+    maxEntries?: number;
+    /** Log a startup warning about non-durability. Defaults to true. */
+    warn?: boolean;
+}
+/**
+ * Default in-memory {@link SeenTxStore}. Bounded by `maxEntries` with FIFO
+ * eviction so a long-running process cannot grow without limit.
+ *
+ * **Not durable.** On serverless/edge runtimes each request may land on a
+ * fresh isolate with an empty cache, which causes duplicate settlements.
+ * Supply a persistent implementation (Supabase, Redis, …) in production.
+ */
+declare class InMemorySeenTxStore implements SeenTxStore {
+    private readonly map;
+    private readonly order;
+    constructor(maxEntriesOrOptions?: number | InMemorySeenTxStoreOptions);
+    private readonly maxEntries;
+    get(key: string): SettlementRecord | undefined;
+    set(key: string, record: SettlementRecord): void;
+}
+/**
+ * Derive a collision-resistant idempotency key from the inbound
+ * payment-bearing headers. Uses SHA-256 instead of 32-bit FNV-1a
+ * (which has a 2^32 keyspace — birthday collisions become likely
+ * well before the 10_000-entry default store is full).
+ *
+ * x402 clients send the signed payment in `payment-signature` / `x-payment`;
+ * mppx clients send it in `authorization` (the `Payment` scheme). A retry
+ * resends byte-identical headers, so hashing the first present one yields a
+ * stable key. Returns `null` when no payment header is present (nothing to
+ * dedupe — e.g. the initial 402 challenge request).
+ */
+declare function paymentIdempotencyKey(getHeader: (name: string) => string | undefined): Promise<string | null>;
+
+/** Store shape extended with optional atomic update operation. */
+type ChannelStore = Store.Store & {
+    update?: (key: string, fn: (prev: unknown) => unknown) => Promise<unknown>;
+};
+/** Expected payload shape for voucher cumulative amount entries. */
+interface VoucherStoreValue {
+    amount: string;
+    [key: string]: unknown;
+}
+/** Validates that a stored store value is an object containing a numeric string amount. */
+declare function isVoucherStoreValue(value: unknown): value is VoucherStoreValue;
+type Network = 'testnet' | 'mainnet';
+/** Why a live session was flagged as orphaned (never cleanly closed). */
+type OrphanReason = 'connection-closed' | 'idle-timeout';
+/** Latest signed state of an orphaned session, enough for the reconciler to settle. */
+interface OrphanedSessionInfo {
+    /** Cumulative amount of the highest voucher seen (human-readable, 7 dp). */
+    cumulativeAmount: string;
+    /** Hex-encoded signature of the highest voucher seen. */
+    lastSignature: string;
+    /** Number of vouchers received before teardown. */
+    voucherCount: number;
+    /** What triggered the orphan flag. */
+    reason: OrphanReason;
+}
+interface MppSessionHandlerOptions {
+    payeeSecretKey: string;
+    network: Network;
+    channelFactory: string;
+    rate: string;
+    assetContract: string;
+    manifest: RouteDockManifest;
+    commitmentPublicKey: string;
+    onSettled?: (txHash: string, totalPaid: string, mode: string, payer: string | null) => Promise<void>;
+    onSessionOpen?: (channelId: string, payer: string | null) => Promise<void>;
+    onVoucher?: (channelId: string, voucherIndex: number, cumulativeAmount: string, signature: string) => Promise<void>;
+    onCallbackError?: (err: unknown, cb: string) => void;
+    /**
+     * Called when the client connection drops mid-session or the session goes
+     * idle, before a clean close. Persist the session as `closing` so the
+     * SessionReconciler can settle it with the latest signed voucher.
+     */
+    onOrphaned?: (channelId: string, info: OrphanedSessionInfo) => Promise<void>;
+    /**
+     * Flag the session orphaned after this many milliseconds with no voucher
+     * activity. Disabled when unset.
+     */
+    idleTimeoutMs?: number;
+}
+declare function createMppSessionHandler(opts: MppSessionHandlerOptions): RequestHandler;
+
+export { type ChannelStore as C, InMemorySeenTxStore as I, type MppSessionHandlerOptions as M, type OrphanedSessionInfo as O, type SeenTxStore as S, type VoucherStoreValue as V, type SettlementRecord as a, type InMemorySeenTxStoreOptions as b, type OrphanReason as c, createMppSessionHandler as d, isVoucherStoreValue as i, paymentIdempotencyKey as p };

package/dist/ProviderRegistry-BJ9oJLVz.d.cts

@@ -0,0 +1,142 @@
+import { usdcToStroops } from '@routedock/nulth-sdk';
+import { m as SpendStore, a as DailySpend, R as RetryPolicy } from './RouteDockClient-B1roCa8h.cjs';
+import { ClientStellarSigner } from '@x402/stellar';
+import { R as RouteDockManifest, c as PaymentResult } from './types-DmhmfLzP.cjs';
+import { Keypair } from '@stellar/stellar-sdk';
+import { SupabaseClient } from '@supabase/supabase-js';
+
+/**
+ * USDC conversion — canonical implementation lives in @routedock/nulth-sdk and is
+ * re-exported here so SDK consumers (client, provider) share one converter.
+ *
+ * @routedock/routedock already depends on @routedock/nulth-sdk, so re-exporting
+ * (rather than defining a parallel helper) keeps a single source of truth.
+ */
+
+/**
+ * @deprecated Use {@link usdcToStroops} — the same validated bigint converter.
+ * Kept as a thin alias so existing call sites keep working during migration.
+ */
+declare const usdcToUnits: typeof usdcToStroops;
+
+/**
+ * File-backed durable {@link SpendStore}.
+ *
+ * Persists the daily spend accumulator to a JSON file on disk, preserving
+ * cumulative spending totals across process restarts, crashes, and redeploys.
+ *
+ * ### Error semantics
+ * - File absent (ENOENT): returns null — legitimately no spend recorded yet.
+ * - File present but unreadable or malformed: throws — a safety control must
+ *   fail closed, not assume nothing was spent.
+ *
+ * ### Write atomicity
+ * Writes go to `<filePath>.tmp` first, then `fs.rename` onto the target.
+ * `rename` is atomic within a filesystem, so there is no window where the
+ * target file is truncated but not yet fully written.
+ */
+declare class FileSpendStore implements SpendStore {
+    readonly filePath: string;
+    constructor(filePath: string);
+    read(): Promise<DailySpend | null>;
+    write(state: DailySpend): Promise<void>;
+}
+
+type Network = 'testnet' | 'mainnet';
+declare class X402Client {
+    private readonly network;
+    private readonly retryPolicy?;
+    private readonly httpClient;
+    private readonly signer;
+    constructor(secretKeyOrSigner: string | ClientStellarSigner, network: Network, retryPolicy?: RetryPolicy | undefined);
+    /** Replace signer (e.g. swap to Nulth ZK account payer before pay) */
+    withSigner(signer: ClientStellarSigner): X402Client;
+    pay(url: string, manifest: RouteDockManifest): Promise<PaymentResult>;
+}
+
+declare class MppChargeClient {
+    private readonly keypair;
+    private readonly network;
+    private readonly retryPolicy?;
+    constructor(keypair: Keypair, network: 'testnet' | 'mainnet', retryPolicy?: RetryPolicy | undefined);
+    pay(url: string, manifest: RouteDockManifest): Promise<PaymentResult>;
+}
+
+interface OnChainProviderInfo {
+    account: string;
+    endpoint: string;
+    tags: string[];
+}
+declare class OnChainRegistry {
+    private readonly horizon;
+    private readonly knownAccounts;
+    private readonly timeoutMs;
+    constructor(options: {
+        horizonUrl: string;
+        knownAccounts: string[];
+        timeoutMs?: number;
+    });
+    /**
+     * 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.
+     */
+    private loadAccountWithTimeout;
+    listProviders(): Promise<OnChainProviderInfo[]>;
+}
+
+interface ProviderRecord {
+    name: string;
+    description: string | undefined;
+    base_url: string;
+    modes: string[];
+    tags: string[];
+    network: string;
+    payee: string;
+    source: 'supabase' | 'onchain';
+    /**
+     * True only when the provider was verified out-of-band — for on-chain
+     * records the payee is the account that published the endpoint, for
+     * supabase records only rows flagged `verified` are returned.
+     */
+    verified: boolean;
+}
+interface ProviderRegistryConfig {
+    supabase?: SupabaseClient;
+    onChain: {
+        horizonUrl: string;
+        knownAccounts: string[];
+        /**
+         * Optional explicit network override. When omitted it is derived from the
+         * Horizon URL: URLs containing `testnet` map to 'testnet', everything else
+         * defaults to 'mainnet'.
+         */
+        network?: 'testnet' | 'mainnet';
+        /**
+         * Per-account timeout for on-chain account loads, in milliseconds.
+         * Defaults to 10000 ms.
+         */
+        timeoutMs?: number;
+    };
+}
+declare class ProviderRegistry {
+    private readonly supabase;
+    private readonly onChain;
+    private readonly network;
+    constructor(config: ProviderRegistryConfig);
+    listProviders(): Promise<ProviderRecord[]>;
+    private trySupabase;
+    private tryOnChain;
+    /**
+     * 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.
+     */
+    fetchProviderManifest(record: ProviderRecord): Promise<RouteDockManifest>;
+}
+
+export { FileSpendStore as F, MppChargeClient as M, type OnChainProviderInfo as O, type ProviderRecord as P, X402Client as X, OnChainRegistry as a, ProviderRegistry as b, type ProviderRegistryConfig as c, usdcToUnits as u };