@solard/sdk 0.2.33 → 0.2.40

package/src/live.ts

@@ -5,35 +5,53 @@ import {
   subscribeTrades as subscribeCoreTrades,
   type TradeEvent,
   type TradeSubscription,
-  type MigrationEvent,
-  createLiveTradeHistoryRecorder,
-  type LiveTradeHistoryOptions,
+  type MigrationEvent,
+  createLiveTradeHistoryRecorder,
+  type LiveTradeHistoryOptions,
 } from "@solard/core";
 
 export type LiveEndpointOptions = {
   /** Ordered endpoints on the same cluster; public RPC can be supplied last. */
   rpcUrls?: readonly string[];
+  websocketUrls?: readonly string[];
   /** Fresh HTTP and WebSocket readiness probes for pooled trade streams (default 30s). */
   healthCheckIntervalMs?: number;
 };
 export type SubscribeLaunchesOptions = Omit<
   Parameters<typeof subscribeCoreLaunches>[0],
   "connection"
-> & LiveEndpointOptions;
+> &
+  LiveEndpointOptions;
 export type SubscribeMigrationsOptions = Omit<
   Parameters<typeof subscribeCoreMigrations>[0],
   "connection"
-> & LiveEndpointOptions;
+> &
+  LiveEndpointOptions;
+/** Applications must explicitly revalidate fresh on-chain pool/mint state.
+ * Returning true asserts current state only, not historical coverage. */
+export type FeedRecoveryVerification = (input: {
+  connection: Connection; tokens: readonly string[]; signal: AbortSignal;
+}) => Promise<boolean>;
+export type RecoverableTradeSubscription = TradeSubscription & {
+  readonly feedVerified: boolean;
+  verifyAndResume(verify: FeedRecoveryVerification, timeoutMs?: number): Promise<boolean>;
+};
 export type SubscribeTradesOptions = Omit<
   Parameters<typeof subscribeCoreTrades>[0],
   "connection"
-> & LiveEndpointOptions;
+> &
+  LiveEndpointOptions;
 
-export type ListenTradesOptions = Omit<SubscribeTradesOptions, "onTrade"> & {
-  dbPath?: string;
-  /** Enabled by default; collected live history is partial and retains commitment. */
-  history?: false | Pick<LiveTradeHistoryOptions, "flushIntervalMs" | "batchSize" | "maxPending">;
-};
+export type ListenTradesOptions = Omit<SubscribeTradesOptions, "onTrade"> & {
+  dbPath?: string;
+  /** Enabled by default; collected live history is partial and retains commitment. */
+  history?:
+    | false
+    | Pick<
+        LiveTradeHistoryOptions,
+        "flushIntervalMs" | "batchSize" | "maxPending"
+      >;
+};
 
 export type TradeListener = {
   add(tokens: string | readonly string[]): Promise<void>;
@@ -41,11 +59,18 @@ export type TradeListener = {
   has(token: string): boolean;
   list(): string[];
   onTrade(callback: (event: TradeEvent) => void | Promise<void>): () => void;
-  onMigration(callback: (event: TradeListenerMigration) => void | Promise<void>): () => void;
+  onMigration(
+    callback: (event: TradeListenerMigration) => void | Promise<void>,
+  ): () => void;
   close(): Promise<void>;
   readonly closed: Promise<void>;
+  readonly feedVerified: boolean;
+  verifyAndResume(verify: FeedRecoveryVerification, timeoutMs?: number): Promise<boolean>;
+};
+export type TradeListenerMigration = MigrationEvent & {
+  oldPool: string | null;
+  newPool: string;
 };
-export type TradeListenerMigration = MigrationEvent & { oldPool: string | null; newPool: string };
 
 type LiveConnection = {
   endpoint: string;
@@ -60,39 +85,77 @@ let readiness: { endpoint: string; promise: Promise<void> } | null = null;
 export class LiveEndpointPool {
   private active = 0;
   readonly endpoints: readonly string[];
-  constructor(endpoints: readonly string[], private readonly probe: (endpoint: string) => Promise<void> = async (endpoint) => {
-    await Promise.all([preflightRpc(endpoint), preflightWebSocket(endpoint)]);
-  }) {
+  constructor(
+    endpoints: readonly string[],
+    private readonly probe: (endpoint: string) => Promise<void> = async (
+      endpoint,
+    ) => {
+      await Promise.all([preflightRpc(endpoint), preflightWebSocket(endpoint)]);
+    },
+  ) {
     this.endpoints = [...new Set(endpoints)];
-    if (!this.endpoints.length) throw new Error("Live RPC endpoint pool cannot be empty");
+    if (!this.endpoints.length)
+      throw new Error("Live RPC endpoint pool cannot be empty");
     for (const endpoint of this.endpoints) deriveWebSocketEndpoint(endpoint);
   }
-  get endpoint(): string { return this.endpoints[this.active]!; }
+  get endpoint(): string {
+    return this.endpoints[this.active]!;
+  }
   async select(skipCurrent = false): Promise<string> {
     const start = this.active;
     let lastError: unknown;
-    for (let offset = skipCurrent ? 1 : 0; offset < this.endpoints.length + (skipCurrent ? 1 : 0); offset++) {
+    for (
+      let offset = skipCurrent ? 1 : 0;
+      offset < this.endpoints.length + (skipCurrent ? 1 : 0);
+      offset++
+    ) {
       const index = (start + offset) % this.endpoints.length;
-      try { await this.probe(this.endpoints[index]!); this.active = index; return this.endpoint; }
-      catch (error) { lastError = error; }
+      try {
+        await this.probe(this.endpoints[index]!);
+        this.active = index;
+        return this.endpoint;
+      } catch (error) {
+        lastError = error;
+      }
     }
     throw lastError;
   }
   async check(): Promise<string> {
-    try { await this.probe(this.endpoint); return this.endpoint; }
-    catch { return await this.select(true); }
+    try {
+      await this.probe(this.endpoint);
+      return this.endpoint;
+    } catch {
+      return await this.select(true);
+    }
   }
 }
 const livePools = new Map<string, LiveEndpointPool>();
-function endpointPool(options: LiveEndpointOptions): LiveEndpointPool | undefined {
-  if (!options.rpcUrls?.length) return undefined;
-  const key = JSON.stringify(options.rpcUrls);
+function endpointPool(
+  options: LiveEndpointOptions,
+): LiveEndpointPool | undefined {
+  const env = process.env.SLRD_RPC_URLS;
+  const urls = options.rpcUrls ?? (env ? JSON.parse(env) as string[] :
+    wsCandidates(options).length ? [endpointFromEnv()] : []);
+  if (!urls.length) return undefined;
+  const key = JSON.stringify([urls, options.websocketUrls ?? process.env.SLRD_WS_URLS]);
   let pool = livePools.get(key);
-  if (!pool) { pool = new LiveEndpointPool(options.rpcUrls); livePools.set(key, pool); }
+  if (!pool) {
+    pool = new LiveEndpointPool(urls, wsCandidates(options).length ? preflightRpc : undefined);
+    livePools.set(key, pool);
+  }
   return pool;
 }
-function connectionFor(endpoint: string): LiveConnection {
-  return { endpoint, websocketEndpoint: deriveWebSocketEndpoint(endpoint), connection: new Connection(endpoint, "confirmed") };
+function wsCandidates(options: LiveEndpointOptions): string[] {
+  const fallback = process.env.SLRD_WS_URLS ? JSON.parse(process.env.SLRD_WS_URLS) as unknown : [];
+  const urls = options.websocketUrls ?? fallback;
+  if (!Array.isArray(urls) || !urls.every(value => typeof value === "string" && /^wss?:\/\//.test(value)))
+    throw new Error("Invalid WebSocket endpoint list");
+  return [...new Set(urls)] as string[];
+}
+function connectionFor(endpoint: string, ws = deriveWebSocketEndpoint(endpoint)): LiveConnection {
+  return { endpoint, websocketEndpoint: ws,
+    connection: new Connection(endpoint, { commitment: "confirmed", wsEndpoint: ws,
+      disableRetryOnRateLimit: true }) };
 }
 
 function endpointFromEnv(): string {
@@ -121,21 +184,8 @@ export function deriveWebSocketEndpoint(endpoint: string): string {
 }
 
 export function redactRpcEndpoint(endpoint: string): string {
-  try {
-    const url = new URL(endpoint);
-    const keys: string[] = [];
-    url.searchParams.forEach((_value, key) => keys.push(key));
-    for (const key of keys) {
-      if (/key|token|secret|auth/i.test(key))
-        url.searchParams.set(key, "<redacted>");
-    }
-    return url.toString().replaceAll("%3Credacted%3E", "<redacted>");
-  } catch {
-    return endpoint.replace(
-      /([?&](?:api-?key|api_key|apikey|key|token|secret|auth)=)[^&]+/gi,
-      "$1<redacted>",
-    );
-  }
+  try { const url = new URL(endpoint); return `${url.protocol}//${url.host}/***`; }
+  catch { return "<invalid RPC endpoint>"; }
 }
 
 function providerName(endpoint: string): string {
@@ -150,12 +200,7 @@ function providerName(endpoint: string): string {
 
 function safeMessage(error: unknown): string {
   const value = error instanceof Error ? error.message : String(error);
-  return value
-    .replace(
-      /([?&](?:api-?key|api_key|apikey|key|token|secret|auth)=)[^&\s]+/gi,
-      "$1<redacted>",
-    )
-    .slice(0, 400);
+  return value.replace(/(?:https?|wss?):\/\/[^\s]+/gi, redactRpcEndpoint).slice(0,400);
 }
 
 function rpcFailure(endpoint: string, detail: string): Error {
@@ -177,7 +222,7 @@ async function preflightRpc(endpoint: string): Promise<void> {
     const response = await fetch(endpoint, {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "getHealth" }),
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "getGenesisHash" }),
       signal: controller.signal,
     });
     if (!response.ok) {
@@ -203,6 +248,16 @@ async function preflightRpc(endpoint: string): Promise<void> {
         `${code}${String(body.error.message ?? "RPC error")}`,
       );
     }
+    if (body.result !== "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d")
+      throw rpcFailure(endpoint, "Non-mainnet genesis hash");
+    const account = await fetch(endpoint, { method: "POST", signal: controller.signal,
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 2, method: "getBalance",
+        params: ["11111111111111111111111111111111"] }) });
+    if (!account.ok) throw rpcFailure(endpoint, `Balance HTTP ${account.status}`);
+    const balance = await account.json() as { error?: unknown; result?: { context?: {slot?:number}; value?:number } };
+    if (balance.error || !Number.isFinite(balance.result?.context?.slot) || !Number.isFinite(balance.result?.value))
+      throw rpcFailure(endpoint, "Balance reads unavailable");
   } catch (error) {
     if (
       error instanceof Error &&
@@ -218,7 +273,7 @@ async function preflightRpc(endpoint: string): Promise<void> {
 }
 
 async function preflightWebSocket(endpoint: string): Promise<void> {
-  const websocketEndpoint = deriveWebSocketEndpoint(endpoint);
+  const websocketEndpoint = /^wss?:\/\//.test(endpoint) ? endpoint : deriveWebSocketEndpoint(endpoint);
   await new Promise<void>((resolve, reject) => {
     let settled = false;
     let socket: WebSocket | null = null;
@@ -245,16 +300,21 @@ async function preflightWebSocket(endpoint: string): Promise<void> {
       finish(websocketFailure(endpoint, safeMessage(error)));
       return;
     }
-    socket.addEventListener(
-      "open",
-      () => {
-        finish();
-        try {
-          socket?.close(1000);
-        } catch {}
-      },
-      { once: true },
-    );
+    socket.addEventListener("open", () => {
+      try { socket?.send(JSON.stringify({ jsonrpc: "2.0", id: 71, method: "slotSubscribe" })); }
+      catch { finish(websocketFailure(endpoint, "Subscription send failed")); }
+    }, { once: true });
+    socket.addEventListener("message", event => {
+      try { const packet = JSON.parse(String(event.data)) as { id?: number; result?: number; error?: unknown };
+        if (packet.id !== 71) return;
+        if (packet.error || !Number.isSafeInteger(packet.result)) {
+          finish(websocketFailure(endpoint, "Subscription was rejected")); return;
+        }
+        try { socket?.send(JSON.stringify({ jsonrpc: "2.0", id: 72,
+          method: "slotUnsubscribe", params: [packet.result] })); } catch {}
+        finish(); try { socket?.close(1000); } catch {}
+      } catch { finish(websocketFailure(endpoint, "Malformed subscription reply")); }
+    });
     socket.addEventListener(
       "error",
       (event) => {
@@ -295,17 +355,25 @@ async function ensureReady(endpoint: string): Promise<void> {
   }
 }
 
-async function liveConnection(options: LiveEndpointOptions = {}): Promise<LiveConnection> {
+async function liveConnection(
+  options: LiveEndpointOptions = {},
+): Promise<LiveConnection> {
   const pool = endpointPool(options);
-  if (pool) return connectionFor(await pool.select());
-  const endpoint = endpointFromEnv();
+  const endpoint = pool ? await pool.select() : endpointFromEnv();
+  const independent = wsCandidates(options);
+  if (independent.length) {
+    await preflightRpc(endpoint);
+    let last: unknown;
+    for (const ws of independent) {
+      try { await preflightWebSocket(ws); return connectionFor(endpoint, ws); }
+      catch (error) { last = error; }
+    }
+    throw last ?? new Error("No usable WSS endpoint");
+  }
+  if (pool) return connectionFor(endpoint);
   await ensureReady(endpoint);
   if (shared?.endpoint === endpoint) return shared;
-  shared = {
-    endpoint,
-    websocketEndpoint: deriveWebSocketEndpoint(endpoint),
-    connection: new Connection(endpoint, "confirmed"),
-  };
+  shared = connectionFor(endpoint);
   return shared;
 }
 
@@ -323,30 +391,56 @@ function notifyReady(
   } catch {}
 }
 
-export async function subscribeTrades(options: SubscribeTradesOptions) {
+export async function subscribeTrades(options: SubscribeTradesOptions): Promise<RecoverableTradeSubscription> {
+  if (options.signal?.aborted) throw new DOMException("Trade subscription cancelled", "AbortError");
   let live = await liveConnection(options);
   notifyReady(options, live);
-  const pool = endpointPool(options);
-  if (!pool) return await subscribeCoreTrades({ ...options, connection: live.connection });
+  const pool = endpointPool(options) ?? new LiveEndpointPool([live.endpoint]);
   // Keep duplicate suppression across connection changes. Provider probes detect
   // dead credentials/quota; they cannot diagnose a silent old socket when a new
   // handshake to that provider remains healthy.
   const seen = new Set<string>();
+  let gapUnverified = false;
+  let lastAcceptedAt = Date.now();
+  let generation = 0;
+  const recoveries = new Set<AbortController>();
+  const invalidate = () => { gapUnverified = true; generation++; };
   const onTrade = async (event: TradeEvent) => {
-    const key = [event.signature, event.venue, event.mint, event.pool, event.eventIndex ?? `${event.side}:${event.baseRaw}:${event.quoteRaw}`].join(":");
+    if (!gapUnverified && Date.now() - lastAcceptedAt >= 60_000) invalidate();
+    if (gapUnverified || !Number.isFinite(event.atMs) || Date.now() - event.atMs > 30_000 || event.atMs > Date.now() + 10_000) {
+      try { options.onStatus?.("feed-stale", { reason: gapUnverified ? "gap-unverified" : "event-outside-live-window" }); } catch {}
+      return;
+    }
+    const key = [
+      event.signature,
+      event.venue,
+      event.mint,
+      event.pool,
+      event.eventIndex ?? `${event.side}:${event.baseRaw}:${event.quoteRaw}`,
+    ].join(":");
     if (seen.has(key)) return;
     seen.add(key);
     if (seen.size > 4096) seen.delete(seen.values().next().value!);
+    lastAcceptedAt = Date.now();
     await options.onTrade(event);
   };
-  let subscription = await subscribeCoreTrades({ ...options, signal: undefined, onTrade, connection: live.connection });
+  let subscription = await subscribeCoreTrades({
+    ...options,
+    signal: undefined,
+    onTrade,
+    connection: live.connection,
+  });
   let stopped = false;
   let tail: Promise<unknown> = Promise.resolve();
   const serial = <T>(work: () => Promise<T>): Promise<T> => {
-    const pending = tail.then(work, work); tail = pending.catch(() => undefined); return pending;
+    const pending = tail.then(work, work);
+    tail = pending.catch(() => undefined);
+    return pending;
   };
   let settle!: () => void;
-  const closed = new Promise<void>((resolve) => { settle = resolve; });
+  const closed = new Promise<void>((resolve) => {
+    settle = resolve;
+  });
   const requestedInterval = options.healthCheckIntervalMs ?? 30_000;
   if (!Number.isFinite(requestedInterval) || requestedInterval < 1000) {
     await subscription.close();
@@ -358,39 +452,136 @@ export async function subscribeTrades(options: SubscribeTradesOptions) {
     checking = true;
     void serial(async () => {
       if (stopped) return;
+      if (!gapUnverified && Date.now() - lastAcceptedAt >= 60_000) {
+        invalidate();
+        try { options.onStatus?.("feed-gap-unverified", {
+          reason: "no-recent-accepted-trades", historyComplete: false,
+        }); } catch {}
+      }
       try {
         const endpoint = await pool.check();
-        if (stopped || endpoint === live.endpoint) return;
+        const independent = wsCandidates(options);
+        let ws = independent.length ? live.websocketEndpoint : deriveWebSocketEndpoint(endpoint);
+        if (independent.length) {
+          try { await preflightWebSocket(ws); }
+          catch {
+            const candidates = independent.filter(candidate => candidate !== ws);
+            let found = false;
+            for (const candidate of candidates) {
+              try { await preflightWebSocket(candidate); ws = candidate; found = true; break; }
+              catch {}
+            }
+            if (!found) throw new Error("All independent WebSocket endpoints are unavailable");
+          }
+        }
+        if (stopped || (endpoint === live.endpoint && ws === live.websocketEndpoint)) return;
+        invalidate();
+        try { options.onStatus?.("feed-gap-unverified", { endpoint: redactRpcEndpoint(endpoint),
+          websocket: redactRpcEndpoint(ws) }); } catch {}
         const tokens = subscription.listTokens();
-        const nextLive = connectionFor(endpoint);
-        const next = await subscribeCoreTrades({ ...options, signal: undefined, tokens, onTrade, connection: nextLive.connection });
+        const nextLive = connectionFor(endpoint, ws);
+        const next = await subscribeCoreTrades({
+          ...options,
+          signal: undefined,
+          tokens,
+          onTrade,
+          connection: nextLive.connection,
+        });
         await subscription.close();
         subscription = next;
         live = nextLive;
         notifyReady(options, live);
-      } catch (error) {
-        try { options.onStatus?.("rpc-unavailable", { error: safeMessage(error) }); } catch {}
+      } catch (error) {
+        invalidate();
+        try {
+          options.onStatus?.("feed-gap-unverified", { reason: "provider-readiness-failed", historyComplete: false });
+          options.onStatus?.("rpc-unavailable", { error: safeMessage(error) });
+        } catch {}
       }
-    }).finally(() => { checking = false; });
+    }).finally(() => {
+      checking = false;
+    });
   }, Math.trunc(requestedInterval));
   timer.unref?.();
   const close = async () => {
     if (stopped) return await closed;
     stopped = true;
+    invalidate();
+    for (const controller of recoveries) controller.abort();
     clearInterval(timer);
     options.signal?.removeEventListener("abort", abort);
-    await serial(async () => { await subscription.close(); settle(); });
+    await serial(async () => {
+      await subscription.close();
+      settle();
+    });
+  };
+  const abort = () => {
+    void close();
   };
-  const abort = () => { void close(); };
   if (options.signal?.aborted) await close();
   else options.signal?.addEventListener("abort", abort, { once: true });
   return {
-    addTokens: (tokens: string | readonly string[]) => serial(async () => { if (stopped) throw new Error("Trade subscription is closed"); await subscription.addTokens(tokens); }),
-    removeTokens: (tokens: string | readonly string[]) => serial(async () => { if (!stopped) await subscription.removeTokens(tokens); }),
+    addTokens: (tokens: string | readonly string[]) => {
+      const values = typeof tokens === "string" ? [tokens] : tokens;
+      if (values.some(token => !subscription.hasToken(token))) invalidate();
+      return serial(async () => {
+        if (stopped) throw new Error("Trade subscription is closed");
+        await subscription.addTokens(tokens);
+      });
+    },
+    removeTokens: (tokens: string | readonly string[]) => {
+      const values = typeof tokens === "string" ? [tokens] : tokens;
+      if (values.some(token => subscription.hasToken(token))) invalidate();
+      return serial(async () => {
+        if (!stopped) await subscription.removeTokens(tokens);
+      });
+    },
     hasToken: (token: string) => !stopped && subscription.hasToken(token),
-    listTokens: () => stopped ? [] : subscription.listTokens(),
-    close, closed,
-  } satisfies TradeSubscription;
+    listTokens: () => (stopped ? [] : subscription.listTokens()),
+    get feedVerified() { return !stopped && !gapUnverified &&
+      Date.now() - lastAcceptedAt < 60_000; },
+    verifyAndResume: (verify: FeedRecoveryVerification, timeoutMs = 5000) => {
+      if (stopped) return Promise.reject(new Error("Trade subscription is closed"));
+      if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30_000)
+        return Promise.reject(new Error("Recovery timeout must be 1..30000ms"));
+      // The deadline includes time queued behind health checks or token edits.
+      invalidate();
+      const expected = generation;
+      const controller = new AbortController();
+      recoveries.add(controller);
+      const timeout = setTimeout(() => controller.abort(), timeoutMs);
+      const onAbort = () => controller.abort();
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+      if (options.signal?.aborted) controller.abort();
+      let rejectAbort!: () => void;
+      const cancelled = new Promise<never>((_, reject) => {
+        rejectAbort = () => reject(new Error("Feed verification cancelled or timed out"));
+        controller.signal.addEventListener("abort", rejectAbort, { once: true });
+        if (controller.signal.aborted) rejectAbort();
+      });
+      const pending = serial(async () => {
+        if (controller.signal.aborted) throw new Error("Feed verification cancelled or timed out");
+        if (stopped) throw new Error("Trade subscription is closed");
+        if (generation !== expected) return false;
+        const verified = await Promise.race([
+          Promise.resolve().then(() => verify({ connection: live.connection,
+            tokens: subscription.listTokens(), signal: controller.signal })), cancelled,
+        ]);
+        if (verified !== true || stopped || generation !== expected || controller.signal.aborted) return false;
+        gapUnverified = false;
+        lastAcceptedAt = Date.now();
+        try { options.onStatus?.("feed-fresh-state-verified", { historyComplete: false }); } catch {}
+        return true;
+      });
+      return Promise.race([pending, cancelled]).finally(() => {
+        clearTimeout(timeout); recoveries.delete(controller);
+        controller.signal.removeEventListener("abort", rejectAbort);
+        options.signal?.removeEventListener("abort", onAbort);
+      });
+    },
+    close,
+    closed,
+  } satisfies RecoverableTradeSubscription;
 }
 
 export async function subscribeLaunches(options: SubscribeLaunchesOptions) {
@@ -413,25 +604,46 @@ export async function subscribeMigrations(options: SubscribeMigrationsOptions) {
 export async function listenTrades(
   options: ListenTradesOptions,
 ): Promise<TradeListener> {
-  const callbacks = new Set<(event: TradeEvent) => void | Promise<void>>();
-  const history = options.history === false ? undefined : createLiveTradeHistoryRecorder({ ...options.history, dbPath: options.dbPath, commitment: options.commitment, onStatus: options.onStatus });
+  const callbacks = new Set<(event: TradeEvent) => void | Promise<void>>();
+  const history =
+    options.history === false
+      ? undefined
+      : createLiveTradeHistoryRecorder({
+          ...options.history,
+          dbPath: options.dbPath,
+          commitment: options.commitment,
+          onStatus: options.onStatus,
+        });
   const pending: TradeEvent[] = [];
-  const migrationCallbacks = new Set<(event: TradeListenerMigration) => void | Promise<void>>();
+  const migrationCallbacks = new Set<
+    (event: TradeListenerMigration) => void | Promise<void>
+  >();
   const pendingMigrations: TradeListenerMigration[] = [];
   const watched = new Set(options.tokens);
   const lastPools = new Map<string, string | null>();
-  let subscription: TradeSubscription;
-  let migrations: Awaited<ReturnType<typeof subscribeMigrations>> | undefined;
-  let stopped = false;
-  let resolveClosed!: () => void;
-  let rejectClosed!: (error: unknown) => void;
-  const closed = new Promise<void>((resolve, reject) => { resolveClosed = resolve; rejectClosed = reject; });
-  void closed.catch(() => undefined);
+  let subscription: RecoverableTradeSubscription;
+  let migrations: Awaited<ReturnType<typeof subscribeMigrations>> | undefined;
+  let stopped = false;
+  let resolveClosed!: () => void;
+  let rejectClosed!: (error: unknown) => void;
+  const closed = new Promise<void>((resolve, reject) => {
+    resolveClosed = resolve;
+    rejectClosed = reject;
+  });
+  void closed.catch(() => undefined);
   let tail: Promise<unknown> = Promise.resolve();
-  const serial = <T>(work: () => Promise<T>): Promise<T> => { const job = tail.then(work, work); tail = job.catch(() => undefined); return job; };
+  const serial = <T>(work: () => Promise<T>): Promise<T> => {
+    const job = tail.then(work, work);
+    tail = job.catch(() => undefined);
+    return job;
+  };
   const onMigration = async (event: MigrationEvent) => {
     if (stopped || !watched.has(event.mint)) return;
-    const migration = { ...event, oldPool: lastPools.get(event.mint) ?? null, newPool: event.pool };
+    const migration = {
+      ...event,
+      oldPool: lastPools.get(event.mint) ?? null,
+      newPool: event.pool,
+    };
     lastPools.set(event.mint, event.pool);
     await serial(async () => {
       if (stopped || !watched.has(event.mint)) return;
@@ -440,14 +652,24 @@ export async function listenTrades(
       await subscription.removeTokens(event.mint);
       await subscription.addTokens(event.mint);
     });
-    if (!migrationCallbacks.size) { pendingMigrations.push(migration); if (pendingMigrations.length > 1000) pendingMigrations.shift(); }
-    else await Promise.all([...migrationCallbacks].map(callback => callback(migration)));
+    if (!migrationCallbacks.size) {
+      pendingMigrations.push(migration);
+      if (pendingMigrations.length > 1000) pendingMigrations.shift();
+    } else
+      await Promise.all(
+        [...migrationCallbacks].map((callback) => callback(migration)),
+      );
   };
-  const dispatch = async (event: TradeEvent) => {
-    if (!watched.has(event.mint) || stopped) return;
-    lastPools.set(event.mint, event.pool);
-    try { await history?.record(event); }
-    catch (error) { options.onStatus?.("history-persistence-error", { error: safeMessage(error) }); }
+  const dispatch = async (event: TradeEvent) => {
+    if (!watched.has(event.mint) || stopped) return;
+    lastPools.set(event.mint, event.pool);
+    try {
+      await history?.record(event);
+    } catch (error) {
+      options.onStatus?.("history-persistence-error", {
+        error: safeMessage(error),
+      });
+    }
     if (callbacks.size === 0) {
       pending.push(event);
       if (pending.length > 1_000) pending.shift();
@@ -461,32 +683,99 @@ export async function listenTrades(
   };
   const onStatus = (event: string, data?: Record<string, unknown>) => {
     options.onStatus?.(event, data);
-    if (event === "rpc-ready" && migrations && !stopped) void serial(async () => {
-      if (stopped) return;
-      const next = await subscribeMigrations({ rpcUrls: options.rpcUrls, tokens: [...watched], commitment: options.commitment, metadata: options.metadata, onMigration, onStatus: options.onStatus });
-      await migrations?.close(); migrations = next;
-    }).catch(error => options.onStatus?.("migration-resubscribe-error", { error: safeMessage(error) }));
+    if (event === "feed-gap-unverified" || event === "feed-stale") pending.length = 0;
+    if (event === "rpc-ready" && migrations && !stopped)
+      void serial(async () => {
+        if (stopped) return;
+        const next = await subscribeMigrations({
+          rpcUrls: options.rpcUrls,
+          websocketUrls: options.websocketUrls,
+          tokens: [...watched],
+          commitment: options.commitment,
+          metadata: options.metadata,
+          onMigration,
+          onStatus: options.onStatus,
+        });
+        await migrations?.close();
+        migrations = next;
+      }).catch((error) =>
+        options.onStatus?.("migration-resubscribe-error", {
+          error: safeMessage(error),
+        }),
+      );
+  };
+  try {
+    subscription = await subscribeTrades({
+      ...options,
+      signal: undefined,
+      onStatus,
+      onTrade: dispatch,
+    });
+  } catch (error) {
+    await history?.close();
+    throw error;
+  }
+  try {
+    migrations = await subscribeMigrations({
+      rpcUrls: options.rpcUrls,
+      websocketUrls: options.websocketUrls,
+      tokens: [...watched],
+      commitment: options.commitment,
+      metadata: options.metadata,
+      onMigration,
+      onStatus: options.onStatus,
+    });
+  } catch (error) {
+    await subscription.close();
+    await history?.close();
+    throw error;
+  }
+  const close = async () => {
+    if (stopped) return await closed;
+    stopped = true;
+    options.signal?.removeEventListener("abort", abort);
+    try {
+      await serial(async () => {
+        await Promise.all([subscription.close(), migrations?.close()]);
+        watched.clear();
+        await history?.close();
+      });
+      resolveClosed();
+    } catch (error) {
+      rejectClosed(error);
+      throw error;
+    }
   };
-  try { subscription = await subscribeTrades({ ...options, signal: undefined, onStatus, onTrade: dispatch }); }
-  catch (error) { await history?.close(); throw error; }
-  try { migrations = await subscribeMigrations({ rpcUrls: options.rpcUrls, tokens: [...watched], commitment: options.commitment, metadata: options.metadata, onMigration, onStatus: options.onStatus }); }
-  catch (error) { await subscription.close(); await history?.close(); throw error; }
-  const close = async () => {
-    if (stopped) return await closed;
-    stopped = true; options.signal?.removeEventListener("abort", abort);
-    try {
-      await serial(async () => { await Promise.all([subscription.close(), migrations?.close()]); watched.clear(); await history?.close(); });
-      resolveClosed();
-    } catch (error) { rejectClosed(error); throw error; }
+  const abort = () => {
+    void close();
   };
-  const abort = () => { void close(); };
   if (options.signal?.aborted) await close();
   else options.signal?.addEventListener("abort", abort, { once: true });
   return {
-    add: (tokens) => serial(async () => { if (stopped) throw new Error("Trade listener is closed"); const values = typeof tokens === "string" ? [tokens] : [...tokens]; await subscription.addTokens(values); await migrations!.addTokens(values); values.forEach(token => watched.add(token)); }),
-    remove: (tokens) => serial(async () => { const values = typeof tokens === "string" ? [tokens] : [...tokens]; values.forEach(token => { watched.delete(token); lastPools.delete(token); }); await Promise.all([subscription.removeTokens(values), migrations!.removeTokens(values)]); }),
+    add: (tokens) =>
+      serial(async () => {
+        if (stopped) throw new Error("Trade listener is closed");
+        const values = typeof tokens === "string" ? [tokens] : [...tokens];
+        await subscription.addTokens(values);
+        await migrations!.addTokens(values);
+        values.forEach((token) => watched.add(token));
+      }),
+    remove: (tokens) =>
+      serial(async () => {
+        const values = typeof tokens === "string" ? [tokens] : [...tokens];
+        values.forEach((token) => {
+          watched.delete(token);
+          lastPools.delete(token);
+        });
+        await Promise.all([
+          subscription.removeTokens(values),
+          migrations!.removeTokens(values),
+        ]);
+      }),
+    get feedVerified() { return !stopped && subscription.feedVerified === true; },
+    verifyAndResume: (verify, timeoutMs) => subscription.verifyAndResume(verify, timeoutMs),
     has: (token) => !stopped && watched.has(token),
-    list: () => stopped ? [] : [...watched],
+    list: () => (stopped ? [] : [...watched]),
     onTrade(callback) {
       callbacks.add(callback);
       if (pending.length) {
@@ -499,12 +788,17 @@ export async function listenTrades(
     },
     onMigration(callback) {
       migrationCallbacks.add(callback);
-      if (pendingMigrations.length) { const rows = pendingMigrations.splice(0); void Promise.resolve().then(async () => { for (const event of rows) await callback(event); }); }
+      if (pendingMigrations.length) {
+        const rows = pendingMigrations.splice(0);
+        void Promise.resolve().then(async () => {
+          for (const event of rows) await callback(event);
+        });
+      }
       return () => migrationCallbacks.delete(callback);
     },
-    close,
-    get closed() {
-      return closed;
+    close,
+    get closed() {
+      return closed;
     },
   };
 }