Resilience & keepalive

Keepalive & idle detection

The nastiest failure is the silent one. A half-open stream — where your side still believes the socket is up but no bytes are arriving — delivers no data and fires no error event. You sit there waiting forever.

Defend on two layers. At the transport, turn on gRPC/HTTP2 keepalive so the channel probes the connection and surfaces a dead socket. At the application, run an idle-timeout watchdog: record the timestamp of every update and reconnect if nothing has arrived within your window. Pair the watchdog with a low-volume subscription — a slots or blocksMeta feed makes a cheap, steady heartbeat even when your real filters are quiet.

1import Client, {
2  CommitmentLevel,
3  SubscribeRequest,
4} from "@triton-one/yellowstone-grpc";
5 
6// gRPC/HTTP2 keepalive pings at the channel level
7const client = new Client(
8  "https://geyser.therpc.io:443",
9  "<YOUR_API_KEY>",
10  {
11    "grpc.keepalive_time_ms": 10_000,
12    "grpc.keepalive_timeout_ms": 5_000,
13    "grpc.keepalive_permit_without_calls": 1,
14  }
15);
16 
17const stream = await client.subscribe();
18 
19// app-level watchdog: if no update lands within the window, reconnect
20let lastUpdateAt = Date.now();
21const IDLE_TIMEOUT_MS = 30_000;
22 
23stream.on("data", (update) => {
24  lastUpdateAt = Date.now();
25  // ...handle update
26});
27 
28setInterval(() => {
29  if (Date.now() - lastUpdateAt > IDLE_TIMEOUT_MS) {
30    console.warn("no updates — stream may be half-open, reconnecting");
31    stream.end();
32    // tear down and re-subscribe from your last processed slot
33  }
34}, 5_000);

The proxy also exposes an app-level Ping you can write into the request channel; the server answers with a Pong. It is a request-channel heartbeat for streams that are otherwise silent.

1// keep a quiet stream warm by writing a Ping into the request channel
2// the server echoes it back as a Pong
3const ping: SubscribeRequest = {
4  accounts: {},
5  slots: {},
6  transactions: {},
7  transactionsStatus: {},
8  blocks: {},
9  blocksMeta: {},
10  entry: {},
11  accountsDataSlice: [],
12  ping: { id: 1 },
13};
14 
15setInterval(() => {
16  stream.write(ping, () => {});
17}, 15_000);

Reconnect & gap recovery

A reconnect gives you a fresh live stream — it does not replay what you missed while you were gone. Closing that gap is on you, and the right tool depends on whether you hold an API key.

With a key, persist the last slot you fully processed and set fromSlot on the next request to replay from there. Before you trust that slot, call SubscribeReplayInfo to learn the earliest slot still available — if your gap predates the replay window, replay can't reach it.

1// you persist the last slot you fully processed
2const lastProcessedSlot = await store.getLastSlot();
3 
4// on reconnect, replay the gap — fromSlot requires an API key
5const request: SubscribeRequest = {
6  accounts: {
7    raydium_pools: {
8      account: [],
9      owner: ["675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8"],
10      filters: [],
11      nonemptyTxnSignature: undefined,
12    },
13  },
14  slots: {},
15  transactions: {},
16  transactionsStatus: {},
17  blocks: {},
18  blocksMeta: {},
19  entry: {},
20  accountsDataSlice: [],
21  commitment: CommitmentLevel.CONFIRMED,
22  fromSlot: lastProcessedSlot,
23};
24 
25// check how far back replay is available before trusting fromSlot
26const info = await client.subscribeReplayInfo();
27if (lastProcessedSlot < info.firstAvailable) {
28  // gap is older than the replay window — backfill instead
29  // via getSignaturesForAddress on standard JSON-RPC
30}

Without a key — or when the gap is older than the replay window — fromSlot isn't available. Fall back to tracking the last processed slot and backfilling the gap with getSignaturesForAddress on standard JSON-RPC, then resume the live stream from the head.

Backpressure

gRPC has flow control. If your consumer reads slower than the server pushes, the window fills and the stream stalls — and a stalled stream looks a lot like an idle one. Keep the read loop thin: pull updates off the wire and hand them to a queue or worker, do the heavy work elsewhere. Watch your lag by comparing the slot on the last update you processed against the chain head from a cheap slots feed. A lag that only grows means your consumer can't keep up, not that the network is slow.

Error handling

Handle gRPC status codes on the stream and retry transient ones with backoff. The first error many people hit is a permission one: keyless public requests may not set the commitment or fromSlot filters. Set either without a key and the proxy returns gRPC PermissionDenied:

The fix is an API key: it unlocks commitment selection and fromSlot replay in one move. Until then, drop those two filters and the stream runs at the default commitment, live-only.