# Applicative Recursion
Source: https://docs.herodotus.cloud/atlantic-api/applicative-recursion
Applicative Recursion (AR) enables you to submit multiple queries to the same bucket and verify them together as a single on-chain operation.
## Overview
Applicative Recursion (AR) lets you group multiple Atlantic queries into a single
bucket and verify them together as one on-chain operation. This is useful for
batch workloads where you want one aggregated verification outcome.
## AR Flow
The Applicative Recursion workflow consists of four main steps:
### 1. Create Bucket
First, you need to create a bucket that will contain your related queries.
Create a new Atlantic bucket for grouping related queries
**Endpoint:** `POST /buckets`
**Required Parameters:**
* `aggregatorVersion`: The version of the aggregator to use (e.g., "snos\_aggregator\_0.14.1")
**Optional Parameters:**
* `externalId`: Custom identifier for the bucket
* `nodeWidth`: Width of the node (integer)
* `aggregatorParams`: Additional parameters for the aggregator
**Response:**
```json theme={null}
{
"atlanticBucket": {
"id": "bucket_123456",
"externalId": "my-custom-id",
"status": "OPEN",
"aggregatorVersion": "snos_aggregator_0.14.1",
"nodeWidth": 4,
"leaves": 0,
"createdAt": "2024-01-01T00:00:00Z"
}
}
```
### 2. Submit Queries with Bucket ID
Once you have a bucket, you can submit multiple queries to it. Each query must include:
* `bucketId`: The ID of the bucket you created
* `bucketJobIndex`: An incremental index (0, 1, 2, ...) for each query in the bucket
Submit queries to a bucket with incremental job indices
**Endpoint:** `POST /atlantic-query`
**AR-Specific Parameters:**
* `bucketId`: The ID of the bucket to submit the query to
* `bucketJobIndex`: The index of the job inside the bucket (must be sequential)
**Example Request Body:**
```json theme={null}
{
"declaredJobSize": "M",
"bucketId": "bucket_123456",
"bucketJobIndex": 0,
"programFile": "program.json",
"result": "PROOF_GENERATION"
}
```
**Important Notes:**
* Use the [Swagger UI](https://atlantic.api.herodotus.cloud/docs#/Atlantic%20Query/post_atlantic_query) for submitting queries due to file upload limitations
* Job indices must be sequential (0, 1, 2, ...)
### 3. Close Bucket
After submitting all your queries to the bucket, you need to close it to signal that no more queries will be added.
Close a bucket to finalize the batch processing
**Endpoint:** `POST /buckets/close`
**Parameters:**
* `bucketId`: The ID of the bucket to close
**Response:**
```json theme={null}
{
"atlanticBucket": {
"id": "bucket_123456",
"status": "IN_PROGRESS",
"aggregatorVersion": "snos_aggregator_0.14.1",
"chain": "L1",
"projectId": "proj_123",
"createdAt": "2024-01-01T00:00:00Z"
}
}
```
### 4. Wait for Results
Once the bucket is closed, Atlantic will process all queries in the bucket and aggregate the results. You can monitor the bucket status using the get bucket endpoint.
Check the status and results of your bucket
**Bucket Status Values:**
* `OPEN`: Bucket is open and accepting queries
* `IN_PROGRESS`: Bucket is closed and processing queries
* `DONE`: All queries in the bucket have been processed successfully
* `FAILED`: One or more queries in the bucket failed
## Managing AR Buckets
You can view and manage your **Applicative Recursion** buckets through the [Herodotus Cloud console](https://www.herodotus.cloud/en/buckets). The interface provides a comprehensive view of all your buckets with their current status and details.
## Bucket Details View
When you select a specific bucket, you can see its details.
## Bucket Tree Structure
The **Applicative Recursion** system creates a tree-like structure.
## Complete Example
Here's a complete example of using **Applicative Recursion**:
### Step 1: Create Bucket
```bash theme={null}
curl -X POST "https://atlantic.api.herodotus.cloud/buckets" \
-H "api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"aggregatorVersion": "snos_aggregator_0.14.1",
"externalId": "my-batch-1"
}'
```
### Step 2: Submit Multiple Queries
```bash theme={null}
# Submit first query
curl -X POST "https://atlantic.api.herodotus.cloud/atlantic-query" \
-H "api-key: YOUR_API_KEY" \
-F "declaredJobSize=M" \
-F "bucketId=bucket_123456" \
-F "bucketJobIndex=0" \
-F "programFile=@program1.json" \
-F "result=PROOF_GENERATION"
# Submit second query
curl -X POST "https://atlantic.api.herodotus.cloud/atlantic-query" \
-H "api-key: YOUR_API_KEY" \
-F "declaredJobSize=M" \
-F "bucketId=bucket_123456" \
-F "bucketJobIndex=1" \
-F "programFile=@program2.json" \
-F "result=PROOF_GENERATION"
# Submit third query
curl -X POST "https://atlantic.api.herodotus.cloud/atlantic-query" \
-H "api-key: YOUR_API_KEY" \
-F "declaredJobSize=M" \
-F "bucketId=bucket_123456" \
-F "bucketJobIndex=2" \
-F "programFile=@program3.json" \
-F "result=PROOF_GENERATION"
```
### Step 3: Close Bucket
```bash theme={null}
curl -X POST "https://atlantic.api.herodotus.cloud/buckets/close?bucketId=bucket_123456" \
-H "api-key: YOUR_API_KEY"
```
### Step 4: Monitor Results
```bash theme={null}
curl -X GET "https://atlantic.api.herodotus.cloud/buckets/bucket_123456" \
-H "api-key: YOUR_API_KEY"
```
## Related Endpoints
View all your buckets
Get detailed bucket information
# Console
Source: https://docs.herodotus.cloud/atlantic-api/console
Access the Herodotus Cloud Console to manage Atlantic API keys, monitor proof generation, and track usage
Use the Herodotus Cloud Console to manage Atlantic projects, keys, and query runs.
Sign in and manage your Atlantic workspace.
Set up your account and copy your API key.
Track in-progress and completed queries.
Configure real-time query notifications.
# Contract Addresses
Source: https://docs.herodotus.cloud/atlantic-api/contract-addresses
Smart contract addresses for Atlantic STARK proof verification on Ethereum, StarkNet, and other supported chains
## Satellite Contracts
### EVM Chains
| Chain | Chain ID | Address |
| ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ethereum Sepolia | 11155111 | [0x396bF739f7b37D81f6CdD4571fDEF298150db88f](https://sepolia.etherscan.io/address/0x396bF739f7b37D81f6CdD4571fDEF298150db88f#multipleProxyContract) |
| Ethereum Mainnet | 1 | [0x2e6f182b06f37cbdc966ff5471c7d98cec2bfe70](https://etherscan.io/address/0x2e6f182b06f37cbdc966ff5471c7d98cec2bfe70#multipleProxyContract) |
| Curtis (Apechain testnet) | 33111 | [0x33f4d13f2D491b0bdc3451046708De0DeD794207](https://curtis.explorer.caldera.xyz/address/0x33f4d13f2D491b0bdc3451046708De0DeD794207?tab=read_proxy) |
| Apechain (Mainnet) | 33139 | [0x82F29Af756036132Ec188FFbB48447895a8D339e](https://apescan.io/address/0x82F29Af756036132Ec188FFbB48447895a8D339e#multipleProxyContract) |
| Worldchain Sepolia | 4801 | [0xd198Fa56B4b457223C67D075374b9Efc84DBAe0d](https://sepolia.worldscan.org/address/0xd198Fa56B4b457223C67D075374b9Efc84DBAe0d#multipleProxyContract) |
| Worldchain Mainnet | 480 | [0x82f29af756036132ec188ffbb48447895a8d339e](https://worldscan.org/address/0x82f29af756036132ec188ffbb48447895a8d339e#multipleProxyContract) |
EVM contracts provide `isCairoFactValid(bytes32 fact_hash, bool is_mocked)` function that is part of `CairoFactRegistry` module (facet) of the diamond proxy contract.
### Starknet Chains
| Chain | Address |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sepolia | [0x00421cd95f9ddabdd090db74c9429f257cb6bc1ccc339278d1db1de39156676e](https://sepolia.starkscan.co/contract/0x00421cd95f9ddabdd090db74c9429f257cb6bc1ccc339278d1db1de39156676e#read-write-contract) |
| Mainnet | [0x01ba7d4b5707f8878c22fb335763abfc26c2ae157c434d597f6416fe6a79bf2e](https://starkscan.co/contract/0x01ba7d4b5707f8878c22fb335763abfc26c2ae157c434d597f6416fe6a79bf2e#read-write-contract) |
Starknet contracts provide `isCairoFactValid(fact_hash: felt252, is_mocked: bool)` function as well as `get_all_verifications_for_fact_hash(fact_hash: felt252, is_mocked: bool)` and `get_verification(verification_hash: felt252, is_mocked: bool)` functions.
## Other Contracts
We recommend using Satellite Contracts listed above, but in case you need to call verifier contracts directly, here are the addresses:
| Contract Name | Chain | Address |
| ------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Integrity Verifier | Starknet Sepolia | [0x4ce7851f00b6c3289674841fd7a1b96b6fd41ed1edc248faccd672c26371b8c](https://sepolia.starkscan.co/contract/0x4ce7851f00b6c3289674841fd7a1b96b6fd41ed1edc248faccd672c26371b8c) |
| Integrity Verifier | Starknet Mainnet | [0xcc63a1e8e7824642b89fa6baf996b8ed21fa4707be90ef7605570ca8e4f00b](https://starkscan.co/contract/0xcc63a1e8e7824642b89fa6baf996b8ed21fa4707be90ef7605570ca8e4f00b) |
| Sharp Verifier | Ethereum Sepolia | [0x07ec0D28e50322Eb0C159B9090ecF3aeA8346DFe](https://sepolia.etherscan.io/address/0x07ec0D28e50322Eb0C159B9090ecF3aeA8346DFe) |
| Sharp Verifier | Ethereum Mainnet | [0x47312450B3Ac8b5b8e247a6bB6d523e7605bDb60](https://etherscan.io/address/0x47312450B3Ac8b5b8e247a6bB6d523e7605bDb60) |
# Downloading PIE & PROOF
Source: https://docs.herodotus.cloud/atlantic-api/downloading-files
Download PIE execution artifacts and STARK proof files from Atlantic queries, including where to find files in the console and which query results expose proof downloads.
You will need the query ID returned from your submitted job to download the
related files.
As described in [Query Status](/atlantic-api/status), find the query you want to download files for.
Open the `TRACE_GENERATION` section to download the PIE file, or
`PROOF_GENERATION` to download the proof file.
Proof files are currently not available for L1 verification queries. To
download a proof file, submit with `result` set to `PROOF_GENERATION` or
`PROOF_VERIFICATION_ON_L2`.
# Dynamic Layout on L2
Source: https://docs.herodotus.cloud/atlantic-api/dynamic
Proof verification with [Integrity](/atlantic-api/integrity-verifier) using `dynamic` or `all_cairo` layouts.
When verifying with Integrity, proofs generated with these layouts work out of the box:
* `recursive`
* `recursive_with_poseidon`
* `dex`
* `small`
* `starknet`
* `starknet_with_keccak`.
Proofs generated with `dynamic` or `all_cairo` layouts are currently not supported by Integrity due to verification complexity.
## Double Verification for Integrity Compatibility
As a workaround, use a form of "double verification":
1. Generate a proof for your original program using the desired layout (for example, `dynamic`). This captures full program execution.
2. Generate a second trace/proof/verification job where `programFile` is StarkWare's Cairo0 verifier program, and pass the proof from step 1 as input.
Modify the `proof.json` from the first proof so the payload is wrapped under a `proof` key. For example, if you have:
```json theme={null}
{
"annotations": [...],
"proofHex": "0x...",
...
}
```
convert it to:
```json theme={null}
{
"proof": {
"annotations": [...],
"proofHex": "0x...",
...
}
}
```
Use the [Cairo0 verifier](https://drive.google.com/uc?export=download\&id=1dRb5c4Co2Abny1gWeHzio0UOPuG5qJD-) as `programFile`, or reference its program hash: `0x193641eb151b0f41674641089952e60bc3aded26e3cf42793655c562b8c3aa0`.
In this flow, you are not directly verifying your program. Instead, you prove that StarkWare's verifier successfully verified your original proof. This indirect approach maintains compatibility with Integrity's current layout limitations.
This is only required when verifying with Integrity. If you do not need Integrity
verification, use the standard verification flow.
# Close bucket
Source: https://docs.herodotus.cloud/atlantic-api/endpoints/close-bucket
post /buckets/close
Close an Atlantic bucket to finalize grouped queries and trigger aggregated on-chain verification.
# Create bucket
Source: https://docs.herodotus.cloud/atlantic-api/endpoints/create-bucket
post /buckets
Create a new Atlantic bucket for grouping multiple queries into a single on-chain verification via Applicative Recursion.
# Get bucket
Source: https://docs.herodotus.cloud/atlantic-api/endpoints/get-bucket
get /buckets/{bucketId}
Retrieve the status and details of an Atlantic bucket by its ID.
# Get query
Source: https://docs.herodotus.cloud/atlantic-api/endpoints/get-query
get /atlantic-query/{atlanticQueryId}
Retrieve the status and details of a submitted Atlantic STARK proof query by its ID
# Get query by dedup ID
Source: https://docs.herodotus.cloud/atlantic-api/endpoints/get-query-by-dedup-id
get /atlantic-query-by-dedup-id
Retrieve an Atlantic STARK proof query using your custom deduplication identifier
## Query Deduplication
Atlantic supports query deduplication through the `dedupId` parameter. When submitting a query, you can provide a custom `dedupId` to:
* **Avoid duplicate processing** of identical queries
* **Track and retrieve queries** using your own identifier
* **Reference queries** across your application consistently
This endpoint allows you to retrieve a query using your custom `dedupId` and `projectId`, which is particularly useful when you want to:
* Ensure idempotent query submissions
* Retrieve query results using your own tracking identifiers
* Check if a query with a specific dedup ID already exists before submitting a new one
## Usage
Provide both the `dedupId` and `projectId` as query parameters to retrieve the Atlantic query details.
# Get query jobs
Source: https://docs.herodotus.cloud/atlantic-api/endpoints/get-query-jobs
get /atlantic-query-jobs/{atlanticQueryId}
Get detailed job information for an Atlantic proof generation query
# Get query stats
Source: https://docs.herodotus.cloud/atlantic-api/endpoints/get-query-stats
get /atlantic-queries/stats
Retrieve aggregate Atlantic query statistics, including average query time and total submitted queries for your API key.
# Is Alive
Source: https://docs.herodotus.cloud/atlantic-api/endpoints/is-alive
get /is-alive
Check the health status and availability of the Atlantic API service
# List buckets
Source: https://docs.herodotus.cloud/atlantic-api/endpoints/list-buckets
get /buckets
List all Atlantic buckets created with your API key.
# List queries
Source: https://docs.herodotus.cloud/atlantic-api/endpoints/list-queries
get /atlantic-queries
List all Atlantic STARK proof queries submitted with your API key with pagination support
# Retry query
Source: https://docs.herodotus.cloud/atlantic-api/endpoints/retry-query
post /atlantic-queries/{atlanticQueryId}/retry
Retry a failed Atlantic query when the error is retriable, subject to the API retry limit for the query.
# Submit query
Source: https://docs.herodotus.cloud/atlantic-api/endpoints/submit-query
post /atlantic-query
Submit a Cairo program for STARK proof generation and optional on-chain verification via Atlantic API
Please use this endpoint through our [Swagger UI](https://atlantic.api.herodotus.cloud/docs#/Atlantic%20Query/post_atlantic_query)!
Sending it from these docs will not work because of a Mintlify (our documentation platform) [issue with uploading files](https://github.com/mintlify/docs/issues/345).
# Examples
Source: https://docs.herodotus.cloud/atlantic-api/examples
Explore practical examples and code samples for integrating Atlantic STARK proving service with your Cairo programs
Use these examples to quickly go from a compiled Cairo program to generated proofs and verification.
Browse ready-to-run examples and scripts.
Start from the API reference for request parameters.
Learn which request body to use for each outcome.
Test requests interactively in your browser.
## Recommended Flow
1. Start with [Getting Started](/atlantic-api/getting-started) to set up your API key.
2. Choose the right request shape in [Sending Query](/atlantic-api/sending-query).
3. Test quickly in [Swagger UI](/atlantic-api/swagger-ui), then automate in your app.
# Getting Started
Source: https://docs.herodotus.cloud/atlantic-api/getting-started
Get started with Atlantic API — sign up via GitHub, create a project, get your API key, and submit your first proof generation query.
Have a look at the [Atlantic API AI Skill](/skills/atlantic-api) to give your
LLM a head start on using the Atlantic API. For programmatic API-key
acquisition without the GUI, see the
[Herodotus Auth AI Skill](/skills/herodotus-auth) and
[Programmatic wallet authentication](/documentation/authentication#programmatic-wallet-authentication).
### Sign in with GitHub
1. Navigate to [https://www.herodotus.cloud/](https://www.herodotus.cloud/)
2. Click 'Start with Github' and Authorize 'HerodotusDev'
3. Once authorized, you will be redirected to the dashboard.
### Obtain your API Key
1. In the sidebar, click on 'API KEYS'.
2. Click on 'Copy' next to your API key or generate a new one.
Keep this key secure as it grants you access to performing queries
### Use the HCloud SDK or CLI
For scripts, agents, and backend services, prefer the HCloud SDK or CLI before
writing a custom Atlantic client. The package handles API-key resolution,
programmatic wallet authentication, query submission, polling helpers, artifact
access, and Atlantic x402 payment retries. See the package on npm:
[https://www.npmjs.com/package/@herodotus\_dev/hcloud](https://www.npmjs.com/package/@herodotus_dev/hcloud).
Install the SDK:
```bash theme={null}
npm install @herodotus_dev/hcloud
```
Install the CLI:
```bash theme={null}
npm install -g @herodotus_dev/hcloud
```
Submit a query with the CLI:
```bash theme={null}
HCLOUD_API_KEY=... hcloud atlantic submit-query --pie-file ./pie.zip --declared-job-size S
```
Or authenticate once with an EVM wallet and let HCloud store credentials under
`~/.hcloud`:
```bash theme={null}
WALLET_PRIVATE_KEY=0x... hcloud auth login
hcloud atlantic submit-query --pie-file ./pie.zip --declared-job-size S
```
Use the SDK from TypeScript:
```ts theme={null}
import { HcloudClient, submitAndWait } from '@herodotus_dev/hcloud';
const client = new HcloudClient({
apiKey: process.env.HCLOUD_API_KEY,
});
const result = await submitAndWait(client.atlantic, {
declaredJobSize: 'S',
pieFile: './pie.zip',
});
console.log(result.atlanticQuery.id, result.atlanticQuery.status);
```
### Apply for credits
Before sending any queries, you need to apply for credits at [https://herodotus.dev/contact-us](https://herodotus.dev/contact-us)
### [Authentication step by step](/documentation/authentication)
# Integrity Verifier
Source: https://docs.herodotus.cloud/atlantic-api/integrity-verifier
Integrity allows you to verify STARK proofs on Starknet. It also registers all verified proofs in its storage, so other Cairo contracts can access them. It is crucial to understand how programs are stored inside Integrity’s Fact Registry.
[Full Integrity documentation](https://github.com/HerodotusDev/integrity)
## Cairo memory sections
Cairo memory consists of 3 main sections - program, execution and output. That's a simplification, but for understanding hashes calculated by Integrity, it will be enough. The program section contains your Cairo code compiled to Cairo VM instructions. Execution and output depend on program and input data. They are both calculated when running the program, but only output is exposed in public memory.
## Fact and Verification Hash
After verifying the proof, Integrity calculates two hashes: `program_hash` and `output_hash`. They are Poseidon hashes of corresponding memory sections. Then, those two hashes are hashed together to get `fact_hash`.
If your contract needs to check whether certain proof was verified, you have to calculate those hashes in your contract and pass a `fact_hash` (or better `verification_hash`) to Integrity's function. Usually you would verify proofs for some constant set of programs with arbitrary input and output, which means that you can hardcode `program_hash` while calculating `output_hash` and `fact_hash` dynamically.
However, as is usually the case, the reality is more complicated. To reduce public memory size, Cairo programs are often bootloaded, which means that your program isn’t run directly, but rather a special program called “bootloader” is placed in program segment, which is responsible for loading your program (called child program) to memory, executing it and calculating `program_hash` of the child program. This means that every bootloaded program will have the same `program_hash` and the `program_hash` of child program will only be present in bootloader’s output. This flow and hash calculation is represented in the following diagram:
Fortunately, you don't need to implement above logic yourself, because Integrity provides a Scarb package with many useful utility functions, namely `calculate_fact_hash` and `calculate_bootloaded_fact_hash`. For more details, see ["Calls from Starknet contracts" section in Integrity documentation](https://github.com/HerodotusDev/integrity#calls-from-starknet-contracts).
If you have `fact_hash` calculated, you can call integrity’s `get_all_verifications_for_fact_hash` function to check whether given `fact_hash` has been verified. However, because Integrity accepts proofs with many settings and any number of security bits, you need to check if the proof has been verified with enough number of security bits. For that you can use `is_fact_hash_valid_with_security` utility function.
Here is an example of how to use those functions:
```rust theme={null}
use integrity::{
Integrity, calculate_bootloaded_fact_hash,
SHARP_BOOTLOADER_PROGRAM_HASH,
};
const SECURITY_BITS: u32 = 70;
const FIBONACCI_PROGRAM_HASH: felt252 = 0x59874649ccc5a0a15ee77538f1eb760acb88cab027a2d48f4246bf17b7b7694;
const IS_MOCKED: bool = false;
fn is_fibonacci_verified(fib_index: felt252, fib_value: felt252) -> bool {
let fact_hash = calculate_bootloaded_fact_hash(
SHARP_BOOTLOADER_PROGRAM_HASH,
FIBONACCI_PROGRAM_HASH,
[fib_index, fib_value].span()
);
let integrity = Integrity::new_satellite(IS_MOCKED); // automatically uses current Satellite address
// Alternatively, you can call Integrity Verifier directly with `Integrity::new()`
integrity.is_fact_hash_valid_with_security(fact_hash, SECURITY_BITS)
}
```
An alternative way is using `verification_hash`, which is composed from `fact_hash`, configuration and security bits. That means that no additional checks are needed.
And here is how you would check verification of multiple proofs with the same configuration using `verification_hash`:
```rust theme={null}
use integrity::{
Integrity, IntegrityWithConfig,
calculate_bootloaded_fact_hash,
SHARP_BOOTLOADER_PROGRAM_HASH,
VerifierConfiguration,
};
fn is_multi_fibonacci_verified(fib: Span<(felt252, felt252)>) -> bool {
let config = VerifierConfiguration {
layout: 'recursive_with_poseidon',
hasher: 'keccak_160_lsb',
stone_version: 'stone6',
memory_verification: 'relaxed',
};
let integrity = Integrity::new().with_config(config, SECURITY_BITS);
let mut result = true;
for f in fib {
let (fib_index, fib_value) = *f;
let fact_hash = calculate_bootloaded_fact_hash(
SHARP_BOOTLOADER_PROGRAM_HASH, FIBONACCI_PROGRAM_HASH, [fib_index, fib_value].span()
);
if !integrity.is_fact_hash_valid(fact_hash) {
result = false;
}
};
result
}
```
If you are having trouble calculating any of those hashes, check out [Integrity Hashes Calculator](https://integrity-hashes-calculator.vercel.app/). Not only does it automatically calculate hashes for provided `program_hash` and output array, but also supports proof uploading, so you can get data directly from it.
# Atlantic API
Source: https://docs.herodotus.cloud/atlantic-api/introduction
Atlantic is a managed STARK prover service — submit Cairo programs, generate proofs, and verify on Ethereum or StarkNet via StarkWare’s SHARP.
Have a look at the [Atlantic API AI Skill](/skills/atlantic-api) to give your
LLM a head start on building with Atlantic.
**Atlantic** is a **managed prover service** that allows developers to easily integrate with **StarkWare’s SHARP (Shared Prover)**. By handling proof generation and verification for Cairo (0 and 1) programs, Atlantic removes the need to run your own proving infrastructure. You can upload your program or trace, request a proof, and verify it on-chain or off-chain — all from a unified API and a simple console.
## Why Choose Atlantic?
**End-to-End Proving**\
From trace generation to on-chain verification, Atlantic covers your entire STARK proof pipeline.
**SHARP Integration**\
Leverage StarkWare’s production-proven SHARP system without hosting or specialized configuration.
**StarkNet Support**\
Easily verify proofs on Layer 2 through the Integrity Verifier, ideal for more advanced use cases like Layer 3 solutions.
**Multi-Chain Compatibility**\
Currently supports Ethereum (SHARP Solidity Verifier), StarkNet (Integrity Verifier), and off-chain targets, with more on the way.
**Flexible Billing & Support**\
Features a pay-as-you-go pricing model, production credits for mainnet usage, and engineering assistance if needed.
## Key Features
Atlantic can perform four main **steps** for you. Use these building blocks to generate and verify your proofs end to end:
Generate traces for Cairo programs
Create STARK proofs from program traces
Generate and verify proofs on Ethereum (Layer 1)
Verify proofs on StarkNet (Layer 2) using Integrity
## Get Started with Atlantic
Ready to dive in? Head to the next page to learn how to sign up, manage your
API keys, and submit queries.
> **Disclaimer**: Atlantic is provided by Herodotus to facilitate access to StarkWare’s SHARP. Herodotus does not operate or host SHARP directly. Uptime and performance of Atlantic may vary and do not reflect SHARP’s established reliability.
# Known Issues
Source: https://docs.herodotus.cloud/atlantic-api/known-issues
Current limitations of Atlantic's Cairo 1 lane (Rust VM / cairo1-run) and practical workarounds.
Atlantic's Cairo 1 lane runs programs with `cairo1-run` (`--append_return_values`, PIE output). A few upstream `cairo-vm` limitations currently break or restrict common programs. This page describes them and the available workarounds.
## Dictionaries with extra builtins or untaken dict paths
**Status:** Broken on Atlantic until
[starkware-libs/cairo-vm#2389](https://github.com/starkware-libs/cairo-vm/pull/2389) is merged and Atlantic deploys
that `cairo-vm` version.
### What fails
Trace generation for Cairo 1 programs that:
1. Use a **dictionary** (`Felt252Dict` / SegmentArena) **together with** other builtins such as **Poseidon** or **Bitwise** (for example `hades_permutation` or bitwise ops), or
2. Contain **dict code on a branch that is not taken** for the given inputs (SegmentArena is still an implicit of `main`, but no dict is allocated at runtime).
Typical errors:
```text theme={null}
VirtualMachine(Math(RelocatableSubUsizeNegOffset((Relocatable { segment_index: N, offset: 0 }, 2))))
VirtualMachine(Memory(AddressNotRelocatable))
VirtualMachine(Hint((0, VariableNotInScopeError("dict_manager_exec_scope"))))
```
Programs that only use a dict (no Poseidon/Bitwise) or only Poseidon (no dict) often succeed. The combination — or an unused dict path — is what trips the runner.
### Why it happens
Atlantic's Cairo 1 path always enables `--append_return_values` so return values can be written into the output segment for the PIE. After `main` returns, that exit wrapper:
1. Serializes outputs with CASM `rescope` blocks, which **drop AP-relative variables**, including the live **SegmentArena** pointer.
2. Tries to recover SegmentArena from a hard-coded FP offset (`fp + 2 * builtins.len() + 2`). That cell holds the **initial** arena pointer (`base+3`), not the pointer `main` returned. Dict alloc/destruct copies the 3-cell header forward, so validation against the initial pointer is wrong (often a silent no-op). Extra builtins (Poseidon, Bitwise) or gas can shift that FP cell onto a felt or a segment base, which leads to `RelocatableSubUsizeNegOffset` / `AddressNotRelocatable`.
3. Always emits the `RelocateAllDictionaries` cheatcode when SegmentArena is present. The dict manager exec scope is only created when a dict is **actually allocated**. If dict types appear in Sierra but the taken path never allocates one, the hint crashes with `VariableNotInScopeError("dict_manager_exec_scope")`.
Upstream PR [#2389](https://github.com/starkware-libs/cairo-vm/pull/2389) fixes both issues: it stashes the **final** SegmentArena pointer in a dedicated FP-stable local, and treats relocate as a no-op when no dict was allocated.
### Workaround until PR is merged
Generate the PIE **locally** with a fixed `cairo-vm`, then submit that PIE to Atlantic for proof / verification (skip Atlantic's broken Cairo 1 trace step).
1. Use the Herodotus fork (includes the fix):
[https://github.com/HerodotusDev/starkware-cairo-vm/tree/main](https://github.com/HerodotusDev/starkware-cairo-vm/tree/main)
2. Build and run `cairo1-run` against your Sierra (gas disabled is recommended for this runner):
```bash theme={null}
git clone https://github.com/HerodotusDev/starkware-cairo-vm.git
cd starkware-cairo-vm
cargo build -p cairo1-run --release
./target/release/cairo1-run path/to/program.sierra.json \
--layout all_cairo \
--append_return_values \
--cairo_pie_output ./pie.zip \
--args_file path/to/input.txt
```
3. Submit `pie.zip` to Atlantic with `pieFile` and the desired result (`PROOF_GENERATION`, `PROOF_VERIFICATION_ON_L1`, or `PROOF_VERIFICATION_ON_L2`). See [Sending Query — Input: Trace File](/atlantic-api/sending-query#input-trace-file-piezip).
Once [#2389](https://github.com/starkware-libs/cairo-vm/pull/2389) is merged and deployed on Atlantic, submitting `programFile` + `inputFile` for these programs should work again without a local PIE step.
## `poseidon_hash_span` / corelib gas helpers (`get_builtin_costs`)
**Status:** Does not work with `cairo1-run` / Atlantic Cairo 1 when programs are compiled with gas checks stripped
(the usual Atlantic / `cairo1-run` setup). This is a long-standing upstream limitation, not specific to Atlantic.
### Official documentation
Documented in the upstream `cairo1-run` README:
* [Libfunc `get_builtin_costs` & function `poseidon_hash_many`](https://github.com/starkware-libs/cairo-vm/blob/main/cairo1-run/README.md#libfunc-get_builtin_costs--function-poseidon_hash_many)
Compiling without gas checks removes gas-related libfuncs that the compiler would emit, but it **cannot** remove gas APIs that appear in Cairo source / corelib. Calls into the `gas` corelib module — `withdraw_gas`, `withdraw_gas_all`, and **`get_builtin_costs`** — fail under that runner.
### Important: not only Poseidon hash-span
`core::poseidon::poseidon_hash_span` is the best-known trigger because its implementation calls `get_builtin_costs`. The same failure mode applies to **any** use of those gas libfuncs / helpers — for example other corelib paths that read the builtin cost table or withdraw gas.
Typical symptom when the cost table was never set up:
```text theme={null}
VirtualMachine(FailedToComputeOperands(...))
```
(or related operand / memory failures during the gas helper).
### What to use instead
Prefer hashing via `HashStateTrait` / `hades_permutation`, or a **gas-free** copy of span hashing (same algorithm as corelib, without `get_builtin_costs`).
Upstream example (also under `cairo_programs/cairo-1-programs/poseidon.cairo` in cairo-vm):
```cairo theme={null}
use core::array::{ArrayTrait, SpanTrait};
use core::hash::HashStateTrait;
use core::poseidon::{hades_permutation, HashState};
// Modified version of poseidon_hash_span that doesn't require builtin gas costs
pub fn poseidon_hash_span(mut span: Span) -> felt252 {
_poseidon_hash_span_inner((0, 0, 0), ref span)
}
fn _poseidon_hash_span_inner(
state: (felt252, felt252, felt252),
ref span: Span,
) -> felt252 {
let (s0, s1, s2) = state;
let x = *match span.pop_front() {
Option::Some(x) => x,
Option::None => { return HashState { s0, s1, s2, odd: false }.finalize(); },
};
let y = *match span.pop_front() {
Option::Some(y) => y,
Option::None => { return HashState { s0: s0 + x, s1, s2, odd: true }.finalize(); },
};
let next_state = hades_permutation(s0 + x, s1 + y, s2);
_poseidon_hash_span_inner(next_state, ref span)
}
```
Do **not** call `core::poseidon::poseidon_hash_span` (or other gas-table helpers) in programs you intend to run on Atlantic's Cairo 1 Rust VM until the runner provisions gas the way Starknet does.
## Large program outputs (\~3700+ felts)
**Status:** Atlantic rejects Cairo 1 runs whose **public output** is larger than about **3700 felts**. This is a
prover limit on the serialized output segment.
### What fails
Programs whose `main` returns a large `Array` (or otherwise writes a large output segment) fail once the output length crosses roughly that threshold — even if the rest of the run is fine.
### Recommended approach
Do **not** return the full array as public output. Return a **Poseidon hash** of the array instead, and **decommit** the preimage on-chain (or elsewhere) only if consumers need the concrete values.
Avoid:
```cairo theme={null}
pub fn main(mut input: Array) -> Array {
let mut output: Array = array![];
// Some operation on that array
// ...
output
}
```
Prefer:
```cairo theme={null}
pub fn main(mut input: Array) -> Array {
let mut output: Array = array![];
// Some operation on that array
// ...
// Use the gas-free poseidon_hash_span from the section above —
// not core::poseidon::poseidon_hash_span
array![poseidon_hash_span(output.span())]
}
```
The public output is then a single felt (plus array length encoding), which stays well under the limit. Verifiers that need the original array can check `poseidon_hash_span(preimage) == output` when the preimage is supplied on-chain or off-chain.
# Pricing
Source: https://docs.herodotus.cloud/atlantic-api/pricing
Atlantic API pricing — trace generation at ~$0.01/min, proof generation costs by step count, and verification pricing for L1/L2.
## Trace generation
Trace generation costs **1 credit (\~\$0.01)** per started minute of execution.
## Proof generation
Proof generation cost depends on the number of program steps.
| Number of steps \[millions] | Size | Cost |
| --------------------------- | ---- | ------------------ |
| 0 - 13 | S | **70 (\~\$0.70)** |
| 13 - 30 | M | **120 (\~\$1.20)** |
| >30 | L | **220 (\~\$2.20)** |
**⚠️ Job sizes are only estimates, the true job sizes are determined by SHARP.**
## Proof verification
For mainnet, proof verification costs **25 credits (\~\$0.25)** per proof.
For testnet, proof verification is free.
# Sending Query
Source: https://docs.herodotus.cloud/atlantic-api/sending-query
Prepare appropriate request body based on your input and desired outcome.
Use this page to choose the right request body based on your input (`programFile` or
`pieFile`) and expected result.
For production scripts and AI agents, prefer the HCloud SDK or CLI for
Atlantic submission, polling, artifact download, auth reuse, and x402
handling. If you want full control over the wire client, implement it from the
Atlantic OpenAPI contract at [https://atlantic.api.herodotus.cloud/docs/json](https://atlantic.api.herodotus.cloud/docs/json).
For step-by-step details, see:
* [Trace Generation](/atlantic-api/steps/trace-generation)
* [Proof Generation](/atlantic-api/steps/proof-generation)
* [L1 Proof Verification](/atlantic-api/steps/l1-proof-verification)
* [L2 Proof Verification](/atlantic-api/steps/l2-proof-verification)
For all queries, send:
* `api-key` as a request header
* `declaredJobSize` in the request body
* `sharpProver` only when you want to override the default prover; accepted values
are `stone` and `stwo`, and the default is `stone`
`declaredJobSize` determines the machine used for trace generation and affects cost.
Choose it based on expected program step count.
| Number of steps \[millions] | Size |
| --------------------------- | ---- |
| 0 - 13 | S |
| 13 - 30 | M |
| >30 | L |
## Input: Cairo Program (`programFile`)
1. **Generate trace (`pie.zip`)**
* Inputs:
* `programFile`
* `inputFile` (optional, available for Cairo1 and Cairo0 with Rust VM)
* `layout` (can be `auto`)
* `cairoVersion`
* `result = TRACE_GENERATION`
* `pieFile` must be empty
* Output: trace file (`pie.zip`)
2. **Generate proof file (`proof.json`)**
* Inputs:
* `programFile`
* `inputFile` (optional, available for Cairo1 and Cairo0 with Rust VM)
* `layout` (can be `auto`)
* `cairoVersion`
* `result = PROOF_GENERATION`
* `sharpProver` (`stone` or `stwo`) - defaults to `stone`; set to `stwo` to use S-two
* `pieFile` must be empty
* Output: proof file (`proof.json`)
3. **Generate proof and verify on Layer 1 (L1)**
* Inputs:
* `programFile`
* `inputFile` (optional, available for Cairo1 and Cairo0 with Rust VM)
* `layout` (can be `auto`)
* `cairoVersion`
* `result = PROOF_VERIFICATION_ON_L1`
* `sharpProver` (`stone` or `stwo`) - defaults to `stone`; set to `stwo` to use S-two
* `pieFile` must be empty
* Output: trace, proof, and L1 verification
4. **Generate proof and verify on Layer 2 (L2)**
* Inputs:
* `programFile`
* `inputFile` (optional, available for Cairo1 and Cairo0 with Rust VM)
* `layout` (can be `auto`)
* `cairoVersion`
* `result = PROOF_VERIFICATION_ON_L2`
* `pieFile` must be empty
* Output: trace, proof, and L2 verification
## Input: Trace File (`pie.zip`)
1. **Generate proof file (`proof.json`)**
* Inputs:
* `pieFile`
* `layout` (can be `auto`)
* `result = PROOF_GENERATION`
* `sharpProver` (`stone` or `stwo`) - defaults to `stone`; set to `stwo` to use S-two
* Output: proof file (`proof.json`)
2. **Generate proof and verify on Layer 1 (L1)**
* Inputs:
* `pieFile`
* `layout` (can be `auto`)
* `result = PROOF_VERIFICATION_ON_L1`
* `sharpProver` (`stone` or `stwo`) - defaults to `stone`; set to `stwo` to use S-two
* Output: proof and L1 verification
3. **Generate proof and verify on Layer 2 (L2)**
* Inputs:
* `pieFile`
* `layout` (can be `auto`)
* `result = PROOF_VERIFICATION_ON_L2`
* Output: proof and L2 verification
# Query Status
Source: https://docs.herodotus.cloud/atlantic-api/status
How to check the status of your Atlantic queries
Go to [https://www.herodotus.cloud/](https://www.herodotus.cloud/)
Select 'Atlantic' and then 'Console' from the sidebar
You will see your queries listed from newest to oldest.
# L1 Proof Verification
Source: https://docs.herodotus.cloud/atlantic-api/steps/l1-proof-verification
STARK proofs can be verified on L1 (Ethereum), so that other contracts deployed on Ethereum can use FactRegistry contract to check whether given proof was verified.
Proof verification can only be performed together with
[Proof Generation](/atlantic-api/steps/proof-generation).
### How to use?
Follow instructions for [Proof Generation](/atlantic-api/steps/proof-generation), but select `PROOF_VERIFICATION_ON_L1` as `result`.
After a proof is verified, you can call
`isCairoFactValid(bytes32 fact_hash, bool is_mocked)` on the
[Satellite contract](/atlantic-api/contract-addresses#evm-chains).
You can also set `mockFactHash` to omit actual proof verification on-chain, reducing the cost for testing purposes.
### Calculating fact hash
On EVM chains, fact hash is calculated from `programHash` and `output` array in the following way:
```solidity theme={null}
// Output has to match the output of the program and can have any length
uint256[] memory outputs = new uint256[](2);
outputs[0] = 10;
outputs[1] = 55;
bytes32 outputHash = keccak256(abi.encodePacked(outputs));
// Program hash is constant for given program, regardless of input and output, so it can be hardcoded
bytes32 programHash = bytes32(uint256(0x407908712e70dd914b006062d8d70bd8aeae06bcfc973cbd4309e7f3a2e825b));
bytes32 fact = keccak256(abi.encode(ms.programHash, outputHash));
```
# L2 Proof Verification
Source: https://docs.herodotus.cloud/atlantic-api/steps/l2-proof-verification
STARK proofs can be verified on L2 (Starknet) with [Integrity](https://github.com/HerodotusDev/integrity) verifier, so that other contracts deployed on Starknet can use its FactRegistry contract to check whether given proof was verified.
For now, proof verification can only be performed together with
[Proof Generation](/atlantic-api/steps/proof-generation).
### How to use?
Follow instructions for [Proof Generation](/atlantic-api/steps/proof-generation), but select `PROOF_VERIFICATION_ON_L2` as `result`.
After the proof is verified, you can call
`isCairoFactValid(fact_hash: felt252, is_mocked: bool)` or
`get_verification(verification_hash: felt252)` on the
[Satellite contract](/atlantic-api/contract-addresses#starknet-chains), as described
in more detail on the [Integrity page](/atlantic-api/integrity-verifier).
You can also set `mockFactHash` to omit actual proof verification on-chain, reducing the cost for testing purposes.
### Calculating fact hash
For fact hash calculation on Starknet, refer to the
[Integrity page](/atlantic-api/integrity-verifier).
# Proof Generation
Source: https://docs.herodotus.cloud/atlantic-api/steps/proof-generation
Proof generation converts a `pie.zip` execution artifact into a STARK proof (`proof.json`) that can be verified later without rerunning the program. Atlantic supports the Stone prover by default and S-two when selected with `sharpProver`.
### How to use?
To generate a proof, submit a PIE file in the `pieFile` body parameter, or start
with [Trace Generation](/atlantic-api/steps/trace-generation) and select
`PROOF_GENERATION` (or a higher `result` target).
The generated proof can then be downloaded or verified on Ethereum or Starknet.
When submitting proof generation with L1 verification to SHARP, the proof file
cannot be downloaded (it is verified, but not returned).
# Trace Generation
Source: https://docs.herodotus.cloud/atlantic-api/steps/trace-generation
Trace generation is a process of running Cairo program on given inputs and generating `pie.zip` file. Pie represents exact execution of Cairo program and is necessary for proof generation.
### How to use?
To generate a trace, you need two things:
1. `programFile` - compiled Cairo program in JSON format for Cairo0 or a Sierra file for Cairo1.
2. (optional) `inputFile` - supported input format depends on Cairo and VM version:
* Cairo1 - text file containing an input array, e.g. `[1 [2 3 4]]`, as described in the [Rust VM documentation](https://github.com/lambdaclass/cairo-vm/tree/main/cairo1-run#cli-argument-list). Your Cairo main function should use `fn main(input: Array) -> Array`.
* Cairo0, Python VM - JSON file representing program private input (as in `cairo-run` from [cairo-lang](https://github.com/starkware-libs/cairo-lang))
* Cairo0, Rust VM - not supported
When submitting a Cairo0 program, you can choose between Rust VM and Python VM. Rust VM is much faster and should be used when possible. However, **custom hints, including inputs, are not supported for Rust VM**. If your program requires custom hints, use Python VM.
Cairo1 only works with Rust VM, and input files are supported there.
For current Cairo 1 / Rust VM limitations (`Felt252Dict`, `poseidon_hash_span`, gas helpers, large outputs), see [Known Issues](/atlantic-api/known-issues).
# S-two 🚀
Source: https://docs.herodotus.cloud/atlantic-api/stwo
Learn about StarkWare's next-generation S-two prover and how Atlantic leverages it for high-performance proof generation
## What is S-two?
**S-two** is [StarkWare's next-generation STARK prover](https://www.starknet.io/blog/s-two-is-live-on-starknet-mainnet-the-fastest-prover-for-a-more-private-future/), representing a major breakthrough in zero-knowledge cryptography. As the world's fastest prover, S-two is now live on Starknet mainnet and powers Atlantic's proof generation capabilities.
S-two is **fully open-source** and built from the ground up to deliver unprecedented performance improvements over its predecessor, Stone, which secured StarkEx and Starknet for the past six years.
## Key Features
| Feature | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| World's Fastest Prover | S-two delivers an unprecedented leap in proving speed, generating proofs up to an order of magnitude faster than its predecessor, Stone, and outperforming every other prover in its class. |
| New Cryptographic Foundation | It is built on cutting-edge Circle STARKs technology and utilizes the M31 field (a small, highly efficient prime field optimized for performance). |
| Open-Source | S-two is a fully open-source prover, allowing the community to examine its codebase and contribute to its continuous development. |
| Implementation | It is implemented in Rust for optimal performance and supports both the Cairo programming language and direct AIR (Algebraic Intermediate Representation) definitions. |
## S-two Integration with Atlantic
Atlantic leverages S-two's exceptional performance to provide:
### Enhanced Proof Generation
When you submit queries to Atlantic, S-two's optimized proving engine processes your Cairo programs and traces with:
* **Faster turnaround times** from trace submission to verified proof
* **Lower computational overhead** reducing overall infrastructure costs
## Getting Started with S-two on Atlantic
To use S-two on Atlantic, submit your query with `sharpProver` set to `stwo`.
Learn how to submit queries
**L1 Only**: S-two is currently supported only for L1 verification. Support for L2 (integrity verifier) will be added soon.
## Learn More
* [S-two Technical Documentation](https://github.com/starkware-libs/stwo) - Official S-two GitHub repository
* [Starknet S-two Announcement](https://www.starknet.io/blog/s-two-is-live-on-starknet-mainnet-the-fastest-prover-for-a-more-private-future/) - Official launch announcement
# Swagger UI
Source: https://docs.herodotus.cloud/atlantic-api/swagger-ui
Interactive API documentation and testing interface for Atlantic STARK proving service endpoints
Swagger UI is the fastest way to explore Atlantic endpoints and test requests
interactively.
Inspect schemas and try endpoint calls in-browser.
See request fields for query submission.
Learn which request shape matches each flow.
Configure query lifecycle notifications.
# Webhooks
Source: https://docs.herodotus.cloud/atlantic-api/webhooks
Configure webhooks to receive real-time notifications about Atlantic query progress
## Overview
Atlantic supports webhooks to notify your application about query status changes in real-time. Instead of polling the API to check query status, you can configure a webhook URL to receive automatic notifications when important events occur.
## Webhook Events
Atlantic can send two types of webhook events:
### ATLANTIC\_STEP\_COMPLETED
Triggered when an individual step of your Atlantic query completes (e.g., trace generation, proof generation, verification).
### ATLANTIC\_QUERY\_COMPLETED
Triggered when the entire Atlantic query completes successfully or fails.
## Webhook Payload Structure
When an event occurs, Atlantic will send a POST request to your configured webhook URL with the following JSON payload:
```json theme={null}
{
"type": "ATLANTIC_STEP_COMPLETED" | "ATLANTIC_QUERY_COMPLETED",
"atlanticQueryId": "your-query-id",
"status": "completed" | "failed",
"context": null | {
// Additional context data specific to the event
},
"jobName": "trace-generation", // Optional: Name of the completed job
"error": null | {
// Error details if status is "failed"
}
}
```
### Payload Fields
| Field | Type | Description |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------- |
| `type` | `string` | The type of webhook event (`ATLANTIC_STEP_COMPLETED` or `ATLANTIC_QUERY_COMPLETED`) |
| `atlanticQueryId` | `string` | The unique identifier of your Atlantic query |
| `status` | `string` | The status of the query or step (e.g., `completed`, `failed`) |
| `context` | `object \| null` | Additional context information about the event |
| `jobName` | `string` | *(Optional)* The name of the completed job/step |
| `error` | `object \| null` | *(Optional)* Error details if the query or step failed |
## Configuring Webhooks
You can configure a webhook URL for each project separately through the Herodotus Cloud console. This allows you to set up different webhook endpoints for different projects based on your needs.
### Setting up Webhooks via Console
1. Navigate to your project page at `https://www.herodotus.cloud/en/projects/{PROJECT_ID}`
2. Locate the **Webhook URL** section
3. Enter your webhook endpoint URL (must be a publicly accessible HTTPS URL)
4. Click **Save** to apply the configuration
Once configured, all Atlantic queries submitted within that project will automatically send webhook notifications to the specified URL when events occur.
## Implementing a Webhook Endpoint
Your webhook endpoint should:
1. **Accept POST requests** with JSON payload
2. **Respond quickly** (within a few seconds) with a 2xx status code
3. **Handle retries gracefully** (Atlantic may retry failed webhook deliveries)
## Related Resources
Learn how to submit queries with webhook configuration
Understand query statuses and states
Fetch query details and results
See complete examples of using Atlantic
# x402 Payments
Source: https://docs.herodotus.cloud/atlantic-api/x402-payments
Pay-per-call access to Atlantic over the canonical x402 v2 HTTP-payments protocol — works with both API-key fallback and pure-wallet anonymous flows.
## Overview
Atlantic's `POST /atlantic-query` endpoint speaks the canonical
**[x402 v2](https://github.com/coinbase/x402)** HTTP-payments protocol.
Header names match the public spec exactly
(`PAYMENT-REQUIRED`, `PAYMENT-SIGNATURE`, `PAYMENT-RESPONSE`), so any
standard x402 client library — `x402-fetch`, `@coinbase/x402-axios`, or
your own — works against Atlantic without modification.
Use x402 when you want pay-per-call access to Atlantic from an EVM
wallet, either:
* as a **fallback** when an API-key project runs out of prepaid
credits, or
* as a **fully anonymous** wallet-only client with no account on
Herodotus Cloud.
If you want long-lived session-based access with prepaid credits, use
the [Atlantic API authentication flow](/documentation/authentication)
instead. For AI agents, see the
[`atlantic-api` AI skill](/skills/atlantic-api).
## Two flows at a glance
| | API-key flow | Anonymous flow |
| --------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **When it triggers** | API key + insufficient project credits | No API key on the request |
| **Identity** | Project + API key (existing) | EVM wallet recovered from EIP-3009 signature |
| **Credit residue** | Settled amount → project credit balance, **2-year TTL**, drawn down by future queries | None — pay-once, use-once |
| **Refunds / leftover** | Yes, leftover credits remain on project | No |
| **`dedupId` / `bucketId`** | Supported | Rejected (`WALLET_FLOW_DEDUP_ID_NOT_SUPPORTED`, `WALLET_FLOW_BUCKET_NOT_SUPPORTED`) |
| **Resumable after disconnect** | Yes, via `extra.atlantic_query_id` | Yes, via `extra.atlantic_query_id` |
| **`paymentRequired.error` field** | `"insufficient_credits"` | `"payment_required"` |
## Wire-level walkthrough
### Step 1 — Submit the query normally
```bash theme={null}
# For anonymous flow, omit the -H flag entirely.
curl -X POST https://atlantic.api.herodotus.cloud/atlantic-query \
-H "api-key: $ATLANTIC_API_KEY" \
-F pieFile=@input.zip \
-F layout=dynamic \
-F declaredJobSize=S
```
If the API key has sufficient credits, the response is the usual
`200` with the query body. **Do not preemptively send a
`PAYMENT-SIGNATURE` header** — the server only invokes x402 after
detecting `INSUFFICIENT_CREDITS`, and a payment header sent with
credits available is wasted.
### Step 2 — Receive the 402
If credits are insufficient (or no API key was provided and anonymous
payments are enabled), the server responds:
```http theme={null}
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Miwi...
{
"paymentRequired": {
"x402Version": 2,
"error": "insufficient_credits",
"accepts": [
{
"scheme": "exact",
"network": "base-sepolia",
"asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
"payTo": "0xAbC...",
"amount": "1000000",
"resource": "Atlantic Query - 01HXX... - S",
"statement": "By signing, you confirm…",
"mimeType": "application/json",
"maxTimeoutSeconds": 600,
"extra": {
"name": "USDC",
"version": "2",
"projectId": "01HXX...",
"clientId": "01HXX...",
"creditAmount": 100,
"challengeId": "01HXX...",
"atlantic_query_id": "01HXX..."
}
}
]
},
"paymentRequiredHeader": "eyJ4NDAyVmVyc2lvbiI6Miwi..."
}
```
The `PAYMENT-REQUIRED` HTTP header carries the same payload, base64-
encoded, for compatibility with standard x402 clients. Either source
is canonical; the body form is shown here because it's easier to
inspect.
`extra` field reference:
| Field | Where | Purpose |
| ----------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | both flows | EIP-712 domain `name` of the asset contract (e.g. `"USDC"`). Use this — do **not** call `eip712Domain()` on the contract. |
| `version` | both flows | EIP-712 domain `version` of the asset contract (e.g. `"2"`). |
| `creditAmount` | both flows | Number of credits this payment will buy. Usually equals `amount` in cents. |
| `challengeId` | both flows | Server-issued ULID. Single-use — the server invalidates it after a successful settle. |
| `atlantic_query_id` | both flows (when set) | Pre-issued query ID. If you echo this in the signed payment, retrying the request resumes the same query rather than creating a new one. |
| `projectId`, `clientId` | API-key flow only | Identity binding — the settle endpoint rejects payments whose `extra` does not match the calling project. |
### Step 3 — Sign EIP-3009 `transferWithAuthorization`
Pick one entry from `accepts[]` (typically the first; production
deployments may offer multiple networks). Then sign EIP-712 typed-data
for `transferWithAuthorization` on the chosen `asset` contract:
```ts theme={null}
import { privateKeyToAccount } from 'viem/accounts';
const NETWORK_TO_CHAIN_ID = {
'base': 8453,
'base-sepolia': 84532,
'ethereum': 1,
'sepolia': 11155111,
} as const;
const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY!);
const requirement = challenge.accepts[0];
const validAfter = 0n;
const validBefore = BigInt(
Math.floor(Date.now() / 1000) + (requirement.maxTimeoutSeconds ?? 300),
);
const nonce = `0x${[...crypto.getRandomValues(new Uint8Array(32))]
.map((b) => b.toString(16).padStart(2, '0'))
.join('')}` as `0x${string}`;
const signature = await account.signTypedData({
domain: {
name: requirement.extra.name, // from challenge
version: requirement.extra.version, // from challenge
chainId: NETWORK_TO_CHAIN_ID[requirement.network],
verifyingContract: requirement.asset,
},
types: {
TransferWithAuthorization: [
{ name: 'from', type: 'address' },
{ name: 'to', type: 'address' },
{ name: 'value', type: 'uint256' },
{ name: 'validAfter', type: 'uint256' },
{ name: 'validBefore', type: 'uint256' },
{ name: 'nonce', type: 'bytes32' },
],
},
primaryType: 'TransferWithAuthorization',
message: {
from: account.address,
to: requirement.payTo,
value: BigInt(requirement.amount),
validAfter,
validBefore,
nonce,
},
});
```
The wallet must hold at least `value` units of the asset on the
specified network. For `base-sepolia` USDC, that's
[Circle's faucet](https://faucet.circle.com).
### Step 4 — Retry with `PAYMENT-SIGNATURE`
Build a v2 `PaymentPayload` and base64-encode it as the
`PAYMENT-SIGNATURE` header. Resubmit the same body:
```ts theme={null}
const paymentPayload = {
x402Version: 2,
accepted: requirement, // verbatim, including extra
payload: {
signature,
authorization: {
from: account.address,
to: requirement.payTo,
value: requirement.amount, // string, atomic units
validAfter: validAfter.toString(),
validBefore: validBefore.toString(),
nonce,
},
},
};
const headerValue = Buffer.from(JSON.stringify(paymentPayload), 'utf8')
.toString('base64');
const res = await fetch('https://atlantic.api.herodotus.cloud/atlantic-query', {
method: 'POST',
headers: {
...(API_KEY ? { 'api-key': API_KEY } : {}),
'PAYMENT-SIGNATURE': headerValue,
},
body: formData,
});
if (!res.ok) {
const errorBody = await res.text();
throw new Error(`x402 retry failed with ${res.status}: ${errorBody}`);
}
```
### Step 5 — Read `PAYMENT-RESPONSE`
On success, the response is `200` with the usual query body and a
settlement receipt in the `PAYMENT-RESPONSE` header:
```http theme={null}
HTTP/1.1 200 OK
PAYMENT-RESPONSE: eyJ4NDAyVmVyc2lvbiI6Miwi...
{ "atlanticQueryId": "01HXX...", ... }
```
Decoded `PAYMENT-RESPONSE`:
```json theme={null}
{
"x402Version": 2,
"success": true,
"transaction": "0xfacd…", // on-chain tx hash, or derived id
"network": "base-sepolia",
"payer": "0xPayer…",
"alreadyProcessed": false
}
```
`alreadyProcessed: true` means the facilitator has already settled this
exact `(challengeId, signature)` pair before — the query is allowed
through but no new credit is added. **Do not retry the payment.** This
typically happens when the client times out after the server has
settled but before the response is read.
## Replay, dedup, and idempotency
* **Challenges are single-use.** The server stores each issued
challenge with its `challengeId` and consumes it on a successful
settle. Reusing the same `PAYMENT-SIGNATURE` after success returns
`X402_SETTLEMENT_FAILED`. For each new query, fetch a fresh 402.
* **Settlements are idempotent on `providerPaymentId`.** Submitting
the same signed payment twice in a tight loop will not double-charge
— the second attempt returns the same `200` with
`alreadyProcessed: true`.
* **Resume an in-flight query.** If you submit a query, get the 402,
sign, but lose the connection before retrying, you can recover the
pre-issued `extra.atlantic_query_id` from your decoded challenge,
embed it in the signed `accepted.extra`, and retry. The server
routes the payment to the original query rather than minting a new
one.
## Error taxonomy
| Code (agent-visible) | Status | When it fires | What to do |
| ------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `X402_NOT_ENABLED` | 503 | x402 disabled in this Atlantic deployment | Back off; do not retry |
| `MISSING_API_KEY` | 400 | Anonymous flow disabled and no API key supplied | Authenticate with [`herodotus-auth`](/documentation/authentication#programmatic-wallet-authentication) and use the API-key flow |
| `X402_CHALLENGE_FAILED` | 502 | Upstream challenge build failed | Transient — retry with backoff |
| `X402_SETTLEMENT_FAILED` | 402 | Verify or settle rejected (bad signature, replay, expired authorization, insufficient wallet balance, mismatched `extra.projectId`/`clientId`) | Fetch a fresh 402 and try again with a new nonce; do not reuse the prior signature |
| `X402_SETTLEMENT_RESPONSE_INVALID` | 502 | Settlement succeeded on-chain but the response failed schema validation | Treat as ambiguous — call `GET /atlantic-query/:id` before paying again to avoid double-charging |
| `X402_SERVICE_AUTH_NOT_CONFIGURED` | 500 | Server misconfiguration with the x402 facilitator | Surface to the user; do not retry |
| `WALLET_FLOW_DEDUP_ID_NOT_SUPPORTED` | 400 | Anonymous flow + `dedupId` in body | Drop `dedupId` and resubmit |
| `WALLET_FLOW_BUCKET_NOT_SUPPORTED` | 400 | Anonymous flow + `bucketId` in body | Drop `bucketId` and resubmit |
| `WALLET_FLOW_NOT_RETRIABLE` | 400 | This anonymous query cannot be retried | Submit a fresh query |
## curl-only recipe
For sanity-checking your environment before integrating a signer:
```bash theme={null}
ATLANTIC=https://atlantic.api.herodotus.cloud
# 1. Submit; capture the 402 challenge body.
curl -s -o challenge.json -w '%{http_code}' -X POST \
"$ATLANTIC/atlantic-query" \
-F pieFile=@input.zip -F layout=dynamic -F declaredJobSize=S
# → 402
# 2. Inspect the challenge.
jq '.paymentRequired.accepts[0]' challenge.json
# 3. Sign EIP-3009 out of band (cast / wallet / KMS) and assemble the
# PaymentPayload JSON in payment.json. Then:
SIG_HEADER=$(base64 -w0 < payment.json)
# 4. Retry with the signature header.
curl -s -X POST "$ATLANTIC/atlantic-query" \
-H "PAYMENT-SIGNATURE: $SIG_HEADER" \
-F pieFile=@input.zip -F layout=dynamic -F declaredJobSize=S \
-D headers.txt
# 5. Read the receipt.
grep -i 'PAYMENT-RESPONSE' headers.txt | cut -d' ' -f2- | base64 -d | jq
```
## AI agent integration
If you're integrating Atlantic from an AI assistant or autonomous
agent, load the [`atlantic-api` AI skill](/skills/atlantic-api). It
includes this entire flow as a copy-pasteable playbook with anti-
hallucination guardrails and a viem reference snippet that handles
both flows in one parameterized function.
In Claude Code:
```bash theme={null}
/herodotus-skills:atlantic-api
```
# Health check
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/health/health-check
/data-processor-api/openapi/openapi-hdp-server.json get /is-alive
Returns the health status of the HDP server, including database connectivity and message queue status. Used for monitoring and load balancer health probes.
# Download module
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/modules/download-module
/data-processor-api/openapi/openapi-hdp-server.json get /modules/{id}/download
Downloads a module as a ZIP file containing the source code (src/ directory), Scarb.toml configuration, and the compiled program JSON. Returns the latest version of the module.
# Download module by program hash
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/modules/download-module-by-program-hash
/data-processor-api/openapi/openapi-hdp-server.json get /modules/by-hash/{hash}/download
Downloads a module by its compiled program hash as a ZIP file. Useful when you have the program hash from a task and want to retrieve the associated module source code and configuration.
# Get module by ID
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/modules/get-module-by-id
/data-processor-api/openapi/openapi-hdp-server.json get /modules/{id}
Retrieves detailed information about a specific module including its name, description, latest version, program hash, and metadata.
# Get module versions
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/modules/get-module-versions
/data-processor-api/openapi/openapi-hdp-server.json get /modules/{id}/versions
Retrieves all versions of a specific module. Each version includes the compiled program hash, version string, and compilation metadata.
# List modules
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/modules/list-modules
/data-processor-api/openapi/openapi-hdp-server.json get /modules
Retrieves a list of available modules. Can filter by marketplace status (published modules) or by creator user ID.
# Publish module to marketplace
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/modules/publish-module-to-marketplace
/data-processor-api/openapi/openapi-hdp-server.json post /modules/{id}/publish
Makes a module available in the public marketplace for other users to discover and use. Only the module creator can publish their module.
# Unpublish module from marketplace
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/modules/unpublish-module-from-marketplace
/data-processor-api/openapi/openapi-hdp-server.json post /modules/{id}/unpublish
Removes a module from the public marketplace. The module will still exist and be accessible by its ID, but won't be listed in marketplace searches.
# Update module metadata
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/modules/update-module-metadata
/data-processor-api/openapi/openapi-hdp-server.json patch /modules/{id}
Updates the metadata of an existing module. Can update name, description, tags, license, and other module properties.
# Upload a new module
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/modules/upload-a-new-module
/data-processor-api/openapi/openapi-hdp-server.json post /modules/upload
Upload a compiled Cairo module as a ZIP file. The ZIP should contain the source code (src/ directory), Scarb.toml, and the compiled program JSON. The module will be compiled and stored for later use in HDP tasks.
# Decommitment only
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/tasks/decommitment-only
/data-processor-api/openapi/openapi-hdp-server.json post /tasks/decommitment
Submit a decommitment request for an HDP task when running HDP and generating PIE locally. You can optionally provide hdp_output and program_hash, and if not provided, they will be automatically fetched from Atlantic storage using the atlantic_query_id.
# Get state transition statistics
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/tasks/get-state-transition-statistics
/data-processor-api/openapi/openapi-hdp-server.json get /tasks/state_transitions/stats
Returns aggregated statistics about state transitions across all tasks. Provides insights into task processing patterns and bottlenecks.
# Get task details
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/tasks/get-task-details
/data-processor-api/openapi/openapi-hdp-server.json get /tasks/{uuid}/details
Retrieves comprehensive details of a specific task including destination chain ID, program hash, task hash, output tree root, and MMRs used. This endpoint does not require authentication.
# Get task output preimage
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/tasks/get-task-output-preimage
/data-processor-api/openapi/openapi-hdp-server.json get /tasks/{uuid}/output_preimage
Retrieves the output tree preimage for a specific task. The preimage contains the raw output data that hashes to the output tree root. This endpoint does not require authentication.
# Get task state transitions
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/tasks/get-task-state-transitions
/data-processor-api/openapi/openapi-hdp-server.json get /tasks/{uuid}/state_transitions
Returns the complete state transition history for a specific task. Shows all status changes with timestamps, useful for debugging and monitoring task progress.
# Get task statistics
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/tasks/get-task-statistics
/data-processor-api/openapi/openapi-hdp-server.json get /tasks/stats
Returns aggregated task counts grouped by status. Provides an overview of all tasks in the system across different processing stages.
# Get task status
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/tasks/get-task-status
/data-processor-api/openapi/openapi-hdp-server.json get /tasks/{uuid}/status
Retrieves the current status of a scheduled Data Processor task. This endpoint does not require authentication.
# Get used MMRs
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/tasks/get-used-mmrs
/data-processor-api/openapi/openapi-hdp-server.json get /tasks/{uuid}/mmrs
Retrieves the list of MMRs (Merkle Mountain Ranges) used by a specific task. This endpoint does not require authentication.
# List tasks
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/tasks/list-tasks
/data-processor-api/openapi/openapi-hdp-server.json get /tasks
Retrieves a paginated list of tasks with optional filtering by status, search query, or client ID. Supports pagination with page number and items per page.
# Retry a failed task
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/tasks/retry-a-failed-task
/data-processor-api/openapi/openapi-hdp-server.json post /tasks/{uuid}/retry
Resets a failed task and re-queues it for processing. Only tasks in failed or errored states can be retried. This endpoint does not require authentication.
# Schedule a new task
Source: https://docs.herodotus.cloud/data-processor-api/api-reference/tasks/schedule-a-new-task
/data-processor-api/openapi/openapi-hdp-server.json post /tasks
Creates a new Data Processor task of verified custom module execution with Atlantic submission and on-chain commitment. The task will be queued for processing through the HDP pipeline: dry run, chain proofs fetch, trace generation, Atlantic proving, and finally on-chain decommitment.
# Schedule a new task
Source: https://docs.herodotus.cloud/data-processor-api/create-task
Create and submit a Data Processor task for verified custom module execution with onchain commitment
# Schedule a new task
Creates a new Data Processor task of verified custom module execution with Atlantic submission and onchain commitment.
## Endpoint
```
POST /tasks
```
## Request Body
| Field | Type | Description |
| ----------------------------------------- | ------- | ------------------------------------------------------------- |
| destination\_chain\_id | integer | The chain ID where the task will be proven |
| webhook\_url | string | Optional URL to receive task completion/failure notifications |
| input | object | The task input parameters |
| input.params | array | Array of parameters for the contract execution |
| input.compiled\_class | object | The custom module compiled contract class |
| input.entry\_points\_by\_type | object | Entry points configuration for different types |
| input.entry\_points\_by\_type.EXTERNAL | array | Array of external entry points |
| input.entry\_points\_by\_type.L1\_HANDLER | array | Array of L1 handler entry points |
| input.entry\_points\_by\_type.CONSTRUCTOR | array | Array of constructor entry points |
### Example Request
```bash theme={null}
curl -X POST https://hdp.api.herodotus.cloud/tasks \
-H "Content-Type: application/json" \
-H "X-API-KEY: your-herodotus-cloud-api-key-here" \
-d '{
"destination_chain_id": 11155111,
"webhook_url": "https://your-domain.com/webhook",
"input": {
"params": [],
"compiled_class": {
<>
},
"entry_points_by_type": {
"EXTERNAL": [
{
"selector": "0xe2054f8a912367e38a22ce773328ff8aabf8082c4120bad9ef085e1dbf29a7",
"offset": 0,
"builtins": [
"range_check"
]
}
],
"L1_HANDLER": [],
"CONSTRUCTOR": []
}
}
}'
```
## Response
### Success Response (200 OK)
```json theme={null}
{
"message": "Task has been queued for processing",
"status": "accepted",
"uuid": "01JPJ03YJT1A93D6NF56G4GVEQ"
}
```
### Error Response (401 Unauthorized)
```json theme={null}
{
"error": "Missing Herodotus Cloud X-API-KEY header"
}
```
### Error Responses
* 400 Bad Request: Invalid request parameters
* 401 Unauthorized: Missing or invalid authentication
* 429 Too Many Requests: Rate limit exceeded
* 500 Internal Server Error: Server-side error
## Webhook Notifications
When a `webhook_url` is provided, the service will send a POST request to the specified URL when the task completes or fails. The webhook payload will be sent as JSON.
### Success Webhook Payload
```json theme={null}
{
"status": "TaskDecommitmentCompleted",
"task_id": "01JPMW7VE29Z0EH1VZKJPSCFR4",
"timestamp": "2025-03-18T15:01:01.303281+00:00",
"transaction_hash": "0xcfb8…6f98"
}
```
### Failure Webhook Payload
```json theme={null}
{
"task_id": "01JPMW7VE29Z0EH1VZKJPSCFR4",
"status": "TraceGenFailed",
"error": "cairo-compile was not found",
"timestamp": "2025-03-18T17:01:01.303281+00:00"
}
```
### Webhook Payload Fields
| Field | Type | Description |
| ----------------- | ------ | --------------------------------------------------------- |
| status | string | Final status of the task |
| task\_id | string | The unique identifier of the task |
| timestamp | string | ISO 8601 timestamp of the status update |
| transaction\_hash | string | Hash of the transaction (only present in success payload) |
| error | string | Error message (only present in failure payload) |
## Notes
* The `compiled_class` field should contain the complete compiled contract class data from the custom module
* Entry points are used to define the contract's interface and execution points
* The `selector` field in entry points is a hash of the encoded function name
* Builtins specify the required built-in functions for the contract execution
* The `uuid` in the response can be used to check the task status using the status endpoint
* Webhook notifications are sent asynchronously after task completion or failure
* The webhook endpoint should be publicly accessible and respond with a 2xx status code
# Decommitment Only
Source: https://docs.herodotus.cloud/data-processor-api/decommitment-only
Submit a decommitment request for an HDP task when running HDP and generating PIE locally
# Decommitment Only
This endpoint allows you to submit a decommitment request for an HDP task when you are running HDP and generating PIE locally. You can optionally provide `hdp_output` and `program_hash`, and if not provided, they will be automatically fetched from Atlantic storage using the `atlantic_query_id`.
## Endpoint
```
POST /tasks/decommitment
```
## Authentication
This endpoint requires authentication using an API key:
```bash theme={null}
X-API-KEY: your-herodotus-cloud-api-key-here
```
## Request Body
| Field | Type | Required | Description |
| ---------------------- | ------ | -------- | ------------------------------------------------------------------------ |
| destination\_chain\_id | string | Yes | Hex-encoded chain ID (e.g., `0x534e5f5345504f4c4941` for SN\_SEPOLIA) |
| atlantic\_query\_id | string | Yes | The Atlantic query ID from PIE submission |
| hdp\_output | object | No | HDP output data. If not provided, will be fetched from Atlantic storage |
| program\_hash | string | No | HDP program hash. If not provided, will be fetched from Atlantic storage |
| webhook\_url | string | No | Optional URL to receive task completion/failure notifications |
### hdp\_output Structure
| Field | Type | Description |
| ------------------------ | ------ | ---------------------------------------------- |
| mmr\_metas | array | Array of MMR metadata objects |
| task\_hash\_low | string | Low 128 bits of task hash (hex string) |
| task\_hash\_high | string | High 128 bits of task hash (hex string) |
| output\_tree\_root\_low | string | Low 128 bits of output tree root (hex string) |
| output\_tree\_root\_high | string | High 128 bits of output tree root (hex string) |
### mmr\_metas Array Items
Each item in `mmr_metas` can be either a Poseidon or Keccak MMR:
**Poseidon MMR:**
```json theme={null}
{
"Poseidon": {
"id": "0x30314b345136303433515133424b4d42324e31394d4443595757",
"size": "0x2644",
"chain_id": "0xaa37dc",
"root": "0x6e7be7495a7126588df5ce10e090b27ea87357b966cc5b4143d0845ee15af0e"
}
}
```
**Keccak MMR:**
```json theme={null}
{
"Keccak": {
"id": "0x30314a4d484d31413242354d38455336505a57524a505354374d",
"size": "0x0a813",
"chain_id": "0xaa36a7",
"root_low": "0x8c03a541b8eb37ccfb5d11f205555666",
"root_high": "0x8df74acdc8c1fc184081e4a2ec4ccca7"
}
}
```
## Example Requests
### With hdp\_output and program\_hash provided
```bash theme={null}
curl -X POST https://hdp.api.herodotus.cloud/tasks/decommitment \
-H "Content-Type: application/json" \
-H "X-API-KEY: your-herodotus-cloud-api-key-here" \
-d '{
"destination_chain_id": "0x534e5f5345504f4c4941",
"atlantic_query_id": "01KA1F1FY93BP2MWF6BP4Y3GW1",
"hdp_output": {
"mmr_metas": [
{
"Poseidon": {
"id": "0x30314b345136303433515133424b4d42324e31394d4443595757",
"size": "0x2644",
"chain_id": "0xaa37dc",
"root": "0x6e7be7495a7126588df5ce10e090b27ea87357b966cc5b4143d0845ee15af0e"
}
}
],
"task_hash_low": "0x89bb92c8c305fd8df0fbcc19602339ac",
"task_hash_high": "0x56839c1e7f817be047794dbdc727585f",
"output_tree_root_low": "0x109640f2deb15a8d29ee5bb754a2943a",
"output_tree_root_high": "0xc103b036a12f8f9307b062b11181a726"
},
"program_hash": "0x34a16478e83f69c4f0bcdb7549d32f92c9b7776bb3f71da06de334f1871eba0",
"webhook_url": "https://your-domain.com/webhook"
}'
```
### Without hdp\_output and program\_hash (fetched from Atlantic)
```bash theme={null}
curl -X POST https://hdp.api.herodotus.cloud/tasks/decommitment \
-H "Content-Type: application/json" \
-H "X-API-KEY: your-herodotus-cloud-api-key-here" \
-d '{
"destination_chain_id": "0x534e5f5345504f4c4941",
"atlantic_query_id": "01KA1F1FY93BP2MWF6BP4Y3GW1",
"webhook_url": "https://your-domain.com/webhook"
}'
```
## Response
### Success Response (202 Accepted)
```json theme={null}
{
"message": "Task has been queued for decommitment",
"status": "accepted",
"uuid": "01KABQ0255W3HHQD8AZAMQNADS"
}
```
### Error Responses
**400 Bad Request - Program hash mismatch:**
```json theme={null}
{
"error": "Program hash mismatch",
"details": "expected 0x34a16478e83f69c4f0bcdb7549d32f92c9b7776bb3f71da06de334f1871eba0, got 0x..."
}
```
**400 Bad Request - Invalid payload:**
```json theme={null}
{
"error": "Invalid decommitment payload",
"details": "mmr_metas must be an array"
}
```
**401 Unauthorized:**
```json theme={null}
{
"error": "Missing API key"
}
```
**500 Internal Server Error:**
```json theme={null}
{
"error": "Failed to fetch from Atlantic: HTTP 404"
}
```
## Response Fields
| Field | Type | Description |
| ------- | ------ | ----------------------------------------------- |
| message | string | Success message |
| status | string | Status of the request (always "accepted") |
| uuid | string | The unique identifier of the decommitment task |
| error | string | Error message (only present in error responses) |
## Automatic Fetching from Atlantic
If `hdp_output` or `program_hash` are not provided, the service will automatically fetch them from Atlantic storage using the `atlantic_query_id`. The metadata is fetched from:
```
https://storage.googleapis.com/hero-atlantic/queries/{atlantic_query_id}/metadata.json
```
The service will:
1. Fetch the metadata JSON from Atlantic storage
2. Parse the `output` array according to the Cairo serialization format
3. Extract `hdp_output` and `program_hash` from the metadata
4. Validate the `program_hash` against the local compiled program
## Notes
* The `destination_chain_id` must be a hex-encoded string starting with `0x`
* If both `hdp_output` and `program_hash` are provided, they will be used directly
* If either is missing, both will be fetched from Atlantic storage
* The `program_hash` is validated against the local compiled program to prevent mismatches
* The task will be queued for decommitment processing
* Webhook notifications work the same way as the main task creation endpoint
# Get Used MMRs
Source: https://docs.herodotus.cloud/data-processor-api/get-mmrs
Retrieve the list of MMRs (Merkle Mountain Ranges) used by a specific task
# Get Used MMRs
Retrieves the list of MMRs (Merkle Mountain Ranges) used by a specific task. This endpoint does not require authentication.
## Endpoint
```
GET /tasks/{task_uuid}/mmrs
```
## Path Parameters
| Parameter | Type | Description |
| ---------- | ------ | ---------------------------------------- |
| task\_uuid | string | The unique identifier (UUID) of the task |
## Example Request
```bash theme={null}
curl -X GET https://hdp.api.herodotus.cloud/tasks/01JPJ03YJT1A93D6NF56G4GVEQ/mmrs \
-H "Content-Type: application/json"
```
## Response
### Success Response (200 OK)
```json theme={null}
{
"taskId": "01JPJ03YJT1A93D6NF56G4GVEQ",
"mmrs": [
{
"id": "0x30314b345136303433515133424b4d42324e31394d4443595757",
"root": "0x6e7be7495a7126588df5ce10e090b27ea87357b966cc5b4143d0845ee15af0e",
"size": "0x2644",
"chain_id": "0xaa37dc",
"hashing_function": "poseidon"
},
{
"id": "0x30314a4d484d31413242354d38455336505a57524a505354374d",
"root": "0x8c03a541b8eb37ccfb5d11f2055556668df74acdc8c1fc184081e4a2ec4ccca7",
"size": "0x0a813",
"chain_id": "0xaa36a7",
"hashing_function": "keccak"
}
]
}
```
### Not Found Response (404)
```json theme={null}
{
"error": "Task not found",
"taskId": "01JPJ03YJT1A93D6NF56G4GVEQ"
}
```
### Server Error Response (500)
```json theme={null}
{
"error": "Server error",
"message": "Failed to decode MMR metadata"
}
```
## Response Fields
| Field | Type | Description |
| ------ | ------ | ----------------------------------------------- |
| taskId | string | The unique identifier of the task |
| mmrs | array | Array of MMR information objects |
| error | string | Error message (only present in error responses) |
### MMR Object Fields
| Field | Type | Description |
| ----------------- | ------ | ----------------------------------------------------------------------------------------- |
| id | string | The MMR identifier (hex string) |
| root | string | The MMR root hash (hex string). For Keccak, this is the combined root\_low and root\_high |
| size | string | The size of the MMR (hex string) |
| chain\_id | string | The chain ID where this MMR is located (hex string) |
| hashing\_function | string | The hashing function used: `"poseidon"` or `"keccak"` |
## Notes
* No authentication is required for this endpoint
* The response includes all MMRs used by the task, regardless of their hashing function
* For Poseidon MMRs, the `root` field contains the single root value
* For Keccak MMRs, the `root` field contains the combined `root_high` and `root_low` values
* The `hashing_function` field explicitly indicates which hashing algorithm was used for each MMR
* This endpoint is useful for verifying which MMRs were used in the task execution
# Get Module
Source: https://docs.herodotus.cloud/data-processor-api/get-module
Retrieve detailed information about a specific HDP module by its ID
# Get Module
Retrieves detailed information about a specific HDP module, including metadata, source code, ABI, and version information. This endpoint does not require authentication.
## Endpoint
```
GET /modules/{id}
```
## Path Parameters
| Parameter | Type | Description |
| --------- | ------ | --------------------------- |
| id | string | The unique module ID (ULID) |
## Example Request
```bash theme={null}
curl -X GET https://hdp.api.herodotus.cloud/modules/01JPJ03YJT1A93D6NF56G4GVEQ \
-H "Content-Type: application/json"
```
## Response
### Success Response (200 OK)
```json theme={null}
{
"id": "01JPJ03YJT1A93D6NF56G4GVEQ",
"latestModuleVersionProgramHash": "0x34a16478e83f69c4f0bcdb7549d32f92c9b7776bb3f71da06de334f1871eba0",
"compilerVersion": "2.7.0",
"name": "my_module",
"description": "My awesome HDP module",
"usageCount": 42,
"tags": ["example", "tutorial"],
"downloadsCount": 100,
"usersCount": 25,
"isVerified": false,
"publishedOnMarketplace": true,
"creatorUser": "user@example.com",
"license": "MIT",
"abi": {
"type": "interface",
"items": []
},
"sourceCode": {
"src/lib.cairo": "fn main() {}"
},
"scarbToml": "[package]\nname = \"my_module\"\n...",
"createdAt": "2024-03-17T10:24:00Z",
"updatedAt": "2024-03-17T10:25:00Z"
}
```
### Not Found Response (404)
```json theme={null}
{
"error": "Module not found"
}
```
### Response Fields
| Field | Type | Description |
| ------------------------------ | -------------- | --------------------------------------------------------- |
| id | string | The unique module ID (ULID) |
| latestModuleVersionProgramHash | string \| null | Program hash of the latest version |
| compilerVersion | string | Compiler version used |
| name | string | Module name |
| description | string \| null | Module description |
| usageCount | integer | Number of times this module has been used |
| tags | array \| null | Array of tags |
| downloadsCount | integer | Number of downloads |
| usersCount | integer | Number of unique users |
| isVerified | boolean | Whether the module is verified |
| publishedOnMarketplace | boolean | Whether the module is published on the marketplace |
| creatorUser | string \| null | Creator user identifier |
| license | string \| null | License identifier |
| abi | object \| null | Module ABI as JSON |
| sourceCode | object \| null | Source code files as JSON object mapping paths to content |
| scarbToml | string \| null | Scarb.toml file content |
| createdAt | string | ISO 8601 timestamp of module creation |
| updatedAt | string | ISO 8601 timestamp of last update |
## Notes
* No authentication is required for this endpoint
* Returns all module metadata including source code and ABI
* The `sourceCode` field contains a JSON object mapping file paths to file contents
* The `latestModuleVersionProgramHash` points to the most recent version of the module
# Get Module Versions
Source: https://docs.herodotus.cloud/data-processor-api/get-module-versions
Retrieve all versions of a specific HDP module
# Get Module Versions
Retrieves all versions (programs) associated with a specific HDP module. This endpoint does not require authentication.
## Endpoint
```
GET /modules/{id}/versions
```
## Path Parameters
| Parameter | Type | Description |
| --------- | ------ | --------------------------- |
| id | string | The unique module ID (ULID) |
## Example Request
```bash theme={null}
curl -X GET https://hdp.api.herodotus.cloud/modules/01JPJ03YJT1A93D6NF56G4GVEQ/versions \
-H "Content-Type: application/json"
```
## Response
### Success Response (200 OK)
```json theme={null}
[
{
"hash": "0x34a16478e83f69c4f0bcdb7549d32f92c9b7776bb3f71da06de334f1871eba0",
"moduleRegistryId": "01JPJ03YJT1A93D6NF56G4GVEQ",
"storageType": "s3",
"version": "1.0.0",
"versionChangelog": "Initial release",
"s3Key": "programs/0x34a16478e83f69c4f0bcdb7549d32f92c9b7776bb3f71da06de334f1871eba0.json",
"createdAt": "2024-03-17T10:24:00Z",
"updatedAt": "2024-03-17T10:24:00Z"
},
{
"hash": "0x45b27589f94g70d5g1cdeb8650e43g03k0c8887cc4g82eb17ef445g2982fcb1",
"moduleRegistryId": "01JPJ03YJT1A93D6NF56G4GVEQ",
"storageType": "s3",
"version": "1.1.0",
"versionChangelog": "Added new features",
"s3Key": "programs/0x45b27589f94g70d5g1cdeb8650e43g03k0c8887cc4g82eb17ef445g2982fcb1.json",
"createdAt": "2024-03-18T10:24:00Z",
"updatedAt": "2024-03-18T10:24:00Z"
}
]
```
### Not Found Response (404)
```json theme={null}
{
"error": "Module not found"
}
```
### Response Fields
Each version object contains:
| Field | Type | Description |
| ---------------- | -------------- | ------------------------------------------------- |
| hash | string | Program hash (unique identifier for this version) |
| moduleRegistryId | string | The module ID this version belongs to |
| storageType | string | Storage type: "s3" or "db" |
| version | string | Semantic version number |
| versionChangelog | string \| null | Changelog for this version |
| s3Key | string \| null | S3 key if stored in S3 |
| createdAt | string | ISO 8601 timestamp of version creation |
| updatedAt | string | ISO 8601 timestamp of last update |
## Notes
* No authentication is required for this endpoint
* Returns all versions of the module ordered by creation date
* Each version represents a different compiled program for the same module
* Versions are identified by their program hash
* The `storageType` indicates where the compiled program is stored (S3 or database)
* The `s3Key` is only present if the program is stored in S3
# Get Task Details
Source: https://docs.herodotus.cloud/data-processor-api/get-task-details
Retrieve comprehensive details of an HDP task including all metadata and MMRs used
# Get Task Details
Retrieves comprehensive details of a specific HDP task, including all metadata, MMRs used, and execution information. This endpoint does not require authentication.
## Endpoint
```
GET /tasks/{task_uuid}/details
```
## Path Parameters
| Parameter | Type | Description |
| ---------- | ------ | ---------------------------------------- |
| task\_uuid | string | The unique identifier (UUID) of the task |
## Example Request
```bash theme={null}
curl -X GET https://hdp.api.herodotus.cloud/tasks/01JPJ03YJT1A93D6NF56G4GVEQ/details \
-H "Content-Type: application/json"
```
## Response
### Success Response (200 OK)
```json theme={null}
{
"taskId": "01JPJ03YJT1A93D6NF56G4GVEQ",
"status": "TaskDecommitmentCompleted",
"destinationChainId": "11155111",
"scheduleMode": "onchain",
"scheduleTxHash": "0xabcd...",
"dataSourceChains": ["0xaa36a7", "0xaa37dc"],
"dataDestinationChain": "0xaa36a7",
"hdpCoreProgramHash": "0x5678...",
"taskHash": "0x9abc...",
"programHash": "0xdef0...",
"programName": "my_module",
"outputTreeRoot": "0x1234...",
"outputTreeRootPreimage": ["0x1", "0x2", "0x3"],
"taskInputs": {
"param1": "value1"
},
"mmrs": [
{
"id": "0x30314b345136303433515133424b4d42324e31394d4443595757",
"root": "0x6e7be7495a7126588df5ce10e090b27ea87357b966cc5b4143d0845ee15af0e",
"size": "0x2644",
"chain_id": "0xaa37dc",
"hashing_function": "poseidon"
}
],
"createdAt": "2024-03-17T10:24:00Z",
"updatedAt": "2024-03-17T10:25:00Z"
}
```
### Not Found Response (404)
```json theme={null}
{
"error": "Task not found",
"taskId": "01JPJ03YJT1A93D6NF56G4GVEQ"
}
```
### Response Fields
| Field | Type | Description |
| ---------------------- | -------------- | ------------------------------------------------- |
| taskId | string | The unique identifier of the task |
| status | string | Current status of the task |
| destinationChainId | string | Chain ID where the task will be proven |
| scheduleMode | string \| null | Schedule mode: "onchain" or "offchain" |
| scheduleTxHash | string \| null | Transaction hash if scheduled onchain |
| dataSourceChains | array \| null | Array of source chain IDs |
| dataDestinationChain | string \| null | Destination chain ID |
| hdpCoreProgramHash | string \| null | HDP core program hash |
| taskHash | string \| null | Task hash |
| programHash | string \| null | Program hash |
| programName | string \| null | Program name |
| outputTreeRoot | string \| null | Output tree root |
| outputTreeRootPreimage | array \| null | Output tree root preimage |
| taskInputs | object \| null | Task input parameters |
| mmrs | array | Array of MMR information objects used by the task |
| createdAt | string | ISO 8601 timestamp of task creation |
| updatedAt | string | ISO 8601 timestamp of last update |
### MMR Object Fields
| Field | Type | Description |
| ----------------- | ------ | --------------------------------------------------- |
| id | string | The MMR identifier (hex string) |
| root | string | The MMR root hash (hex string) |
| size | string | The size of the MMR (hex string) |
| chain\_id | string | The chain ID where this MMR is located (hex string) |
| hashing\_function | string | The hashing function used: "poseidon" or "keccak" |
## Notes
* No authentication is required for this endpoint
* This endpoint provides the most comprehensive view of a task
* MMRs array will be empty if no MMRs were used
* If task\_hash or output\_tree\_root are not stored in the database, they will be extracted from the task results if available
* The program\_hash will fallback to the HDP core program hash if not specified
# Get Task Output Preimage
Source: https://docs.herodotus.cloud/data-processor-api/get-task-output-preimage
Retrieve the output tree root preimage for a specific HDP task
# Get Task Output Preimage
Retrieves the output tree root preimage for a specific HDP task. This endpoint does not require authentication.
## Endpoint
```
GET /tasks/{task_uuid}/output_preimage
```
## Path Parameters
| Parameter | Type | Description |
| ---------- | ------ | ---------------------------------------- |
| task\_uuid | string | The unique identifier (UUID) of the task |
## Example Request
```bash theme={null}
curl -X GET https://hdp.api.herodotus.cloud/tasks/01JPJ03YJT1A93D6NF56G4GVEQ/output_preimage \
-H "Content-Type: application/json"
```
## Response
### Success Response (200 OK)
```json theme={null}
{
"taskId": "01JPJ03YJT1A93D6NF56G4GVEQ",
"outputPreimage": ["0x1", "0x2", "0x3", "0x4"]
}
```
### Not Found Response (404)
```json theme={null}
{
"error": "Task not found",
"taskId": "01JPJ03YJT1A93D6NF56G4GVEQ"
}
```
### Response Fields
| Field | Type | Description |
| -------------- | ------------- | --------------------------------------------------------------- |
| taskId | string | The unique identifier of the task |
| outputPreimage | array \| null | Array of preimage values (hex strings) or null if not available |
## Notes
* No authentication is required for this endpoint
* The output preimage is only available for completed tasks
* Returns null if the task doesn't have an output preimage stored
* The preimage values are hex-encoded strings representing the output tree root preimage
# Get Task State Transitions
Source: https://docs.herodotus.cloud/data-processor-api/get-task-state-transitions
Retrieve the complete state transition history for a specific HDP task
# Get Task State Transitions
Retrieves the complete state transition history for a specific HDP task, showing all status changes over time. This endpoint does not require authentication.
## Endpoint
```
GET /tasks/{task_uuid}/state_transitions
```
## Path Parameters
| Parameter | Type | Description |
| ---------- | ------ | ---------------------------------------- |
| task\_uuid | string | The unique identifier (UUID) of the task |
## Example Request
```bash theme={null}
curl -X GET https://hdp.api.herodotus.cloud/tasks/01JPJ03YJT1A93D6NF56G4GVEQ/state_transitions \
-H "Content-Type: application/json"
```
## Response
### Success Response (200 OK)
```json theme={null}
{
"taskId": "01JPJ03YJT1A93D6NF56G4GVEQ",
"state_transitions": [
{
"id": "01JPJ03YJT1A93D6NF56G4GVE1",
"task_id": "01JPJ03YJT1A93D6NF56G4GVEQ",
"from_status": null,
"to_status": "Received",
"created_at": "2024-03-17T10:24:00Z"
},
{
"id": "01JPJ03YJT1A93D6NF56G4GVE2",
"task_id": "01JPJ03YJT1A93D6NF56G4GVEQ",
"from_status": "Received",
"to_status": "DryRunStarted",
"created_at": "2024-03-17T10:24:05Z"
},
{
"id": "01JPJ03YJT1A93D6NF56G4GVE3",
"task_id": "01JPJ03YJT1A93D6NF56G4GVEQ",
"from_status": "DryRunStarted",
"to_status": "DryRunCompleted",
"created_at": "2024-03-17T10:24:10Z"
}
]
}
```
### Not Found Response (404)
```json theme={null}
{
"error": "Task not found",
"taskId": "01JPJ03YJT1A93D6NF56G4GVEQ"
}
```
### Response Fields
| Field | Type | Description |
| ------------------ | ------ | ---------------------------------------------------------- |
| taskId | string | The unique identifier of the task |
| state\_transitions | array | Array of state transition objects, ordered chronologically |
### State Transition Object Fields
| Field | Type | Description |
| ------------ | -------------- | -------------------------------------------------- |
| id | string | Unique identifier of the state transition |
| task\_id | string | The task UUID this transition belongs to |
| from\_status | string \| null | Previous status (null for initial state) |
| to\_status | string | New status after the transition |
| created\_at | string | ISO 8601 timestamp of when the transition occurred |
## Notes
* No authentication is required for this endpoint
* State transitions are ordered chronologically (oldest first)
* The first transition will have `from_status` as `null` (initial state)
* Useful for debugging and understanding task execution flow
* Each status change in the task lifecycle is recorded as a separate transition
# Health Check
Source: https://docs.herodotus.cloud/data-processor-api/health-check
Check the health status of the HDP server, database, and message queues
# Health Check
Returns the health status of the HDP server, including database and message queue connectivity. This endpoint does not require authentication.
## Endpoint
```
GET /is-alive
```
## Example Request
```bash theme={null}
curl -X GET https://hdp.api.herodotus.cloud/is-alive \
-H "Content-Type: application/json"
```
## Response
### Success Response (200 OK) - Healthy
```json theme={null}
{
"status": "healthy",
"database": "operational",
"queues": "operational"
}
```
### Service Unavailable Response (503) - Unhealthy
```json theme={null}
{
"status": "unhealthy",
"database": "unavailable",
"queues": "operational"
}
```
### Response Fields
| Field | Type | Description |
| -------- | ------ | ---------------------------------------------------- |
| status | string | Overall health status: "healthy" or "unhealthy" |
| database | string | Database status: "operational" or "unavailable" |
| queues | string | Message queue status: "operational" or "unavailable" |
## Health Status Logic
* The service is considered **healthy** only if both database and queues are operational
* If either database or queues are unavailable, the service returns a 503 status code
* This endpoint is useful for load balancer health checks and monitoring
## Notes
* No authentication is required for this endpoint
* Returns 200 OK if all systems are operational
* Returns 503 Service Unavailable if any system is down
* Useful for monitoring and automated health checks
# Data Processor API
Source: https://docs.herodotus.cloud/data-processor-api/introduction
HDP Server API for scheduling and managing Data Processor tasks — create tasks, upload modules, track status, and integrate with Atlantic proving.
Have a look at the [Data Processor API AI Skill](/skills/data-processor-api)
to give your LLM a head start on using the HDP Server API.
# HDP Server API
The HDP Server API provides endpoints for scheduling Data Processor tasks to Herodotus Atlantic.
## Base URL
```
https://hdp.api.herodotus.cloud
```
## Authentication
All API requests require authentication using an API key. Include your Herodotus Cloud API key in the request headers:
```bash theme={null}
X-API-KEY: your-herodotus-cloud-api-key-here
```
You can obtain an API key from the [Herodotus Console](https://www.herodotus.cloud).
## Rate Limiting
The API implements rate limiting to ensure fair usage. Please contact support for specific rate limit information.
## Response Format
All responses are returned in JSON format. Successful responses will have a 2xx status code, while errors will have appropriate 4xx or 5xx status codes with error details in the response body.
# List Modules
Source: https://docs.herodotus.cloud/data-processor-api/list-modules
Retrieve a list of HDP modules with optional filtering by marketplace or creator
# List Modules
Retrieves a list of HDP modules. Can be filtered to show only marketplace-published modules or modules by a specific creator. This endpoint does not require authentication.
## Endpoint
```
GET /modules
```
## Query Parameters
| Parameter | Type | Required | Description |
| ------------- | ------- | -------- | ------------------------------------------------------------ |
| marketplace | boolean | No | If `true`, returns only modules published on the marketplace |
| creator\_user | string | No | Filter modules by creator user identifier |
## Example Requests
### List all modules
```bash theme={null}
curl -X GET https://hdp.api.herodotus.cloud/modules \
-H "Content-Type: application/json"
```
### List only marketplace modules
```bash theme={null}
curl -X GET "https://hdp.api.herodotus.cloud/modules?marketplace=true" \
-H "Content-Type: application/json"
```
### List modules by creator
```bash theme={null}
curl -X GET "https://hdp.api.herodotus.cloud/modules?creator_user=user@example.com" \
-H "Content-Type: application/json"
```
## Response
### Success Response (200 OK)
```json theme={null}
{
"modules": [
{
"id": "01JPJ03YJT1A93D6NF56G4GVEQ",
"latestModuleVersionProgramHash": "0x34a16478e83f69c4f0bcdb7549d32f92c9b7776bb3f71da06de334f1871eba0",
"compilerVersion": "2.7.0",
"name": "my_module",
"description": "My awesome HDP module",
"usageCount": 42,
"tags": ["example", "tutorial"],
"downloadsCount": 100,
"usersCount": 25,
"isVerified": false,
"publishedOnMarketplace": true,
"creatorUser": "user@example.com",
"license": "MIT",
"abi": {
"type": "interface",
"items": []
},
"sourceCode": {
"src/lib.cairo": "fn main() {}"
},
"scarbToml": "[package]\nname = \"my_module\"\n...",
"createdAt": "2024-03-17T10:24:00Z",
"updatedAt": "2024-03-17T10:25:00Z"
}
]
}
```
### Response Fields
| Field | Type | Description |
| ------- | ----- | ----------------------- |
| modules | array | Array of module objects |
Each module object has the same structure as described in the [Get Module](./get-module) endpoint.
## Notes
* No authentication is required for this endpoint
* If `marketplace=true` is specified, only published modules are returned
* If `creator_user` is specified, only modules created by that user are returned
* If neither parameter is specified, all modules are returned
* The response includes full module details including source code and ABI
# List Tasks
Source: https://docs.herodotus.cloud/data-processor-api/list-tasks
Retrieve a paginated list of HDP tasks with optional search and filtering
# List Tasks
Retrieves a paginated list of all HDP tasks with optional search functionality. This endpoint does not require authentication.
## Endpoint
```
GET /tasks
```
## Query Parameters
| Parameter | Type | Required | Description |
| --------------------- | ------- | -------- | ------------------------------------------------------------------------------------- |
| hdp\_tasks\_page | integer | No | Page number (default: 1, minimum: 1) |
| hdp\_tasks\_per\_page | integer | No | Number of tasks per page (default: 10, minimum: 1, maximum: 100) |
| hdp\_tasks\_search | string | No | Search term to filter tasks by UUID, program hash, or program name (case-insensitive) |
## Example Request
```bash theme={null}
curl -X GET "https://hdp.api.herodotus.cloud/tasks?hdp_tasks_page=1&hdp_tasks_per_page=10&hdp_tasks_search=01JPJ" \
-H "Content-Type: application/json"
```
## Response
### Success Response (200 OK)
```json theme={null}
{
"tasks": [
{
"uuid": "01JPJ03YJT1A93D6NF56G4GVEQ",
"status": "TaskDecommitmentCompleted",
"destinationChainId": "11155111",
"contractClassHash": "0x1234...",
"scheduleMode": "onchain",
"scheduleTxHash": "0xabcd...",
"dataSourceChains": ["0xaa36a7", "0xaa37dc"],
"dataDestinationChain": "0xaa36a7",
"hdpCoreProgramHash": "0x5678...",
"taskHash": "0x9abc...",
"programHash": "0xdef0...",
"programName": "my_module",
"outputTreeRoot": "0x1234...",
"createdAt": "2024-03-17T10:24:00Z",
"updatedAt": "2024-03-17T10:25:00Z"
}
],
"pagination": {
"page": 1,
"perPage": 10,
"total": 42,
"totalPages": 5
}
}
```
### Response Fields
| Field | Type | Description |
| ---------- | ------ | --------------------- |
| tasks | array | Array of task objects |
| pagination | object | Pagination metadata |
### Task Object Fields
| Field | Type | Description |
| -------------------- | -------------- | -------------------------------------- |
| uuid | string | The unique identifier of the task |
| status | string | Current status of the task |
| destinationChainId | string | Chain ID where the task will be proven |
| contractClassHash | string | Hash of the contract class |
| scheduleMode | string \| null | Schedule mode: "onchain" or "offchain" |
| scheduleTxHash | string \| null | Transaction hash if scheduled onchain |
| dataSourceChains | array \| null | Array of source chain IDs |
| dataDestinationChain | string \| null | Destination chain ID |
| hdpCoreProgramHash | string \| null | HDP core program hash |
| taskHash | string \| null | Task hash |
| programHash | string \| null | Program hash |
| programName | string \| null | Program name |
| outputTreeRoot | string \| null | Output tree root |
| createdAt | string | ISO 8601 timestamp of task creation |
| updatedAt | string | ISO 8601 timestamp of last update |
### Pagination Object Fields
| Field | Type | Description |
| ---------- | ------- | ------------------------ |
| page | integer | Current page number |
| perPage | integer | Number of items per page |
| total | integer | Total number of tasks |
| totalPages | integer | Total number of pages |
## Notes
* No authentication is required for this endpoint
* Tasks are ordered by creation date (newest first)
* Search is case-insensitive and matches UUID, program hash, or program name
* Maximum 100 tasks per page to prevent excessive response sizes
* Empty search string is treated as no search filter
# Publish Module
Source: https://docs.herodotus.cloud/data-processor-api/publish-module
Publish an HDP module to the marketplace
# Publish Module
Publishes an HDP module to the marketplace, making it visible to all users. This endpoint requires authentication.
## Endpoint
```
POST /modules/{id}/publish
```
## Authentication
This endpoint requires authentication using an API key:
```bash theme={null}
X-API-KEY: your-herodotus-cloud-api-key-here
```
## Path Parameters
| Parameter | Type | Description |
| --------- | ------ | --------------------------- |
| id | string | The unique module ID (ULID) |
## Example Request
```bash theme={null}
curl -X POST https://hdp.api.herodotus.cloud/modules/01JPJ03YJT1A93D6NF56G4GVEQ/publish \
-H "Content-Type: application/json" \
-H "X-API-KEY: your-herodotus-cloud-api-key-here"
```
## Response
### Success Response (200 OK)
```json theme={null}
{
"message": "Module published to marketplace"
}
```
### Not Found Response (404)
```json theme={null}
{
"error": "Module not found"
}
```
### Unauthorized Response (401)
```json theme={null}
{
"error": "Missing Herodotus Cloud X-API-KEY header"
}
```
## Notes
* Authentication is required for this endpoint
* Publishing a module makes it visible in the marketplace
* Published modules can be discovered by all users
* Use the [Unpublish Module](./unpublish-module) endpoint to remove a module from the marketplace
# Retry Task
Source: https://docs.herodotus.cloud/data-processor-api/retry-task
Retry a failed HDP task from the beginning or retry only decommitment for TaskDecommitmentFailed tasks
# Retry Task
Retries a failed HDP task. For tasks that failed at decommitment stage (`TaskDecommitmentFailed`), only the decommitment step will be retried. For other failed tasks, the entire workflow will be retried from the beginning. This endpoint requires authentication.
## Endpoint
```
POST /tasks/{task_uuid}/retry
```
## Authentication
This endpoint requires authentication using an API key:
```bash theme={null}
X-API-KEY: your-herodotus-cloud-api-key-here
```
## Path Parameters
| Parameter | Type | Description |
| ---------- | ------ | ------------------------------------------------- |
| task\_uuid | string | The unique identifier (UUID) of the task to retry |
## Example Request
```bash theme={null}
curl -X POST https://hdp.api.herodotus.cloud/tasks/01JPJ03YJT1A93D6NF56G4GVEQ/retry \
-H "Content-Type: application/json" \
-H "X-API-KEY: your-herodotus-cloud-api-key-here"
```
## Response
### Success Response (200 OK)
```json theme={null}
{
"message": "Task has been queued for retry",
"status": "accepted",
"uuid": "01JPJ03YJT1A93D6NF56G4GVEQ"
}
```
### Not Found Response (404)
```json theme={null}
{
"error": "Task not found",
"uuid": "01JPJ03YJT1A93D6NF56G4GVEQ"
}
```
### Bad Request Response (400)
For decommitment retry without results:
```json theme={null}
{
"error": "Cannot retry decommitment",
"details": "Task results are missing. Cannot retry decommitment without results."
}
```
### Unauthorized Response (401)
```json theme={null}
{
"error": "Missing Herodotus Cloud X-API-KEY header"
}
```
### Response Fields
| Field | Type | Description |
| ------- | ------ | ----------------------------------------------- |
| message | string | Success message |
| status | string | Status of the request (always "accepted") |
| uuid | string | The unique identifier of the task |
| error | string | Error message (only present in error responses) |
## Retry Behavior
### Full Retry
For tasks that failed at any stage except `TaskDecommitmentFailed`, the entire workflow will be retried:
* Dry run validation
* Chain proofs fetching
* Trace generation
* Atlantic proving
* Task decommitment
### Decommitment-Only Retry
For tasks with status `TaskDecommitmentFailed`, only the decommitment step will be retried:
* The task results must be available
* Trace generation and Atlantic proving steps are skipped
* Only the decommitment workflow is executed
## Notes
* Authentication is required for this endpoint
* The task status will be reset to `Received` before retry
* For decommitment-only retries, the task results must be present
* The retry will create a new task execution in the queue
* Use this endpoint to recover from transient failures
# Get Task Status
Source: https://docs.herodotus.cloud/data-processor-api/task-status
Retrieve the current processing status and details of an HDP task by its UUID
# Get Task Status
Retrieves the current status of a scheduled Data Processor task. This endpoint does not require authentication.
## Endpoint
```
GET /tasks/{task_uuid}/status
```
## Path Parameters
| Parameter | Type | Description |
| ---------- | ------ | ---------------------------------------- |
| task\_uuid | string | The unique identifier (UUID) of the task |
## Example Request
```bash theme={null}
curl -X GET https://hdp.api.herodotus.cloud/tasks/01JPJ03YJT1A93D6NF56G4GVEQ/status \
-H "Content-Type: application/json"
```
## Response
### Success Response (200 OK)
```json theme={null}
{
"taskId": "01JPJ03YJT1A93D6NF56G4GVEQ",
"status": "AtlanticProvingStarted",
"errorMessage": null,
"updatedAt": "2024-03-17T10:24:00Z"
}
```
### Not Found Response (404)
```json theme={null}
{
"error": "Task not found",
"taskId": "01JPJ03YJT1A93D6NF56G4GVEQ"
}
```
### Server Error Response (500)
```json theme={null}
{
"error": "Internal Server Error"
}
```
### Response Fields
| Field | Type | Description |
| ------------ | -------------- | ----------------------------------------------- |
| taskId | string | The unique identifier of the task |
| status | string | Current status of the task |
| errorMessage | string \| null | Error message if task failed, null otherwise |
| updatedAt | string | ISO 8601 timestamp of the last status update |
| error | string | Error message (only present in error responses) |
### Possible Status Values
* `Received`: Task has been received and is queued
* `DryRunStarted`: Dry run validation has started
* `DryRunCompleted`: Dry run validation completed successfully
* `DryRunFailed`: Dry run validation failed
* `ChainProofsFetchStarted`: Started fetching chain storage proofs
* `ChainProofsFetchCompleted`: Chain proofs fetched successfully
* `ChainProofsFetchFailed`: Failed to fetch chain storage proofs
* `TraceGenStarted`: Trace generation has started
* `TraceGenCompleted`: Trace generation completed successfully
* `TraceGenFailed`: Trace generation failed
* `AtlanticProvingStarted`: Atlantic proving has started
* `AtlanticProvingCompleted`: Atlantic proving completed successfully
* `AtlanticProvingFailed`: Atlantic proving failed
* `TaskDecommitmentStarted`: Task decommitment has started
* `TaskDecommitmentCompleted`: Task decommitment completed successfully. This is the final status for completed workflows.
* `TaskDecommitmentFailed`: Task decommitment failed
## Notes
* No authentication is required for this endpoint
* The response includes the task ID and current status
* For completed tasks, the response includes the completion timestamp
* If the task failed, the error message will be included in the response
* The status endpoint can be polled to track task progress
# Unpublish Module
Source: https://docs.herodotus.cloud/data-processor-api/unpublish-module
Remove an HDP module from the marketplace
# Unpublish Module
Removes an HDP module from the marketplace, making it no longer visible to other users. This endpoint requires authentication.
## Endpoint
```
POST /modules/{id}/unpublish
```
## Authentication
This endpoint requires authentication using an API key:
```bash theme={null}
X-API-KEY: your-herodotus-cloud-api-key-here
```
## Path Parameters
| Parameter | Type | Description |
| --------- | ------ | --------------------------- |
| id | string | The unique module ID (ULID) |
## Example Request
```bash theme={null}
curl -X POST https://hdp.api.herodotus.cloud/modules/01JPJ03YJT1A93D6NF56G4GVEQ/unpublish \
-H "Content-Type: application/json" \
-H "X-API-KEY: your-herodotus-cloud-api-key-here"
```
## Response
### Success Response (200 OK)
```json theme={null}
{
"message": "Module unpublished from marketplace"
}
```
### Not Found Response (404)
```json theme={null}
{
"error": "Module not found"
}
```
### Unauthorized Response (401)
```json theme={null}
{
"error": "Missing Herodotus Cloud X-API-KEY header"
}
```
## Notes
* Authentication is required for this endpoint
* Unpublishing a module removes it from the marketplace but does not delete it
* The module remains accessible via direct ID lookup
* Use the [Publish Module](./publish-module) endpoint to republish a module
# Update Module
Source: https://docs.herodotus.cloud/data-processor-api/update-module
Update metadata for an existing HDP module
# Update Module
Updates metadata for an existing HDP module. Only the provided fields will be updated. This endpoint requires authentication.
## Endpoint
```
PATCH /modules/{id}
```
## Authentication
This endpoint requires authentication using an API key:
```bash theme={null}
X-API-KEY: your-herodotus-cloud-api-key-here
```
## Path Parameters
| Parameter | Type | Description |
| --------- | ------ | --------------------------- |
| id | string | The unique module ID (ULID) |
## Request Body
| Field | Type | Required | Description |
| ------------ | ------ | -------- | --------------------------------------------------------- |
| description | string | No | Module description |
| tags | array | No | Array of tags |
| license | string | No | License identifier |
| abi | object | No | Module ABI as JSON |
| source\_code | object | No | Source code files as JSON object mapping paths to content |
### Example Request
```bash theme={null}
curl -X PATCH https://hdp.api.herodotus.cloud/modules/01JPJ03YJT1A93D6NF56G4GVEQ \
-H "Content-Type: application/json" \
-H "X-API-KEY: your-herodotus-cloud-api-key-here" \
-d '{
"description": "Updated description",
"tags": ["updated", "tags"],
"license": "Apache-2.0"
}'
```
## Response
### Success Response (200 OK)
Returns the updated module with the same structure as [Get Module](./get-module).
### Not Found Response (404)
```json theme={null}
{
"error": "Module not found"
}
```
### Unauthorized Response (401)
```json theme={null}
{
"error": "Missing Herodotus Cloud X-API-KEY header"
}
```
## Notes
* Authentication is required for this endpoint
* Only the fields provided in the request body will be updated
* Fields not included in the request will remain unchanged
* The `source_code` field should be a JSON object mapping file paths to file contents
* The `abi` field should be a valid JSON object
# Upload Module
Source: https://docs.herodotus.cloud/data-processor-api/upload-module
Upload a new HDP module with compiled program, source code, and metadata
# Upload Module
Uploads a new HDP module to the registry. This endpoint accepts multipart form data containing the compiled module, source files, ABI, and metadata. The creator user is automatically inferred from the API key. This endpoint requires authentication.
## Endpoint
```
POST /modules/upload
```
## Authentication
This endpoint requires authentication using an API key:
```bash theme={null}
X-API-KEY: your-herodotus-cloud-api-key-here
```
## Request Body (Multipart Form Data)
| Field | Type | Required | Description |
| ------------------ | ------------- | -------- | ------------------------------------------------------------------------------ |
| module | file (JSON) | Yes | The compiled contract class JSON file |
| name | string | Yes | Module name |
| compiler\_version | string | No | Compiler version (extracted from module if not provided) |
| version | string | Yes | Semantic version (e.g., "1.0.0") |
| description | string | No | Module description |
| tags | string | No | Comma-separated tags |
| license | string | No | License identifier |
| version\_changelog | string | No | Changelog for this version |
| source\_files | string (JSON) | No | JSON object mapping file paths to content: `{"src/lib.cairo": "content", ...}` |
| abi | string (JSON) | No | Module ABI as JSON |
| scarb\_toml | string | No | Scarb.toml file content |
## Example Request
```bash theme={null}
curl -X POST https://hdp.api.herodotus.cloud/modules/upload \
-H "X-API-KEY: your-herodotus-cloud-api-key-here" \
-F "module=@my_module.compiled_contract_class.json" \
-F "name=my_module" \
-F "version=1.0.0" \
-F "description=My awesome HDP module" \
-F "tags=example,tutorial" \
-F "license=MIT" \
-F "version_changelog=Initial release" \
-F "source_files={\"src/lib.cairo\": \"fn main() {}\"}" \
-F "abi={\"type\": \"interface\", ...}" \
-F "scarb_toml=[package]\nname = \"my_module\"\n..."
```
## Response
### Success Response (201 Created)
```json theme={null}
{
"id": "01JPJ03YJT1A93D6NF56G4GVEQ",
"programHash": "0x34a16478e83f69c4f0bcdb7549d32f92c9b7776bb3f71da06de334f1871eba0",
"compilerVersion": "2.7.0",
"createdAt": "2024-03-17T10:24:00Z",
"message": "Module uploaded successfully"
}
```
### Error Response (400 Bad Request)
```json theme={null}
{
"error": "Version 1.0.0 already exists for this module"
}
```
### Error Response (401 Unauthorized)
```json theme={null}
{
"error": "Missing Herodotus Cloud X-API-KEY header"
}
```
### Response Fields
| Field | Type | Description |
| --------------- | ------ | --------------------------------------- |
| id | string | The unique module ID (ULID) |
| programHash | string | The program hash of the uploaded module |
| compilerVersion | string | The compiler version used |
| createdAt | string | ISO 8601 timestamp of module creation |
| message | string | Success message |
## Version Management
* Each module can have multiple versions
* Version numbers must be unique per module (semantic versioning recommended)
* The uploaded version becomes the latest version for the module
* If a version already exists for the module, the upload will fail with a 400 error
## Storage
* Compiled programs are stored in S3 (if configured) or in the database as fallback
* Source code is always stored in the database
* Scarb.toml is stored in the database for reference
## Notes
* Authentication is required for this endpoint
* The creator user is automatically inferred from the API key
* The module must be a Cairo 1 compiled program (Cairo 0 is not supported)
* The compiler version is extracted from the module if not provided
* Source files should be provided as a JSON object mapping relative paths to file contents
* The ABI should be provided as a JSON string
* Duplicate versions for the same module are not allowed
# Architecture Overview
Source: https://docs.herodotus.cloud/data-processor/architecture
How Cairo1 modules, Cairo0 verification, and Rust handlers work together in HDP
HDP is a layered system that combines Cairo1 developer ergonomics with Cairo0 verification/runtime machinery and Rust orchestration.
## Layers
* **Cairo1 user layer**: your module uses `hdp_cairo` APIs.
* **Bootloader layer (Cairo0)**: loads and executes the compiled Cairo1 class.
* **Verification layer (Cairo0)**: validates MMR/MPT/Patricia proofs (see [Verification model](/data-processor/verification)).
* **Hint processors (Rust)**: bridge Cairo VM execution with proof decoding and data handling.
* **Orchestration layer (Rust)**: runs `dry-run`, `fetch-proofs`, and `sound-run`.
## Data flow
```text theme={null}
+-----------+ +-----------+ +-----------+
| Dry Run | -> | Fetcher | -> | Sound Run |
| RPC keys | | Proofs | | Verify run|
+-----------+ +-----------+ +-----------+
dry_run_output.json -> proofs.json -> outputs
```
## Cairo1 and Cairo0 boundary
* Cairo1 module code requests data through `hdp_cairo`.
* Under the hood this uses VM syscalls routed to HDP handlers.
* In **dry run**, handlers query RPCs and record accessed keys.
* In **sound run**, handlers read from already-verified memorizers (offline path).
This keeps your module logic the same across stages while switching the data source from live RPC to verified local state.
For stage-by-stage behavior, see [Pipeline stages](/data-processor/pipeline).
## Syscall model (high level)
* Main selector for HDP data access: `CallContract`
* Hashing selector used by runtime: `Keccak`
Routing uses:
* special contract addresses for internal handlers,
* plus chain-id-aware dispatch for EVM vs Starknet access paths.
## Why this architecture matters
* You write simple module logic once.
* HDP separates discovery, proof retrieval, and deterministic replay.
* The final execution is reproducible and ready for proof workflows.
# HDP Capabilities and API Surface
Source: https://docs.herodotus.cloud/data-processor/capabilities
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` | 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` | Current root for the labeled injected trie |
| `read_key(label, key)` | `label: felt252, key: felt252` | `Option` | 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)
# CLI Installation and Usage
Source: https://docs.herodotus.cloud/data-processor/cli-installation
Install the HDP CLI and run your first HDP pipeline
Use this page to install the HDP CLI and run a complete local pipeline.
## Prerequisites
HDP requires:
* Rust
* Scarb (Cairo toolchain)
* `uv` (Python package manager)
* Access to chain RPC endpoints
Install Rust:
```bash theme={null}
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
Install `uv`:
```bash theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Optional:
* Docker
* Nightly Rust (if you plan to generate [STWO prover input](/data-processor/proving) locally)
## Install HDP CLI
Install latest:
```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/HerodotusDev/hdp-cairo/main/install-cli.sh | bash
```
Install a specific version:
```bash theme={null}
VERSION=vX.X.X curl -fsSL https://raw.githubusercontent.com/HerodotusDev/hdp-cairo/main/install-cli.sh | bash
```
## Build from source (optional)
```bash theme={null}
git clone https://github.com/HerodotusDev/hdp-cairo.git
cd hdp-cairo
git submodule update --init
uv sync
source .venv/bin/activate
```
Optional Make targets:
```bash theme={null}
make setup
make build
make test
```
Optional Docker path:
```bash theme={null}
docker build -t hdp-cairo .
docker run --rm -it hdp-cairo --help
```
## Configure environment
Check required variables:
```bash theme={null}
hdp env-info
```
Check only the variables needed for your run:
```bash theme={null}
hdp env-check --inputs dry_run_output.json
```
For all environment variables, see [Configuration reference](/data-processor/reference-configuration).
If you are working from a local `hdp-cairo` checkout, copy:
```bash theme={null}
cp example.env .env
```
Then set your RPC endpoints and environment values.
## First usage flow (CLI)
After you compile your module (for example with `scarb build`), run:
1. Dry run:
```bash theme={null}
hdp dry-run -m module_contract_class.json --print_output
```
2. Fetch proofs:
```bash theme={null}
hdp fetch-proofs
```
3. Sound run:
```bash theme={null}
hdp sound-run -m module_contract_class.json --print_output
```
At the end of the flow, HDP prints output data used for downstream proving and settlement workflows.
## First full run example (`starkgate`)
```bash theme={null}
cd examples/starkgate
scarb build
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
```
Expected artifacts:
* Stage 1: `dry_run_output.json`
* Stage 2: `proofs.json`
* Stage 3 output includes `task_hash`, `output_root`, and `mmr_metas`
See output details in [Output model](/data-processor/output).
## Full command example (`eth_call`)
From the official example:
```bash theme={null}
scarb build -p example_eth_call && \
hdp dry-run -m target/dev/example_eth_call_module.compiled_contract_class.json --print_output && \
hdp fetch-proofs --mmr-deployment-config examples/eth_call/mmr_deployment_config.json && \
hdp sound-run -m target/dev/example_eth_call_module.compiled_contract_class.json --print_output --cairo_pie ./pie.zip
```
Reference files:
* Module: [examples/eth\_call/src/lib.cairo](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/eth_call/src/lib.cairo)
* Run script: [examples/eth\_call/run.sh](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/eth_call/run.sh)
## On-chain finality reminder
Even with successful local execution, on-chain settlement requires that accessed blocks are included in [Herodotus Satellite](https://github.com/HerodotusDev/satellite) MMRs.
# Debugging
Source: https://docs.herodotus.cloud/data-processor/debugging
Common troubleshooting steps for HDP pipelines and Cairo modules
## Increase logs
* Use `--log-level `
* Use `--debug`
* Or set `RUST_LOG=debug`
## Check environment early
```bash theme={null}
hdp env-info
hdp env-check --inputs dry_run_output.json
```
For environment variable definitions, see [Configuration reference](/data-processor/reference-configuration).
## Inspect stage artifacts
* `dry_run_output.json` should contain key sets
* `proofs.json` should contain chain/state/unconstrained proof data
* `--print_output` helps verify computed outputs during dry/sound run
See artifact flow in [Pipeline stages](/data-processor/pipeline).
If outputs look inconsistent, rerun the pipeline in order and keep module + inputs unchanged across stages.
## Cairo module debugging with `println!`
In development, you can allow debug prints by setting:
```toml theme={null}
[[target.starknet-contract]]
allowed-libfuncs-deny = true
```
## Sound run is offline
`sound-run` does not call RPCs.\
If data seems missing, the usual cause is mismatched or incomplete `proofs.json`.
## Injected state checks
* Verify `INJECTED_STATE_BASE_URL`
* Confirm [state server](/data-processor/state-server) is running
* Ensure `--injected_state` points to the intended JSON
## Proof-mode outputs
* `--proof_mode`
* `--cairo_pie `
* `--stwo_prover_input `
# Design Patterns and Constraints
Source: https://docs.herodotus.cloud/data-processor/design-patterns
How to design sound HDP modules without overtrusting off-chain indexing
This page is about building **sound** HDP applications.
## Core principle
HDP proves:
1. The on-chain data your module accessed is authentic for the specified chain/block.
2. Your Cairo logic ran correctly over that data.
HDP does **not** automatically prove that an off-chain query/[indexer](/data-structure-indexer-api/introduction) found every item unless your module enforces constraints that make omission/duplication impossible.
## Pattern: "Gather off-chain, constrain in HDP"
When working with subsets ("all events matching X"), use this shape:
1. Gather candidates off-chain ([indexer](/data-structure-indexer-api/introduction)/API/backend).
2. Pass them to HDP.
3. In Cairo, enforce:
* membership authenticity,
* uniqueness,
* completeness commitment (counter/root/range/accumulator).
If completeness is not constrained, "processed subset" claims are weaker.
## Useful constraint patterns
* **Monotonic counters**: contract-level counters that must match processed counts.
* **Root commitments**: Merkle/MMR roots committed on-chain, then matched in HDP (see [Verification model](/data-processor/verification)).
* **Uniqueness guards**: nonce/order constraints to prevent duplicates.
* **Range commitments**: explicit `(start, end)` bounds and deterministic traversal checks.
## Multi-chain and finality caveat
Even with successful local stages ([`dry-run`/`fetch-proofs`/`sound-run`](/data-processor/pipeline)), settlement depends on chain data being present in settlement [MMRs](/data-processor/verification).
Always confirm your target blocks and chain combination are supported by the relevant [MMR](/data-processor/verification) state.
## Practical sizing guidance
Throughput depends on your actual computation and resulting step count, not only on payload shape. Start with a narrow prototype, measure steps/resources, then scale (including splitting and recursive composition when needed).
## Debugging and iteration tips
* Keep modules small at first, then add constraints incrementally.
* Print intermediate values during development (`println!`).
* Use fixed known blocks and deterministic test inputs early.
* Keep assumptions explicit in code and docs.
# Official HDP Documentation
Source: https://docs.herodotus.cloud/data-processor/documentation
Primary upstream docs for hdp-cairo
Read the upstream HDP Cairo documentation:
* [https://herodotusdev.github.io/hdp-cairo/](https://herodotusdev.github.io/hdp-cairo/)
These are the more in-depth, technical HDP docs maintained with the core implementation.
Key pages:
* Introduction: [https://herodotusdev.github.io/hdp-cairo/introduction.html](https://herodotusdev.github.io/hdp-cairo/introduction.html)
* Architecture: [https://herodotusdev.github.io/hdp-cairo/architecture.html](https://herodotusdev.github.io/hdp-cairo/architecture.html)
* Getting Started: [https://herodotusdev.github.io/hdp-cairo/getting\_started.html](https://herodotusdev.github.io/hdp-cairo/getting_started.html)
# Provable EVM Contract Calls
Source: https://docs.herodotus.cloud/data-processor/eth-call
Using execute_eth_call to call EVM contracts at historical blocks inside HDP
`execute_eth_call` is one of HDP's most powerful features: you can run an EVM contract call inside a ZK execution context and prove the result.
In practice, this gives you a clean way to reason about **time**:
* "What was this wallet's USDC balance at block X?"
* "What was voting power exactly when voting started?"
* "Was an address eligible at snapshot block Y?"
## Why this dramatically simplifies development
With `execute_eth_call`, you can often avoid manual slot math and low-level proof wiring:
* Reuse contract ABIs and familiar call patterns.
* Keep most application logic in Solidity/backends.
* Add a focused Cairo1 proof module only for the verifiable part.
* Get historical, provable answers without deep storage-proof expertise.
Under the hood, HDP wraps the call in an EIP-1559-style transaction context and executes it inside a Cairo EVM interpreter while reading state through HDP memorizers.
## Function signature
```rust theme={null}
pub fn execute_eth_call(
hdp: @HDP,
time_and_space: @TimeAndSpace,
sender: EthAddress,
target: EthAddress,
calldata: Span,
) -> TransactionResult
```
`TimeAndSpace` pins the call to a specific chain and block:
```rust theme={null}
TimeAndSpace { chain_id: 1, block_number: 21370000 }
```
## Return value
`TransactionResult` includes:
* `success: bool`
* `return_data: Span`
* `gas_used: u64`
* `state: State`
You decode `return_data` in your Cairo module according to the ABI.
## Real example: historical `balanceOf`
The official example calls USDC `balanceOf(address)` for Vitalik at a fixed Ethereum mainnet block and converts return bytes into `u256`:
* Example module: [examples/eth\_call/src/lib.cairo](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/eth_call/src/lib.cairo)
* Example run script: [examples/eth\_call/run.sh](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/eth_call/run.sh)
## Typical use cases
* Historical balance snapshots for governance, rewards, and accounting
* Time-bounded eligibility checks (airdrop, campaign, compliance windows)
* Proof-backed state derivations without manual storage-slot plumbing
* Solidity-heavy products that need minimal Cairo1 surface area
## Current behavior to be aware of
As currently implemented, `execute_eth_call` constructs an EIP-1559 call with fixed internals (for example `nonce = 0`, `value = 0`, configured gas fields, empty access list). For most read-style calls this is exactly what you want, but advanced flows should still review implementation details in source.
`execute_eth_call` is designed for `eth_call`-style execution (read-oriented behavior, no state mutation as part of settled chain state), and opcode support is intentionally scoped.
## Run and prove
One practical flow is:
1. Build and run HDP pipeline (`dry-run` -> `fetch-proofs` -> `sound-run`)
2. Export Cairo PIE
3. Send proving/verification workload to [Atlantic](/atlantic-api/introduction)
See:
* [Ways to run HDP](/data-processor/running-hdp)
* [Atlantic Introduction](/atlantic-api/introduction)
# Official Examples by Use Case
Source: https://docs.herodotus.cloud/data-processor/examples
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.
# Glossary
Source: https://docs.herodotus.cloud/data-processor/glossary
Core HDP terms
* **Dry run**: Simulation phase that discovers which on-chain keys are needed. See [Pipeline stages](/data-processor/pipeline).
* **Fetcher**: Stage that collects cryptographic proofs for discovered keys. See [Pipeline stages](/data-processor/pipeline).
* **Sound run**: Offline verification and execution stage. See [Pipeline stages](/data-processor/pipeline).
* **Memorizer**: Cairo0 dictionary-based storage for verified data. See [State management](/data-processor/state-management).
* **MMR**: Merkle Mountain Range accumulator for block headers. See [Verification model](/data-processor/verification).
* **MPT**: Merkle Patricia Trie used for Ethereum state proofs. See [Verification model](/data-processor/verification).
* **Task hash**: Unique identifier for a computation. See [Output model](/data-processor/output).
* **Output root**: Merkle root of computed results. See [Output model](/data-processor/output).
* **Injected state**: Custom persistent state backed by a Patricia trie. See [State management](/data-processor/state-management) and [State Server](/data-processor/state-server).
* **Unconstrained data**: Data validated by hash instead of inclusion proof.
* **STWO**: STARK proving path supported by HDP tooling. See [Proving with STWO](/data-processor/proving).
* **Bootloader**: Cairo0 program that executes compiled Cairo1 modules.
# Data Processor (HDP)
Source: https://docs.herodotus.cloud/data-processor/introduction
What HDP is, why teams use it, and what it can (and cannot) prove — verifiable computation over historical on-chain data with Cairo modules.
Have a look at the [Data Processor AI Skill](/skills/data-processor) to give
your LLM a head start on using HDP.
HDP (Herodotus Data Processor) is a Cairo framework for **provable on-chain data access + provable computation**.
You write Cairo logic, HDP fetches and verifies the required chain data and proofs, then executes your logic and produces a trace that can be proven.
## The problem HDP solves
Historical on-chain data is hard to use in a verifiable way at scale.
* [Indexers](/data-structure-indexer-api/introduction) are fast, but not cryptographic truth by themselves.
* Raw chain replay is expensive and difficult to operationalize.
* Proving historical statements needs both the data and a proof trail back to trusted roots.
## Why HDP is great for builders
HDP removes most of the painful parts of proof-backed chain data work:
* **You can use storage proofs without becoming a storage-proof expert.**
* **You can read historical state from [MMR-backed](/data-processor/verification) chain history**, not only latest state.
* **You write simple Cairo1 modules while leveraging Cairo0 performance** thanks to HDP's backend.
* **You can choose managed proving in [Atlantic](/atlantic-api/introduction)**, use the latest `S-two` prover and legacy `Stone`, leveraging the cost savings of using SHARP (Starkware's shared proving service) and proving your programs alongside StarkNet itself and many other projects.
* **You can stay Solidity-first for business logic** by utilizing the provable ETH Call and use HDP where proof-backed historical access is needed.
## What HDP gives you
* **Trustless access to historical and current chain data** from supported EVM chains and Starknet.
* **Provable execution** of your Cairo program over that authenticated data.
* **Cross-chain modules** where one program reads from multiple chains in a single run.
* **Composable proving flows**: run locally, send to [Atlantic](/atlantic-api/introduction), or orchestrate through [HDP Server](/data-processor-api/introduction).
* **High flexibility**: you define the computation, constraints, and output format.
## What HDP is not
HDP is **not** an [indexer](/data-structure-indexer-api/introduction) and **not** a SQL-like query engine by itself.
If you need "all events matching condition X", you typically:
1. Gather candidate data off-chain ([indexer](/data-structure-indexer-api/introduction), backend, or your own pipeline).
2. Feed that data into your HDP module.
3. Add hard constraints in Cairo so missing/duplicated/tampered data is rejected.
This separation is important and keeps the system explicit and auditable.
## Why teams use HDP
* **Historical state checks** (for example, balances at specific old blocks).
* **Governance and voting logic** (for example, voting power at vote time).
* **Airdrop eligibility and scoring** over historical activity.
* **Compliance-style checks** over a bounded transaction/event set.
* **Bridge and cross-chain accounting** with one verifiable pipeline.
* **Faster product delivery** because teams do not need to hand-build proof plumbing from scratch.
## Execution model in one view
HDP follows three practical stages:
1. **Dry run**: discover which on-chain facts your module needs.
2. **Fetch proofs**: retrieve required chain data and proofs.
3. **Sound run**: execute the module against verified data and generate the trace / Cairo PIE.
From there, you can send proving/verification jobs to [Atlantic](/atlantic-api/introduction) or schedule workflows through [HDP Server](/data-processor-api/introduction).
## Architecture at a glance
```text theme={null}
+------------------------+
| Cairo1 module |
| uses hdp.* APIs |
+------------------------+
| Cairo0 bootloader |
| verifiers + outputs |
+------------------------+
| Rust hints/handlers |
| Dry: RPC keys |
| Sound: memorizer reads |
+------------------------+
```
## Important finality note
Even when local stages succeed, settlement depends on [MMR](/data-processor/verification) inclusion:
* The blocks you access must be included in the corresponding [Herodotus Satellite](https://github.com/HerodotusDev/satellite) MMRs.
* This is especially important when mixing chains or environments.
## Continue reading
* [More in-depth technical HDP docs](https://herodotusdev.github.io/hdp-cairo/)
* [CLI installation and usage](/data-processor/cli-installation)
* [Architecture overview](/data-processor/architecture)
* [Pipeline stages](/data-processor/pipeline)
* [HDP Capabilities and API Surface](/data-processor/capabilities)
* [Verification model](/data-processor/verification)
* [State management](/data-processor/state-management)
* [State Server](/data-processor/state-server)
* [Output model](/data-processor/output)
* [Provable EVM Contract Calls (`execute_eth_call`)](/data-processor/eth-call)
* [Proving with STWO](/data-processor/proving)
* [Ways to run HDP](/data-processor/running-hdp)
* [HDP Server docs](/data-processor-api/introduction)
* [Design patterns and constraints](/data-processor/design-patterns)
* [Examples mapped to use cases](/data-processor/examples)
* [CLI reference](/data-processor/reference-cli)
* [Configuration reference](/data-processor/reference-configuration)
* [Types reference](/data-processor/reference-types)
* [Debugging](/data-processor/debugging)
* [Glossary](/data-processor/glossary)
# Output Model
Source: https://docs.herodotus.cloud/data-processor/output
task_hash, output_root, and mmr_metas produced by HDP
After sound run, HDP produces three core outputs:
1. **task\_hash**
2. **output\_root**
3. **[mmr\_metas](/data-processor/verification)**
These values are designed for verification and settlement workflows.
See also [Verification model](/data-processor/verification).
## task\_hash
`task_hash` uniquely identifies the computation for the module + public inputs.
Formula:
```text theme={null}
task_hash = keccak(module_hash || 0x40 || public_inputs_len || public_inputs)
```
## output\_root
`output_root` is a Merkle commitment over module results (`retdata`), using an OpenZeppelin StandardMerkleTree-style approach with double-hashed leaves.
This lets consumers verify result inclusion against a compact root.
## mmr\_metas
`mmr_metas` contains metadata for header commitments used during verification.
* Poseidon entries: `(id, size, chain_id, root)`
* Keccak entries: `(id, size, chain_id, root_low, root_high)`
## Output segment layout
```text theme={null}
task_hash_low
task_hash_high
output_root_low
output_root_high
poseidon_len
keccak_len
poseidon_metas (4 felts each)
keccak_metas (5 felts each)
```
# Pipeline Stages
Source: https://docs.herodotus.cloud/data-processor/pipeline
Dry run, fetch-proofs, and sound run end-to-end
HDP execution is split into three stages so proof collection and deterministic execution stay clean and debuggable.
## Why three stages
You can only fetch proofs after you know which keys your module touched.\
So HDP first discovers keys, then fetches proofs, then replays computation offline.
## Flow
```text theme={null}
+-----------+ +-----------+ +-----------+
| Dry Run | -> | Fetcher | -> | Sound Run |
| RPC keys | | Proofs | | Verify run|
+-----------+ +-----------+ +-----------+
dry_run_output.json -> proofs.json -> outputs
```
## Stage 1: Dry run
Purpose:
* Execute module against live RPCs
* Collect every key used by EVM/Starknet/injected-state/unconstrained handlers
Main output:
* `dry_run_output.json`
Command:
```bash theme={null}
hdp dry-run -m --print_output
```
## Stage 2: Fetch proofs
Purpose:
* Build proof payloads from keys found in stage 1
Proof sources:
* MMR proofs for headers (via [Herodotus Indexer](/data-structure-indexer-api/introduction))
* MPT/Patricia proofs for state (see [Verification model](/data-processor/verification))
* Injected-state proofs from the [state server](/data-processor/state-server)
* Unconstrained payloads (for example bytecode blobs validated later by hash)
Main output:
* `proofs.json`
Command:
```bash theme={null}
hdp fetch-proofs --inputs dry_run_output.json --output proofs.json
```
Useful options:
* `--mmr-hasher-config `
* `--mmr-deployment-config `
## Stage 3: Sound run
Purpose:
* Verify proofs
* Execute the same module offline (no RPC calls)
* Produce commitments for downstream verification and settlement workflows
Main outputs:
* `task_hash`
* `output_root`
* `mmr_metas`
Command:
```bash theme={null}
hdp sound-run -m --proofs proofs.json --print_output
```
Proof-mode options:
* `--proof_mode`
* `--cairo_pie `
* `--stwo_prover_input ` (when CLI is built with [STWO support](/data-processor/proving))
## Consistency requirement
`proofs.json` must come from the matching `dry_run_output.json` for the same module and inputs.
# Proving with STWO
Source: https://docs.herodotus.cloud/data-processor/proving
Generate STWO prover input from HDP sound-run
HDP can emit STWO prover input during `sound-run`.
## Build CLI with STWO feature
```bash theme={null}
cargo +nightly build --release --bin hdp-cli --features stwo
```
## Generate STWO input
```bash theme={null}
hdp sound-run \
-m \
--proof_mode \
--stwo_prover_input stwo_input.json
```
## Notes
* `--proof_mode` is required.
* `--stwo_prover_input` requires a CLI binary built with `--features stwo`.
* You can also emit Cairo PIE with `--cairo_pie ` in proof mode.
For managed proving/verification workflows, see [Atlantic](/atlantic-api/introduction).
# CLI Reference
Source: https://docs.herodotus.cloud/data-processor/reference-cli
Commands and flags for the HDP CLI
CLI usage:
```bash theme={null}
hdp [options]
```
## Commands
* `dry-run` - run [Stage 1](/data-processor/pipeline) and generate `dry_run_output.json`
* `fetch-proofs` - run [Stage 2](/data-processor/pipeline) and generate `proofs.json`
* `sound-run` - run [Stage 3](/data-processor/pipeline) and print outputs
* `program-hash` - compute program hash for a compiled Cairo program
* `env-info` - print expected environment variables
* `env-check` - check required RPC env vars for a dry-run output
* `link` - symlink `hdp_cairo` into a local project
* `update` - update CLI installation
* `pwd` - print HDP repository path
## Common flags
* `--log-level `
* `--debug`
## `dry-run`
```bash theme={null}
hdp dry-run --compiled_module [--inputs ] [--injected_state ]
```
Key options:
* `--program ` / `-p`
* `--compiled_module ` / `-m`
* `--inputs ` / `-i`
* `--injected_state ` / `-s`
* `--output ` / `-o`
* `--print_output`
## `fetch-proofs`
```bash theme={null}
hdp fetch-proofs [--inputs dry_run_output.json] [--output proofs.json]
```
Key options:
* `--inputs ` / `-i`
* `--output ` / `-o`
* `--mmr-hasher-config `
* `--mmr-deployment-config `
## `sound-run`
```bash theme={null}
hdp sound-run --compiled_module --proofs proofs.json
```
Key options:
* `--program ` / `-p`
* `--compiled_module ` / `-m`
* `--inputs ` / `-i`
* `--injected_state ` / `-s`
* `--print_output`
* `--proof_mode`
* `--cairo_pie `
* `--stwo_prover_input `
## `env-check`
```bash theme={null}
hdp env-check --inputs dry_run_output.json
```
## `env-info`
```bash theme={null}
hdp env-info
```
## `program-hash`
```bash theme={null}
hdp program-hash [--program ]
```
## `link`
```bash theme={null}
hdp link
```
## `update`
```bash theme={null}
hdp update [--clean] [--local]
```
## `pwd`
```bash theme={null}
hdp pwd
```
# Configuration Reference
Source: https://docs.herodotus.cloud/data-processor/reference-configuration
Environment variables and runtime configuration for HDP
HDP reads runtime configuration from environment variables.\
The CLI loads `.env` automatically.
## RPC endpoints
```bash theme={null}
RPC_URL_ETHEREUM_MAINNET=
RPC_URL_ETHEREUM_TESTNET=
RPC_URL_OPTIMISM_MAINNET=
RPC_URL_OPTIMISM_TESTNET=
RPC_URL_STARKNET_MAINNET=
RPC_URL_STARKNET_TESTNET=
RPC_URL_HERODOTUS_INDEXER=https://rs-indexer.api.herodotus.cloud/
```
`RPC_URL_HERODOTUS_INDEXER` points to the [Herodotus Indexer](/data-structure-indexer-api/introduction), used for header commitment proof retrieval.
## Injected state
```bash theme={null}
INJECTED_STATE_BASE_URL=http://localhost:3000
```
Set this explicitly when using injected state.
See injected-state flow details in [State management](/data-processor/state-management) and [State Server](/data-processor/state-server).
## Validate environment for a run
```bash theme={null}
hdp env-check --inputs dry_run_output.json
```
This checks only the RPC endpoints required by the specific key set in that dry-run output.
## Logging
Use either:
* `--log-level ` / `--debug`
* `RUST_LOG=`
## Advanced
* `HDP_SOUND_RUN_PATH` - override compiled sound-run program path
# Types Reference
Source: https://docs.herodotus.cloud/data-processor/reference-types
Core HDP input/output and proof-related types
This page summarizes the most important HDP runtime types and where to find them in source.
## Source links
* Rust HDP types: [`crates/types/src/lib.rs`](https://github.com/HerodotusDev/hdp-cairo/blob/main/crates/types/src/lib.rs)
* Injected-state proof types: [`crates/types/src/proofs/injected_state/`](https://github.com/HerodotusDev/hdp-cairo/tree/main/crates/types/src/proofs/injected_state)
* EVM Cairo key types: [`hdp_cairo/src/evm/`](https://github.com/HerodotusDev/hdp-cairo/tree/main/hdp_cairo/src/evm)
* Starknet Cairo key types: [`hdp_cairo/src/starknet/`](https://github.com/HerodotusDev/hdp-cairo/tree/main/hdp_cairo/src/starknet)
## Rust pipeline types
| Type | Used in | Purpose |
| ----------------- | -------------- | ---------------------------------------------------------------------------------- |
| `HDPDryRunInput` | Stage 1 | Input payload for `dry-run` (module + params + optional injected state) |
| `HDPInput` | Stage 3 | Input payload for `sound-run` (module + params + proofs + optional injected state) |
| `ProofsData` | Stage 2 output | Full proof payload (`chain_proofs`, `state_proofs`, `unconstrained`) |
| `HDPDryRunOutput` | Stage 1 output | Decoded output fields emitted by dry run |
| `HDPOutput` | Stage 3 output | Decoded output fields emitted by sound run |
| `MmrMetaOutput` | Stage 3 output | Per-chain MMR metadata entry |
Related docs:
* [Pipeline stages](/data-processor/pipeline)
* [Output model](/data-processor/output)
* [Verification model](/data-processor/verification)
## `ProofsData` JSON shape
```json theme={null}
{
"chain_proofs": [],
"state_proofs": [],
"unconstrained": {}
}
```
`chain_proofs` carries chain-specific header/state proof bundles, `state_proofs` carries injected-state read/write proofs, and `unconstrained` carries hash-validated large payloads.
## Chain-level enums and bundles
| Type | Purpose |
| ----------------- | ----------------------------------------- |
| `ChainIds` | Supported chain enum |
| `ChainProofs` | Per-chain proof bundle wrapper |
| `HashingFunction` | MMR hashing mode (`Poseidon` or `Keccak`) |
## Cairo constants (chain IDs)
EVM:
* `ETHEREUM_MAINNET_CHAIN_ID`
* `ETHEREUM_TESTNET_CHAIN_ID`
* `OPTIMISM_MAINNET_CHAIN_ID`
* `OPTIMISM_TESTNET_CHAIN_ID`
Starknet:
* `STARKNET_MAINNET_CHAIN_ID`
* `STARKNET_TESTNET_CHAIN_ID`
See API usage in [Capabilities](/data-processor/capabilities).
## Cairo key structs (practical shapes)
EVM keys:
```cairo theme={null}
HeaderKey { chain_id, block_number }
AccountKey { chain_id, block_number, address }
StorageKey { chain_id, block_number, address, storage_slot }
BlockTxKey { chain_id, block_number, transaction_index }
BlockReceiptKey { chain_id, block_number, transaction_index }
LogKey { chain_id, block_number, transaction_index, log_index }
```
Starknet keys:
```cairo theme={null}
HeaderKey { chain_id, block_number }
StorageKey { chain_id, block_number, address, storage_slot }
```
## Output fields (decoded from output segment)
```text theme={null}
task_hash_low, task_hash_high,
output_root_low, output_root_high,
poseidon_len, keccak_len,
poseidon_metas (4 felts each),
keccak_metas (5 felts each)
```
For semantics and formulas:
* [Output model](/data-processor/output)
# GitHub Repository
Source: https://docs.herodotus.cloud/data-processor/repository
Source code, examples, and release history for HDP Cairo
Official repository:
* [https://github.com/HerodotusDev/hdp-cairo](https://github.com/HerodotusDev/hdp-cairo)
High-value locations:
* Examples: [https://github.com/HerodotusDev/hdp-cairo/tree/main/examples](https://github.com/HerodotusDev/hdp-cairo/tree/main/examples)
* Cairo library: [https://github.com/HerodotusDev/hdp-cairo/tree/main/hdp\_cairo](https://github.com/HerodotusDev/hdp-cairo/tree/main/hdp_cairo)
* Runtime and verifiers: [https://github.com/HerodotusDev/hdp-cairo/tree/main/src](https://github.com/HerodotusDev/hdp-cairo/tree/main/src)
# Ways to Run HDP
Source: https://docs.herodotus.cloud/data-processor/running-hdp
Local execution, Atlantic proving, and HDP Server orchestration
There are three common ways to run HDP workflows.
## 1) Run locally (developer loop)
Best for fast iteration on module logic.
Core flow:
1. `hdp dry-run -m .json --print_output`
2. `hdp fetch-proofs`
3. `hdp sound-run -m .json --print_output`
Example (from [examples/eth\_call/run.sh](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/eth_call/run.sh)):
```bash theme={null}
scarb build -p example_eth_call && \
hdp dry-run -m target/dev/example_eth_call_module.compiled_contract_class.json --print_output && \
hdp fetch-proofs --mmr-deployment-config examples/eth_call/mmr_deployment_config.json && \
hdp sound-run -m target/dev/example_eth_call_module.compiled_contract_class.json --print_output --cairo_pie ./pie.zip
```
## 2) Prove with [Atlantic](/atlantic-api/introduction)
Best when you want managed proving and verification pipelines.
[Atlantic](/atlantic-api/introduction) can be used with different prover modes exposed in Atlantic docs (currently `stone` and `stwo`). This lets teams optimize for workflow needs without running prover infrastructure themselves.
Typical flow:
1. Produce trace/PIE from HDP run
2. Submit [Atlantic](/atlantic-api/introduction) query
3. Track query status and retrieve proof-related job details
4. Verify on chosen target (for example L1, L2, or off-chain mode depending on workflow)
Start here:
* [Atlantic Introduction](/atlantic-api/introduction)
* [Atlantic Getting Started](/atlantic-api/getting-started)
* [S-two on Atlantic](/atlantic-api/stwo)
* [Atlantic Query Jobs Endpoint](/atlantic-api/endpoints/get-query-jobs)
## 3) Use [HDP Server API](/data-processor-api/introduction) (orchestrated path)
Best when you want API-driven scheduling and lifecycle management from your backend.
This is **not** the same as [State Server](/data-processor/state-server):
* **HDP Server API** orchestrates HDP task execution lifecycle (`/tasks`, status, retries, outputs).
* **State Server** provides injected-state trie read/write/proof endpoints used in injected-state workflows.
Key endpoints:
* `POST /tasks` -> schedule a task
* `GET /tasks/{task_uuid}/status` -> track task status
* `GET /tasks/{task_uuid}/details` -> inspect execution metadata
* `POST /tasks/{task_uuid}/retry` -> retry failed tasks
Start here:
* [HDP Server Introduction](/data-processor-api/introduction)
* [Schedule a new task](/data-processor-api/create-task)
* [Get task status](/data-processor-api/task-status)
* [List tasks](/data-processor-api/list-tasks)
* [Get task details](/data-processor-api/get-task-details)
* [Get task state transitions](/data-processor-api/get-task-state-transitions)
* [Get task output preimage](/data-processor-api/get-task-output-preimage)
* [Get used MMRs](/data-processor-api/get-mmrs)
* [Retry task](/data-processor-api/retry-task)
* [Decommitment only](/data-processor-api/decommitment-only)
## Choosing the path
* Use **local HDP** for module development and testing.
* Use **[Atlantic](/atlantic-api/introduction)** for self-running but managed proving/verification.
* Use **[HDP Server](/data-processor-api/introduction)** for full managed orchestration including proving/verification with Atlantic.
Most teams combine all three: local dev loop → [Atlantic](/atlantic-api/introduction)/[HDP Server](/data-processor-api/introduction) in production.
# State Management
Source: https://docs.herodotus.cloud/data-processor/state-management
Memorizers, injected state, and unconstrained data in HDP
HDP uses specialized state paths so sound execution is offline, deterministic, and fast.
## Memorizers
Memorizers are Cairo0 dictionaries populated during verification, then read during module execution.
Core memorizer domains:
* EVM: headers, accounts, storage, txs, receipts, logs
* Starknet: headers, storage
* Injected state: custom trie-backed state
* Unconstrained: large blobs validated by hash
## Injected state
Injected state is a custom persistent state model backed by a Patricia trie and served by `state_server`.
Typical use:
1. Start [State Server](/data-processor/state-server)
2. Provide `--injected_state ` in dry run and sound run
3. Fetch state proofs during [stage 2](/data-processor/pipeline)
4. Read/write with `hdp.injected_state` APIs in your module
State server base URL:
* `INJECTED_STATE_BASE_URL`
For full setup, endpoints, and examples, see [State Server](/data-processor/state-server).
## Unconstrained data
Unconstrained mode is used for large payloads like EVM bytecode.
Flow:
* Dry run collects the key and payload source
* Sound run loads payload from memorizer
* HDP validates payload hash (for bytecode, against account code hash)
Cairo helper:
* `evm_account_get_bytecode(key) -> ByteCode`
This gives efficient access to large data while preserving integrity guarantees.
For troubleshooting injected state flows, see [Debugging](/data-processor/debugging).
# State Server
Source: https://docs.herodotus.cloud/data-processor/state-server
Run and use the HDP state_server for injected state proofs
`state_server` is a REST API for managing persistent Merkle tries used by HDP injected state workflows.
It is different from [HDP Server API](/data-processor-api/introduction):
* **State Server**: injected-state trie service (`/create_trie`, `/read`, `/write`, `/get_state_proofs`).
* **HDP Server API**: orchestrated HDP task execution service (`/tasks`, task status, task outputs).
Repository:
* [hdp-cairo/crates/state\_server](https://github.com/HerodotusDev/hdp-cairo/tree/main/crates/state_server)
## What it provides
* Create and manage multiple tries by label
* Read and write key/value pairs
* Return trie roots for specific states
* Generate inclusion/non-inclusion and update proofs
* Persist trie data in SQLite-backed storage
## Run the server
```bash theme={null}
cargo run --release --bin state_server -- --host 0.0.0.0 --port 3000 --db_root_path db
```
Common options:
* `--host` (default `0.0.0.0`)
* `--port` (default `3000`)
* `--db_root_path` (default `db`)
Set HDP to use it with:
```bash theme={null}
INJECTED_STATE_BASE_URL=http://localhost:3000
```
## Core endpoints
* `POST /create_trie`
* `GET /read`
* `POST /write`
* `POST /get_state_proofs`
* `GET /get_trie_root_node_idx`
### Endpoint behavior
* `POST /create_trie`: create a trie label with initial keys/values
* `GET /read`: read a key for a specific trie root
* `POST /write`: upsert key/value and return the new trie root
* `POST /get_state_proofs`: generate proof payloads for read/write actions
* `GET /get_trie_root_node_idx`: resolve the internal node index for a root
## Quick examples
Create trie:
```bash theme={null}
curl -X POST http://localhost:3000/create_trie \
-H "Content-Type: application/json" \
-d '{
"trie_label": "0x123",
"keys": ["0x1", "0x2"],
"values": ["0x42", "0x84"]
}'
```
Read key:
```bash theme={null}
curl "http://localhost:3000/read?trie_label=0x123&trie_root=0x0&key=0x1"
```
Write key:
```bash theme={null}
curl -X POST http://localhost:3000/write \
-H "Content-Type: application/json" \
-d '{
"trie_label": "0x123",
"trie_root": "0x0",
"key": "0x4",
"value": "0x168"
}'
```
Get state proofs:
```bash theme={null}
curl -X POST http://localhost:3000/get_state_proofs \
-H "Content-Type: application/json" \
-d '{
"actions": [
{
"Read": {
"trie_label": "0x123",
"trie_root": "0x0",
"key": "0x1"
}
}
]
}'
```
All trie labels, keys, values, and roots are felt-compatible values (hex or decimal strings).
## HDP integration
In HDP flows, injected-state handlers use the state server during dry/fetch phases, and the resulting proofs are consumed during [sound-run](/data-processor/pipeline).
### End-to-end usage with HDP
This is the practical flow most teams use:
1. Start `state_server`
2. Set `INJECTED_STATE_BASE_URL`
3. Run `dry-run` with `--injected_state`
4. Run `fetch-proofs` (state proofs are pulled from state server)
5. Run `sound-run` with the same `--injected_state` file
Example:
```bash theme={null}
# 1) Start state server
cargo run --release --bin state_server -- --host 0.0.0.0 --port 3000 --db_root_path db
# 2) Point HDP to state server
export INJECTED_STATE_BASE_URL=http://localhost:3000
# 3) Run HDP pipeline with injected state
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
```
During this flow:
* `dry-run` records injected-state read/write actions,
* `fetch-proofs` converts those actions into state proof payloads,
* `sound-run` verifies those proofs before your Cairo logic consumes the values.
### Cairo-side usage in modules
In your module, use `hdp.injected_state` helpers:
```cairo theme={null}
let root = hdp.injected_state.read_injected_state_trie_root('my_trie');
let maybe_value = hdp.injected_state.read_key('my_trie', 'my_key');
let new_root = hdp.injected_state.write_key('my_trie', 'my_key', 42);
```
### Working example to copy from
* Module: [examples/injected\_state/src/lib.cairo](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/injected_state/src/lib.cairo)
* Run script: [examples/injected\_state/run.sh](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/injected_state/run.sh)
* Injected state input: [examples/injected\_state/injected\_state.json](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/injected_state/injected_state.json)
See:
* [State management](/data-processor/state-management)
* [Examples (`injected_state`)](/data-processor/examples)
* [Debugging](/data-processor/debugging)
# Verification Model
Source: https://docs.herodotus.cloud/data-processor/verification
How HDP verifies historical chain data before executing your module
Verification runs in Cairo0 during [`sound-run`](/data-processor/pipeline).\
It ensures every value used by your module is backed by valid cryptographic proofs.
## Verification order
1. **Headers** are verified against [MMR commitments](/data-processor/verification#mmr-proofs-header-anchor).
2. **Accounts** are verified against header `state_root`.
3. **Storage** is verified against account `storage_root`.
4. **Transactions and receipts** are verified against block roots.
This dependency chain is what makes historical reads trustworthy.
## MMR proofs (header anchor)
MMRs provide append-only commitments to block headers.
* HDP supports Poseidon and Keccak MMR hashing modes.
* Hasher mode can be configured per chain with `--mmr-hasher-config`.
* Once a header is verified via MMR, it becomes the trusted root for downstream checks.
* Header commitments are fetched through the [Herodotus Indexer](/data-structure-indexer-api/introduction).
## MPT/Patricia proofs (state proofing)
For EVM state, HDP verifies:
* account proofs against block `state_root`,
* storage proofs against account `storage_root`.
This supports both inclusion and non-inclusion style checks.
## Why this matters
Your module can reason about historical chain facts while HDP guarantees those facts are cryptographically linked to trusted roots before computation proceeds.
# Get all accumulators
Source: https://docs.herodotus.cloud/data-structure-indexer-api/accumulators/get-all-accumulators
/data-structure-indexer-api/openapi-data-structure-indexer-api.json get /accumulators
List Data Structure Indexer accumulators with optional filters for deployment chain, accumulated chain, and contract type to discover supported proof data.
# Get peaks of a MMR
Source: https://docs.herodotus.cloud/data-structure-indexer-api/accumulators/get-peaks-of-a-mmr
/data-structure-indexer-api/openapi-data-structure-indexer-api.json get /accumulators/peaks
Get peaks of a MMR
# Get proofs for MMR
Source: https://docs.herodotus.cloud/data-structure-indexer-api/accumulators/get-proofs-for-mmr
/data-structure-indexer-api/openapi-data-structure-indexer-api.json get /accumulators/proofs
Get proofs for MMR
# Get root hash of an accumulator and helper data
Source: https://docs.herodotus.cloud/data-structure-indexer-api/accumulators/get-root-hash-of-an-accumulator-and-helper-data
/data-structure-indexer-api/openapi-data-structure-indexer-api.json get /accumulators/info
Get root hash of an accumulator and helper data
# Simple health check endpoint
Source: https://docs.herodotus.cloud/data-structure-indexer-api/health-check/simple-health-check-endpoint
/data-structure-indexer-api/openapi-data-structure-indexer-api.json get /is-alive
Simple health check endpoint
# Data Structure Indexer API
Source: https://docs.herodotus.cloud/data-structure-indexer-api/introduction
Query accumulators, remappers, and proof-support data structures used by Herodotus Storage Proofs and Data Processor APIs.
Have a look at the [Data Structure Indexer API AI Skill](/skills/data-structure-indexer-api)
to give your LLM a head start on indexer workflows.
## Overview
The **Data Structure Indexer API** provides a convenient way to query and verify on-chain data structures—particularly *Merkle Mountain Range (MMR) accumulators* and *remappers* that map timestamps to block numbers. Built on top of these cryptographic accumulators, the API supplies endpoints for retrieving proofs, peaks, and other metadata, allowing developers to validate and explore block data from various chains.
## Key Concepts
### Accumulators
An **accumulator** is a data structure (in this case, a Merkle Mountain Range) used to store and prove the inclusion of block headers. The API:
* **Lists all accumulators** on a given chain (and the chains they reference).
* **Provides Merkle proofs** to confirm block header inclusion in an MMR.
* **Exposes helper data** like the MMR's root hash, size, and peaks.
### Remappers
A **remapper** is another MMR-based construction used for mapping timestamps to block numbers and verifying these relationships. The API includes:
* **Endpoints to fetch the remapper peaks**, which reveal the top-level hashes of the structure.
* **Binary search path retrieval** by timestamp to pinpoint a matching block number.
* **Block-to-timestamp mappings**, enabling cross-chain time-based lookups.
# Get all remappers
Source: https://docs.herodotus.cloud/data-structure-indexer-api/remappers/get-all-remappers
/data-structure-indexer-api/openapi-data-structure-indexer-api.json get /remappers/
Get all remappers
# Get block header by timestamp
Source: https://docs.herodotus.cloud/data-structure-indexer-api/remappers/get-block-header-by-timestamp
/data-structure-indexer-api/openapi-data-structure-indexer-api.json get /remappers/get-block-header-by-timestamp
Get block header by timestamp
# Get remapper peaks by remapper id
Source: https://docs.herodotus.cloud/data-structure-indexer-api/remappers/get-remapper-peaks-by-remapper-id
/data-structure-indexer-api/openapi-data-structure-indexer-api.json get /remappers/peaks
Get remapper peaks by remapper id
# Get remappersbinsearch path
Source: https://docs.herodotus.cloud/data-structure-indexer-api/remappers/get-remappersbinsearch-path
/data-structure-indexer-api/openapi-data-structure-indexer-api.json get /remappers/binsearch-path
# Post remappersblocks mapped to timestamps
Source: https://docs.herodotus.cloud/data-structure-indexer-api/remappers/post-remappersblocks-mapped-to-timestamps
/data-structure-indexer-api/openapi-data-structure-indexer-api.json post /remappers/blocks-mapped-to-timestamps
# Authentication
Source: https://docs.herodotus.cloud/documentation/authentication
How to authenticate with the Herodotus Cloud Services APIs
## Overview
To use the Herodotus Cloud Services APIs, you need to obtain an API key:
1. Visit the [Herodotus Console](https://www.herodotus.cloud/).
2. Register or log in using your GitHub account or in-browser wallet with Sign in with Ethereum.
3. Apply for credits or use an invite link to a project with credits.
4. Once logged in, you can access your API key for your Project.
5. Include this API key in your requests to authenticate with the API.
## Programmatic wallet authentication
For AI agents, CLIs, and other non-browser clients, you can authenticate without the Herodotus Console UI using an EVM wallet and the EIP-712 challenge flow. The result is a Bearer access token plus an API key — no cookie jar required.
Want a copy-paste playbook for an AI assistant? Load the
[Herodotus Auth AI Skill](/skills/herodotus-auth) — it includes the full
protocol contract, anti-hallucination guardrails, and a viem reference
example.
**Base URL (prod):** `https://auth-billing.api.herodotus.cloud`
### Step 1 — Fetch a challenge
```http theme={null}
GET /auth/web3/challenge?wallet=0xYOUR_WALLET_ADDRESS
```
Response contains a short-lived `challengeToken` plus an `eip712` object with `domain`, `types`, `primaryType`, and `message`. Sign exactly those fields — do not reconstruct them client-side.
### Step 2 — Sign the typed data
Use any EIP-712 signer (viem, ethers, MetaMask, KMS, hardware wallet). The wallet that signs must match the address in the challenge URL.
### Step 3 — Exchange for a Bearer session
```http theme={null}
POST /auth/web3/session
Content-Type: application/json
{
"wallet": "0xYOUR_WALLET_ADDRESS",
"challengeToken": "",
"signature": "",
"channel": "bearer"
}
```
Response body:
```json theme={null}
{
"accessToken": "...",
"refreshToken": "...",
"expiresAt": 1730000000,
"selectedProject": "01J..."
}
```
When `channel` is `"bearer"`, no `Set-Cookie` is sent. Use `Authorization: Bearer ` on every subsequent call. Omit `channel` (or pass `"cookie"`) to fall back to the browser cookie flow.
### Step 4 — Retrieve your API key
First-time wallets are auto-provisioned with a Personal project and one active API key. Read it with:
```http theme={null}
GET /api-keys?projectId=&limit=10&offset=0
Authorization: Bearer
```
Response `data[0].apiKey` is the value to use against Atlantic API, Storage Proof API, etc. To mint additional keys later, `POST /api-keys` with `{ "projectId": "...", "type": { "name": "...", "color": "..." } }`.
### Step 5 — Refresh
When the access token approaches `expiresAt`, exchange the refresh token for a new pair:
```http theme={null}
POST /auth/refresh-token
Authorization: Bearer
```
Response body returns a fresh `{ accessToken, refreshToken, expiresAt }`. The previous refresh token is invalidated. Cookie callers continue to refresh via cookies — the same endpoint serves both transports.
**Channel binding is enforced server-side.** A token issued with
`channel: "bearer"` is rejected if presented via cookie, and vice versa.
This is a security property — do not extract a cookie session JWT and
forward it as `Authorization: Bearer`. If you need both surfaces, run
the cookie path and the bearer path independently.
### End-to-end example (viem)
```ts theme={null}
import { privateKeyToAccount } from 'viem/accounts';
const BASE = 'https://auth-billing.api.herodotus.cloud';
const account = privateKeyToAccount(process.env.HERODOTUS_WALLET_PRIVATE_KEY as `0x${string}`);
const challengeRes = await fetch(`${BASE}/auth/web3/challenge?wallet=${account.address}`);
if (!challengeRes.ok) throw new Error(`Challenge request failed: ${challengeRes.status}`);
const challenge = await challengeRes.json();
const signature = await account.signTypedData({
domain: challenge.eip712.domain,
types: challenge.eip712.types,
primaryType: challenge.eip712.primaryType,
message: challenge.eip712.message,
});
const sessionRes = await fetch(`${BASE}/auth/web3/session`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({
wallet: account.address,
challengeToken: challenge.challengeToken,
signature,
channel: 'bearer',
}),
});
if (!sessionRes.ok) throw new Error(`Session exchange failed: ${sessionRes.status}`);
const { accessToken, refreshToken, selectedProject } = await sessionRes.json();
const keysRes = await fetch(`${BASE}/api-keys?projectId=${selectedProject}&limit=10&offset=0`, {
headers: { authorization: `Bearer ${accessToken}` },
});
if (!keysRes.ok) throw new Error(`API keys request failed: ${keysRes.status}`);
const keys = await keysRes.json();
const apiKey = keys.data?.[0]?.apiKey;
if (!apiKey) throw new Error('No API key found for selected project');
```
# Herodotus Cloud Documentation
Source: https://docs.herodotus.cloud/documentation/introduction
Herodotus Cloud provides managed ZK infrastructure, Storage Proofs, verifiable data, and coprocessing APIs for building secure cross-chain applications.
Herodotus Cloud provides a suite of APIs that enable developers to leverage managed ZK infrastructure, verifiable data and coprocessing capabilities across blockchain networks.
Have a look at the [AI Skills](/skills/index) to give your LLM a head start on
using the Herodotus tooling.
}
href="/storage-proofs-api/introduction"
>
Request cryptographic proofs of arbitrary on-chain data.
}
href="/data-processor/introduction"
>
Perform verifiable computations over arbitrary on-chain data.
}
href="/data-structure-indexer-api/introduction"
>
Access the data structures we use to power Storage Proofs and Data Processor
APIs.
}
href="/atlantic-api/introduction"
>
Managed ZK Proving Infrastructure. Your gateway to the StarkWare SHARP.
# Quick Start
Source: https://docs.herodotus.cloud/documentation/quickstart
Get started with Herodotus Cloud Services in minutes — sign up, get your API key, and make your first API call.
This quick start guide will help you set up and make your first API call to Herodotus Cloud Services.
## Step 1: Sign Up for an API Key
1. Visit the [Herodotus Cloud Console](https://www.herodotus.cloud).
2. Click on "Sign Up" and create an account.
3. Once logged in, navigate to the API Keys section.
4. You will see your API key. Save it securely.
If you're having trouble getting the API key, have a look at the
[authentication](/documentation/authentication) page.
## Step 2: Choose the Right API
Herodotus Cloud Services offers several APIs tailored to different use cases:
}
href="/storage-proofs-api/introduction"
>
Request cryptographic proofs of arbitrary on-chain data.
}
href="/data-processor-api/introduction"
>
Perform verifiable computations over arbitrary on-chain data.
}
href="/data-structure-indexer-api/introduction"
>
Access the data structures we use to power Storage Proofs and Data Processor
APIs.
}
href="/atlantic-api/introduction"
>
Managed ZK Prover Infrastructure. Your gateway to the StarkWare SHARP prover
service.
## Step 3: Make Your First API Call
Submit a Storage Proof request via Mission Control to prove an account's balance:
```bash theme={null}
curl -X POST https://mission-control.api.herodotus.cloud/submit-request \
-H 'Content-Type: application/json' \
-H 'api-key: your-api-key-here' \
-d '{
"destination_chain_id": "11155111",
"data": {
"11155111": {
"block:5150551": {
"accounts": {
"0x17C2D875CB397D813eAE817DaFD25807E348Df07": {
"props": ["BALANCE"]
}
}
}
}
}
}'
```
If successful, you'll receive a request ID:
```json theme={null}
{
"status": "success",
"request_id": "01J2V235ABJY55JS2MY051ZJFJ"
}
```
Track query status with:
```bash theme={null}
curl -X GET "https://mission-control.api.herodotus.cloud/get_queries/01J2V235ABJY55JS2MY051ZJFJ" \
-H 'api-key: your-api-key-here'
```
## Step 4: View the request in the Console
You can use the returned `request_id` in the [Herodotus Cloud Console](https://www.herodotus.cloud) to inspect the request.
For detailed usage instructions, refer to your chosen service's specific API documentation.
# Architecture
Source: https://docs.herodotus.cloud/satellite-contracts/architecture
Satellite design: MMR commitments, proof verification, and contract composition
Satellite is implemented as a modular proxy system (Diamond pattern) where functionality is split into modules ("facets") and routed through a central contract.
## Core architectural ideas
### 1) MMR-based block commitments
Satellite stores Merkle Mountain Range (MMR) roots and sizes per chain and MMR ID.
* MMRs represent append-only commitments to block headers.
* Roots are tracked by hashing function (Keccak and Poseidon are supported in the codebase).
* Parent hashes are cached and reused for growth continuation and cross-chain syncing.
### 2) Verification pipeline
The verification flow is layered:
1. Verify a header against an MMR commitment.
2. Verify account proof against header `state_root`.
3. Verify storage proof against account `storage_root`.
4. Optionally persist selected verified fields for later reads.
This is why Satellite read functions can return historical data with cryptographic grounding.
### 3) Two growth modes
Satellite supports two ways to grow MMRs:
* **On-chain growth**: append batches directly in-contract from block header chains.
* **SHARP/off-chain growth**: verify Cairo fact outputs and update MMR roots/sizes from proven jobs.
Off-chain growth is designed for scalability while preserving verifiability.
### 4) Cross-chain transport
Satellite can send and receive parent hashes, MMR snapshots, and Cairo fact hashes across chains via messaging modules, using registry-defined chain connections.
## Solidity + Cairo implementations
The repository includes both:
* **Solidity contracts** for EVM deployments (`solidity/src/...`).
* **Cairo contract components** for Starknet (`cairo/src/...`).
Both sides implement analogous concepts: MMR state, proof verification logic, and task/fact authentication modules.
## Why this architecture matters
The design separates concerns:
* commitment state (MMRs),
* proof checking,
* messaging,
* and operations/maintenance.
That modularity helps evolve components without redesigning the whole system and keeps verification-critical logic explicit.
# Deployments and Integration
Source: https://docs.herodotus.cloud/satellite-contracts/deployments-and-integration
Where to find deployed satellites, interfaces, and repository resources
## Canonical repository
Satellite source code and deployment metadata live in:
* [HerodotusDev/satellite](https://github.com/HerodotusDev/satellite)
## Deployed contract sets
The repository includes environment deployment manifests:
* `deployments/prod.json`
* `deployments/stage.json`
These files map chain IDs to satellite contract addresses and known cross-chain connections.
## Interface entry points
For Solidity integrations, start from:
* `solidity/src/interfaces/ISatellite.sol`
This interface aggregates module surfaces, including:
* fact reads/proving interfaces,
* MMR state and growth operations,
* messaging and registry functions,
* data processor task authentication methods.
## Importing into your project
### NPM dependency
```bash theme={null}
npm install https://github.com/HerodotusDev/satellite
```
```solidity theme={null}
import { ISatellite } from "@HerodotusDev/satellite/solidity/src/interfaces/ISatellite.sol";
```
### Foundry dependency
```bash theme={null}
forge install HerodotusDev/satellite
```
```solidity theme={null}
import { ISatellite } from "lib/satellite/solidity/src/interfaces/ISatellite.sol";
```
With remapping:
```toml theme={null}
remappings = [
"@HerodotusDev/satellite/=lib/satellite/",
]
```
## Recommended reading path
For practical integration:
1. Read [For End Users](/satellite-contracts/for-end-users).
2. Review [Storage Proof API Contracts docs](/storage-proofs-api/contracts/accessing-data).
3. Use environment deployment manifests for target chain addresses.
4. Integrate only the specific read/prove surfaces your contract needs.
# For End Users
Source: https://docs.herodotus.cloud/satellite-contracts/for-end-users
How to consume proven historical data from Satellite contracts
If you are integrating Satellite into an application contract, most of your usage is through read functions on the `ISatellite` interface.
## Core read functions
The three most common reads are:
* `accountField(chainId, blockNumber, account, field) -> bytes32`
* `storageSlot(chainId, blockNumber, account, slot) -> bytes32`
* `timestamp(chainId, timestamp) -> uint256`
Use these when you need historical account fields, storage values, or "latest block at a given time" lookups.
## Safe vs reverting reads
Most Satellite read functions come in two versions:
* `...Safe(...)` returns `(exists, value)` and does not revert on missing data.
* Non-`Safe` variant returns the value directly and reverts when data is not present.
This pattern lets you choose between explicit existence checks and strict failure behavior.
## Data lifecycle for a read
Your contract reads only facts already saved in Satellite. The typical lifecycle is:
1. A proof workflow verifies block/account/storage data against Satellite MMR commitments.
2. Verified fields are written into Satellite storage.
3. Your contract reads the saved values by chain ID and block number.
In managed flows, [Storage Proof API](/storage-proofs-api/introduction) handles step 1 and the related proof plumbing.
## Example integration path
To consume the interface in Solidity:
```bash theme={null}
npm install https://github.com/HerodotusDev/satellite
```
```solidity theme={null}
import { ISatellite } from "@HerodotusDev/satellite/solidity/src/interfaces/ISatellite.sol";
```
You can also install with Foundry and import from `lib/satellite/...`.
## Practical usage patterns
* Historical token balance checks for voting and governance snapshots.
* Storage-slot based eligibility logic (airdrops, allowlists, retroactive rewards).
* Time-based historical reads using `timestamp(...)` first, then account/storage lookups.
## Important expectation
Satellite is a verification and data-access contract layer, not a general-purpose query engine.
If your app needs broad candidate discovery (for example, "all addresses matching X"), do that off-chain first, then verify and consume only the needed facts on-chain.
# How Satellite Powers Herodotus Services
Source: https://docs.herodotus.cloud/satellite-contracts/herodotus-stack
How Satellite connects Storage Proof API, Data Structure Indexer, and HDP
Satellite is the on-chain anchor that other Herodotus services build on.
## Storage Proof API -> Satellite
[Storage Proof API](/storage-proofs-api/introduction) manages proof workflows and writes verified historical facts into Satellite.
From the app perspective:
1. You request proof-backed data.
2. The pipeline verifies data against block commitments.
3. Verified facts become readable through Satellite contract functions.
This is why on-chain reads can be simple while still cryptographically grounded.
## Data Structure Indexer -> off-chain visibility for Satellite data structures
[Data Structure Indexer API](/data-structure-indexer-api/introduction) is the off-chain companion for accumulator/remapper access.
It provides queryable access to data structures and metadata such as:
* MMR-related roots/peaks/proof data,
* remapper lookup helpers,
* and other proof-oriented indexing primitives.
In practice, this is the off-chain indexing and retrieval layer around the same commitment system that Satellite enforces on-chain.
## HDP -> computation on top of committed history
[HDP](/data-processor/introduction) executes proof-backed computation over historical chain data.
Its verification model relies on header commitments and proof chains rooted in MMR-backed history. In other words, the blocks and proofs HDP consumes are tied to the same Satellite commitment layer.
This linkage is central to HDP soundness:
* historical facts are validated against committed roots,
* those roots are anchored in Satellite MMR state,
* and resulting computations can be authenticated through fact-registry flows.
## Why this matters for trust
Together, these layers separate concerns cleanly:
* index and fetch off-chain efficiently,
* verify and anchor on-chain,
* compute with proof constraints.
That division is what lets Herodotus scale while preserving verifiable correctness across services.
# Satellite Contracts
Source: https://docs.herodotus.cloud/satellite-contracts/introduction
Herodotus Satellite Contracts provide trust-minimized on-chain data access — consume verified storage proofs and coprocessor outputs directly in your smart contracts.
Have a look at the [Satellite Contracts AI Skill](/skills/satellite-contracts) to
give your LLM a head start on Satellite workflows.
Herodotus Satellite Contracts are the on-chain trustlessness-providing layer behind Herodotus historical data services.
They maintain append-only block commitments (MMRs), verify block/account/storage proofs, and expose verified data through contract read functions that applications can consume directly.
If a value is stored in Satellite, downstream contracts can use it without trusting a centralized indexer, API operator or oracle.
## What this section covers
This section explains Satellite from two angles:
* End-user usage (what to call, what to expect).
* Internal architecture (MMRs, growth, messaging, and module design).
It also connects Satellite to the broader Herodotus stack:
* [Storage Proof API](/storage-proofs-api/introduction) prepares and submits proofs so data is saved in Satellite.
* [Data Structure Indexer API](/data-structure-indexer-api/introduction) provides off-chain access to accumulators, peaks, and proof-related metadata used around Satellite workflows.
* [HDP](/data-processor/introduction) relies on these committed blocks and proofs for sound historical computation.
## Why this contract layer exists
On-chain applications cannot query arbitrary historical chain state by default. Satellite solves this by:
1. Anchoring historical block headers in on-chain MMRs.
2. Verifying storage-proof components against those anchored headers.
3. Saving selected verified facts for cheap on-chain reuse.
This is the core mechanism that makes Herodotus data products verifiable rather than trust-based.
## Where to go next
* [For End Users](/satellite-contracts/for-end-users)
* [Architecture](/satellite-contracts/architecture)
* [Module Map](/satellite-contracts/module-map)
* [How Satellite Powers Herodotus Services](/satellite-contracts/herodotus-stack)
* [Deployments and Integration](/satellite-contracts/deployments-and-integration)
# Module Map
Source: https://docs.herodotus.cloud/satellite-contracts/module-map
Satellite module responsibilities across MMR, proofs, messaging, and operations
Satellite functionality is split across modules that are combined through the `ISatellite` interface.
## MMR and block commitment modules
* **`MmrCoreModule`**: manages MMR creation, root/size history, parent hash storage, and MMR queries.
* **`EvmOnChainGrowingModule`**: appends EVM header batches directly on-chain.
* **`EvmSharpMmrGrowingModule`**: updates MMR state from SHARP-proven job outputs.
* **`StarknetSharpMmrGrowingModule`**: Starknet-oriented SHARP growth module surface.
## Proof and fact registry modules
* **`EvmFactRegistryModule`**: verifies and stores EVM header/account/storage/timestamp facts.
* **`CairoFactRegistryModule`**: tracks Cairo facts (verified and mocked modes are both represented).
## Parent hash fetch modules
* **Native fetcher**: pulls recent parent hashes from the local chain context.
* **Network-specific fetchers**: modules for Starknet, Arbitrum, and Optimism-specific flows.
These modules provide authenticated continuity points used by growth processes.
## Messaging modules
* **Sender side**: universal sender plus network-specific senders (for example L1->Starknet, L1->Optimism, L1->Arbitrum, L1->ZkSync, Arbitrum->ApeChain).
* **Receiver side**: receiver modules validate the cross-domain source and ingest incoming parent hashes/MMRs/facts.
* **Registry**: `SatelliteRegistryModule` stores known satellites and connection metadata.
## Data Processor module
* **`DataProcessorModule`**: stores HDP task status/results and authenticates task completion by checking authorized program hashes and valid Cairo facts against MMR roots used by the task.
## Governance and maintenance modules
* **Ownership/admin controls**: owner and admin management.
* **Inspector module**: module/function selector introspection.
* **Maintenance module**: add/replace/remove module selectors (diamond maintenance operations).
## Practical interpretation
For most integrators, the key interaction is with proof/read surfaces (`EvmFactRegistryModule` + read helpers).
For protocol operators, growth/messaging/maintenance modules are what keep commitments fresh and synchronized across chains.
# Atlantic API AI Skill
Source: https://docs.herodotus.cloud/skills/atlantic-api
Vendor-neutral AI playbook for building with Atlantic API — covers proof submission, lifecycle tracking, artifact handling, and SHARP verification routing.
**AI Skills**