> ## Documentation Index
> Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# BlockHeader

> Ethereum block header with metadata and Merkle roots

## Overview

BlockHeader contains all metadata for a block including Merkle roots, gas limits, timestamps, and consensus-related fields. The block hash is computed from RLP(header).

```typescript theme={null}
import * as BlockHeader from '@voltaire/primitives/BlockHeader'

const header = BlockHeader.from({
  parentHash: "0x...",
  ommersHash: "0x...",
  beneficiary: "0x...",
  stateRoot: "0x...",
  transactionsRoot: "0x...",
  receiptsRoot: "0x...",
  logsBloom: new Uint8Array(256),
  difficulty: 0n,
  number: 18000000n,
  gasLimit: 30000000n,
  gasUsed: 15000000n,
  timestamp: 1700000000n,
  extraData: new Uint8Array(0),
  mixHash: "0x...",
  nonce: new Uint8Array(8),
  baseFeePerGas: 30000000000n,
})
```

## Type Definition

```typescript theme={null}
type BlockHeaderType = {
  readonly parentHash: BlockHashType
  readonly ommersHash: HashType
  readonly beneficiary: AddressType
  readonly stateRoot: HashType
  readonly transactionsRoot: HashType
  readonly receiptsRoot: HashType
  readonly logsBloom: Uint8Array         // 256 bytes
  readonly difficulty: Uint256Type
  readonly number: BlockNumberType
  readonly gasLimit: Uint256Type
  readonly gasUsed: Uint256Type
  readonly timestamp: Uint256Type
  readonly extraData: Uint8Array         // max 32 bytes
  readonly mixHash: HashType
  readonly nonce: Uint8Array             // 8 bytes
  readonly baseFeePerGas?: Uint256Type   // EIP-1559 (London)
  readonly withdrawalsRoot?: HashType    // Shanghai
  readonly blobGasUsed?: Uint256Type     // EIP-4844 (Cancun)
  readonly excessBlobGas?: Uint256Type   // EIP-4844 (Cancun)
  readonly parentBeaconBlockRoot?: HashType // EIP-4788 (Cancun)
}
```

## Creating BlockHeader

### from

Universal constructor with all header fields.

```typescript theme={null}
const header = BlockHeader.from({
  // Required fields (all blocks)
  parentHash: "0x1234...",
  ommersHash: "0x1dcc...", // Usually empty hash post-merge
  beneficiary: "0xfee...",  // Fee recipient
  stateRoot: "0xabcd...",
  transactionsRoot: "0xef01...",
  receiptsRoot: "0x2345...",
  logsBloom: new Uint8Array(256),
  difficulty: 0n,          // 0 post-merge
  number: 18500000n,
  gasLimit: 30000000n,
  gasUsed: 12345678n,
  timestamp: 1700000000n,
  extraData: new Uint8Array(0),
  mixHash: "0x0000...",    // 0 post-merge
  nonce: new Uint8Array(8), // 0 post-merge

  // EIP-1559 (London fork)
  baseFeePerGas: 30000000000n,

  // Shanghai fork
  withdrawalsRoot: "0x5678...",

  // EIP-4844 (Cancun fork)
  blobGasUsed: 262144n,
  excessBlobGas: 0n,
  parentBeaconBlockRoot: "0x9abc...",
})
```

## Header Fields by Fork

### Genesis (All Blocks)

| Field            | Description                     |
| ---------------- | ------------------------------- |
| parentHash       | Hash of parent block            |
| ommersHash       | Hash of ommers list RLP         |
| beneficiary      | Block reward recipient          |
| stateRoot        | State trie root after execution |
| transactionsRoot | Transactions trie root          |
| receiptsRoot     | Receipts trie root              |
| logsBloom        | 256-byte bloom filter for logs  |
| difficulty       | PoW difficulty (0 post-merge)   |
| number           | Block height                    |
| gasLimit         | Max gas for block               |
| gasUsed          | Total gas consumed              |
| timestamp        | Unix timestamp (seconds)        |
| extraData        | Arbitrary data (max 32 bytes)   |
| mixHash          | PoW mix hash (0 post-merge)     |
| nonce            | PoW nonce (0 post-merge)        |

### EIP-1559 (London Fork)

| Field         | Description              |
| ------------- | ------------------------ |
| baseFeePerGas | Dynamic base fee per gas |

### Shanghai Fork

| Field           | Description                |
| --------------- | -------------------------- |
| withdrawalsRoot | Merkle root of withdrawals |

### EIP-4844 (Cancun Fork)

| Field                 | Description                 |
| --------------------- | --------------------------- |
| blobGasUsed           | Total blob gas used         |
| excessBlobGas         | Excess blob gas for pricing |
| parentBeaconBlockRoot | Beacon chain parent root    |

## Post-Merge Changes

After The Merge, several fields are deprecated but still present:

```typescript theme={null}
const postMergeHeader = BlockHeader.from({
  // ...other fields
  difficulty: 0n,               // Always 0
  mixHash: "0x" + "00".repeat(32), // RANDAO reveal
  nonce: new Uint8Array(8),     // Always 0
})
```

## See Also

* [BlockHeader (Effect)](https://voltaire-effect.tevm.sh/primitives/block-header) - Effect.ts integration with Schema validation
* [Block](/primitives/block) - Complete block type
* [BlockBody](/primitives/block-body) - Block body
* [BlockHash](/primitives/block-hash) - Block identifier
* [BloomFilter](/primitives/bloomfilter) - Logs bloom filter