@solard/sdk 0.2.37 → 0.2.40

package/src/live.ts

@@ -13,6 +13,7 @@ import {
 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;
 };
@@ -26,6 +27,15 @@ export type SubscribeMigrationsOptions = Omit<
   "connection"
 > &
   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"
@@ -54,6 +64,8 @@ export type TradeListener = {
   ): () => 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;
@@ -121,21 +133,29 @@ const livePools = new Map<string, LiveEndpointPool>();
 function endpointPool(
   options: LiveEndpointOptions,
 ): LiveEndpointPool | undefined {
-  if (!options.rpcUrls?.length) return undefined;
-  const key = JSON.stringify(options.rpcUrls);
+  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);
+    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 {
@@ -164,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 {
@@ -193,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 {
@@ -220,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) {
@@ -246,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 &&
@@ -261,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;
@@ -288,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) => {
@@ -342,15 +359,21 @@ 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;
 }
 
@@ -368,20 +391,26 @@ 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) => {
+    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,
@@ -392,6 +421,7 @@ export async function subscribeTrades(options: SubscribeTradesOptions) {
     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({
@@ -422,11 +452,34 @@ 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 nextLive = connectionFor(endpoint, ws);
         const next = await subscribeCoreTrades({
           ...options,
           signal: undefined,
@@ -438,9 +491,11 @@ export async function subscribeTrades(options: SubscribeTradesOptions) {
         subscription = next;
         live = nextLive;
         notifyReady(options, live);
-      } catch (error) {
-        try {
-          options.onStatus?.("rpc-unavailable", { error: safeMessage(error) });
+      } catch (error) {
+        invalidate();
+        try {
+          options.onStatus?.("feed-gap-unverified", { reason: "provider-readiness-failed", historyComplete: false });
+          options.onStatus?.("rpc-unavailable", { error: safeMessage(error) });
         } catch {}
       }
     }).finally(() => {
@@ -451,6 +506,8 @@ export async function subscribeTrades(options: SubscribeTradesOptions) {
   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 () => {
@@ -464,20 +521,67 @@ export async function subscribeTrades(options: SubscribeTradesOptions) {
   if (options.signal?.aborted) await close();
   else options.signal?.addEventListener("abort", abort, { once: true });
   return {
-    addTokens: (tokens: string | readonly string[]) =>
-      serial(async () => {
+    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[]) =>
-      serial(async () => {
+      });
+    },
+    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()),
+    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 TradeSubscription;
+  } satisfies RecoverableTradeSubscription;
 }
 
 export async function subscribeLaunches(options: SubscribeLaunchesOptions) {
@@ -517,7 +621,7 @@ export async function listenTrades(
   const pendingMigrations: TradeListenerMigration[] = [];
   const watched = new Set(options.tokens);
   const lastPools = new Map<string, string | null>();
-  let subscription: TradeSubscription;
+  let subscription: RecoverableTradeSubscription;
   let migrations: Awaited<ReturnType<typeof subscribeMigrations>> | undefined;
   let stopped = false;
   let resolveClosed!: () => void;
@@ -579,11 +683,13 @@ export async function listenTrades(
   };
   const onStatus = (event: string, data?: Record<string, unknown>) => {
     options.onStatus?.(event, data);
+    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,
@@ -612,6 +718,7 @@ export async function listenTrades(
   try {
     migrations = await subscribeMigrations({
       rpcUrls: options.rpcUrls,
+      websocketUrls: options.websocketUrls,
       tokens: [...watched],
       commitment: options.commitment,
       metadata: options.metadata,
@@ -665,6 +772,8 @@ export async function listenTrades(
           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]),
     onTrade(callback) {