Skip to main content

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.

SuperVaults Merkle Trees — Hook Configs and Merkle Trees tabs with Create Hook Config action The Merkle Trees page is the authorization control center for keeper operations. Every onchain action a keeper can perform must be encoded as a leaf in the vault’s merkle tree and verified against the onchain root before execution. The workflow: create a hook config defining authorized operations, generate a merkle tree from that config, then sync the tree root onchain through a timelocked proposal-execute cycle.

​
Tab 1: Hook Configs

​
Version History

Each vault maintains a history of hook configuration versions. The active version is highlighted. Previous versions are read-only for audit purposes.

​
Creating a Config

Click Create New Config. For each hook to authorize:
  1. Select Hook — from the global Hook Registry (GET /api/v1/registry/hooks)
  2. Set Parameters — for each inspectParam defined by the hook:
    • yield_source ref → yield source address
    • token ref → ERC-20 token address
    • oracle ref → oracle address
    • others → freeform hex value
Each row becomes one leaf in the merkle tree. A keeper can only call a hook with the exact parameter combination matching a leaf.

​
Activating a Config

Click Activate on a config version. Only one version is active at a time. The active config is used for the next tree generation.

​
Tab 2: Merkle Trees

Generated trees for the vault, showing:
FieldDescription
Root Hash32-byte merkle root
Leaf CountNumber of authorized (hook, params) combinations
Config HashHash of the source config version
Is CurrentWhether this root is active onchain
Click a tree to view individual leaves: hook name and address, encoded argument values, leaf hash, index, and merkle proof path. This makes the contents of each leaf explicit to depositors and operators, including the hook name and parameter values that were authorized.
SuperVaults use two merkle roots for hook authorization: a governance-controlled global hooks root and a manager-proposed strategy hooks root. Both flow through the aggregator’s hook-root timelock, which defaults to 15 minutes and can be updated by governance. A hook must be included in either root to execute.

​
Generating a Tree

Click Generate Merkle Tree. Erebor starts an async job:
  • Polling uses exponential backoff: 2s → 4s → 8s → 15s
  • 409 Conflict = generation already in progress
  • Job status: pending → running → completed / failed
POST /api/v1/merkle/generate
{ "vault_address": "0x...", "chain_id": 8453 }

GET /api/v1/merkle/jobs/{job_id}

​
Syncing to Chain

After generation, click Sync to Chain. Erebor evaluates onchain state and returns the required action:
Sync ActionDescription
in_syncOn-chain root matches. No action needed.
needs_generationNo tree exists for the active config.
proposeTree ready. Sign and submit root proposal (starts timelock).
pending_timelockRoot proposed. Waiting for timelock expiry. Shows effectiveTime.
executeTimelock expired. Sign to activate the new root onchain.
GET /api/v1/merkle/sync?vault_address={addr}&chain_id={id}
# Returns 204 No Content when already in sync
Keepers cannot execute against yield sources until the merkle root is synced onchain. A pending timelock means your authorization changes are queued but not yet active.

​
Publishing the Tree

Once a tree is generated, primary managers can publish it to make the full proof set available to integrators, keepers, and frontends without requiring Erebor authentication. Navigate to the Merkle Trees tab and locate the active tree — the one currently synced onchain. Click Publish on that tree to trigger an async publish job that uploads the complete proof artifact to a public S3 URL. Only the active tree can be published. Publishing a tree that is not the current active tree is not permitted.
Publishing is separate from syncing. Sync updates the onchain root; publish makes the off-chain proof artifact publicly accessible. Both steps are needed before external consumers can verify and use the proofs.
Erebor runs the upload asynchronously. Poll the job status until completed: 
POST /api/v1/merkle/publish
{ "vault_address": "0x...", "chain_id": 8453 }
# Returns 202 + Location: /api/v1/merkle/publish/jobs/{id}
# 409 if a publish is already in progress

GET /api/v1/merkle/publish/jobs/{id}
# status: pending → running → completed / failed
Once completed, the published artifact is accessible to anyone via the public endpoint — no authentication required. See Getting SuperVaults Merkle Tree for how consumers fetch and use it.

​
Merkle Proofs

Proofs for each leaf are available via GET /api/v1/merkle/proofs?vault_address={}&chain_id={}. Use these for programmatic validation or custom keeper implementations.

​
All Merkle Endpoints

EndpointMethodDescription
/api/v1/merkle/configs/versionsGETConfig version history
/api/v1/merkle/configs/versionGETSingle version by number
/api/v1/merkle/configs/activeGETActive config
/api/v1/merkle/configsPOSTCreate new config
/api/v1/merkle/configs/activatePUTActivate a version
/api/v1/merkle/treesGETAll trees for vault
/api/v1/merkle/proofsGETAll leaf proofs
/api/v1/merkle/generatePOSTStart generation job
/api/v1/merkle/jobs/{id}GETPoll job status
/api/v1/merkle/jobsGETRecent jobs list
/api/v1/merkle/syncGETSync status and required action
/api/v1/merkle/publishPOSTPublish active tree (primary manager only)
/api/v1/merkle/publish/jobs/{id}GETPoll publish job status
/api/v1/merkle/published/{chain_id}/{vault}GETPublic — get published tree metadata