Skip to content

Commit 4b2139d

Browse files
Okm165Okm165
committed
Refresh README quick start and runtime guidance
1 parent 0a12ad0 commit 4b2139d

File tree

1 file changed

+111
-127
lines changed

1 file changed

+111
-127
lines changed

‎README.md‎

Lines changed: 111 additions & 127 deletions
Original file line numberDiff line numberDiff line change
@@ -1,187 +1,171 @@
11
# HDP Cairo
22

3-
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.
4-
5-
---
3+
HDP (Herodotus Data Processor) validates on-chain data across multiple chains, runs user-defined Cairo1 logic, and
4+
produces an execution trace suitable for zero-knowledge proofs.
65

76
<p align="center">
87
<img src="./docs/HDPCairo.png" alt="HDP Cairo">
98
</p>
109

11-
---
12-
1310
<p align="left">
1411
<a href="https://herodotusdev.github.io/hdp-cairo/program_hash.json">
1512
<img src="https://img.shields.io/badge/dynamic/json?url=https://herodotusdev.github.io/hdp-cairo/program_hash.json&query=$.program_hash&label=program_hash&color=blue&style=flat-square" alt="program_hash">
1613
</a>
1714
</p>
1815

19-
---
20-
21-
## Installation
22-
23-
### Prerequisites
24-
25-
Both installation methods require Rust and `uv` (Python package manager):
26-
27-
1. **Install Rust**: If you don't have Rust, install it via `rustup`.
28-
29-
```sh
30-
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
31-
```
32-
33-
2. **Install uv**: Install the `uv` Python package manager.
34-
35-
```sh
36-
curl -LsSf https://astral.sh/uv/install.sh | sh
37-
```
38-
39-
### Option 1: Using CLI Tool (Recommended)
40-
41-
Install the HDP CLI tool using the installation script:
16+
## Quick start (CLI)
4217

4318
```sh
4419
curl -fsSL https://raw.githubusercontent.com/HerodotusDev/hdp-cairo/main/install-cli.sh | bash
20+
hdp env-info
21+
hdp dry-run -m module_contract_class.json --print_output
22+
hdp fetch-proofs
23+
hdp sound-run -m module_contract_class.json --print_output
4524
```
4625

47-
> To install a specific version:
48-
>
49-
> ```sh
50-
> VERSION=vX.X.X curl -fsSL https://raw.githubusercontent.com/HerodotusDev/hdp-cairo/main/install-cli.sh | bash
51-
> ```
52-
53-
---
54-
55-
### Option 2: Manual Build from Source
56-
57-
This project uses `uv` for Python package management and `cargo` for Rust.
58-
59-
#### Build Steps
60-
61-
1. **Clone the Repository**: Clone the repository and initialize the submodules.
62-
63-
```sh
64-
git clone https://github.com/HerodotusDev/hdp-cairo.git
65-
cd hdp-cairo
66-
git submodule update --init
67-
```
68-
69-
2. **Create Virtual Environment**: This command creates a `.venv` directory and installs all Python packages specified in `pyproject.toml`.
70-
71-
```sh
72-
uv sync
73-
```
74-
75-
3. **Activate Virtual Environment**: To use tools like `cairo-format`, you need to activate the environment.
76-
77-
```sh
78-
source .venv/bin/activate
79-
```
80-
81-
---
82-
83-
## Running
84-
85-
The runtime requires RPC calls to blockchain nodes. Set up your environment variables:
26+
`module_contract_class.json` is produced by a Scarb build of your Cairo1 module.
8627

87-
- **Using CLI**: Run `hdp env-info` to see the required environment variables and get an example `.env` file.
88-
- **Manual Build**: Copy the example environment file and edit it:
28+
## Prerequisites
8929

30+
- **Rust toolchain**: pinned to `nightly-2025-04-06` via `rust-toolchain.toml`.
31+
`rustup` will install it automatically, or run:
9032
```sh
91-
cp example.env .env
33+
rustup toolchain install nightly-2025-04-06
34+
```
35+
- **uv**: Python package manager used to install Cairo0 tooling.
36+
```sh
37+
curl -LsSf https://astral.sh/uv/install.sh | sh
9238
```
9339

94-
Edit the `.env` file to provide the correct RPC endpoints and configuration details.
40+
## Installation
9541

96-
1. **Simulate Cairo1 Module & Collect Proof Information**:
97-
This step performs a dry run of your Cairo module. `module_contract_class.json` is a compiled contract from a Scarb build.
42+
### Option 1: CLI tool (recommended)
9843

99-
**Using CLI**:
44+
```sh
45+
curl -fsSL https://raw.githubusercontent.com/HerodotusDev/hdp-cairo/main/install-cli.sh | bash
46+
```
10047

101-
```sh
102-
hdp dry-run -m module_contract_class.json --print_output
103-
```
48+
To install a specific version:
10449

105-
**Manual Build**:
50+
```sh
51+
VERSION=vX.X.X curl -fsSL https://raw.githubusercontent.com/HerodotusDev/hdp-cairo/main/install-cli.sh | bash
52+
```
10653

107-
```sh
108-
cargo run --release --bin hdp-cli -- dry-run -m module_contract_class.json --print_output
109-
```
54+
### Option 2: Build from source
55+
56+
1. Clone and init submodules:
57+
```sh
58+
git clone https://github.com/HerodotusDev/hdp-cairo.git
59+
cd hdp-cairo
60+
git submodule update --init
61+
```
62+
2. Install Python deps and Cairo0 tooling:
63+
```sh
64+
uv sync
65+
```
66+
3. Build the CLI:
67+
```sh
68+
cargo build --release --bin hdp-cli
69+
```
70+
71+
To use `cairo-format` from the virtual environment:
11072

111-
2. **Fetch On-Chain Proofs**:
112-
This command fetches the necessary on-chain proofs required for the HDP run.
73+
```sh
74+
source .venv/bin/activate
75+
```
11376

114-
**Using CLI**:
77+
## Toolchain and features
11578

116-
```sh
117-
hdp fetch-proofs
118-
```
79+
- **Default**: builds with the pinned nightly toolchain.
80+
- **STWO prover input**: build with `--features stwo`.
11981

120-
**Manual Build**:
82+
```sh
83+
cargo build --release --bin hdp-cli --features stwo
84+
```
12185

122-
```sh
123-
cargo run --release --bin hdp-cli --features progress_bars -- fetch-proofs
124-
```
86+
If you run `hdp sound-run --stwo_prover_input ...` without `--features stwo`, the CLI will instruct you to rebuild.
12587

126-
3. **Run Cairo1 Module with Verified Data**:
127-
This executes the module with verified on-chain data.
88+
## Runtime configuration
12889

129-
**Using CLI**:
90+
The runtime requires RPC access. Use the CLI helpers or copy the example env file:
13091

131-
```sh
132-
hdp sound-run -m module_contract_class.json --print_output
133-
```
92+
```sh
93+
hdp env-info
94+
hdp env-check --inputs dry_run_output.json
95+
cp example.env .env
96+
```
13497

135-
**Manual Build**:
98+
RPC variables (see `example.env`):
13699

137-
```sh
138-
cargo run --release --bin hdp-cli -- sound-run -m module_contract_class.json --print_output
139-
```
100+
- `RPC_URL_HERODOTUS_INDEXER`
101+
- `RPC_URL_ETHEREUM_MAINNET`
102+
- `RPC_URL_ETHEREUM_TESTNET`
103+
- `RPC_URL_STARKNET_MAINNET`
104+
- `RPC_URL_STARKNET_TESTNET`
105+
- `RPC_URL_OPTIMISM_MAINNET`
106+
- `RPC_URL_OPTIMISM_TESTNET`
140107

141-
The program will output the **results root** and **tasks root**, which can be used to extract the results from the on-chain contract.
108+
`hdp fetch-proofs` reads the dry-run output and fails fast with the missing variables for the chains used in that run.
142109

143-
---
110+
## Workflow
144111

145-
## Testing
112+
1. **Dry run**: simulate the module and collect proof requirements.
113+
```sh
114+
hdp dry-run -m module_contract_class.json --print_output
115+
```
116+
2. **Fetch proofs**:
117+
```sh
118+
hdp fetch-proofs
119+
```
120+
3. **Sound run**: execute the module with verified data.
121+
```sh
122+
hdp sound-run -m module_contract_class.json --print_output
123+
```
146124

147-
Tests also require chain node RPC calls, so make sure your `.env` file is set up correctly.
125+
For source builds, use `cargo run --release --bin hdp-cli -- <command>`.
148126

149-
1. **Build Cairo1 Modules**:
127+
## Documentation
150128

151-
```sh
152-
scarb build
153-
```
129+
- `docs/` contains the mdBook sources.
130+
- Cairo library details live under `docs/src/cairo_library/`.
154131

155-
2. **Run Tests**:
156-
Execute the test suite using `nextest`.
132+
## Development and testing
157133

158-
```sh
159-
cargo nextest run
160-
```
134+
```sh
135+
cargo test
136+
```
161137

162-
---
138+
Optional:
163139

164-
## Note on On-Chain Finality
140+
```sh
141+
scarb build
142+
cargo nextest run
143+
```
165144

166-
Even if all local stages (dry run, proof fetching, sound run) succeed, on-chain settlement depends on the **MMRs (Merkle Mountain Ranges)**. The data for all accessed values must be present in the MMRs inside [Herodotus Satellite contracts](https://github.com/HerodotusDev/satellite) used for settlement.
145+
To enable integration-heavy tests:
167146

168-
This means the blocks you are accessing must have been included in the settlement contract's MMRs. This is a critical consideration, especially when mixing testnet and mainnet data or for cross-chain access within the same HDP module. If you encounter issues during on-chain settlement, verify that the relevant block numbers have been included in the on-chain MMRs.
147+
```sh
148+
HDP_INTEGRATION_TESTS=1 cargo test
149+
```
169150

170-
---
151+
If you see future-incompatible warnings (e.g. `size-of`), inspect with:
171152

172-
## Mentions
153+
```sh
154+
make future-incompat
155+
```
173156

174-
Provable ETH call (located in [hdp_cairo/src/eth_call](./hdp_cairo/src/eth_call/)) makes use of code adapted from [**Kakarot**](https://github.com/kkrt-labs) [(@kkrt-labs/kakarot-ssj)](https://github.com/kkrt-labs/kakarot-ssj) under the [MIT License](https://github.com/kkrt-labs/kakarot-ssj/blob/main/LICENSE).
157+
## Note on on-chain finality
175158

176-
Thanks for all the hard work guys 🙏
159+
Even if local stages (dry run, proof fetching, sound run) succeed, on-chain settlement depends on **MMRs (Merkle
160+
Mountain Ranges)**. Blocks accessed must be included in the MMRs within the
161+
[Herodotus Satellite contracts](https://github.com/HerodotusDev/satellite).
177162

178-
> Original project: https://github.com/kkrt-labs/kakarot-ssj
179-
> License file: https://github.com/kkrt-labs/kakarot-ssj/blob/main/LICENSE
163+
## Mentions
180164

181-
---
165+
Provable ETH call (in `hdp_cairo/src/eth_call/`) adapts code from
166+
[Kakarot](https://github.com/kkrt-labs) ([kkrt-labs/kakarot-ssj](https://github.com/kkrt-labs/kakarot-ssj))
167+
under the [MIT License](https://github.com/kkrt-labs/kakarot-ssj/blob/main/LICENSE).
182168

183169
## License
184170

185171
`hdp-cairo` is licensed under the [Apache-2.0 license](./LICENSE).
186-
187-
---

0 commit comments

Comments
 (0)