eth_newBlockFilter | Optimism RPC Docs

Create a filter for new block notifications on Optimism. Essential for block monitoring, chain progression tracking, and reorg detection for cross-chain DeFi, Superchain-interoperable dApps, and public goods funding recipients.

Creates a filter on Optimism that notifies when new blocks arrive. Once created, poll the filter with eth_getFilterChanges to receive an array of block hashes for each new block added to the chain since your last poll.

Why Optimism? Build on the heart of the Superchain powering 60%+ of Ethereum L2 transactions with $6B+ TVL with OP Stack modularity, Superchain interoperability, 17M+ daily transactions across 33 chains, and 20% of tokens for public goods.

When to Use This Method

eth_newBlockFilter is essential for L2 builders, DeFi developers, and teams launching Superchain-compatible apps:

Block Monitoring — Detect new blocks on Optimism as they are mined or finalized, without repeatedly calling eth_blockNumber
Chain Progression Tracking — Build dashboards or alerting systems that track block production rate and timing
Reorg Detection — Identify chain reorganizations by monitoring for blocks that are replaced or missing
Event-Driven Architectures — Trigger downstream processing (indexing, notifications, settlement) whenever a new block appears

async function monitorBlockRate(provider) {
  const filterId = await provider.send('eth_newBlockFilter', []);
  let lastBlockTime = null;
  const blockTimes = [];

  setInterval(async () => {
    const blockHashes = await provider.send('eth_getFilterChanges', [filterId]);

    for (const hash of blockHashes) {
      const block = await provider.getBlock(hash);
      const blockTime = block.timestamp;

      if (lastBlockTime) {
        const interval = blockTime - lastBlockTime;
        blockTimes.push(interval);

        // Keep last 100 block times
        if (blockTimes.length > 100) blockTimes.shift();

        const avgBlockTime = blockTimes.reduce((a, b) => a + b, 0) / blockTimes.length;
        console.log(`Block #${block.number} | interval: ${interval}s | avg: ${avgBlockTime.toFixed(1)}s`);

        if (interval > avgBlockTime * 3) {
          console.warn(`Slow block detected — ${interval}s vs ${avgBlockTime.toFixed(1)}s average`);
        }
      }
      lastBlockTime = blockTime;
    }
  }, 2000);
}

2. Reorg-Aware Block Tracker

Detect chain reorganizations by tracking block hashes:

JavaScript

async function trackBlocksWithReorgDetection(provider) {
  const filterId = await provider.send('eth_newBlockFilter', []);
  const blockHistory = new Map(); // blockNumber -> blockHash

  setInterval(async () => {
    const newBlockHashes = await provider.send('eth_getFilterChanges', [filterId]);

    for (const hash of newBlockHashes) {
      const block = await provider.getBlock(hash);
      const existingHash = blockHistory.get(block.number);

      if (existingHash && existingHash !== hash) {
        console.warn(`Reorg detected at block #${block.number}!`);
        console.warn(`  Old hash: ${existingHash}`);
        console.warn(`  New hash: ${hash}`);
        // Trigger reorg handling logic
      }

      blockHistory.set(block.number, hash);

      // Prune old entries
      if (blockHistory.size > 1000) {
        const minBlock = block.number - 500;
        for (const [num] of blockHistory) {
          if (num < minBlock) blockHistory.delete(num);
        }
      }
    }
  }, 2000);
}

3. Block-Triggered Task Scheduler

Execute tasks whenever a new block is produced:

JavaScript

async function onNewBlock(provider, callback) {
  const filterId = await provider.send('eth_newBlockFilter', []);

  const poll = async () => {
    try {
      const hashes = await provider.send('eth_getFilterChanges', [filterId]);
      for (const hash of hashes) {
        await callback(hash);
      }
    } catch (error) {
      if (error.message.includes('filter not found')) {
        return provider.send('eth_newBlockFilter', []).then(newId => {
          console.log('Block filter recreated');
          return newId;
        });
      }
      throw error;
    }
    return filterId;
  };

  let currentFilterId = filterId;
  setInterval(async () => {
    currentFilterId = await poll() || currentFilterId;
  }, 2000);
}

// Usage
onNewBlock(provider, async (blockHash) => {
  console.log(`Processing block: ${blockHash}`);
  // Run indexer, check conditions, send notifications, etc.
});

Error Handling

Common errors and solutions:

Error Code	Description	Solution
-32603	Internal error	Node may not support filters — verify node capabilities
-32000	Filter not found	Filter expired (~5 min inactivity) — recreate with `eth_newBlockFilter`
-32005	Rate limit exceeded	Reduce polling frequency or implement client-side rate limiting
-32601	Method not found	Node does not support filter methods — use `eth_blockNumber` polling instead

JavaScript

async function createBlockFilterWithFallback(provider) {
  try {
    const filterId = await provider.send('eth_newBlockFilter', []);
    return { type: 'filter', id: filterId };
  } catch (error) {
    console.warn('Block filter not supported — falling back to polling');
    return { type: 'polling', lastBlock: await provider.getBlockNumber() };
  }
}

eth_getFilterChanges — Poll this filter for new block hashes
eth_uninstallFilter — Remove the block filter when no longer needed
eth_blockNumber — Get the current block number (alternative to filter-based monitoring)
eth_getBlockByHash — Fetch full block details for hashes returned by the filter

eth_newBlockFilter - Optimism RPC Method

When to Use This Method

Code Examples

Common Use Cases

1. Block Production Rate Monitor

2. Reorg-Aware Block Tracker

3. Block-Triggered Task Scheduler

Error Handling

On this page