Data freshness monitoring

The solanaRpcLatencyWatcher subscribes to RPC endpoints via WebSocket and measures when blocks arrive at the Portal versus when they appear at the RPC endpoints.

The measured values include client-side network latency. For RPC endpoints, only the arrival time of blocks is measured. This does not capture the node’s internal processing or response latency if queried directly. Results represent end-to-end delays as experienced by the client, not pure Portal or RPC processing performance.

Pass the watcher as the source output. You can chain a .pipe() transform to it, for example to expose the measurements as Prometheus metrics:

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

async function main() {
  const stream = solanaPortalStream({
    id: 'solana-latency',
    portal: 'https://portal.sqd.dev/datasets/solana-mainnet',
    outputs: solanaRpcLatencyWatcher({
      rpcUrl: ['https://api.mainnet-beta.solana.com'], // RPC endpoints to monitor
    }).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'],
        })

        // Each batch carries the samples that became decidable in it
        for (const sample of data) {
          for (const rpc of sample.rpc) {
            // The endpoint never reported this slot, so there is no delay to record
            if (rpc.portalDelayMs === undefined) continue

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

        return data
      },
    }),

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

  // Iterate over the stream, logging block and RPC latency data
  for await (const { data } of stream) {
    for (const sample of data) {
      console.log(`Slot: ${formatBlock(sample.number)} / ${sample.timestamp.toString()}`)
      console.table(sample.rpc)
    }
  }
}

void main()

Output format

Each batch carries an array of samples: the ones that became decidable in that batch. A sample is decidable once both the Portal and the RPC endpoints have reported it, or once the wait window set by resolveTimeoutMs closes. It defaults to 60 seconds. Each sample includes:

number / timestamp: the observed slot and its timestamp
portal.receivedAt: when the block arrived from the Portal
rpc: one entry per configured RPC endpoint:
- url: RPC endpoint URL
- receivedAt: when the RPC endpoint received the block
- hash: block hash as seen by the RPC (not set on Solana)
- portalDelayMs: signed milliseconds between RPC arrival and Portal availability. A negative value means the Portal delivered the block first
- unresolved: set when the endpoint did not report the block, in which case receivedAt and portalDelayMs are absent

An endpoint that did not report the block is rpc-behind when it had not reached the block before the window closed, and rpc-missing when it is already past the block but never reported it. Count these entries rather than charting them. A missing delay is not zero.

portalDelayMs can be negative. If you feed these values into a histogram, revisit the buckets and any max(0, ...) clamping, or every Portal lead folds back into the zero bucket.

Slot: 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           │
└───┴─────────────────────────────────────┴──────────────────────────┴───────────────┘

The Prometheus gauge registered in the .pipe() transform above is served on the metricsServer() port, http://localhost:9090/metrics in this example. See the Metrics guide for details on custom metrics.

Pipes SDK

Squid SDK

Output format

​Output format

Output format