Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.herodotus.cloud/llms.txt

Use this file to discover all available pages before exploring further.

​
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: 
X-API-KEY: your-herodotus-cloud-api-key-here

​
Request Body

FieldTypeRequiredDescription
destination_chain_idstringYesHex-encoded chain ID (e.g., 0x534e5f5345504f4c4941 for SN_SEPOLIA)
atlantic_query_idstringYesThe Atlantic query ID from PIE submission
hdp_outputobjectNoHDP output data. If not provided, will be fetched from Atlantic storage
program_hashstringNoHDP program hash. If not provided, will be fetched from Atlantic storage
webhook_urlstringNoOptional URL to receive task completion/failure notifications

​
hdp_output Structure

FieldTypeDescription
mmr_metasarrayArray of MMR metadata objects
task_hash_lowstringLow 128 bits of task hash (hex string)
task_hash_highstringHigh 128 bits of task hash (hex string)
output_tree_root_lowstringLow 128 bits of output tree root (hex string)
output_tree_root_highstringHigh 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: 
{
  "Poseidon": {
    "id": "0x30314b345136303433515133424b4d42324e31394d4443595757",
    "size": "0x2644",
    "chain_id": "0xaa37dc",
    "root": "0x6e7be7495a7126588df5ce10e090b27ea87357b966cc5b4143d0845ee15af0e"
  }
}
Keccak MMR: 
{
  "Keccak": {
    "id": "0x30314a4d484d31413242354d38455336505a57524a505354374d",
    "size": "0x0a813",
    "chain_id": "0xaa36a7",
    "root_low": "0x8c03a541b8eb37ccfb5d11f205555666",
    "root_high": "0x8df74acdc8c1fc184081e4a2ec4ccca7"
  }
}

​
Example Requests

​
With hdp_output and program_hash provided

curl -X POST https://staging.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)

curl -X POST https://staging.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)

{
  "message": "Task has been queued for decommitment",
  "status": "accepted",
  "uuid": "01KABQ0255W3HHQD8AZAMQNADS"
}

​
Error Responses

400 Bad Request - Program hash mismatch: 
{
  "error": "Program hash mismatch",
  "details": "expected 0x34a16478e83f69c4f0bcdb7549d32f92c9b7776bb3f71da06de334f1871eba0, got 0x..."
}
400 Bad Request - Invalid payload: 
{
  "error": "Invalid decommitment payload",
  "details": "mmr_metas must be an array"
}
401 Unauthorized: 
{
  "error": "Missing API key"
}
500 Internal Server Error: 
{
  "error": "Failed to fetch from Atlantic: HTTP 404"
}

​
Response Fields

FieldTypeDescription
messagestringSuccess message
statusstringStatus of the request (always “accepted”)
uuidstringThe unique identifier of the decommitment task
errorstringError 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