Getting SuperVaults Merkle Tree

Fetch the published merkle tree and proofs for a SuperVault. No authentication required.

The merkle publish endpoint returns the latest published merkle tree metadata for any vault. It is public — no authentication required. Use it to retrieve the proof artifact, verify the root hash, and check whether the published tree reflects the manager’s current active configuration.

Endpoint

GET /api/v1/merkle/published/{chain_id}/{vault_address}

Base URL: https://erebor.superform.xyz
Auth: None

Path Parameters

Parameter	Type	Description
chain_id	integer	Chain ID (e.g., 8453 for Base, 1 for Ethereum)
vault_address	string	Vault contract address (checksummed or lowercase)

Response

Published tree

{
  "success": true,
  "data": {
    "is_stale": false,
    "published": true,
    "published_at": "2026-04-28T08:47:56.558012Z",
    "root_hash": "0xfadbeed8d842eabf62ae6388506ca506f716ab5722c21af61899baf04b2ed6dc",
    "s3_url": "https://erebor-merkle-trees-231862524346.s3.eu-north-1.amazonaws.com/vaults/8453/0x01c427580a2dfbdd894dabc4bff6c1dce7aab53c/e31ee747-c953-4a9d-ba28-0296c12397ec.json",
    "total_leaves": 4,
    "tree_id": "e31ee747-c953-4a9d-ba28-0296c12397ec"
  }
}

Not yet published

{
  "success": false,
  "published": false,
  "message": "no published tree found for this vault"
}

Response Fields

Field	Type	Description
published	boolean	Whether the manager has published a tree for this vault
published_at	string	ISO 8601 timestamp of the most recent publish
root_hash	string	32-byte merkle root. Verify this against the onchain root in SuperVaultAggregator before using any proof
s3_url	string	Direct URL to the full proof JSON artifact
total_leaves	integer	Number of authorized (hook, params) combinations in the tree
tree_id	string	UUID of the published tree version
is_stale	boolean	Whether the published tree is out of date — see below

Understanding is_stale

is_stale: true when the published tree is not the vault’s current active tree (including the case where no current active tree exists). The published artifact at s3_url was generated from a config version that no longer matches the vault’s current state.

When is_stale is true:

• The root_hash in this response may no longer match the current onchain root
• The proof artifact may not cover all currently authorized operations
• Wait for the manager to re-publish before relying on these proofs for execution

When is_stale is false:

• The published tree was generated from the manager’s current active config
• The artifact is current, but still verify root_hash against the onchain SuperVaultAggregator state — publishing updates the off-chain record; the onchain root is updated separately through the proposal-timelock-execute cycle

Even when is_stale: false, always verify root_hash against the onchain SuperVaultAggregator before passing proofs to executeHooks(). The off-chain publish and the onchain root sync are independent operations.

Fetching the Proof Artifact

The s3_url is a direct public URL to a JSON file containing the complete merkle tree with all leaf proofs.

cURL

# 1. Get metadata
curl https://erebor.superform.xyz/api/v1/merkle/published/8453/0x01c427580a2dfbdd894dabc4bff6c1dce7aab53c

# 2. Fetch the proof artifact (use s3_url from response)
curl https://erebor-merkle-trees-231862524346.s3.eu-north-1.amazonaws.com/vaults/8453/0x01c427580a2dfbdd894dabc4bff6c1dce7aab53c/e31ee747-c953-4a9d-ba28-0296c12397ec.json

Proof Artifact Shape

The JSON at s3_url matches the MerkleTreeWithLeaves shape returned by GET /api/v1/merkle/proofs. Each leaf contains the hook address and name, encoded argument values, leaf hash, index in the tree, and the merkle proof path.

{
  "root_hash": "0xfadbeed8d842eabf62ae6388506ca506f716ab5722c21af61899baf04b2ed6dc",
  "leaves": [
    {
      "index": 0,
      "leaf_hash": "0x...",
      "hook_address": "0x...",
      "hook_name": "depositHook",
      "encoded_args": "0x...",
      "proof": ["0x...", "0x..."]
    }
  ]
}

Pass leaf.proof as strategyProofs[i] when calling executeHooks().

Caching

Responses are cached — 60 seconds on a successful hit, 30 seconds on a negative (unpublished) response. Build polling intervals of at least 60 seconds around this endpoint.

Error Codes

Code	Meaning
200	Success — check data.published and data.is_stale
404	Vault not registered in Erebor
500	Internal error