HDP Cairo

HDP (Herodotus Data Processor) is a modular framework for validating on-chain data from multiple blockchain RPC sources, executing user-defined logic written in Cairo1, and producing an execution trace that can be used to generate a zero-knowledge proof. The proof attests to the correctness of both the on-chain data and the performed computation.

---

Quick start (CLI)

curl -fsSL https://raw.githubusercontent.com/HerodotusDev/hdp-cairo/main/install-cli.sh | bash
hdp env-info
hdp dry-run -m module_contract_class.json --print_output
hdp fetch-proofs
hdp sound-run -m module_contract_class.json --print_output

module_contract_class.json is produced by a Scarb build of your Cairo1 module.

Prerequisites

• Rust toolchain: pinned to nightly-2025-04-06 via rust-toolchain.toml. rustup will install it automatically, or run:

  rustup toolchain install nightly-2025-04-06

• uv: Python package manager used to install Cairo0 tooling.

  curl -LsSf https://astral.sh/uv/install.sh | sh

Installation

Option 1: CLI tool (recommended)

curl -fsSL https://raw.githubusercontent.com/HerodotusDev/hdp-cairo/main/install-cli.sh | bash

To install a specific version:

VERSION=vX.X.X curl -fsSL https://raw.githubusercontent.com/HerodotusDev/hdp-cairo/main/install-cli.sh | bash

Option 2: Build from source

1. Clone and init submodules:

   git clone https://github.com/HerodotusDev/hdp-cairo.git
   cd hdp-cairo
   git submodule update --init

2. Install Python deps and Cairo0 tooling:

   uv sync

3. Build the CLI:

   cargo build --release --bin hdp-cli

To use cairo-format from the virtual environment:

source .venv/bin/activate

Toolchain and features

• Default: builds with the pinned nightly toolchain.
• STWO prover input: build with --features stwo.

cargo build --release --bin hdp-cli --features stwo

If you run hdp sound-run --stwo_prover_input ... without --features stwo, the CLI will instruct you to rebuild.

Runtime configuration

The runtime requires RPC access. Use the CLI helpers or copy the example env file:

hdp env-info
hdp env-check --inputs dry_run_output.json
cp example.env .env

RPC variables (see example.env):

• RPC_URL_HERODOTUS_INDEXER
• RPC_URL_ETHEREUM_MAINNET
• RPC_URL_ETHEREUM_TESTNET
• RPC_URL_STARKNET_MAINNET
• RPC_URL_STARKNET_TESTNET
• RPC_URL_OPTIMISM_MAINNET
• RPC_URL_OPTIMISM_TESTNET

hdp fetch-proofs reads the dry-run output and fails fast with the missing variables for the chains used in that run.

Workflow

1. Dry run: simulate the module and collect proof requirements.

   hdp dry-run -m module_contract_class.json --print_output

2. Fetch proofs:

   hdp fetch-proofs

3. Sound run: execute the module with verified data.

   hdp sound-run -m module_contract_class.json --print_output

For source builds, use cargo run --release --bin hdp-cli -- <command>.

Documentation

• docs/ contains the mdBook sources.
• Cairo library details live under docs/src/cairo_library/.

Development and testing

cargo test

Optional:

scarb build
cargo nextest run

To enable integration-heavy tests:

HDP_INTEGRATION_TESTS=1 cargo test

If you see future-incompatible warnings (e.g. size-of), inspect with:

make future-incompat

Note on on-chain finality

Even if local stages (dry run, proof fetching, sound run) succeed, on-chain settlement depends on MMRs (Merkle Mountain Ranges). Blocks accessed must be included in the MMRs within the Herodotus Satellite contracts.

Mentions

Provable ETH call (in hdp_cairo/src/eth_call/) adapts code from Kakarot (kkrt-labs/kakarot-ssj) under the MIT License.

License

hdp-cairo is licensed under the Apache-2.0 license.