# @metamask/eth-block-tracker

> A block tracker for the Ethereum blockchain. Keeps track of the latest block

Latest version **16.0.0** (published 2026-09-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install @metamask/eth-block-tracker
pnpm add @metamask/eth-block-tracker
yarn add @metamask/eth-block-tracker
bun add @metamask/eth-block-tracker
```

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 16.0.0 |
| Published | 2026-09-09 |
| First published | 2024-05-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | ^22.14.0 \|\| ^24 |
| Dependencies | 4 |
| Unpacked size | 49.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Maintainers | frederikbolding, metamaskbot, gudahtt, mrten, mcmire, naugtur |
| Keywords | Ethereum, MetaMask |

## Links

- npm: https://www.npmjs.com/package/@metamask/eth-block-tracker
- Repository: https://github.com/MetaMask/core
- Homepage: https://github.com/MetaMask/core/tree/main/packages/eth-block-tracker#readme
- Issues: https://github.com/MetaMask/core/issues
- npm.io page: https://npm.io/package/@metamask/eth-block-tracker

## Dependencies (4)

- [@metamask/utils](https://npm.io/package/@metamask/utils.md) ^11.12.0
- [json-rpc-random-id](https://npm.io/package/json-rpc-random-id.md) ^1.0.1
- [@metamask/safe-event-emitter](https://npm.io/package/@metamask/safe-event-emitter.md) ^3.1.3
- [@metamask/eth-json-rpc-provider](https://npm.io/package/@metamask/eth-json-rpc-provider.md) ^7.0.0

## Recent versions

- 16.0.0 (latest) — 2026-09-09
- 15.0.1 — 2026-01-15
- 15.0.0 — 2025-11-20
- 14.0.0 — 2025-10-16
- 13.0.0 — 2025-10-15
- 12.2.1 — 2025-10-14
- 12.2.0 — 2025-10-08
- 12.1.0 — 2025-09-24
- 12.0.1 — 2025-05-29
- 12.0.0 — 2025-05-23
- 11.0.4 — 2024-12-18
- 11.0.3 — 2024-12-04
- 11.0.2 — 2024-10-18
- 11.0.1 — 2024-07-23
- 11.0.0 — 2024-07-22
- … 6 more at https://npm.io/package/@metamask/eth-block-tracker/versions

## README

# `@metamask/eth-block-tracker`

This module walks the Ethereum blockchain, keeping track of the latest block. It uses a web3 provider as a data source and will continuously poll for the next block.

## Installation

`yarn add @metamask/eth-block-tracker`

or

`npm install @metamask/eth-block-tracker`

## Usage

```js
const createInfuraProvider = require('@metamask/eth-json-rpc-infura');
const { PollingBlockTracker } = require('@metamask/eth-block-tracker');

const provider = createInfuraProvider({
  network: 'mainnet',
  projectId: process.env.INFURA_PROJECT_ID,
});
const blockTracker = new PollingBlockTracker({ provider });

blockTracker.on('sync', ({ newBlock, oldBlock }) => {
  if (oldBlock) {
    console.log(`sync #${Number(oldBlock)} -> #${Number(newBlock)}`);
  } else {
    console.log(`first sync #${Number(newBlock)}`);
  }
});
```

## API

### Methods

#### new PollingBlockTracker({ provider, pollingInterval, retryTimeout, keepEventLoopActive, usePastBlocks })

- Creates a new block tracker with `provider` as a data source and `pollingInterval` (ms) timeout between polling for the latest block.
- If an error is encountered when fetching blocks, it will wait `retryTimeout` (ms) before attempting again.
- If `keepEventLoopActive` is `false`, in Node.js it will [unref the polling timeout](https://nodejs.org/api/timers.html#timers_timeout_unref), allowing the process to exit during the polling interval. Defaults to `true`, meaning the process will be kept alive.
- If `usePastBlocks` is `true`, block numbers less than the current block number can used and emitted. Defaults to `false`, meaning that only block numbers greater than the current block number will be used and emitted.

#### getCurrentBlock()

Synchronously returns the current block. May be `null`.

```js
console.log(blockTracker.getCurrentBlock());
```

#### async getLatestBlock()

Asynchronously returns the latest block. if not immediately available, it will fetch one.

#### async checkForLatestBlock()

Tells the block tracker to ask for a new block immediately, in addition to its normal polling interval. Useful if you received a hint of a new block (e.g. via `tx.blockNumber` from `getTransactionByHash`). Will resolve to the new latest block when done polling.

### Events

#### latest

The `latest` event is emitted for whenever a new latest block is detected. This may mean skipping blocks if there were two created since the last polling period.

```js
blockTracker.on('latest', (newBlock) => console.log(newBlock));
```

#### sync

The `sync` event is emitted the same as "latest" but includes the previous block.

```js
blockTracker.on('sync', ({ newBlock, oldBlock }) =>
  console.log(newBlock, oldBlock),
);
```

#### error

The `error` event means an error occurred while polling for the latest block.

```js
blockTracker.on('error', (err) => console.error(err));
```

## Contributing

This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core#readme).

---
_Source: https://npm.io/package/@metamask/eth-block-tracker · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._