solanaRpcLatencyWatcher

The solanaRpcLatencyWatcher function monitors the latency between Portal and external RPC providers, helping you track indexing performance.

Import

import { solanaRpcLatencyWatcher } from '@subsquid/pipes/solana'

Signature

function solanaRpcLatencyWatcher(options: {
  rpcUrl: string[]
  resolveTimeoutMs?: number
}): Transformer

Parameters

Parameter	Type	Description
`rpcUrl`	`string[]`	Array of RPC endpoint URLs to monitor
`resolveTimeoutMs`	`number`	How long to wait for an endpoint to report a slot before recording it as `rpc-behind`. Defaults to `60_000`

Return Value

Returns a query-transformer combo that already includes the block query it needs. Pass it directly as the source’s outputs. You can chain .pipe() transforms to it.

Output Data Structure

Each batch carries the samples that became decidable in it, so iterate the result:

type LatencySample = {
  number: number,           // Slot number
  timestamp: Date,          // Block timestamp
  portal: {
    receivedAt: Date,       // When the block arrived from the Portal
  },
  rpc: Array<{
    url: string,            // RPC endpoint URL
    hash?: string,          // Not set on Solana: slot update notifications carry no hash
    receivedAt?: Date,      // When the block was received from this RPC
    portalDelayMs?: number, // Signed delay; negative means the Portal delivered first
    unresolved?: 'rpc-behind' | 'rpc-missing',
  }>
}

A sample is emitted once both the Portal and the RPC endpoints have reported the slot, or once the wait window closes. rpc carries one entry per configured endpoint on every sample. portalDelayMs is signed. A negative value means the Portal delivered the slot before that endpoint did. If these values feed a histogram, revisit the buckets and any max(0, ...) clamping, or Portal leads fold back into the zero bucket. portalDelayMs and receivedAt are absent whenever unresolved is set:

`unresolved`	Meaning
`rpc-behind`	The endpoint had not reached the slot before the wait window closed, so the Portal is ahead by at least that window.
`rpc-missing`	The endpoint is already past the slot but never reported it, after a reorg, a dropped update, or a slot seen while the stream was backfilling.

Count unresolved entries rather than charting them. A missing delay is not zero.

Basic Usage

import { solanaPortalStream, solanaRpcLatencyWatcher } from '@subsquid/pipes/solana'

const stream = solanaPortalStream({
  id: 'solana-latency',
  portal: 'https://portal.sqd.dev/datasets/solana-mainnet',
  outputs: solanaRpcLatencyWatcher({
    rpcUrl: ['https://api.mainnet-beta.solana.com'],
  }),
})

for await (const { data } of stream) {
  for (const sample of data) {
    console.log(`Slot: ${sample.number}`)
    console.table(sample.rpc)
  }
}

Example Output

-------------------------------------
BLOCK DATA: 369,377,455 / Fri Sep 26 2025 15:31:36 GMT+0400
┌───┬─────────────────────────────────────┬──────────────────────────┬───────────────┐
│   │ url                                 │ receivedAt               │ portalDelayMs │
├───┼─────────────────────────────────────┼──────────────────────────┼───────────────┤
│ 0 │ https://api.mainnet-beta.solana.com │ 2025-09-26T11:31:37.075Z │ 358           │
└───┴─────────────────────────────────────┴──────────────────────────┴───────────────┘

Multiple RPC Endpoints

Monitor multiple RPC providers simultaneously:

const stream = solanaPortalStream({
  id: 'solana-latency',
  portal: 'https://portal.sqd.dev/datasets/solana-mainnet',
  outputs: solanaRpcLatencyWatcher({
    rpcUrl: [
      'https://api.mainnet-beta.solana.com',
      'https://solana-mainnet.rpc.extrnode.com',
    ],
  }),
})

Metrics Integration

Export latency data to Prometheus via the built-in metrics registry. Skip the entries that carry unresolved, since they have no delay to record. See the Data freshness monitoring guide for the full example:

import { solanaPortalStream, solanaRpcLatencyWatcher } from '@subsquid/pipes/solana'
import { metricsServer } from '@subsquid/pipes/metrics/node'

const stream = solanaPortalStream({
  id: 'solana-latency',
  portal: 'https://portal.sqd.dev/datasets/solana-mainnet',
  outputs: solanaRpcLatencyWatcher({
    rpcUrl: ['https://api.mainnet-beta.solana.com'],
  }).pipe({
    profiler: { name: 'expose metrics' },
    transform: (data, { metrics }) => {
      const gauge = metrics.gauge({
        name: 'rpc_latency_ms',
        help: 'Portal delay against an RPC endpoint, in ms (negative: the Portal delivered first)',
        labelNames: ['url'],
      })

      for (const sample of data) {
        for (const rpc of sample.rpc) {
          if (rpc.portalDelayMs === undefined) continue

          gauge.set({ url: rpc.url }, rpc.portalDelayMs)
        }
      }

      return data
    },
  }),
  metrics: metricsServer({ port: 9090 }),
})

How It Works

The RPC latency watcher:

Subscribes to slot updates via WebSocket (slotsUpdatesSubscribe)
Listens for optimisticConfirmation events from each RPC
Holds each slot until both sides have reported it, or until resolveTimeoutMs passes
Reports the signed delay as portalDelayMs, or unresolved when an endpoint never reported the slot

The measured values include client-side network latency. For RPC, only the arrival time of the block is measured. This does not capture the node’s internal processing latency.

Use Cases

Performance monitoring - Track indexing latency in production
RPC comparison - Compare performance across different RPC providers
Alerting - Trigger alerts when latency exceeds thresholds
Optimization - Identify bottlenecks in your indexing pipeline

Pipes SDK

Squid SDK

Import

Signature

Parameters

Return Value

Output Data Structure

Basic Usage

Example Output

Multiple RPC Endpoints

Metrics Integration

How It Works

Use Cases

​Import

​Signature

​Parameters

​Return Value

​Output Data Structure

​Basic Usage

​Example Output

​Multiple RPC Endpoints

​Metrics Integration

​How It Works

​Use Cases

Import

Signature

Parameters

Return Value

Output Data Structure

Basic Usage

Example Output

Multiple RPC Endpoints

Metrics Integration

How It Works

Use Cases