eth_getUncleByBlockNumberAndIndex

The eth_getUncleByBlockNumberAndIndex method returns information about an uncle (ommer) block by a block number and uncle index position.

Use Cases

• Analyzing blockchain network health
• Verifying uncle rewards distribution
• Researching mining/validation competition
• Studying blockchain throughput and latency
• Understanding network security through uncle rate
• Historical blockchain research
• Block confirmation verification
• Network congestion analysis

Method Details

Returns information about the uncle (ommer) block by the block number and uncle index position.

Block Number Parameter Options

The blockNumber parameter accepts:

• Hex string of a block number
• "earliest" for the genesis block
• "latest" for the most recently mined block
• "pending" for the pending state/transactions
• "safe" for the most recent block that's safe from reorgs
• "finalized" for the most recent finalized block

Response Example

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"difficulty": "0x57f17a09378",
		"extraData": "0x476574682f76312e302e302f6c696e75782f676f312e342e32",
		"gasLimit": "0x1388",
		"gasUsed": "0x0",
		"hash": "0x932bdf904546a2287a2c9b2ede37925f698a7657484b172d4e5184f80bdd464d",
		"logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
		"miner": "0xbb7b8287f3f0a933474a79eae42cbca977791171",
		"mixHash": "0x4500aa4ee2b3044a155252e35273770edeb2ab6f8cb19ca8e732771484462169",
		"nonce": "0x24732773618271bc",
		"number": "0x299",
		"parentHash": "0xa779859b1ee558258b7008bbabff272280136c5dd3eb3ea3bfa8f6ae03bf91e5",
		"receiptsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
		"sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
		"size": "0x21d",
		"stateRoot": "0x2604fbf5183f5360da249b51f1b9f1e0f315d2ff3ffa1a4143ff221ad9ca1fec",
		"timestamp": "0x55ba4827",
		"totalDifficulty": null,
		"transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
		"uncles": []
	}
}

Understanding Uncle Blocks

Uncle blocks (also called ommers) are valid blocks that were mined but not included in the main blockchain. This happens when two miners find a valid block at nearly the same time, but only one can be accepted into the main chain.

Why Uncle Blocks Matter

• Network Security: A high uncle rate may indicate network latency or high mining competition
• Rewards: Miners of uncle blocks receive partial rewards (2/32 of block reward pre-EIP-1559)
• Block Inclusion: Uncles are referenced in regular blocks (up to 2 per block)
• Chain Confirmation: Uncles contribute to blockchain security despite not being in the main chain

Differences Between eth_getUncleByBlockNumberAndIndex and eth_getUncleByBlockHashAndIndex

Both methods retrieve the same uncle block data, but they use different reference methods:

• eth_getUncleByBlockNumberAndIndex - Uses the block number (or named tag like "latest") to identify the block containing the uncle
• eth_getUncleByBlockHashAndIndex - Uses the block hash to identify the block containing the uncle

The number parameter is often more convenient as it allows using block tags like "latest" and is easier to work with sequentially, while hash-based lookups provide absolute reference certainty.

Historical Significance

Uncle rates in Ethereum have historically been important metrics:

• Early Ethereum had uncle rates around 7-10%
• Network upgrades like Byzantium and Constantinople adjusted uncle rewards
• Post-Merge (PoS transition), uncle blocks no longer exist as validators produce blocks in determined slots

Example Usage

// Get the latest uncle block
async function getLatestUncle() {
  // First, find a recent block with uncles
  let blockNumber = "latest";
  let uncleCount = 0;

  while (uncleCount === 0) {
    // Get the block
    const block = await provider.send("eth_getBlockByNumber", [blockNumber, false]);

    // Check uncle count
    uncleCount = block.uncles.length;

    // If no uncles, check previous block
    if (uncleCount === 0) {
      blockNumber = "0x" + (parseInt(block.number, 16) - 1).toString(16);
    }
  }

  // Once we find a block with uncles, get the first uncle
  const uncleBlock = await provider.send("eth_getUncleByBlockNumberAndIndex", [
    blockNumber,
    "0x0"
  ]);

  return uncleBlock;
}

See also

• eth_getUncleByBlockHashAndIndex - Get uncle block data using the block hash and uncle index
• eth_getUncleCountByBlockNumber - Count the number of uncles in a block using its number
• eth_getBlockByNumber - Get full block information including uncle references