@effectstream/sync 0.101.1 → 0.102.0

package/src/sync-protocols/base/state.ts

@@ -69,11 +69,62 @@ export abstract class SyncState<
   public lastPage: undefined | LastPage<Page, RootPage>;
   /** Timestamp of the last successful fetch (readData completed without error). */
   public lastSuccessfulFetchMs: number = 0;
+  /**
+   * Wall-clock time of the last completed pass through the fetch loop, whatever
+   * its outcome (fetched, caught up, or errored).
+   *
+   * This — not `lastSuccessfulFetchMs` — is the hang detector. A chain that is
+   * caught up never calls `readData`, so its last-successful-fetch time is
+   * indistinguishable from that of a chain wedged inside a request that will
+   * never return. The loop still cycles in the first case and does not in the
+   * second, so a heartbeat that is stale by many polling intervals means the
+   * loop is stuck in `stateToInput`/`readData`.
+   */
+  public lastPollAtMs: number = 0;
   /** Number of consecutive errors since the last successful fetch. */
   public consecutiveErrors: number = 0;
   /** Timestamp of the most recent error, or 0 if no error has occurred. */
   public lastErrorTimestamp: number = 0;
 
+  // ── Streaming producer (see startAsync + orchestration/sync.ts) ──
+  /**
+   * Whether {@link SyncState#startAsync} runs a long-lived producer that this
+   * protocol depends on for its data (a subscription/stream), as opposed to the
+   * base-class no-op used by polled chains.
+   *
+   * `startSync` supervises and restarts the producer only when this is true.
+   * A polled chain must leave it false, or its no-op `startAsync` would be
+   * "restarted" forever.
+   */
+  public readonly hasAsyncProducer: boolean = false;
+  /**
+   * How many times the streaming producer has been restarted after dying —
+   * either by throwing or by returning (a producer that returns has ended its
+   * stream). Surfaced on `/health`; a climbing count means a flapping upstream.
+   */
+  public producerRestarts: number = 0;
+  /**
+   * Producer failures, tracked separately from {@link consecutiveErrors}.
+   *
+   * That counter belongs to the fetch loop and is only cleared by a successful
+   * `readData`, so sharing it conflated two independent signals: an idle
+   * streaming chain would report `erroring` long after its producer recovered,
+   * and a successful poll would erase the record of a flapping producer.
+   */
+  public producerErrors: number = 0;
+  /** Wall-clock time of the last producer failure, or 0 if none. */
+  public lastProducerErrorMs: number = 0;
+
+  /**
+   * Resolved polling interval for this protocol, stamped by `startSync`.
+   *
+   * Single source of truth: `/health` derives its wedged threshold from this
+   * rather than reaching back into `fetcher.config.syncProtocol`, which it can
+   * only do through an unchecked cast that would fail silently to a default if
+   * the config shape ever moved.
+   */
+  public pollingIntervalMs: number = 0;
+
   // ── Backpressure observability (see common/page-helpers.ts + README) ──
   /** Resolved fetch cap (`maxBufferedPages`); set on each backpressure check, 0 until the first. */
   public bufferCap: number = 0;

package/src/sync-protocols/bitcoin/fetcher.ts

@@ -27,6 +27,7 @@ import type {
   BitcoinTxId,
 } from "@effectstream/utils";
 import { blockNumberRelation } from "../common/utils.ts";
+import { DEFAULT_REQUEST_TIMEOUT_MS, fetchWithTimeout } from "../common/http.ts";
 import type { ConfigType } from "./types.ts";
 
 const SATOSHIS_PER_BTC = 100_000_000;
@@ -457,6 +458,8 @@ type BitcoinRpcClientOptions = {
   url: string;
   username?: string | null;
   password?: string | null;
+  /** Per-request deadline; defaults to {@link DEFAULT_REQUEST_TIMEOUT_MS}. */
+  requestTimeoutMs?: number;
 };
 
 type BitcoinRpcRequest = {
@@ -515,16 +518,21 @@ export class BitcoinRpcClient {
   private async call<TResult>(
     request: BitcoinRpcRequest,
   ): Promise<TResult> {
-    const response = await fetch(this.options.url, {
-      method: "POST",
-      headers: this.buildHeaders(),
-      body: JSON.stringify({
-        jsonrpc: "2.0",
-        id: ++this.nextId,
-        method: request.method,
-        params: request.params ?? [],
-      }),
-    });
+    const response = await fetchWithTimeout(
+      this.options.url,
+      {
+        method: "POST",
+        headers: this.buildHeaders(),
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: ++this.nextId,
+          method: request.method,
+          params: request.params ?? [],
+        }),
+      },
+      `Bitcoin ${request.method}`,
+      this.options.requestTimeoutMs,
+    );
     if (!response.ok) {
       const body = await response.text();
       throw new Error(

package/src/sync-protocols/celestia/CelestiaClient.ts

@@ -54,6 +54,11 @@ const CELESTIA_NODE_URL = ENV.getString(
   "http://localhost:26658",
 );
 const CELESTIA_AUTH_TOKEN = ENV.getString("CELESTIA_AUTH_TOKEN", "");
+/**
+ * Fallback per-request deadline, kept for compatibility with deployments that
+ * set it. The protocol config's `requestTimeoutMs` takes precedence — see the
+ * constructor.
+ */
 const CELESTIA_RPC_TIMEOUT_MS = parseInt(
   ENV.getString("CELESTIA_RPC_TIMEOUT_MS", "15000"),
 );
@@ -77,9 +82,18 @@ export function celestiaNamespaceToBase64(hex: string): string {
 
 export class CelestiaClient {
   private readonly rpcUrl: string;
+  /**
+   * Per-attempt deadline. Unlike the other clients this one retries internally
+   * (see `rpc` below), so this bounds each attempt rather than the whole call.
+   */
+  private readonly requestTimeoutMs: number;
 
-  constructor(rpcUrl: string = CELESTIA_NODE_URL) {
+  constructor(
+    rpcUrl: string = CELESTIA_NODE_URL,
+    requestTimeoutMs: number = CELESTIA_RPC_TIMEOUT_MS,
+  ) {
     this.rpcUrl = rpcUrl;
+    this.requestTimeoutMs = requestTimeoutMs;
   }
 
   private async rpc<T>(method: string, params: unknown[]): Promise<T | null> {
@@ -95,7 +109,7 @@ export class CelestiaClient {
           method: "POST",
           headers,
           body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
-          signal: AbortSignal.timeout(CELESTIA_RPC_TIMEOUT_MS),
+          signal: AbortSignal.timeout(this.requestTimeoutMs),
         });
         const json = await res.json();
         if (json.error) {

package/src/sync-protocols/celestia/fetcher.ts

@@ -2,6 +2,7 @@ import {
   ConfigSyncProtocolType,
   type PrimitiveEntry,
 } from "@effectstream/config";
+import { requestTimeoutOf } from "../common/http.ts";
 import { BaseDataFetcher } from "../base/fetcher.ts";
 import type { DataFetched } from "../base/fetcher.ts";
 import type {
@@ -37,7 +38,10 @@ export class CelestiaFetcher extends BaseDataFetcher<
     readonly config: ConfigType,
   ) {
     super(config.syncProtocol.name);
-    this.client = new CelestiaClient(config.network.rpcUrl);
+    this.client = new CelestiaClient(
+      config.network.rpcUrl,
+      requestTimeoutOf(config.syncProtocol),
+    );
   }
 
   @bound

package/src/sync-protocols/celestia/state.ts

@@ -10,6 +10,7 @@ import type { ConfigNetworkType, SyncProtocolWithNetwork } from "@effectstream/c
 import { getPage } from "@effectstream/db";
 import { CelestiaClient } from "./CelestiaClient.ts";
 import { applyDelay } from "../common/utils.ts";
+import { requestTimeoutOf } from "../common/http.ts";
 import { bufferAtCap } from "../common/page-helpers.ts";
 
 export class CelestiaSyncState extends SyncState<
@@ -135,7 +136,10 @@ export class CelestiaSyncState extends SyncState<
       page,
       config,
       fetcher,
-      new CelestiaClient(config.network.rpcUrl),
+      new CelestiaClient(
+        config.network.rpcUrl,
+        requestTimeoutOf(config.syncProtocol),
+      ),
       dbConn,
     );
   }

package/src/sync-protocols/common/http.ts

@@ -0,0 +1,77 @@
+/**
+ * Bounded HTTP for sync-protocol RPC clients.
+ *
+ * `fetch` has no default timeout. Against a blackholed endpoint — a load
+ * balancer that drops its backend, a socket left half-open by a NAT rebind —
+ * the connection is established and simply never answers, so the promise never
+ * settles. For a sync protocol that is the worst possible failure: `readData`
+ * never returns, so the fetch loop in `orchestration/sync.ts` never reaches its
+ * `catch`, `consecutiveErrors` stays 0, `lastSuccessfulFetchMs` freezes, and
+ * the merge blocks on that chain's page forever. The node stops producing
+ * blocks and reports nothing wrong.
+ *
+ * Deliberately timeout-only, with NO internal retry. The fetch loop already
+ * retries: it catches, counts the error, sleeps `pollingInterval` and re-runs
+ * the same page range (fetches are idempotent — `lastPage` only advances on a
+ * complete `DataFetched`). Retrying inside the client as well would double the
+ * backoff and, worse, hide failures from `consecutiveErrors`, which is what the
+ * health endpoint reports on.
+ *
+ * Regression test: `sync/test/rpc-timeout.test.ts` points each client at a
+ * blackhole and asserts it rejects rather than hanging.
+ */
+
+/** Used when a protocol config carries no `requestTimeoutMs`. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+
+/** Thrown when a request exceeds its budget, so callers can tell it apart. */
+export class RequestTimeoutError extends Error {
+  constructor(
+    readonly label: string,
+    readonly timeoutMs: number,
+  ) {
+    super(`[${label}] request timed out after ${timeoutMs}ms`);
+    this.name = "RequestTimeoutError";
+  }
+}
+
+/**
+ * `fetch` with a hard deadline.
+ *
+ * @param label   Prefix for the thrown error, e.g. `"Bitcoin getblockhash"`.
+ * @param timeoutMs Falls back to {@link DEFAULT_REQUEST_TIMEOUT_MS}.
+ * @param signal  Optional caller signal; aborting either one aborts the request.
+ */
+export async function fetchWithTimeout(
+  url: string,
+  init: RequestInit,
+  label: string,
+  timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS,
+  signal?: AbortSignal,
+): Promise<Response> {
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  const combined = signal
+    ? AbortSignal.any([signal, timeoutSignal])
+    : timeoutSignal;
+
+  try {
+    return await fetch(url, { ...init, signal: combined });
+  } catch (err) {
+    // Surface our own error for the timeout case; a caller-supplied abort and
+    // ordinary transport failures propagate unchanged.
+    if (timeoutSignal.aborted && !(signal?.aborted ?? false)) {
+      throw new RequestTimeoutError(label, timeoutMs);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Resolve the timeout for a protocol config. Optional in the schema, so this
+ * centralises the fallback instead of repeating `?? DEFAULT` at each client.
+ */
+export function requestTimeoutOf(
+  syncProtocol: { requestTimeoutMs?: number } | undefined,
+): number {
+  return syncProtocol?.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+}

package/src/sync-protocols/midnight/fetcher.ts

@@ -1,4 +1,5 @@
 import { BaseDataFetcher } from "../base/fetcher.ts";
+import { requestTimeoutOf } from "../common/http.ts";
 import type {
   Block,
   ConfigType,
@@ -59,6 +60,7 @@ export class MidnightFetcher extends BaseDataFetcher<
     this.client = new MidnightClient(
       indexerHttp,
       this.networkId,
+      requestTimeoutOf(config.syncProtocol),
     );
   }
 

package/src/sync-protocols/midnight/types.ts

@@ -35,7 +35,7 @@ export type CommonFunnelArgs = {
 // Graphql Block
 // =============
 
-// Interfaces approximated from GraphQL schema served by indexer v1.3.1
+// Interfaces approximated from GraphQL schema served by indexer v4.3.3 (/api/v3)
 
 interface ContractCallOrDeploy {
   address: MidnightAddress;

package/src/sync-protocols/near/NearClient.ts

@@ -1,3 +1,5 @@
+import { DEFAULT_REQUEST_TIMEOUT_MS, fetchWithTimeout } from "../common/http.ts";
+
 // ============================
 // NEAR JSON-RPC type responses
 // ============================
@@ -107,17 +109,25 @@ export function parseNep297Log(log: string): Nep297Event | null {
 
 export class NearClient {
   private readonly rpcUrl: string;
+  /** Per-request deadline; see `sync-protocols/common/http.ts`. */
+  private readonly requestTimeoutMs: number;
 
-  constructor(rpcUrl: string) {
+  constructor(rpcUrl: string, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
     this.rpcUrl = rpcUrl;
+    this.requestTimeoutMs = requestTimeoutMs;
   }
 
   private async rpc<T>(method: string, params: Record<string, unknown>): Promise<T> {
-    const res = await fetch(this.rpcUrl, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
-    });
+    const res = await fetchWithTimeout(
+      this.rpcUrl,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+      },
+      `NEAR ${method}`,
+      this.requestTimeoutMs,
+    );
 
     const json = await res.json();
     if (json.error) {

package/src/sync-protocols/near/fetcher.ts

@@ -4,6 +4,7 @@ import {
 } from "@effectstream/config";
 import { BaseDataFetcher } from "../base/fetcher.ts";
 import type { DataFetched } from "../base/fetcher.ts";
+import { requestTimeoutOf } from "../common/http.ts";
 import type {
   LastPage,
   OutputAndCleanup,
@@ -39,7 +40,10 @@ export class NearFetcher extends BaseDataFetcher<
     readonly config: ConfigType,
   ) {
     super(config.syncProtocol.name);
-    this.client = new NearClient(config.network.rpcUrl);
+    this.client = new NearClient(
+      config.network.rpcUrl,
+      requestTimeoutOf(config.syncProtocol),
+    );
   }
 
   @bound

package/src/sync-protocols/near/state.ts

@@ -11,6 +11,7 @@ import { getPage } from "@effectstream/db";
 import { NearClient } from "./NearClient.ts";
 import { applyDelay } from "../common/utils.ts";
 import { bufferAtCap } from "../common/page-helpers.ts";
+import { requestTimeoutOf } from "../common/http.ts";
 
 export class NearSyncState extends SyncState<
   Input,
@@ -134,7 +135,10 @@ export class NearSyncState extends SyncState<
       page,
       config,
       fetcher,
-      new NearClient(config.network.rpcUrl),
+      new NearClient(
+        config.network.rpcUrl,
+        requestTimeoutOf(config.syncProtocol),
+      ),
       dbConn,
     );
   }

package/src/sync-protocols/orchestration/sync.ts

@@ -4,19 +4,113 @@ import { ComponentNames, log, SeverityNumber } from "@effectstream/log";
 import type { AllSyncProtocols, ISyncProtocol } from "../types.ts";
 import { tryYield } from "@effectstream/utils";
 
+/**
+ * Used when a protocol config carries no `pollingInterval`.
+ *
+ * Every polling protocol declares one via `PollingSyncProtocol`, so this should
+ * be unreachable — it exists because the cost of getting it wrong is not a slow
+ * loop but a dead node. A pass through this loop that neither fetches nor
+ * sleeps never yields to the macrotask queue, which starves the entire process:
+ * no timers, no HTTP server, no other chain's fetch loop, and (for streaming
+ * chains) none of the stream callbacks that would let this loop make progress.
+ * See `sync/test/poll-loop-spin.test.ts`.
+ */
+const FALLBACK_POLLING_INTERVAL_MS = 1_000;
+
+/** This protocol's polling interval, or the fallback above. */
+function pollingIntervalOf(config: { syncProtocol: unknown }): number {
+  const syncProtocol = config.syncProtocol as { pollingInterval?: number };
+  return syncProtocol?.pollingInterval ?? FALLBACK_POLLING_INTERVAL_MS;
+}
+
+/** Backoff bounds for restarting a dead streaming producer. */
+const PRODUCER_MIN_BACKOFF_MS = 1_000;
+const PRODUCER_MAX_BACKOFF_MS = 30_000;
+
 export function* startSync(
   state: AllSyncProtocols,
 ): Operation<void> {
   const iState: ISyncProtocol = state as ISyncProtocol;
 
-  // spawn async task
+  // Resolve once and publish it, so `/health` and anything else reads the same
+  // value this loop paces itself with instead of re-deriving it.
+  state.pollingIntervalMs = pollingIntervalOf(state.fetcher.config);
+
   yield* spawn(function* () {
-    yield* iState.startAsync();
+    if (!iState.hasAsyncProducer) {
+      // Polled chain: startAsync is the base-class no-op. Run it once, as
+      // before — supervising it would mean restarting a no-op forever.
+      yield* iState.startAsync();
+      return;
+    }
+
+    // Streaming chain: all of this protocol's data arrives through the
+    // producer, so if it dies the chain goes silent and the merge blocks on its
+    // page forever. Both of its exit modes used to be unhandled — a throw tore
+    // down the enclosing scope (in production, `start()`, taking every other
+    // chain with it), and a clean return went entirely unnoticed. Supervise
+    // both. See `sync/test/start-async-supervision.test.ts`.
+    let attempt = 0;
+    while (true) {
+      const startedAt = Date.now();
+      const result = yield* tryYield(iState.startAsync());
+      const ranForMs = Date.now() - startedAt;
+
+      if (result.error != null) {
+        // Producer failures are tracked separately from `consecutiveErrors`.
+        // That counter belongs to the fetch loop and is only cleared by a
+        // successful `readData`, so bumping it here left an idle streaming chain
+        // reporting `erroring` until its next block arrived — and conversely, a
+        // successful poll would erase the record of a flapping producer.
+        state.producerErrors++;
+        state.lastProducerErrorMs = Date.now();
+        log.remote(
+          ComponentNames.EFFECTSTREAM_SYNC,
+          [...state.getNamespace(), "startAsync"],
+          SeverityNumber.ERROR,
+          (l) => l(result.error),
+        );
+      } else {
+        // Returning is a failure for a producer: its stream ended. Treated the
+        // same as a throw, because the observable effect is identical — no
+        // more data.
+        log.remote(
+          ComponentNames.EFFECTSTREAM_SYNC,
+          [...state.getNamespace(), "startAsync"],
+          SeverityNumber.WARN,
+          (l) => l("producer returned: stream ended, restarting"),
+        );
+      }
+
+      state.producerRestarts++;
+
+      // De-escalate after a producer that clearly worked. Without this `attempt`
+      // only ever grows, so a stream that ran healthily for a day between
+      // incidents would still be waiting the 30s cap on its next restart —
+      // penalising a healthy chain for ancient history. (It also keeps
+      // `2 ** attempt` from reaching Infinity after ~1024 restarts, which
+      // `Math.min` currently absorbs silently.)
+      if (ranForMs >= PRODUCER_MAX_BACKOFF_MS) {
+        attempt = 0;
+      }
+
+      const backoff = Math.min(
+        PRODUCER_MIN_BACKOFF_MS * 2 ** attempt,
+        PRODUCER_MAX_BACKOFF_MS,
+      );
+      attempt++;
+      yield* sleep(backoff);
+    }
   });
 
   // spawn polling task
   yield* spawn(function* () {
     while (true) {
+      // Liveness heartbeat: stamped every pass regardless of outcome, so a
+      // stale value means the loop is wedged inside a call that never returns
+      // rather than merely idle. See SyncState.lastPollAtMs.
+      state.lastPollAtMs = Date.now();
+
       const inputResult = yield* tryYield(iState.stateToInput());
       if (inputResult.error != null) {
         state.consecutiveErrors++;
@@ -27,18 +121,14 @@ export function* startSync(
           SeverityNumber.ERROR,
           (log) => log(inputResult.error),
         );
-        const { config } = state.fetcher;
-        if ("pollingInterval" in config.syncProtocol) {
-          yield* sleep(config.syncProtocol.pollingInterval);
-        }
+        yield* sleep(state.pollingIntervalMs);
         continue;
       }
       const input = inputResult.data;
-      const { config } = state.fetcher;
       if (input == null) {
-        if ("pollingInterval" in config.syncProtocol) {
-          yield* sleep(config.syncProtocol.pollingInterval);
-        }
+        // Caught up. This is the ordinary steady state, and the pass that must
+        // never skip its sleep — see FALLBACK_POLLING_INTERVAL_MS.
+        yield* sleep(state.pollingIntervalMs);
         continue;
       }
 
@@ -52,9 +142,7 @@ export function* startSync(
           SeverityNumber.ERROR,
           (l) => l(result.error),
         );
-        if ("pollingInterval" in config.syncProtocol) {
-          yield* sleep(config.syncProtocol.pollingInterval);
-        }
+        yield* sleep(state.pollingIntervalMs);
         continue;
       }
       state.consecutiveErrors = 0;

package/src/sync-protocols/solana/SolanaClient.ts

@@ -0,0 +1,158 @@
+import {
+  DEFAULT_REQUEST_TIMEOUT_MS,
+  fetchWithTimeout,
+} from "../common/http.ts";
+
+// ==========================
+// Solana JSON-RPC type defs
+// ==========================
+
+export type SolanaBlock = {
+  blockhash: string;
+  blockTime: number | null;
+  blockHeight: number | null;
+  parentSlot: number;
+  previousBlockhash: string;
+  transactions: SolanaTransaction[];
+};
+
+export type SolanaTransaction = {
+  transaction: {
+    message: {
+      accountKeys: string[];
+      instructions: SolanaInstruction[];
+    };
+    signatures: string[];
+  };
+  /**
+   * Null when the RPC could not decode the transaction (e.g. a version newer
+   * than `maxSupportedTransactionVersion`). Callers must null-check.
+   */
+  meta: {
+    err: unknown | null;
+    logMessages: string[] | null;
+    preBalances: number[];
+    postBalances: number[];
+    /**
+     * Addresses a versioned (v0) transaction pulled in through an address
+     * lookup table. These are NOT in `message.accountKeys`, which carries only
+     * static keys — but `pre`/`postBalances` are indexed over the full list.
+     * See {@link resolveAccountKeys} for the ordering.
+     */
+    loadedAddresses?: {
+      writable: string[];
+      readonly: string[];
+    } | null;
+  } | null;
+};
+
+/**
+ * The account list `pre`/`postBalances` are indexed against: static message
+ * keys first, then lookup-table writable addresses, then lookup-table readonly
+ * ones. Legacy transactions have no `loadedAddresses`, so this is just the
+ * static keys.
+ */
+export function resolveAccountKeys(
+  accountKeys: string[],
+  loadedAddresses?: { writable: string[]; readonly: string[] } | null,
+): string[] {
+  if (!loadedAddresses) return accountKeys;
+  return [
+    ...accountKeys,
+    ...(loadedAddresses.writable ?? []),
+    ...(loadedAddresses.readonly ?? []),
+  ];
+}
+
+export type SolanaInstruction = {
+  programId: string;
+  accounts: string[];
+  data: string;
+};
+
+// ===========
+// RPC Client
+// ===========
+
+export class SolanaClient {
+  private readonly rpcUrl: string;
+  /** Per-request deadline; see `sync-protocols/common/http.ts`. */
+  private readonly requestTimeoutMs: number;
+
+  constructor(rpcUrl: string, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+    this.rpcUrl = rpcUrl;
+    this.requestTimeoutMs = requestTimeoutMs;
+  }
+
+  private async rpc<T>(
+    method: string,
+    params: unknown[] = [],
+  ): Promise<T> {
+    // Bounded: a blackholed endpoint would otherwise hang readData forever,
+    // freezing block production with every health counter clean (sync
+    // CLAUDE.md finding #4).
+    const res = await fetchWithTimeout(
+      this.rpcUrl,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 1,
+          method,
+          params,
+        }),
+      },
+      `Solana ${method}`,
+      this.requestTimeoutMs,
+    );
+
+    const json = await res.json();
+    if (json.error) {
+      const err = new Error(
+        `[Solana] RPC error [${method}]: ${json.error.message ?? JSON.stringify(json.error)}`,
+      ) as Error & { rpcCode?: number };
+      // Preserve the JSON-RPC code so callers can branch on it instead of
+      // pattern-matching human-readable messages.
+      err.rpcCode = typeof json.error.code === "number" ? json.error.code : undefined;
+      throw err;
+    }
+    return json.result as T;
+  }
+
+  async getSlot(): Promise<number> {
+    return this.rpc<number>("getSlot", [
+      { commitment: "confirmed" },
+    ]);
+  }
+
+  async getBlock(
+    slot: number,
+  ): Promise<SolanaBlock | null> {
+    try {
+      return await this.rpc<SolanaBlock | null>("getBlock", [
+        slot,
+        {
+          encoding: "json",
+          transactionDetails: "full",
+          rewards: false,
+          maxSupportedTransactionVersion: 0,
+          commitment: "confirmed",
+        },
+      ]);
+    } catch (e) {
+      // A skipped slot is normal on Solana: no block was produced. Branch on the
+      // JSON-RPC code rather than the message text —
+      //   -32007 SLOT_SKIPPED, -32009 LONG_TERM_STORAGE_SLOT_SKIPPED.
+      // Deliberately NOT -32004 (block not available yet): that is a transient
+      // "ask again" and must keep throwing so the fetcher retries rather than
+      // treating the slot as permanently empty.
+      const code = (e as { rpcCode?: number }).rpcCode;
+      if (code === -32007 || code === -32009) return null;
+      // Fall back to the message for RPCs that omit or remap the code.
+      if (e instanceof Error && e.message.includes("was skipped")) return null;
+      throw e;
+    }
+  }
+
+}