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.

SuperformOS Merkle Trees — hook configs, roots, and proof publishing 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: 
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:
ActionMeaning
in_syncOnchain root already matches
needs_generationGenerate a tree for the active config
proposeSign a root proposal transaction
pending_timelockWait for the proposal timelock
executeSign 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. 
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

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/treesGETList trees for a vault
/api/v1/merkle/proofsGETList proofs
/api/v1/merkle/proofs/lookupGETLookup one proof
/api/v1/merkle/generatePOSTStart generation
/api/v1/merkle/jobs/{id}GETPoll generation job
/api/v1/merkle/syncGETDetermine root sync action
/api/v1/merkle/publishPOSTPublish active tree proof artifact
/api/v1/merkle/publish/jobs/{id}GETPoll publish job
/api/v1/merkle/published/{chain_id}/{vault}GETPublic published tree metadata