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:

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:

{
  "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

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