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.

​
The Institution Role

An institution curates a SuperVault’s yield strategy: which protocols receive capital, in what order, under what conditions, and with what risk parameters. The institution does not hold depositor funds — the vault contract does. What institutions control: yield source selection, oracle assignment, allocation priority, reserve ratio, strategy rules, merkle authorization, fee configuration (at creation), redeem timelock, service controls, emergency pause, and access management. What the protocol enforces: merkle-verified execution, timelocked root updates, fee bounds (SuperGovernor), PPS staleness enforcement, $UP upkeep requirements, high-water mark fee accrual, and protocol revenue share. Trust model: Depositors trust the institution to select sound yield sources and maintain vault health. Depositors do NOT need to trust the institution for fund custody (held by contract), honest execution (merkle-verified), accurate PPS (oracle-enforced), or fee limits (SuperGovernor-enforced).

​
Institution Access Tiers

RoleOn-chain?Capabilities
Primary ManagerYesFull vault control. Set at creation, immutable.
Secondary ManagerYesAll operations except vault settings and user management.
View OnlyNoRead-only dashboard access.
The primary manager key is the root of trust for the vault. If compromised, an attacker could modify yield sources, update merkle authorization, and pause operations. Use hardware wallets and consider multi-sig for production vaults.
SuperVaults combine onchain vault contracts with offchain automation services. Understanding how these layers interact is essential for effective institutional operations.

​
ERC-7540 Vault Standard

SuperVault contracts are live onchain and fully non-custodial. The institutional dashboard at institutions.superform.xyz is an execution layer — it never holds keys or assets. All vault interactions are direct onchain transactions signed by your wallet.
SuperVaults implement ERC-7540, the asynchronous tokenized vault standard. ERC-7540 extends ERC-4626 compatibility (standard deposit/withdraw interface) with asynchronous request-fulfillment flows for deposits and redemptions. Why async matters: Cross-chain yield sources, illiquid positions, and redemption timelocks all require time between a user’s request and its fulfillment. ERC-7540 formalizes this into a two-phase flow:
  1. Request — Depositor submits a deposit or redemption request onchain
  2. Fulfillment — Keeper workers process the request when conditions are met (liquidity available, timelock expired, strategy rules satisfied)
Vault shares are ERC-20 tokens representing a depositor’s pro-rata claim on vault assets. Price-per-share (PPS) tracks the value of each share in terms of the underlying asset.

​
Price-Per-Share (PPS)

PPS is the core accounting primitive. It determines:
  • How many shares a depositor receives for a given deposit
  • How many underlying assets a depositor receives for redeeming shares
  • When performance fees accrue (PPS exceeds high-water mark)
  • Whether the vault is operational (PPS must be updated within the staleness window)
PPS MetricDescription
Current PPSLast onchain recorded value
Calculated PPSOff-chain computed value (may differ during update intervals)
HWM PPSAll-time high-water mark. Performance fees accrue only above this level.
Staleness countdownTime remaining before PPS expires. If PPS goes stale, vault operations are blocked until an update is pushed. The staleness window is configurable per vault and defaults to 24 hours.
Validators compute PPS offchain, sign the result as EIP-712 typed data, and any party can submit the update onchain via ECDSAPPSOracle.updatePPS(). A PPS update is accepted only after at least two-thirds of weighted validator stake has signed off, with signature, staleness, and deviation checks enforced onchain.

​
The Hook System

Hooks are onchain modules that keepers invoke to interact with external protocols. Each hook type corresponds to an operation:
Hook TypeOperation
DEPOSITDeploy vault assets into a yield source
WITHDRAWALUnwind a position from a yield source
REBALANCEMove capital between yield sources
Hooks are registered in the global Hook Registry with typed parameters (inspectParams) that define what arguments each invocation requires: yield source addresses, token addresses, oracle addresses, or freeform values. A keeper can only call a hook if the exact combination of hook address + parameters matches a leaf in the vault’s onchain merkle tree.

​
Merkle Authorization

Merkle authorization is the access control layer for keeper operations. The flow:
1

Configure

Create a hook configuration specifying which hooks are authorized with which parameters. Each (hook, params) combination becomes one leaf.
2

Generate

Erebor computes a merkle tree from the active configuration. The tree root is a single 32-byte hash that encodes all authorized operations.
3

Propose

Submit the new root to the SuperVaultStrategy contract. A timelock period begins.
4

Execute

After the timelock expires, execute the root update onchain. Keepers can now use proofs from the new tree.
Why timelocks: The timelock between proposal and execution gives depositors time to exit if they disagree with an institution’s authorization changes. This is a standard DeFi governance safety pattern. When a keeper executes a hook, the onchain contract verifies the merkle proof. If the proof is invalid (the hook + params combination was not authorized), the transaction reverts. SuperVaults use a dual-merkle model for hook authorization. The global hooks root is governance-controlled and contains generic hooks without beneficiary-specific arguments. The strategy hooks root is proposed by the vault’s main manager and contains the full strategy-specific authorization set, including beneficiary-specific hooks. Both update flows use the aggregator’s hook-root timelock, which defaults to 15 minutes and can be updated by governance. A hook must be present in either tree to execute.

​
Yield Sources and Oracles

A yield source is an external protocol contract where the vault deploys capital to generate returns. SuperVaults support two yield source types:
TypeDescriptionExample
erc4626Standard ERC-4626 vaultMorpho vaults, Aave wrappers
pendle_ptPendle Principal TokenFixed-rate yield via PT purchase
ERC-7540 yield sources are also on the roadmap as an upcoming yield source type. Each yield source must be paired with an oracle that prices the position back into the vault’s underlying asset:
Oracle TypePricing Method
erc4626Share price of the underlying ERC-4626 vault
pendle_ptSpot market price of the PT
pendle_pt_amortizedLinear decay to par value as PT approaches maturity
Adding or removing yield sources and updating oracle assignments are onchain operations that follow the prepare pattern (Erebor constructs calldata, institution signs).

​
Keeper Workers

Seven Celery-based keeper workers run continuously against each vault’s configuration:
WorkerResponsibility
fulfill_depositsAllocates free vault assets to yield sources based on the configured allocation strategy
fulfill_redeemsProcesses pending ERC-7540 redemption requests
fulfill_claimsClaims accumulated reward tokens from external protocols
fulfill_swapsSwaps non-underlying tokens back to the vault’s base asset
redemption_queue_engineMonitors the subgraph for new redemption requests
cleanup_processed_redeemsReconciles pending redemptions with onchain state
tx_managerBroadcasts transactions, monitors confirmations, handles reorgs
Workers execute on configurable intervals. Institutions control:
  • Global enable/disable per vault (stops all workers)
  • Per-service pause/resume (targeted worker control)
  • Schedule adjustment (change execution frequency)

​
The Strategy Engine

The Strategy Engine adds rule-based automation on top of the keeper system. Institutions define strategies via the Strategy Canvas with:
  • Indicators — named variables evaluated each tick (e.g., morpho_apy, free_assets)
  • Rules — boolean logic trees (EXPR, AND, OR, NOT, VOTE) that determine when to act
  • Action config — what to do when rules trigger (deposit size, target hook, slippage limits)
  • Conviction config — how many consecutive ticks must pass before dispatching an intent
Strategies evaluate on configurable tick intervals and dispatch DeFiX intents to the OMS when conditions are met.

​
DeFiX v0.1 Intent Protocol

DeFiX is the standardized intent interface between the Strategy Engine and the OMS (Order Management System). An intent represents a desired vault operation: 
Strategy triggers → Intent submitted to OMS → OMS validates merkle proof → OMS executes onchain
Intent lifecycle:
StatusDescription
ProcessingQueued or being executed
CompletedSuccessfully executed onchain
FailedExecution failed (error details attached)
CancelledCancelled before execution
The OMS handles nonce management, gas estimation, transaction broadcasting, and merkle proof validation. Failed intents include error messages and may be retried by the Strategy Engine depending on the failure type.

​
The Prepare Pattern

All onchain operations in SuperVaults follow a consistent two-phase flow:
  1. Prepare — Call a prepare-* endpoint on Erebor. It returns raw EVM calldata ({ to, data, value }).
  2. Sign — Pass the calldata to your wallet for signature and broadcast.
  3. Confirm (where applicable) — Notify Erebor of the transaction hash for indexing.
This pattern keeps private keys off the server. Erebor constructs the correct calldata; your wallet controls signing authority. Used for: vault creation, yield source management, user management, merkle root proposals, emergency pause/unpause.