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

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)