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.
Public SuperVault detail pages expose hook and proof context as read-only inspection tabs. Drafting, activating, generating, syncing, and publishing remain manager workflows in Operate.
The operational flow is:
- Draft a root configuration.
- Activate the configuration version.
- Generate a merkle tree from the active config.
- Primary manager proposes / publishes the root onchain.
- 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:
POST /api/v1/merkle/generate
GET /api/v1/merkle/jobs/{job_id}
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 |
GET /api/v1/merkle/sync?vault_address={addr}&chain_id={id}
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.
Publish Proof Artifact
Publishing makes the active proof set available to integrators, keepers, and frontends without Erebor authentication. The app exposes this as a primary-manager-gated Publish or Re-publish action on the active tree. Once the current artifact matches the active tree, the button state becomes Published.
POST /api/v1/merkle/publish
GET /api/v1/merkle/publish/jobs/{id}
GET /api/v1/merkle/published/{chain_id}/{vault}
| Field | Description |
|---|
published | Whether a published tree exists for the vault. |
published_at | Timestamp for the most recent publish. |
root_hash | Published merkle root. Verify this against the onchain root before using proofs. |
s3_url | Public JSON artifact containing the full tree and leaf proofs. |
total_leaves | Number of authorized leaf combinations. |
tree_id | Published tree identifier. |
is_stale | Whether the artifact no longer matches the current active tree. |
is_stale is true, re-publish before relying on the artifact for execution. Even when is_stale is false, verify root_hash against the onchain SuperVaultAggregator state; offchain publish and onchain root sync are independent steps.
curl https://erebor.superform.xyz/api/v1/merkle/published/8453/{vault_address}
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 |
