# 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. Atlantic AR Buckets Overview ## Bucket Details View When you select a specific bucket, you can see its details. Atlantic Bucket Details ## Bucket Tree Structure The **Applicative Recursion** system creates a tree-like structure. Atlantic AR Tree 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. integrity verifier logo [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. Atlantic Banner 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 Webhook URL 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. Herodotus Data Processor Server Banner 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. Herodotus Data Processor Banner 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. Indexer Banner 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. Herodotus Console Login 3. Apply for credits or use an invite link to a project with credits. Herodotus Console Project 4. Once logged in, you can access your API key for your Project. Herodotus Console API Keys 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 Banner 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. Herodotus Satellite Banner 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**
Use this playbook when an AI assistant needs to design, implement, or troubleshoot Atlantic proving workflows. Download this skill when you are implementing Atlantic submission, lifecycle tracking, artifact handling, and verification routing. Global: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude ``` Or project-local: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude --project ``` Or inside Claude Code: ```bash theme={null} /plugin marketplace add HerodotusDev/ai-skills /plugin install herodotus-skills@herodotus ``` Or via the Claude CLI: ```bash theme={null} claude plugin marketplace add HerodotusDev/ai-skills claude plugin install herodotus-skills@herodotus ``` Then use: `/herodotus-skills:atlantic-api` ```bash theme={null} mkdir -p .cursor/skills/herodotus/atlantic-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/atlantic-api/SKILL.md \ -o .cursor/skills/herodotus/atlantic-api/SKILL.md ``` **Global:** ```bash theme={null} mkdir -p ~/.codex/skills/herodotus/atlantic-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/atlantic-api/SKILL.md \ -o ~/.codex/skills/herodotus/atlantic-api/SKILL.md ``` **Or project-local:** ```bash theme={null} mkdir -p .codex/skills/herodotus/atlantic-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/atlantic-api/SKILL.md \ -o .codex/skills/herodotus/atlantic-api/SKILL.md ``` ```bash theme={null} mkdir -p .agent/skills/herodotus/atlantic-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/atlantic-api/SKILL.md \ -o .agent/skills/herodotus/atlantic-api/SKILL.md ``` ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash ``` # Data Processor AI Skill Source: https://docs.herodotus.cloud/skills/data-processor Vendor-neutral AI playbook for building provable computation modules with HDP — covers module design, soundness constraints, and verifiable execution over historical on-chain data. **AI Skills**
Use this playbook when an AI assistant needs to design HDP modules and enforce soundness over candidate data discovered off-chain. Download this skill when you need architecture patterns for indexer-plus-HDP systems, constraints, and deterministic verified execution. Global: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude ``` Or project-local: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude --project ``` Or inside Claude Code: ```bash theme={null} /plugin marketplace add HerodotusDev/ai-skills /plugin install herodotus-skills@herodotus ``` Or via the Claude CLI: ```bash theme={null} claude plugin marketplace add HerodotusDev/ai-skills claude plugin install herodotus-skills@herodotus ``` Then use: `/herodotus-skills:data-processor` ```bash theme={null} mkdir -p .cursor/skills/herodotus/data-processor curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/data-processor/SKILL.md \ -o .cursor/skills/herodotus/data-processor/SKILL.md ``` **Global:** ```bash theme={null} mkdir -p ~/.codex/skills/herodotus/data-processor curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/data-processor/SKILL.md \ -o ~/.codex/skills/herodotus/data-processor/SKILL.md ``` **Or project-local:** ```bash theme={null} mkdir -p .codex/skills/herodotus/data-processor curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/data-processor/SKILL.md \ -o .codex/skills/herodotus/data-processor/SKILL.md ``` ```bash theme={null} mkdir -p .agent/skills/herodotus/data-processor curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/data-processor/SKILL.md \ -o .agent/skills/herodotus/data-processor/SKILL.md ``` ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash ``` # Data Processor API AI Skill Source: https://docs.herodotus.cloud/skills/data-processor-api Vendor-neutral AI playbook for HDP Server task and module orchestration — covers task creation, status tracking, module upload/publish, and lifecycle management. **AI Skills**
Use this playbook when an AI assistant needs to orchestrate HDP tasks/modules through HTTP with lifecycle tracking and retries. Download this skill when building a production control plane around task scheduling, status transitions, and result consumption. Global: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude ``` Or project-local: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude --project ``` Or inside Claude Code: ```bash theme={null} /plugin marketplace add HerodotusDev/ai-skills /plugin install herodotus-skills@herodotus ``` Or via the Claude CLI: ```bash theme={null} claude plugin marketplace add HerodotusDev/ai-skills claude plugin install herodotus-skills@herodotus ``` Then use: `/herodotus-skills:data-processor-api` ```bash theme={null} mkdir -p .cursor/skills/herodotus/data-processor-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/data-processor-api/SKILL.md \ -o .cursor/skills/herodotus/data-processor-api/SKILL.md ``` **Global:** ```bash theme={null} mkdir -p ~/.codex/skills/herodotus/data-processor-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/data-processor-api/SKILL.md \ -o ~/.codex/skills/herodotus/data-processor-api/SKILL.md ``` **Or project-local:** ```bash theme={null} mkdir -p .codex/skills/herodotus/data-processor-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/data-processor-api/SKILL.md \ -o .codex/skills/herodotus/data-processor-api/SKILL.md ``` ```bash theme={null} mkdir -p .agent/skills/herodotus/data-processor-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/data-processor-api/SKILL.md \ -o .agent/skills/herodotus/data-processor-api/SKILL.md ``` ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash ``` # Data Structure Indexer API AI Skill Source: https://docs.herodotus.cloud/skills/data-structure-indexer-api Vendor-neutral AI playbook for working with accumulators and remappers — covers data discovery, proof-support planning, and safe query patterns. **AI Skills**
Use this playbook when an AI assistant needs indexer-based discovery for proof-planning over accumulators and remappers. Download this skill when implementing candidate planning that must later be validated through proof-backed paths. Global: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude ``` Or project-local: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude --project ``` Or inside Claude Code: ```bash theme={null} /plugin marketplace add HerodotusDev/ai-skills /plugin install herodotus-skills@herodotus ``` Or via the Claude CLI: ```bash theme={null} claude plugin marketplace add HerodotusDev/ai-skills claude plugin install herodotus-skills@herodotus ``` Then use: `/herodotus-skills:data-structure-indexer-api` ```bash theme={null} mkdir -p .cursor/skills/herodotus/data-structure-indexer-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/data-structure-indexer-api/SKILL.md \ -o .cursor/skills/herodotus/data-structure-indexer-api/SKILL.md ``` **Global:** ```bash theme={null} mkdir -p ~/.codex/skills/herodotus/data-structure-indexer-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/data-structure-indexer-api/SKILL.md \ -o ~/.codex/skills/herodotus/data-structure-indexer-api/SKILL.md ``` **Or project-local:** ```bash theme={null} mkdir -p .codex/skills/herodotus/data-structure-indexer-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/data-structure-indexer-api/SKILL.md \ -o .codex/skills/herodotus/data-structure-indexer-api/SKILL.md ``` ```bash theme={null} mkdir -p .agent/skills/herodotus/data-structure-indexer-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/data-structure-indexer-api/SKILL.md \ -o .agent/skills/herodotus/data-structure-indexer-api/SKILL.md ``` ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash ``` # Herodotus Full Stack AI Skill Source: https://docs.herodotus.cloud/skills/herodotus One skill to understand the entire Herodotus stack — pick the right products, compose cross-product workflows, and get started fast. **AI Skills — Start Here**
This is the **recommended starting skill** for any Herodotus integration. It covers the full product stack, helps your AI assistant pick the right products for your use case, and routes to the detailed per-product skills when you need implementation specifics. Use this skill when you're: * New to Herodotus and not sure which product you need * Building a workflow that spans multiple Herodotus products * Want your AI assistant to have full context on the stack Global: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude ``` Or project-local: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude --project ``` Or inside Claude Code: ```bash theme={null} /plugin marketplace add HerodotusDev/ai-skills /plugin install herodotus-skills@herodotus ``` Or via the Claude CLI: ```bash theme={null} claude plugin marketplace add HerodotusDev/ai-skills claude plugin install herodotus-skills@herodotus ``` Then use: `/herodotus-skills:herodotus` ```bash theme={null} mkdir -p .cursor/skills/herodotus curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus/SKILL.md \ -o .cursor/skills/herodotus/SKILL.md ``` The installer also places sub-skills under `.cursor/skills/herodotus//`. **Global:** ```bash theme={null} mkdir -p ~/.codex/skills/herodotus curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus/SKILL.md \ -o ~/.codex/skills/herodotus/SKILL.md ``` **Or project-local:** ```bash theme={null} mkdir -p .codex/skills/herodotus curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus/SKILL.md \ -o .codex/skills/herodotus/SKILL.md ``` ```bash theme={null} mkdir -p .agent/skills/herodotus curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus/SKILL.md \ -o .agent/skills/herodotus/SKILL.md ``` ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash ``` # Herodotus Auth AI Skill Source: https://docs.herodotus.cloud/skills/herodotus-auth Vendor-neutral AI playbook for authenticating to Herodotus Cloud programmatically with an EVM wallet (EIP-712 → Bearer access token → API key). Required precondition for every Herodotus API skill. **AI Skills**
Use this playbook when an AI assistant or CLI needs to authenticate to Herodotus Cloud programmatically using an EVM wallet — exchanging an EIP-712 challenge for a Bearer access token, then retrieving an API key. This is the **first skill to load** for any non-browser Herodotus integration: the Atlantic, Storage Proof, Data Processor, and Satellite skills all assume an API key is already in hand. Global: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude ``` Or project-local: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude --project ``` Or inside Claude Code: ```bash theme={null} /plugin marketplace add HerodotusDev/ai-skills /plugin install herodotus-skills@herodotus ``` Or via the Claude CLI: ```bash theme={null} claude plugin marketplace add HerodotusDev/ai-skills claude plugin install herodotus-skills@herodotus ``` Then use: `/herodotus-skills:herodotus-auth` ```bash theme={null} mkdir -p .cursor/skills/herodotus/herodotus-auth curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus-auth/SKILL.md \ -o .cursor/skills/herodotus/herodotus-auth/SKILL.md ``` **Global:** ```bash theme={null} mkdir -p ~/.codex/skills/herodotus/herodotus-auth curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus-auth/SKILL.md \ -o ~/.codex/skills/herodotus/herodotus-auth/SKILL.md ``` **Or project-local:** ```bash theme={null} mkdir -p .codex/skills/herodotus/herodotus-auth curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus-auth/SKILL.md \ -o .codex/skills/herodotus/herodotus-auth/SKILL.md ``` ```bash theme={null} mkdir -p .agent/skills/herodotus/herodotus-auth curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus-auth/SKILL.md \ -o .agent/skills/herodotus/herodotus-auth/SKILL.md ``` ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash ``` ## What this skill teaches * The full wire protocol: `GET /auth/web3/challenge` → sign EIP-712 → `POST /auth/web3/session` (with `channel: "bearer"` in the JSON body) → `GET /api-keys` → `POST /auth/refresh-token`. * Channel-binding semantics — why a Bearer-issued JWT must never be presented via cookie (and vice versa). * A bring-your-own-signer model: the protocol is signer-agnostic. The reference example uses viem; KMS, hardware wallets, MetaMask, and ethers all work without changing the skill. * Anti-hallucination guardrails: do not invent endpoints, do not hardcode the EIP-712 domain/types/statement, do not assume a default `projectId`. For the human-readable walkthrough of the same flow, see [Programmatic wallet authentication](/documentation/authentication#programmatic-wallet-authentication). # How to Use AI Skills Source: https://docs.herodotus.cloud/skills/how-to-use Install and apply Herodotus AI skills in Claude Code, Cursor, Codex, Gemini, and other AI coding tools. Includes per-tool setup, skill selection guide, and multi-skill composition patterns. Use this guide to install and apply Herodotus skills in your AI coding tools. ## Quick Install Run the installer — it auto-detects your tools and lets you pick which ones to set up: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash ``` Or skip the selector and target a specific tool directly: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --cursor curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --codex curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --google curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --antigravity ``` ## Per-Tool Setup **Via the installer (global):** ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude ``` **Or project-local:** ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude --project ``` **Or via the plugin marketplace (inside Claude Code):** ```bash theme={null} /plugin marketplace add HerodotusDev/ai-skills /plugin install herodotus-skills@herodotus ``` **Or via the Claude CLI:** ```bash theme={null} claude plugin marketplace add HerodotusDev/ai-skills claude plugin install herodotus-skills@herodotus ``` Then invoke any skill by name: ``` /herodotus-skills:herodotus # start here — full stack overview /herodotus-skills:atlantic-api /herodotus-skills:data-processor /herodotus-skills:storage-proof-api ``` Skills are installed under a `herodotus/` folder. Install globally or per-project: ```bash theme={null} # Global (all projects) curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --cursor # Current project only curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --cursor --project ``` Or install a single skill manually: ```bash theme={null} mkdir -p .cursor/skills/herodotus/atlantic-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/atlantic-api/SKILL.md \ -o .cursor/skills/herodotus/atlantic-api/SKILL.md ``` Skills are installed under a `herodotus/` folder. Install globally or per-project: ```bash theme={null} # Global (~/.codex/skills/herodotus/) curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --codex # Current project only curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --codex --project ``` Google tools read `AGENTS.md` from the project root: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --google ``` Or manually: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/AGENTS.md -o AGENTS.md ``` Skills are installed under a `herodotus/` folder in `~/.gemini/antigravity/skills/` (global) or `.agent/skills/` (per-project): ```bash theme={null} # Global (all projects) curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --antigravity # Current project only curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --antigravity --project ``` Or install a single skill manually: ```bash theme={null} mkdir -p .agent/skills/herodotus/atlantic-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/atlantic-api/SKILL.md \ -o .agent/skills/herodotus/atlantic-api/SKILL.md ``` Use the `Copy Full Skill` or `Download Skill` buttons on each skill page to get the raw markdown content. Then paste it into your agent config, prompt library, or project files. Or download directly via curl: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/atlantic-api/SKILL.md \ -o atlantic-api-SKILL.md ``` ## Skill selection guide * Use `Herodotus Full Stack AI Skill` when you're new or need the AI to understand the full stack and pick the right products. * Use `Atlantic API AI Skill` for proving job submission, lifecycle, and artifact handling. * Use `Data Processor AI Skill` for HDP module design and soundness-focused execution. * Use `Data Processor API AI Skill` for module/task orchestration through HTTP endpoints. * Use `Storage Proof API AI Skill` for proof requests and Satellite readback flows. * Use `Satellite Contracts AI Skill` for on-chain integration and contract-side read patterns. * Use `Data Structure Indexer API AI Skill` for accumulator/remapper discovery and proof-support data planning. ## Recommended workflow ```text theme={null} 1) Discovery and planning 2) Apply the relevant skill page 3) Implement from embedded reference example 4) Validate against canonical sources and OpenAPI 5) Add retries/observability/fail-closed behavior ``` ## Multi-skill composition patterns * **HDP + Indexer + Satellite:** use indexer for candidate discovery, HDP for constrained validation, Satellite for trusted consumption. * **Storage Proof + Satellite:** submit proof jobs, wait for terminal success, then read via safe Satellite methods. * **Data Processor API + Atlantic:** use API orchestration for queued jobs, Atlantic for proving lifecycle and artifacts. ## Safe usage rules * Treat OpenAPI as source of truth for request/response shapes. * Do not infer undocumented statuses, fields, chain support, or addresses. * Keep chain/environment explicit in every workflow. * Use safe-read methods and fail-closed policies for business decisions. ## GitHub Repository All skills are open source. Contributions welcome: [github.com/HerodotusDev/ai-skills](https://github.com/HerodotusDev/ai-skills) # AI Skills Overview Source: https://docs.herodotus.cloud/skills/index Browse and install Herodotus AI skills — vendor-neutral playbooks that give your AI coding tools deep knowledge of Storage Proofs, ZK Proving, Data Processing, and Satellite Contracts. This page lists all Herodotus AI skills — vendor-neutral playbooks you can install into your AI coding tools or download for manual use. Read the practical usage guide for selecting, importing, and composing skills. Browse the source, open issues, and contribute on GitHub. ## Install All Skills Run the installer — it auto-detects your tools and lets you pick which ones to set up: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash ``` **Via the installer (global):** ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude ``` **Or project-local:** ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude --project ``` **Or inside Claude Code:** ```bash theme={null} /plugin marketplace add HerodotusDev/ai-skills /plugin install herodotus-skills@herodotus ``` **Or via the Claude CLI:** ```bash theme={null} claude plugin marketplace add HerodotusDev/ai-skills claude plugin install herodotus-skills@herodotus ``` Then use any skill: ``` /herodotus-skills:herodotus # start here — full stack overview /herodotus-skills:atlantic-api /herodotus-skills:data-processor /herodotus-skills:storage-proof-api ``` ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --cursor ``` Or install into current project only: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --cursor --project ``` Skills are installed under `herodotus/` in your skills directory. ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --codex ``` Or install into current project only: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --codex --project ``` Skills are installed under `herodotus/` in your skills directory. ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --google ``` Or manually: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/AGENTS.md -o AGENTS.md ``` ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --antigravity ``` Or install into current project only: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --antigravity --project ``` ## Download Individual Skills
## Cross-stack map ```mermaid theme={null} flowchart LR userApp[User App] --> storageProofApi[Storage Proof API] userApp --> dataProcessorApi[Data Processor API] userApp --> dataProcessor[Data Processor] userApp --> atlanticApi[Atlantic API] dataProcessorApi --> atlanticApi[Atlantic API] storageProofApi --> satelliteContracts[Satellite Contracts] dataProcessorApi --> dataProcessor[Data Processor] dataProcessor --> dataStructureIndexer[Data Structure Indexer API] dataProcessor --> satelliteContracts[Satellite Contracts] storageProofApi --> dataStructureIndexer satelliteContracts --> userApp ``` ## Non-hallucination operating rules 1. Prefer docs pages for workflow semantics. 2. Prefer OpenAPI for exact API contract details. 3. Never invent endpoints, statuses, chain support, or deployment addresses. 4. If source conflicts exist, surface them explicitly and choose the stricter source. # Satellite Contracts AI Skill Source: https://docs.herodotus.cloud/skills/satellite-contracts Vendor-neutral AI playbook for integrating with Herodotus Satellite contracts — covers on-chain read patterns, safe methods, and trust-minimized data consumption. **AI Skills**
Use this playbook when an AI assistant needs to integrate trust-minimized read flows against Satellite contracts. Download this skill when building contract-side adapters, address resolution, and fail-closed verified-data policies. Global: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude ``` Or project-local: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude --project ``` Or inside Claude Code: ```bash theme={null} /plugin marketplace add HerodotusDev/ai-skills /plugin install herodotus-skills@herodotus ``` Or via the Claude CLI: ```bash theme={null} claude plugin marketplace add HerodotusDev/ai-skills claude plugin install herodotus-skills@herodotus ``` Then use: `/herodotus-skills:satellite-contracts` ```bash theme={null} mkdir -p .cursor/skills/herodotus/satellite-contracts curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/satellite-contracts/SKILL.md \ -o .cursor/skills/herodotus/satellite-contracts/SKILL.md ``` **Global:** ```bash theme={null} mkdir -p ~/.codex/skills/herodotus/satellite-contracts curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/satellite-contracts/SKILL.md \ -o ~/.codex/skills/herodotus/satellite-contracts/SKILL.md ``` **Or project-local:** ```bash theme={null} mkdir -p .codex/skills/herodotus/satellite-contracts curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/satellite-contracts/SKILL.md \ -o .codex/skills/herodotus/satellite-contracts/SKILL.md ``` ```bash theme={null} mkdir -p .agent/skills/herodotus/satellite-contracts curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/satellite-contracts/SKILL.md \ -o .agent/skills/herodotus/satellite-contracts/SKILL.md ``` ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash ``` # Storage Proof API AI Skill Source: https://docs.herodotus.cloud/skills/storage-proof-api Vendor-neutral AI playbook for requesting, tracking, and consuming storage proofs — covers proof requests, completion polling, and Satellite contract readback patterns. **AI Skills**
Use this playbook when an AI assistant needs to build proof request pipelines and consume verified values on-chain via Satellite. Download this skill when implementing request construction, terminal-state tracking, and safe readback patterns. ## Production API surface (Mission Control) Product name remains **Storage Proof API**. Requests are served by Mission Control. | Item | Value | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Base URL | `https://mission-control.api.herodotus.cloud` (alias `https://api.herodotus.cloud`) | | Swagger UI | [https://mission-control.api.herodotus.cloud/swagger/](https://mission-control.api.herodotus.cloud/swagger/) | | OpenAPI | [https://mission-control.api.herodotus.cloud/api-docs/openapi.json](https://mission-control.api.herodotus.cloud/api-docs/openapi.json) | | Auth | Header `api-key` (required except `/is-alive`) | | Console | [https://www.herodotus.cloud](https://www.herodotus.cloud) | Primary endpoints: * `POST /submit-request` → `{ status, request_id }` * `GET /get_queries/{request_id}` → `{ queries: [{ internal_id, status, typ, created_at, completed_at }] }` * `GET /get_actions/{query_id}` → `{ actions: [...] }` * Grow orders: `GET/POST /grow-orders`, `GET /grow-orders/{id}`, `POST /grow-orders/{id}/cancel` * `GET /is-alive` → `{ message: "Alive!" }` Request body uses snake\_case (`destination_chain_id`, not `destinationChainId`). Do not use the retired paths `/submit-batch-query` or `/batch-query-status`. `https://api.herodotus.cloud` is the Storage Proof API alias for the same Mission Control service. Global: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude ``` Or project-local: ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash -s -- --claude --project ``` Or inside Claude Code: ```bash theme={null} /plugin marketplace add HerodotusDev/ai-skills /plugin install herodotus-skills@herodotus ``` Or via the Claude CLI: ```bash theme={null} claude plugin marketplace add HerodotusDev/ai-skills claude plugin install herodotus-skills@herodotus ``` Then use: `/herodotus-skills:storage-proof-api` ```bash theme={null} mkdir -p .cursor/skills/herodotus/storage-proof-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/storage-proof-api/SKILL.md \ -o .cursor/skills/herodotus/storage-proof-api/SKILL.md ``` **Global:** ```bash theme={null} mkdir -p ~/.codex/skills/herodotus/storage-proof-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/storage-proof-api/SKILL.md \ -o ~/.codex/skills/herodotus/storage-proof-api/SKILL.md ``` **Or project-local:** ```bash theme={null} mkdir -p .codex/skills/herodotus/storage-proof-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/storage-proof-api/SKILL.md \ -o .codex/skills/herodotus/storage-proof-api/SKILL.md ``` ```bash theme={null} mkdir -p .agent/skills/herodotus/storage-proof-api curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/storage-proof-api/SKILL.md \ -o .agent/skills/herodotus/storage-proof-api/SKILL.md ``` ```bash theme={null} curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash ``` # Get get actions Source: https://docs.herodotus.cloud/storage-proofs-api/actions/get-get_actions /storage-proofs-api/openapi-storage-proof-api.json get /get_actions/{query_id} # Accessing Data On-chain Source: https://docs.herodotus.cloud/storage-proofs-api/contracts/accessing-data After API request has finished, you can access the data on-chain using Satellite contract. ## Block header fields For accessing block header data, Satellite contract has following functions: * `headerField(uint256 chainId, uint256 blockNumber, BlockHeaderField field) returns (bytes32)` * `headerFieldSafe(uint256 chainId, uint256 blockNumber, BlockHeaderField field) returns (bool, bytes32)` where `BlockHeaderField` is an enum with following values: * `PARENT_HASH` (0) * `OMMERS_HASH` (1) * `BENEFICIARY` (2) * `STATE_ROOT` (3) * `TRANSACTIONS_ROOT` (4) * `RECEIPTS_ROOT` (5) * `DIFFICULTY` (7) * `GAS_LIMIT` (9) * `GAS_USED` (10) * `TIMESTAMP` (11) * `EXTRA_DATA` (12) * `MIX_HASH` (13) * `NONCE` (14) `LOGS_BLOOM` (6) is currently not supported. `NUMBER` (8) is not stored and cannot be accessed, because all block data is accessed via its number, so there is no need to store or access it. ## Account fields To read account fields, you can use one of the following functions: * `accountField(uint256 chainId, uint256 blockNumber, address account, AccountField field) returns (bytes32)` * `accountFieldSafe(uint256 chainId, uint256 blockNumber, address account, AccountField field) returns (bool, bytes32)` where `AccountField` is an enum with following values: * `NONCE` (0) * `BALANCE` (1) * `STORAGE_ROOT` (2) * `CODE_HASH` (3) There are also additional fields that are ApeChain (or Curtis) specific: * `APE_FLAGS` (4) * `APE_FIXED` (5) * `APE_SHARES` (6) * `APE_DEBT` (7) * `APE_DELEGATE` (8) ## Block by timestamp You can also find closest block given the timestamp. For this, you can use one of the following functions: * `timestamp(uint256 chainId, uint256 timestamp) returns (uint256)` * `timestampSafe(uint256 chainId, uint256 timestamp) returns (bool, uint256)` They return largest block number that has timestamp less than or equal to the given timestamp. This means that asking for timestamp that is less than timestamp of genesis block is not possible. Also, if you ask for timestamp that doesn't match any block exactly, it will return block with smaller timestamp from two closest blocks. In case you are using blockchain that can produce more than one block per second and you ask for timestamp that matches multiple blocks, it will return the block with the largest timestamp. ## Storage slot values To read storage slot value, you can use one of the following functions: * `storageSlotSafe(uint256 chainId, uint256 blockNumber, address account, bytes32 slot) returns (bool, bytes32)` * `storageSlot(uint256 chainId, uint256 blockNumber, address account, bytes32 slot) returns (bytes32)` ## Read functions All of functions above are designed in the same way. They read data that was already proven by the API. Functions that end with `Safe` suffix return `(bool, bytes32)` tuple, where first value is `true` if the data was found and `false` otherwise. Functions that do not end with `Safe` suffix return `bytes32` value and revert if the data was not found. ## ApeChain specific functions On ApeChain (and Curtis) there are also additional functions that calculate Share Price for the given block: * `getApechainSharePriceSafe(uint256 chainId, uint256 blockNumber) returns (bool, uint256)` * `getApechainSharePrice(uint256 chainId, uint256 blockNumber) returns (uint256)` # Contract Addresses Source: https://docs.herodotus.cloud/storage-proofs-api/contracts/contract-addresses Smart contract addresses for verification of Storage Proofs across Ethereum, StarkNet, and other supported chains ## Staging | Chain name | Chain ID | Contract Address | | ------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Ethereum Sepolia | 11155111 | [0x59c0B3D09151aA2C0201808fEC0860f1168A4173](https://sepolia.etherscan.io/address/0x59c0B3D09151aA2C0201808fEC0860f1168A4173) | | Optimism Sepolia | 11155420 | [0x5Fb58a5282B6E657337AD7789B05B802E34a3F78](https://sepolia-optimism.etherscan.io/address/0x5Fb58a5282B6E657337AD7789B05B802E34a3F78) | | Base Sepolia | 84532 | [0xb18a66fbab151c42a81e7c53d11810b6c632987b](https://sepolia.basescan.org/address/0xb18a66fbab151c42a81e7c53d11810b6c632987b) | | WorldChain Sepolia | 4801 | [0x03a80459734A98f8DbFC6d5f1B0EB04F84CA87A4](https://sepolia.worldscan.org/address/0x03a80459734A98f8DbFC6d5f1B0EB04F84CA87A4) | | Arbitrum Sepolia | 421614 | [0xE8c8E43eF7ebF52De69dd8e10479F607E1A493C5](https://sepolia.arbiscan.io/address/0xE8c8E43eF7ebF52De69dd8e10479F607E1A493C5) | | Curtis (ApeChain testnet) | 33111 | [0xc9854fd6034fbc41B65b454919a48a5a9b342fa8](https://curtis.explorer.caldera.xyz/address/0xc9854fd6034fbc41B65b454919a48a5a9b342fa8) | | Starknet Sepolia | 393402133025997798000961 | [0x06d523b16d7f6f71e250fc7f8d95df3e9e987a120878ea1a25ff312d92f42c8e](https://sepolia.starkscan.co/contract/0x06d523b16d7f6f71e250fc7f8d95df3e9e987a120878ea1a25ff312d92f42c8e) | ## Production ### Sepolia (Testnet) | Chain name | Chain ID | Contract Address | | ------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Ethereum Sepolia | 11155111 | [0x396bF739f7b37D81f6CdD4571fDEF298150db88f](https://sepolia.etherscan.io/address/0x396bF739f7b37D81f6CdD4571fDEF298150db88f) | | Optimism Sepolia | 11155420 | [0x495F332aDb2b5134f4633F5AeDF981bd1A6be3A0](https://sepolia-optimism.etherscan.io/address/0x495F332aDb2b5134f4633F5AeDF981bd1A6be3A0) | | Base Sepolia | 84532 | [0x40d8dc2e3979a769c6f0712ed96d651f228d37e5](https://sepolia.basescan.org/address/0x40d8dc2e3979a769c6f0712ed96d651f228d37e5) | | WorldChain Sepolia | 4801 | [0xd198Fa56B4b457223C67D075374b9Efc84DBAe0d](https://sepolia.worldscan.org/address/0xd198Fa56B4b457223C67D075374b9Efc84DBAe0d) | | Arbitrum Sepolia | 421614 | [0x160416c6721db82A312A09D78dfBeC446F7a3a9d](https://sepolia.arbiscan.io/address/0x160416c6721db82A312A09D78dfBeC446F7a3a9d) | | Curtis (ApeChain testnet) | 33111 | [0x33f4d13f2D491b0bdc3451046708De0DeD794207](https://curtis.explorer.caldera.xyz/address/0x33f4d13f2D491b0bdc3451046708De0DeD794207) | | Starknet Sepolia | 393402133025997798000961 | [0x00421cd95f9ddabdd090db74c9429f257cb6bc1ccc339278d1db1de39156676e](https://sepolia.starkscan.co/contract/0x00421cd95f9ddabdd090db74c9429f257cb6bc1ccc339278d1db1de39156676e) | ### Mainnet | Chain name | Chain ID | Contract Address | | ------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Ethereum Mainnet | 1 | [0x2e6f182b06f37cbdc966ff5471c7d98cec2bfe70](https://etherscan.io/address/0x2e6f182b06f37cbdc966ff5471c7d98cec2bfe70) | | Optimism Mainnet | 10 | | | Base Mainnet | 8453 | [0xb036f7bdd9c7a5984323f148064f815f4c75174b](https://basescan.org/address/0xb036f7bdd9c7a5984323f148064f815f4c75174b) | | WorldChain Mainnet | 480 | [0x82f29af756036132ec188ffbb48447895a8d339e](https://worldscan.org/address/0x82f29af756036132ec188ffbb48447895a8d339e) | | Arbitrum Mainnet | 42161 | [0x4357e87460436a1CE94B12A8B2ce349624979396](https://arbiscan.io/address/0x4357e87460436a1CE94B12A8B2ce349624979396) | | ApeChain Mainnet | 33139 | [0x82F29Af756036132Ec188FFbB48447895a8D339e](https://apescan.io/address/0x82F29Af756036132Ec188FFbB48447895a8D339e) | | Starknet Mainnet | 23448594291968334 | [0x01ba7d4b5707f8878c22fb335763abfc26c2ae157c434d597f6416fe6a79bf2e](https://starkscan.co/contract/0x01ba7d4b5707f8878c22fb335763abfc26c2ae157c434d597f6416fe6a79bf2e) | # Example Smart Contract - Voting Source: https://docs.herodotus.cloud/storage-proofs-api/contracts/example-smart-contract Example smart contract that uses the Satellite Contract to access Storage Proofs data for voting. For easier integration, you can add the Satellite contract as a dependency and use its interfaces inside your smart contract. To do that using Foundry, you should first install it using: ```bash theme={null} forge install HerodotusDev/satellite ``` and then we recommend configuring a remapping inside your `foundry.toml` file: ```toml theme={null} remappings = [ # Your other remappings go here "@HerodotusDev/satellite/=lib/satellite/", ] ``` Or if you are using NPM (e.g. with Hardhat), you can just install it using: ```bash theme={null} npm install https://github.com/HerodotusDev/satellite ``` ## How it works The contract uses historical token balances as voting power. Because the system operates on **timestamps rather than block numbers**, the same historical moment can be proven across multiple chains simultaneously — Satellite resolves the correct block number per chain internally. This makes it possible to aggregate cross-chain balances in a single vote without manually tracking chain-specific block heights. Proving individual storage slots for every voter via the Storage Proof API would be impractical at scale. Instead, only **two things need to be proven once per vote**: the block header (to anchor the timestamp on-chain) and the token account's storage root (a single 32-byte value that commits to the entire account storage at that block). After that, each voter's balance is verified **on-demand** at vote time using an MPT proof they fetch themselves from any standard RPC node (`eth_getProof`). The contract checks this proof against the already-proven storage root using `verifyOnlyStorage` from Satellite — no Storage Proof API call is needed per voter. In practice, getting the MPT proof and constructing the transaction would be abstracted away from the user behind a frontend (or a frontend + backend). The UI would fetch the MPT proof from an RPC node, construct the transaction, and submit it on the user's behalf — voters would just click "Vote" without being aware of the proof mechanics. Our example flow is: 1. **Operator initializes a vote** at a historical checkpoint timestamp via `initializeVote`. 2. **One-time proof request** is submitted to the Storage Proof API for that timestamp. It only needs to cover the block header (timestamp → block number) and the token account's storage root. Proof generation takes non-trivial time — submit requests as early as possible, well before the voting window opens. 3. **Voters call `vote`** with an MPT proof for their own balance slot, fetched from any RPC node via `eth_getProof` at the checkpoint block. The contract verifies the proof on-chain against the proven storage root and derives voting power without any additional Storage Proof API requests. 4. **Operator closes the vote** via `closeVote`, which tallies results and records the winning outcome on-chain. To find the correct `balancesSlot` for your token, run `forge inspect storage-layout`. For most OpenZeppelin ERC-20 tokens the `_balances` mapping is at slot `0`. ## Example contract ```solidity theme={null} // SPDX-License-Identifier: GPL-3.0 pragma solidity ^0.8.27; import {ISatellite} from "@HerodotusDev/satellite/solidity/src/interfaces/ISatellite.sol"; import {IEvmFactRegistryModule} from "@HerodotusDev/satellite/solidity/src/interfaces/modules/IEvmFactRegistryModule.sol"; /** * @notice Proof generation via the Storage Proof API takes non-trivial time. After initializing * a vote at a checkpoint timestamp, submit a proof request for that timestamp before the voting * window opens. The same checkpoint timestamp maps to the correct block number on every chain, so * cross-chain balances can be aggregated in a single vote without tracking per-chain block numbers. * * @notice Only the block header and token account storage root need to be proven via the Storage * Proof API — once per vote. Each voter's balance is then verified on-demand using an MPT proof * they supply themselves (via eth_getProof from any RPC node), checked against the proven storage * root with `verifyOnlyStorage`. No per-voter Storage Proof API requests are required. */ contract HistoricalBalanceVoting { ISatellite public immutable satellite; /// @notice Account allowed to initialize and close votes. address public immutable operator; /// @notice The ERC-20 token contract whose balance determines voting power. address public immutable token; /// @notice The chain ID on which the token lives. uint256 public immutable tokenChainId; /** * @notice Solidity storage slot index of the token's `_balances` mapping. * @dev For most OpenZeppelin ERC-20 tokens this is 0. * Verify with `forge inspect storage-layout`. */ uint256 public immutable balancesSlot; // ─── Vote storage ───────────────────────────────────────────────────────── struct VoteInfo { uint256 checkpointTimestamp; bool active; bool closed; bytes32 winner; bytes32[] outcomes; } uint256 public voteCount; mapping(uint256 voteId => VoteInfo) public voteInfo; mapping(uint256 voteId => mapping(bytes32 outcome => uint256 power)) public votesByOutcome; mapping(uint256 voteId => mapping(address voter => bool)) public hasVoted; // ─── Events ─────────────────────────────────────────────────────────────── event VoteInitialized(uint256 indexed voteId, uint256 checkpointTimestamp, bytes32[] outcomes); event Voted(uint256 indexed voteId, address indexed voter, bytes32 outcome, uint256 power); event VoteClosed(uint256 indexed voteId, bytes32 winner); modifier onlyOperator() { require(msg.sender == operator, "Only operator"); _; } constructor( address _satellite, address _operator, address _token, uint256 _tokenChainId, uint256 _balancesSlot ) { satellite = ISatellite(_satellite); operator = _operator; token = _token; tokenChainId = _tokenChainId; balancesSlot = _balancesSlot; } // ─── Operator actions ───────────────────────────────────────────────────── /** * @notice Opens a new vote anchored to a historical checkpoint timestamp. * @dev Before the voting window opens, request proofs for `checkpointTimestamp` via the * Storage Proof API. The API needs to prove the block header (anchoring the timestamp * on-chain) and the token account's storage root (one value that commits to all balances * at that block). Because the API works with timestamps, the same request can cover data * from multiple chains at once. Individual balance slots are verified on-demand by voters. * @param checkpointTimestamp Unix timestamp of the balance checkpoint (must be in the past). * @param outcomes At least two distinct outcome labels (e.g. keccak256("FOR")). * @return voteId Identifier for this vote. */ function initializeVote(uint256 checkpointTimestamp, bytes32[] calldata outcomes) external onlyOperator returns (uint256 voteId) { require(checkpointTimestamp < block.timestamp, "Timestamp must be in the past"); require(outcomes.length >= 2, "At least 2 outcomes required"); voteId = voteCount++; VoteInfo storage v = voteInfo[voteId]; v.checkpointTimestamp = checkpointTimestamp; v.active = true; v.outcomes = outcomes; emit VoteInitialized(voteId, checkpointTimestamp, outcomes); } /** * @notice Closes an active vote and records the winning outcome on-chain. */ function closeVote(uint256 voteId) external onlyOperator { VoteInfo storage v = voteInfo[voteId]; require(v.active && !v.closed, "Vote not active"); bytes32 winner; uint256 highestVotes; for (uint256 i = 0; i < v.outcomes.length; i++) { bytes32 outcome = v.outcomes[i]; if (votesByOutcome[voteId][outcome] > highestVotes) { highestVotes = votesByOutcome[voteId][outcome]; winner = outcome; } } v.active = false; v.closed = true; v.winner = winner; emit VoteClosed(voteId, winner); } // ─── Voter actions ──────────────────────────────────────────────────────── /** * @notice Cast a vote. Voting power equals the token balance at the checkpoint timestamp, * verified on-demand against the proven storage root using the caller-supplied MPT proof. * @dev The block header and token account storage root must already be proven in Satellite via * the Storage Proof API. The `storageSlotMptProof` can be fetched from any RPC node via * `eth_getProof` at the checkpoint block number — no Storage Proof API call is needed. * @param storageSlotMptProof MPT proof for the caller's balance slot, from eth_getProof. */ function vote(uint256 voteId, bytes32 outcome, bytes calldata storageSlotMptProof) external { VoteInfo storage v = voteInfo[voteId]; require(v.active && !v.closed, "Vote not active"); require(!hasVoted[voteId][msg.sender], "Already voted"); bool valid = false; for (uint256 i = 0; i < v.outcomes.length; i++) { if (v.outcomes[i] == outcome) { valid = true; break; } } require(valid, "Invalid outcome"); uint256 power = getVotingPower(voteId, msg.sender, storageSlotMptProof); require(power > 0, "No voting power at this checkpoint"); hasVoted[voteId][msg.sender] = true; votesByOutcome[voteId][outcome] += power; emit Voted(voteId, msg.sender, outcome, power); } // ─── Views ──────────────────────────────────────────────────────────────── /** * @notice Returns the voting power of `account` for a given vote. * @dev Resolves the checkpoint timestamp to a block number via Satellite, reads the proven * storage root of the token account, then verifies the caller-supplied MPT proof against * it on-demand. Reverts if the block header or storage root are not yet proven in Satellite. * @param storageSlotMptProof MPT proof for `account`'s balance slot, obtained via eth_getProof * at the checkpoint block number from any standard RPC node. */ function getVotingPower(uint256 voteId, address account, bytes calldata storageSlotMptProof) public view returns (uint256) { VoteInfo storage v = voteInfo[voteId]; require(v.checkpointTimestamp != 0, "Vote does not exist"); (bool tsOk, uint256 blockNumber) = satellite.timestampSafe(tokenChainId, v.checkpointTimestamp); require(tsOk, "Checkpoint not yet proven — request proof via Storage Proof API first"); (bool rootOk, bytes32 storageRoot) = satellite.accountFieldSafe( tokenChainId, blockNumber, token, IEvmFactRegistryModule.AccountField.STORAGE_ROOT ); require(rootOk, "Storage root not yet proven — request proof via Storage Proof API first"); // Storage slot for `_balances[account]` in a standard ERC-20. // The MPT proof is verified on-demand against the proven storage root — no Storage Proof // API request is needed per voter. bytes32 slot = keccak256(abi.encode(account, balancesSlot)); bytes32 balance = satellite.verifyOnlyStorage(slot, storageRoot, storageSlotMptProof); return uint256(balance); } } ``` # Get grow orders Source: https://docs.herodotus.cloud/storage-proofs-api/grow-orders/get-grow-orders /storage-proofs-api/openapi-storage-proof-api.json get /grow-orders # Get grow orders 1 Source: https://docs.herodotus.cloud/storage-proofs-api/grow-orders/get-grow-orders-1 /storage-proofs-api/openapi-storage-proof-api.json get /grow-orders/{grow_order_id} # Post grow orders Source: https://docs.herodotus.cloud/storage-proofs-api/grow-orders/post-grow-orders /storage-proofs-api/openapi-storage-proof-api.json post /grow-orders # Post grow orders cancel Source: https://docs.herodotus.cloud/storage-proofs-api/grow-orders/post-grow-orders-cancel /storage-proofs-api/openapi-storage-proof-api.json post /grow-orders/{grow_order_id}/cancel # Simple health check endpoint Source: https://docs.herodotus.cloud/storage-proofs-api/health-check/simple-health-check-endpoint /storage-proofs-api/openapi-storage-proof-api.json get /is-alive # Storage Proof API Source: https://docs.herodotus.cloud/storage-proofs-api/introduction Request cryptographic proofs of arbitrary on-chain data across Ethereum, StarkNet, and other supported chains — verify storage slots, balances, and account state. Storage Proofs Banner Have a look at the [Storage Proof API AI Skill](/skills/storage-proof-api) to give your LLM a head start on working with Storage Proofs. Welcome to the Storage Proof API documentation. Storage Proofs enable secure, trustless access to blockchain data across networks and layers. They address key challenges in scalability, interoperability, and data verification without introducing new trust assumptions. ## How it works Requests are submitted to **Mission Control**, which serves the Storage Proof API: * **Base URL:** `https://mission-control.api.herodotus.cloud` (alias: `https://api.herodotus.cloud`) * **Swagger UI:** [https://mission-control.api.herodotus.cloud/swagger/](https://mission-control.api.herodotus.cloud/swagger/) * **Auth:** `api-key` header (required on all endpoints except `/is-alive`) Typical flow: 1. `POST /submit-request` with origin-chain proof data and a `destination_chain_id` 2. `GET /get_queries/{request_id}` to track query status 3. Optionally `GET /get_actions/{query_id}` for execution detail 4. Consume proven values on-chain via [Satellite contracts](/satellite-contracts/introduction) In this documentation, you'll learn about: 1. The fundamental concepts behind Storage Proofs 2. How to submit and track proof requests through Mission Control 3. How to access proven block header, account, and storage data on-chain with Satellite Whether you're building cross-chain applications or verifying historical state, this documentation provides the tools to use Storage Proofs effectively. # Key Concepts Source: https://docs.herodotus.cloud/storage-proofs-api/key-concepts Essential concepts for understanding Storage Proofs including block hashes, inclusion proofs, and zero-knowledge verification Before diving into the details of Storage Proofs, it's important to understand some key concepts: 1. **Storage Proofs**: A fusion of inclusion proofs, which confirm data's presence, and proofs of computation, which validate the execution of a multi-step workflow to attest the validity of one or multiple elements in a large dataset such as the whole Ethereum blockchain or a rollup. 2. **Block Hash**: A unique identifier for a block, summarizing all its contents. It's crucial for anchoring Storage Proofs to a specific point in blockchain history. 3. **Block Header**: Contains metadata about a block, including important roots (state, receipts, transactions) used in the Storage Proof process. 4. **Merkle Trees**: Data structures used in blockchains to efficiently and securely verify the contents of large data sets. 5. **Inclusion Proofs**: Demonstrate that a specific piece of data is part of a larger data set (like a Merkle tree) without revealing the entire data set. 6. **Zero-Knowledge Proofs**: Allow verification of information without revealing the underlying data, enhancing privacy and efficiency in blockchain systems. 7. **Mission Control**: The production service that serves the Storage Proof API — submit proof requests, track queries, and manage grow orders. 8. **Satellite**: On-chain contracts that store and expose proven blockchain data so other contracts can read verified values safely. 9. **Historical Block Hash Accumulator**: A system that allows smart contracts to access and verify historical block hashes efficiently. 10. **Cross-Chain Interoperability**: The ability for different blockchain networks to communicate and share data securely, a key use case for Storage Proofs. Understanding these concepts will provide a solid foundation as you explore the more detailed aspects of Storage Proofs and their applications in the following sections. # Get get queries Source: https://docs.herodotus.cloud/storage-proofs-api/queries/get-get_queries /storage-proofs-api/openapi-storage-proof-api.json get /get_queries/{request_id} # Quick Start Guide Source: https://docs.herodotus.cloud/storage-proofs-api/quick-start-guide This guide will help you quickly get started with using Storage Proofs. Follow these steps to submit your first Storage Proof request and access verified blockchain data. ## Proving Account Balance ### Step 1: Sign Up for an API Key 1. Visit the [Herodotus Cloud Console](https://www.herodotus.cloud). 2. Sign in using your Wallet or Github. 3. Once logged in, access your API key from the console. ### Step 2: Prepare Your Storage Proof Request Construct a POST request to the Storage Proof API (Mission Control). Here's a basic example: ```json theme={null} { "destination_chain_id": "11155111", "data": { "11155111": { "block:5150551": { "accounts": { "0x17C2D875CB397D813eAE817DaFD25807E348Df07": { "props": ["BALANCE"] } } } } } } ``` This request proves the balance of a specific account on Ethereum Sepolia. Header and account field enums accept `SCREAMING_SNAKE` values such as `BALANCE` and `STATE_ROOT` (normalized internally). Optional `settings` may include `max_cost`, `optimize` (`Cost` or `Time`), and related fields. When omitted, defaults apply (`max_cost` 10.0, `optimize` Cost, `allow_offchain_growing` false). ### Step 3: Submit Your Request Send a POST request to Mission Control: ```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"] } } } } } }' ``` A successful response looks like: ```json theme={null} { "status": "success", "request_id": "01J2V235ABJY55JS2MY051ZJFJ" } ``` ### Step 4: Check Query Status Use the returned `request_id` to list queries for that request: ```bash theme={null} curl -X GET "https://mission-control.api.herodotus.cloud/get_queries/YOUR_REQUEST_ID" \ -H 'api-key: YOUR_API_KEY_HERE' ``` Example response: ```json theme={null} { "queries": [ { "internal_id": "01J2V235ABJY55JS2MY051ZJFJ", "status": "IN_PROGRESS", "typ": {}, "created_at": "2026-01-01T00:00:00Z", "completed_at": null } ] } ``` Poll until each query reaches a terminal status such as `COMPLETED` or `FAILED`. Optionally inspect execution steps with `GET /get_actions/{query_id}`. ### Step 5: Access Proven Data Once queries complete, access proven data through the Satellite contract on the destination chain. For Ethereum Sepolia: 1. Go to the [Satellite contract on Etherscan](https://sepolia.etherscan.io/address/0x396bF739f7b37D81f6CdD4571fDEF298150db88f#multipleProxyContract). 2. Use the `accountField` function to retrieve the proven data. * `chainId`: `11155111` * `blockNumber`: `5150551` * `account`: `0x17C2D875CB397D813eAE817DaFD25807E348Df07` * `field`: `0` See [Accessing Data](/storage-proofs-api/contracts/accessing-data) for Satellite read patterns. ## Next Steps * Explore the interactive [Swagger UI](https://mission-control.api.herodotus.cloud/swagger/) and the OpenAPI-backed endpoint docs in this section. * Use Satellite contracts to consume proven values on-chain. * Try header fields, storage slots, and cross-chain destination chain IDs. You've now used Storage Proofs to verify blockchain data. As you become more familiar with the system, you can create more complex proofs and integrate them into your applications. # Post submit request Source: https://docs.herodotus.cloud/storage-proofs-api/submit-request/post-submit-request /storage-proofs-api/openapi-storage-proof-api.json post /submit-request # Use Cases Source: https://docs.herodotus.cloud/storage-proofs-api/use-cases Storage Proof use cases — cross-chain lending, DEX margin accounts, governance voting, bridging, insurance, and account recovery. Here are a few examples of what can be built using Storage Proofs: | Use Case | Opportunity | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Cross-chain lending | Lending platforms can offer cross-chain lending by enabling users to secure loans on one chain, supported by a Storage Proof of collateral from another. For instance, securing a loan on a Layer 2 platform using collateral on Ethereum. | | DEX | Implement Storage Proofs for margin accounts and withdrawals, ensuring sufficient margin and debt obligations are met across chains. | | Account recovery | Trigger a withdrawal to a predefined address if specific criteria are fulfilled. For example, use a Storage Proof showing that the wallet nonce has not changed in over a year. | | Insurance | Insurance protocols can leverage Storage Proofs to automate claims based on predefined conditions. Upon risk events, Storage Proofs can be generated and submitted for near-instant on-chain verification, enabling fast, efficient, and transparent claim processing. | | Governance | Enable users to vote on Layer 2 using their Ethereum-held assets, verifying voting power without transferring assets. | | Bridging | Verify locked assets on an origin chain using Storage Proofs and initiate the minting of equivalent tokens on the target chain, enhancing security of cross-chain transfers. | | Gaming | Enable users to verify ownership of in-game NFTs across different Layer 2s. Utilize Storage Proofs as an app-chain operator to confirm user asset ownership on your app chain. | | Access to RANDAO | Provide access to RANDAO randomness generated by the Ethereum Consensus Layer on other chains. | | Circuit Breakers | Implement protocol safeguards by halting operations if a Storage Proof demonstrates unexpected behaviour on another chain. | ## Explore Integration Opportunities Have an awesome project idea? We are open to collaboration and integration opportunities! If you would like to explore integrating your project with Storage Proofs, please complete [this form](https://www.storageproofs.com/contact).