> ## 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

> 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://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)

```bash theme={null}
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)

```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