> ## 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.

# Official Examples by Use Case

> What each hdp-cairo example demonstrates and which APIs it uses

All examples below are from the official `hdp-cairo` repository:

* [https://github.com/HerodotusDev/hdp-cairo/tree/main/examples](https://github.com/HerodotusDev/hdp-cairo/tree/main/examples)

## Example map

### `starkgate`

* **Goal**: compare L1 bridge balance vs L2 token supply at fixed blocks.
* **APIs**: `hdp.evm.account_get_balance`, `hdp.starknet.storage_get_slot`.
* **Why it matters**: cross-chain solvency/supply checks.
* **Files**:
  * [examples/starkgate/src/lib.cairo](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/starkgate/src/lib.cairo)
  * [examples/starkgate/run.sh](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/starkgate/run.sh)
* **CLI flow**:
  * `hdp dry-run -m target/dev/example_starkgate_module.compiled_contract_class.json --print_output`
  * `hdp fetch-proofs`
  * `hdp sound-run -m target/dev/example_starkgate_module.compiled_contract_class.json --print_output`

### `multi_chain_access`

* **Goal**: read chain header data across Ethereum Sepolia, Starknet, and OP Sepolia in one module.
* **APIs**: `hdp.evm.header_get_parent`, `hdp.starknet.header_get_block_number`.
* **Why it matters**: one proof, multiple chains.
* **Files**:
  * [examples/multi\_chain\_access/src/lib.cairo](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/multi_chain_access/src/lib.cairo)
  * [examples/multi\_chain\_access/run.sh](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/multi_chain_access/run.sh)
  * [examples/multi\_chain\_access/mmr\_hasher\_config.json](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/multi_chain_access/mmr_hasher_config.json)
* **CLI flow**:
  * `hdp dry-run -m target/dev/example_multi_chain_access_module.compiled_contract_class.json --print_output`
  * `hdp fetch-proofs --mmr-hasher-config examples/multi_chain_access/mmr_hasher_config.json`
  * `hdp sound-run -m target/dev/example_multi_chain_access_module.compiled_contract_class.json --print_output`

### `most_bridge`

* **Goal**: verify bridge/order fulfillment logic with storage-slot reads.
* **APIs**: `hdp.evm.storage_get_slot`.
* **Why it matters**: custom protocol logic over proven historical storage.

### `injected_state`

* **Goal**: read/write injected trie state and assert root transitions.
* **APIs**: `hdp.injected_state.read_injected_state_trie_root`, `read_key`, `write_key`.
* **Why it matters**: mix off-chain provided state with strict proof-time constraints.
* **Files**:
  * [examples/injected\_state/src/lib.cairo](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/injected_state/src/lib.cairo)
  * [examples/injected\_state/run.sh](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/injected_state/run.sh)
  * [examples/injected\_state/injected\_state.json](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/injected_state/injected_state.json)
* **CLI flow**:
  * Start [state server](/data-processor/state-server) first
  * `hdp dry-run -m target/dev/example_injected_state_module.compiled_contract_class.json --injected_state examples/injected_state/injected_state.json --print_output`
  * `hdp fetch-proofs`
  * `hdp sound-run -m target/dev/example_injected_state_module.compiled_contract_class.json --injected_state examples/injected_state/injected_state.json --print_output`

### `eth_call`

* **Goal**: provable contract call (`balanceOf`) at a historical Ethereum block.
* **APIs**: `execute_eth_call`.
* **Why it matters**: ABI-level historical reads without manual slot derivation.
* **Files**:
  * [examples/eth\_call/src/lib.cairo](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/eth_call/src/lib.cairo)
  * [examples/eth\_call/run.sh](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/eth_call/run.sh)

### `compliance`

* **Goal**: prove user tx sequence and enforce forbidden counterparty exclusion.
* **APIs**: `hdp.evm.account_get_nonce`, `block_tx_get_nonce`, `block_tx_get_sender`, `block_tx_get_receiver`.
* **Why it matters**: bounded, auditable compliance checks.

### `blacklist`

* **Goal**: scan bounded blocks/tx/logs for event signature + decode event data.
* **APIs**: `header_get_bloom`, `block_receipt_get_bloom`, `block_tx_get_receiver`, `log_get_topic0`, `log_get_data`.
* **Why it matters**: event-driven constraints with authenticity guarantees.

### `all_features_combined`

* **Goal**: combine injected state + EVM header/storage/account reads in one module.
* **APIs**: mixed APIs across `injected_state` and `evm`.
* **Why it matters**: reference for composing multiple HDP features together.

## How to use these examples effectively

1. Pick the nearest example for your use case.
2. Keep the key structure and constraint style.
3. Replace addresses, slots, block numbers, and assertions with your domain logic.
4. Add explicit completeness/uniqueness constraints when proving subsets.