Skip to main content
This page is a placeholder. All examples on this page are currently AI-generated and are not correct. This documentation will be completed in the future with accurate, tested examples.

Overview

Block context instructions provide access to blockchain environment data within smart contract execution. These opcodes allow contracts to query information about the current block, historical blocks, and chain configuration. Opcode Range: 0x40 - 0x4A (11 opcodes)

Instructions

Core Block Information

OpcodeNameGasIntroducedDescription
0x40BLOCKHASH20FrontierGet hash of recent block
0x41COINBASE2FrontierGet block beneficiary address
0x42TIMESTAMP2FrontierGet block timestamp
0x43NUMBER2FrontierGet block number
0x44DIFFICULTY2FrontierGet block difficulty (PREVRANDAO post-Merge)
0x45GASLIMIT2FrontierGet block gas limit

Chain and Account Context

OpcodeNameGasIntroducedDescription
0x46CHAINID2IstanbulGet chain identifier
0x47SELFBALANCE5IstanbulGet balance of executing contract

EIP-4844 Blob Context

OpcodeNameGasIntroducedDescription
0x49BLOBHASH3CancunGet versioned blob hash by index
0x4ABLOBBASEFEE2CancunGet current blob base fee

Historical Evolution

Frontier (Genesis)

  • BLOCKHASH, COINBASE, TIMESTAMP, NUMBER, DIFFICULTY, GASLIMIT
  • Original block context operations for basic blockchain awareness

Istanbul (EIP-1344, EIP-1884)

  • CHAINID - Enable replay protection across different chains
  • SELFBALANCE - More efficient balance queries for current contract

Paris (The Merge)

  • DIFFICULTY repurposed as PREVRANDAO for post-merge randomness

Cancun (EIP-4844)

  • BLOBHASH, BLOBBASEFEE - Support for proto-danksharding blob transactions

Common Patterns

Timestamp-Based Logic

// Time-locked functionality
contract TimeLock {
    uint256 public unlockTime;

    function withdraw() public {
        require(block.timestamp >= unlockTime, "Still locked");
        // Withdrawal logic
    }
}

Block-Based Randomness (Legacy)

// DEPRECATED: Not secure for production
function randomNumber() public view returns (uint256) {
    return uint256(keccak256(abi.encodePacked(
        blockhash(block.number - 1),
        block.timestamp,
        block.difficulty  // Now PREVRANDAO post-merge
    )));
}

Chain-Specific Behavior

// Cross-chain contract behavior
function getToken() internal view returns (address) {
    if (block.chainid == 1) return MAINNET_TOKEN;
    if (block.chainid == 137) return POLYGON_TOKEN;
    revert("Unsupported chain");
}

Historical Block Queries

// Verify past block hash
function verifyProof(uint256 blockNumber, bytes32 expectedHash) public view returns (bool) {
    require(block.number - blockNumber <= 256, "Block too old");
    return blockhash(blockNumber) == expectedHash;
}

Gas Costs Summary

CategoryGas CostOpcodes
Fast3BLOBHASH
Quick2COINBASE, TIMESTAMP, NUMBER, DIFFICULTY, GASLIMIT, CHAINID, BLOBBASEFEE
Fast5SELFBALANCE
Ext20BLOCKHASH

Security Considerations

Timestamp Manipulation

Block timestamps can be manipulated by miners within bounds (±15 seconds typically):
// VULNERABLE: Exact timestamp matching
require(block.timestamp == expectedTime);

// SAFER: Range checking
require(block.timestamp >= startTime && block.timestamp <= endTime);

Blockhash Limitations

BLOCKHASH only returns hashes for the most recent 256 blocks:
function getBlockHash(uint256 blockNum) public view returns (bytes32) {
    require(blockNum < block.number, "Future block");
    require(block.number - blockNum <= 256, "Block too old");
    return blockhash(blockNum);
}

PREVRANDAO Considerations

Post-merge, DIFFICULTY returns PREVRANDAO - beacon chain randomness:
  • More unpredictable than PoW difficulty
  • Still not suitable for high-stakes randomness
  • Use Chainlink VRF for critical applications

Chain ID Replay Protection

Always include block.chainid in transaction hashing for cross-chain protection:
// EIP-155: Replay-protected transaction signing
bytes32 hash = keccak256(abi.encodePacked(
    nonce, gasPrice, gasLimit, to, value, data, chainId, 0, 0
));

Implementation Notes

TypeScript Usage

import { BlockHandlers } from '@tevm/voltaire/evm/block';
import { createFrame } from '@tevm/voltaire/evm/Frame';

// Create frame with block context
const frame = createFrame({
  blockContext: {
    block_number: 18_000_000n,
    block_timestamp: 1696000000n,
    block_coinbase: coinbaseAddress,
    block_gas_limit: 30_000_000n,
    block_base_fee: 20_000_000_000n,
    chain_id: 1n,
  }
});

// Execute block opcode
const handlers = BlockHandlers(frame);
const err = handlers.timestamp(frame);

References