Docs
Docs
Home
Getting Started
Agent Tooling
CLI
Supported Chains
Acala
Aptos
Arbitrum
Arc
Asset Hub
Astar
Avalanche
Base
Berachain
Bifrost
Binance Smart Chain
Bittensor
Blast
Boba Network
Bridge Hub
Celo
Centrifuge
Chiliz
Cronos
Enjin
Ethereum
Etherlink
Flow EVM Gateway
Gnosis
Hydration
Hyperliquid
Immutable
Ink
IoTeX
Kusama
Linea
LISK
Manta Atlantic
Manta Pacific
Mantle
MegaETH
Monad
Movement
Neuroweb
opBNB
Optimism
Plasma
Polkadot
Polygon
Pulsechain
Robinhood
Ronin
Scroll
Sonic
Starknet
Taiko
Tempo
Sui
TRON
Unichain
Viction
World Chain
XDC Network
XX Network
Zetachain
zkSync Era
Zora
Supported ChainsPlasmaJSON-RPC APISmart Contract Methods

eth_newBlockFilter - Plasma RPC Method

Create a filter for new block notifications on Plasma. Essential for block monitoring, chain progression tracking, and reorg detection for stablecoin transfers, payment apps, and wallets that need 1 second confirmation.

Plasma RPC endpoint: endpoint URLs, plans and pricing.

Creates a filter on Plasma 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 Plasma? Build on an EVM Layer 1 for stablecoin payments with PlasmaBFT consensus and Reth execution with 1 second blocks, XPL gas, full EVM JSON-RPC, and debug plus txpool on Dwellir.

When to Use This Method

eth_newBlockFilter is essential for payment app developers, wallet teams, and teams shipping Solidity contracts for dollar transfers:

  • Block Monitoring - Detect new blocks on Plasma 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

Best Practices

  • Use WebSocket subscriptions (eth_subscribe) for real-time block notifications in production environments
  • Poll with eth_getFilterChanges at 1-5 second intervals to receive new block hashes
  • Combine with eth_getBlockByNumber or eth_getBlockByHash to retrieve full block details
JSON-RPC request
{
  "jsonrpc": "2.0",
  "method": "eth_newBlockFilter",
  "params": [],
  "id": 1
}

Code Examples

Bash
# Create the block filter
FILTER_ID=$(curl -s -X POST https://api-plasma-mainnet.n.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_newBlockFilter",
    "params": [],
    "id": 1
  }' | jq -r '.result')

echo "Filter ID: $FILTER_ID"

# Poll for new blocks
curl -X POST https://api-plasma-mainnet.n.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d "{
    \"jsonrpc\": \"2.0\",
    \"method\": \"eth_getFilterChanges\",
    \"params\": [\"$FILTER_ID\"],
    \"id\": 2
  }"

Common Use Cases

1. Block Production Rate Monitor

Track block times and detect slowdowns on Plasma:

JavaScript
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 CodeDescriptionSolution
-32603Internal errorNode may not support filters - verify node capabilities
-32000Filter not foundFilter expired (~5 min inactivity) - recreate with eth_newBlockFilter
-32005Rate limit exceededReduce polling frequency or implement client-side rate limiting
-32601Method not foundNode 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() };
  }
}

Related Methods

  • 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_uninstallFilter

Remove a filter on Plasma created by eth_newFilter, eth_newBlockFilter, or eth_newPendingTransactionFilter. Essential for resource cleanup after event monitoring.

eth_newPendingTransactionFilter

Create a filter for pending transaction notifications on Plasma. Essential for mempool monitoring, transaction tracking, and MEV opportunity detection for stablecoin transfers, payment apps, and wallets that need 1 second confirmation.

On this page

When to Use This MethodBest PracticesCode ExamplesCommon Use Cases1. Block Production Rate Monitor2. Reorg-Aware Block Tracker3. Block-Triggered Task SchedulerError HandlingRelated Methods