watchBlockNumber ​

Watches and returns incoming block numbers.

Usage ​

Pass through your Public Client, along with a listener.

import { publicClient } from './client'

const unwatch = publicClient.watchBlockNumber( 
  { onBlockNumber: blockNumber => console.log(blockNumber) }
)
/**
 * > 69420n
 * > 69421n
 * > 69422n
 */

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

export const publicClient = createPublicClient({
  chain: mainnet,
  transport: http()
})

Listener ​

(blockNumber: bigint) => void

The block number.

Returns ​

UnwatchFn

A function that can be invoked to stop watching for new block numbers.

Parameters ​

emitMissed (optional) ​

• Type: boolean
• Default: false

Whether or not to emit missed block numbers to the callback.

Missed block numbers may occur in instances where internet connection is lost, or the block time is lesser than the polling interval of the client.

const unwatch = publicClient.watchBlockNumber(
  { 
    emitMissed: true, 
    onBlockNumber: blockNumber => console.log(blockNumber),
  }
)

emitOnBegin (optional) ​

• Type: boolean
• Default: false

Whether or not to emit the latest block number to the callback when the subscription opens.

const unwatch = publicClient.watchBlockNumber(
  { 
    emitOnBegin: true, 
    onBlockNumber: blockNumber => console.log(blockNumber),
  }
)

poll (optional) ​

• Type: boolean
• Default: false for WebSocket Transports, true for non-WebSocket Transports

Whether or not to use a polling mechanism to check for new block numbers instead of a WebSocket subscription.

This option is only configurable for Clients with a WebSocket Transport.

import { createPublicClient, webSocket } from 'viem'
import { mainnet } from 'viem/chains'

const publicClient = createPublicClient({
  chain: mainnet,
  transport: webSocket()
})

const unwatch = publicClient.watchBlockNumber(
  { 
    onBlockNumber: blockNumber => console.log(blockNumber),
    poll: true, 
  }
)

pollingInterval (optional) ​

• Type: number

Polling frequency (in ms). Defaults to Client's pollingInterval config.

const unwatch = publicClient.watchBlockNumber(
  { 
    onBlockNumber: blockNumber => console.log(blockNumber),
    pollingInterval: 12_000, 
  }
)

Example ​

Check out the usage of watchBlockNumber in the live Watch Block Numbers Example below.

JSON-RPC Methods ​

• When poll: true, calls eth_blockNumber on a polling interval.
• When poll: false & WebSocket Transport, uses a WebSocket subscription via eth_subscribe and the "newHeads" event.