> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superform.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Merkle Trees

> Configure hook authorization, generate merkle proofs, and publish active proof artifacts.

Merkle Trees are the authorization layer for keeper and strategy execution. A keeper can only execute a hook when the hook call matches a leaf in an authorized merkle tree.

The operational flow is:

1. Draft a root configuration.
2. Activate the configuration version.
3. Generate a merkle tree from the active config.
4. Primary manager proposes / publishes the root onchain.
5. Publish the proof artifact for consumers.

## Hook Configs

Hook configs define which hook + parameter combinations the vault authorizes.

When creating a config, choose hooks from the registry and set inspect parameters such as:

* `yield_source` — target yield source address.
* `token` — token address.
* `oracle` — oracle address.
* Freeform hook parameters.

Each parameterized row becomes a merkle leaf. Keepers must supply the matching proof at execution time.

## Activate Config

Only one config version is active at a time. Activating a config selects the version used for the next tree generation.

Activating a config does not update the onchain root by itself. It selects what Erebor will generate next.

## Generate Tree

Generation is asynchronous:

```bash theme={null}
POST /api/v1/merkle/generate
GET /api/v1/merkle/jobs/{job_id}
```

A `409 Conflict` means generation is already in progress for the vault.

The generated tree includes:

* Root hash.
* Leaf count.
* Config hash / version.
* Leaf details and proof paths.

## Sync Root Onchain

The Sync action compares generated tree state to onchain state and returns the next action:

| Action             | Meaning                               |
| ------------------ | ------------------------------------- |
| `in_sync`          | Onchain root already matches          |
| `needs_generation` | Generate a tree for the active config |
| `propose`          | Sign a root proposal transaction      |
| `pending_timelock` | Wait for the proposal timelock        |
| `execute`          | Sign execution after timelock expiry  |

```bash theme={null}
GET /api/v1/merkle/sync?vault_address={addr}&chain_id={id}
```

<Warning>
  Strategies and emergency exits depend on active merkle withdrawal hooks. A yield source can be whitelisted but still unavailable for execution if the active merkle root does not authorize the required hook path.
</Warning>

## Publish Proof Artifact

Publishing makes the active proof set available to integrators, keepers, and frontends without Erebor authentication.

```bash theme={null}
POST /api/v1/merkle/publish
GET /api/v1/merkle/publish/jobs/{id}
GET /api/v1/merkle/published/{chain_id}/{vault}
```

Publishing is separate from syncing. Sync updates the protocol root; publish exposes the proof artifact.

## Emergency Exit Dependency

Emergency liquidity exit requires an active withdrawal hook for the target yield source. If the active config has no matching withdrawal hook or the proof artifact is missing the leaf, the Pause page cannot arm that source until the merkle configuration is fixed.

## API Reference

| Endpoint                                      | Method | Description                        |
| --------------------------------------------- | ------ | ---------------------------------- |
| `/api/v1/merkle/configs/versions`             | GET    | Config version history             |
| `/api/v1/merkle/configs/version`              | GET    | Single version by number           |
| `/api/v1/merkle/configs/active`               | GET    | Active config                      |
| `/api/v1/merkle/configs`                      | POST   | Create new config                  |
| `/api/v1/merkle/configs/activate`             | PUT    | Activate a version                 |
| `/api/v1/merkle/trees`                        | GET    | List trees for a vault             |
| `/api/v1/merkle/proofs`                       | GET    | List proofs                        |
| `/api/v1/merkle/proofs/lookup`                | GET    | Lookup one proof                   |
| `/api/v1/merkle/generate`                     | POST   | Start generation                   |
| `/api/v1/merkle/jobs/{id}`                    | GET    | Poll generation job                |
| `/api/v1/merkle/sync`                         | GET    | Determine root sync action         |
| `/api/v1/merkle/publish`                      | POST   | Publish active tree proof artifact |
| `/api/v1/merkle/publish/jobs/{id}`            | GET    | Poll publish job                   |
| `/api/v1/merkle/published/{chain_id}/{vault}` | GET    | Public published tree metadata     |