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

# HDP Capabilities and API Surface

> Everything available through the HDP object in Cairo modules

HDP exposes four capability groups in your Cairo module:

* `hdp.evm` for EVM data
* `hdp.starknet` for Starknet data
* `hdp.injected_state` for injected trie state
* `hdp.unconstrained` helpers for unconstrained reads

It also exposes `execute_eth_call` for provable EVM contract calls at a chosen historical block.

## HDP object in your module

```cairo theme={null}
pub struct HDP {
    pub evm: EvmMemorizer,
    pub starknet: StarknetMemorizer,
    pub injected_state: InjectedStateMemorizer,
    pub unconstrained: UnconstrainedMemorizer,
}
```

## 1) `hdp.evm` (EVM memorizer)

Reads verified EVM data for a specific `(chain_id, block_number, ...)` key.

Chain constants:

* `ETHEREUM_MAINNET_CHAIN_ID`
* `ETHEREUM_TESTNET_CHAIN_ID`
* `OPTIMISM_MAINNET_CHAIN_ID`
* `OPTIMISM_TESTNET_CHAIN_ID`

### Header fields

**Input key for all methods below:** `HeaderKey { chain_id, block_number }`

| API | Output | What it gives you |
| - | - | - |
| `header_get_parent` | `u256` | Parent block hash of the block header |
| `header_get_uncle` | `u256` | Uncle/ommer hash field from the header |
| `header_get_coinbase` | `u256` | Block proposer (beneficiary) address |
| `header_get_state_root` | `u256` | Global EVM state root for that block |
| `header_get_transaction_root` | `u256` | Transaction trie root for that block |
| `header_get_receipt_root` | `u256` | Receipt trie root for that block |
| `header_get_bloom` | `ByteArray` | Header bloom filter for event prefiltering |
| `header_get_difficulty` | `u256` | Block difficulty field |
| `header_get_number` | `u256` | Block number from the header |
| `header_get_gas_limit` | `u256` | Block gas limit |
| `header_get_gas_used` | `u256` | Total gas used in that block |
| `header_get_timestamp` | `u256` | Block timestamp |
| `header_get_mix_hash` | `u256` | Header mix hash field |
| `header_get_nonce` | `u256` | Header nonce field |
| `header_get_base_fee_per_gas` | `u256` | EIP-1559 base fee for the block |
| `header_get_blob_gas_used` | `u256` | Blob gas used (EIP-4844 field) |
| `header_get_excess_blob_gas` | `u256` | Excess blob gas (EIP-4844 field) |
| `header_get_requests_hash` | `u256` | Requests hash field from the header |

### Account fields

**Input key for all methods below:** `AccountKey { chain_id, block_number, address }`

| API | Output | What it gives you |
| - | - | - |
| `account_get_nonce` | `u256` | Account nonce at the selected block |
| `account_get_balance` | `u256` | Account ETH balance at the selected block |
| `account_get_state_root` | `u256` | Account storage root |
| `account_get_code_hash` | `u256` | Account bytecode hash |

### Storage

| API | Input | Output | What it gives you |
| - | - | - | - |
| `storage_get_slot` | `StorageKey { chain_id, block_number, address, storage_slot }` | `u256` | Value of a specific storage slot for a contract at that block |

### Block transactions

**Input key for all methods below:** `BlockTxKey { chain_id, block_number, transaction_index }`

| API | Output | What it gives you |
| - | - | - |
| `block_tx_get_nonce` | `u256` | Nonce of a transaction by block/index |
| `block_tx_get_gas_price` | `u256` | Legacy gas price of the transaction |
| `block_tx_get_gas_limit` | `u256` | Gas limit set on the transaction |
| `block_tx_get_receiver` | `u256` | Recipient address (`to`) |
| `block_tx_get_value` | `u256` | Native token value transferred |
| `block_tx_get_v` | `u256` | Signature `v` component |
| `block_tx_get_r` | `u256` | Signature `r` component |
| `block_tx_get_s` | `u256` | Signature `s` component |
| `block_tx_get_chain_id` | `u256` | Transaction chain id |
| `block_tx_get_max_fee_per_gas` | `u256` | EIP-1559 max fee per gas |
| `block_tx_get_max_priority_fee_per_gas` | `u256` | EIP-1559 priority fee |
| `block_tx_get_max_fee_per_blob_gas` | `u256` | EIP-4844 max fee per blob gas |
| `block_tx_get_tx_type` | `u256` | Transaction type |
| `block_tx_get_sender` | `u256` | Sender address (`from`) |
| `block_tx_get_hash` | `u256` | Transaction hash |

### Block receipts

**Input key for all methods below:** `BlockReceiptKey { chain_id, block_number, transaction_index }`

| API | Output | What it gives you |
| - | - | - |
| `block_receipt_get_status` | `u256` | Execution status of a transaction receipt |
| `block_receipt_get_cumulative_gas_used` | `u256` | Cumulative gas used at this receipt index |
| `block_receipt_get_bloom` | `ByteArray` | Receipt bloom for event filtering |

### Logs

**Input key for all methods below:** `LogKey { chain_id, block_number, transaction_index, log_index }`

| API | Output | What it gives you |
| - | - | - |
| `log_get_address` | `u256` | Contract address that emitted the log |
| `log_get_topic0` | `u256` | First topic (usually event signature hash) |
| `log_get_topic1` | `u256` | Second indexed topic |
| `log_get_topic2` | `u256` | Third indexed topic |
| `log_get_topic3` | `u256` | Fourth indexed topic |
| `log_get_topic4` | `u256` | Fifth topic when present |
| `log_get_data` | `Array<u128>` | Unindexed event data payload |

## 2) `hdp.starknet` (Starknet memorizer)

Reads verified Starknet data for a specific `(chain_id, block_number, ...)` key.

Chain constants:

* `STARKNET_MAINNET_CHAIN_ID`
* `STARKNET_TESTNET_CHAIN_ID`

### Header fields

**Input key for all methods below:** `HeaderKey { chain_id, block_number }`

| API | Output | What it gives you |
| - | - | - |
| `header_get_block_number` | `felt252` | Starknet block number |
| `header_get_state_root` | `felt252` | Global Starknet state root |
| `header_get_sequencer_address` | `felt252` | Sequencer address for that block |
| `header_get_block_timestamp` | `felt252` | Block timestamp |
| `header_get_transaction_count` | `felt252` | Number of transactions in the block |
| `header_get_transaction_commitment` | `felt252` | Transaction commitment value |
| `header_get_event_count` | `felt252` | Number of events in the block |
| `header_get_event_commitment` | `felt252` | Event commitment value |
| `header_get_parent_block_hash` | `felt252` | Parent block hash |
| `header_get_state_diff_commitment` | `felt252` | State diff commitment |
| `header_get_state_diff_length` | `felt252` | State diff length |
| `header_get_l1_gas_price_in_wei` | `felt252` | L1 gas price (wei unit field) |
| `header_get_l1_gas_price_in_fri` | `felt252` | L1 gas price (fri unit field) |
| `header_get_l1_data_gas_price_in_wei` | `felt252` | L1 data gas price (wei unit field) |
| `header_get_l1_data_gas_price_in_fri` | `felt252` | L1 data gas price (fri unit field) |
| `header_get_receipts_commitment` | `felt252` | Receipts commitment value |
| `header_get_l1_data_mode` | `felt252` | L1 data availability mode field |
| `header_get_protocol_version` | `felt252` | Protocol version field |

### Storage

| API | Input | Output | What it gives you |
| - | - | - | - |
| `storage_get_slot` | `StorageKey { chain_id, block_number, address, storage_slot }` | `felt252` | Value of a specific Starknet storage slot at that block |

## 3) `hdp.injected_state` (InjectedState memorizer)

Works with labeled trie-like injected state you provide for a run.

| API | Input | Output | What it gives you |
| - | - | - | - |
| `read_injected_state_trie_root(label)` | `label: felt252` | `Option<felt252>` | Current root for the labeled injected trie |
| `read_key(label, key)` | `label: felt252, key: felt252` | `Option<felt252>` | Value for a key in the labeled injected trie |
| `write_key(label, key, value)` | `label: felt252, key: felt252, value: felt252` | `felt252` | Writes a value and returns the updated trie root |

## 4) `hdp.unconstrained` / unconstrained helpers

| API | Input | Output | What it gives you |
| - | - | - | - |
| `evm_account_get_bytecode(key)` | `AccountKey { chain_id, block_number, address }` | `ByteCode` | Contract bytecode for an EVM account at a chosen block |

## 5) `execute_eth_call` (provable EVM call)

`execute_eth_call` lets you perform a provable EVM contract call at a chosen historical block.

| Item | What it means |
| - | - |
| Input `HDP` | Access to HDP-backed verified chain state |
| Input `TimeAndSpace { chain_id, block_number }` | Selects which chain and historical block to execute against |
| Input `sender` | Caller address context for the call |
| Input `target` | Contract being called |
| Input `calldata` | ABI-encoded function selector + arguments |
| Output `success` | Whether the call execution succeeded |
| Output `return_data` | Raw return bytes from the contract |
| Output `gas_used` | Gas consumed by the call execution |
| Output `state` | Post-call execution state object |

See the dedicated page for details and patterns:

* [Provable EVM Contract Calls (`execute_eth_call`)](/data-processor/eth-call)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.