SuperVaults

Introduction

SuperVaults are flexible and secure vault primitives built to scale by leveraging infrastructure provided in Superform core. On top of tablestakes features for vault products, including simplified access through a singular product, non-custodial management, and the composability and transparency brought by being onchain, SuperVaults enable:

  • Permissionless Vault Creation: Anyone can create a new vault with Hooks, charge fees, and have validator support by paying upkeep

  • Infinitely Flexible Execution: Validates and executes arbitrary Hooks created in Superform Core via Merkle proofs. These can be used to deposit, stake, bridge, loop, and arbitrary set of actions that have been validated in the root

  • Security through Dual Merkle Validation: The system uses two Merkle trees for hook validation. A global root is managed by governance for protocol-wide hook approval and a strategy root is managed by strategists for vault-specific operations

  • Fee Management: Can take both management and performance fees, configurable by the strategist, with timelocked updates

  • Automated Emergency Controls: Provides emergency withdrawal mechanisms with built-in pause functionality on circuit breakers

These are the explainer docs for SuperVaults. We recommend users interested in building on these to simply interact with the Superform SDK, detailed further in Manage a SuperVault.

How do SuperVaults work?

SuperVault (entrypoint) — ERC-7540 vault that implements synchronous deposits and asynchronous redemptions

SuperVaultStrategy (execution) — uses Hooks execute arbitrary strategies safely

SuperVaultEscrow (holding) — custodies shares during redemption requests

SuperVaultAggregator (control) — registry, factory, and PPS oracle for all SuperVaults

Operational Flow

Deposits

  1. User Deposit: User calls deposit() with assets

  2. Immediate Minting: Shares minted synchronously at current PPS

  3. Asset Custody: Assets transferred to strategy for allocation

  4. Hook Execution: Strategist executes hooks to deploy capital

  5. PPS Updates: Validators provide updated PPS reflecting new positions

Redemptions

  1. Redeem Request: User calls requestRedeem() with shares

  2. Share Escrow: Shares transferred to escrow contract

  3. Fulfillment: Strategist executes hooks to free up assets

  4. PPS Validation: Slippage protection against recorded request PPS

  5. Asset Claim: User calls withdraw() to receive assets

Strategy Management

  1. Hook Approval: Strategist proposes new hook root

  2. Timelock Period: 15-minute delay configurable by governance for strategy hooks

  3. Execution: Hook root updated and new strategies enabled

  4. Guardian Oversight: Guardians can veto malicious updates

PPS Updates

  1. Off-Chain Calculation: Validators calculate PPS independently

  2. Signature Generation: Validators sign PPS with private keys

  3. Aggregation: Signatures collected and submitted to oracle

  4. Validation: Oracle verifies signatures and quorum

  5. Forwarding: Validated PPS forwarded to aggregator

  6. Strategy Checks: Aggregator runs dispersion/deviation checks

  7. Storage: PPS stored and made available for vault operations

Creating setting up, and managing a vault

Vaults can be created in SuperVaultAggregator by calling createVault using the following parameters. The primary strategist has full control over strategy operations and multiple secondary strategists as backup accounts can propose primary strategist changes with 7-day timelock. 

function createVault(VaultCreationParams calldata params) external 
    returns (address superVault, address strategy, address escrow)

struct VaultCreationParams {
    address asset; // Address of the underlying asset
    string name; // Name of the vault token
    string symbol; // Symbol of the vault token
    address mainStrategist; // Address of the vault mainStrategist
    uint256 minUpdateInterval; // Minimum time interval between PPS updates
    uint256 maxStaleness; // Maximum time allowed between PPS updates before staleness
    FeeConfig feeConfig;
}

struct FeeConfig {
    uint256 managementFeeBps; // Management fee in basis points
    uint256 performanceFeeBps; // Performance fee in basis points
    address recipient; // Fee recipient address
}

Once vaults are created, strategists automatically benefit from the list of hooks that are in the global hooks root. However, if more functionality is to be added, primary strategists can propose a new strategy hooks root. 

function proposeStrategyHooksRoot(address strategy, bytes32 newRoot) external validStrategy(strategy)

Once vaults are have funds in them, strategists must deposit UP tokens to ensure that validators are compensated for the cost of updating onchain PPS for their vaults. This is also done in SuperVaultAggregator. 

function depositUpkeep(address strategist, uint256 amount)

Once funds arrive into the vault via users requestDeposit, strategists can execute any of the hooks in the root to fulfill a deposit. 

function executeHooks(ExecuteArgs calldata args) external

struct ExecuteArgs {
    address[] hooks;
    bytes[] hookCalldata;
    uint256[] expectedAssetsOrSharesOut;
    bytes32[][] globalProofs;
    bytes32[][] strategyProofs;
}

A similar flow presents itself on redemptions.

Validating PPS

Flexibilty and security is economically enforced by validators submitting PPS, supported by oracle infrastructure in Superform core. If interested in becoming a SuperVault validator, we recommend reading Become a Validator.

Validators currently use a ECDSAPPSOracle which validates price updates using cryptographic signatures from the decentralized validator network.

  1. Message Construction: keccak256(abi.encodePacked(strategy, pps, ppsStdev, validatorSet, totalValidators, timestamp))

  2. Signature Recovery: Uses ECDSA to recover signer addresses

  3. Validator Verification: Checks signers against registered validator set

  4. Quorum Enforcement: Requires minimum number of signatures

  5. Duplicate Prevention: Prevents the same validator from signing twice

Security

SuperVaults provide superior security through a combination of hook validation, emergency circuit breakers, and comprehensive access controls with timelocks.

Hook Validation System

The dual Merkle tree system provides layered security while retaining flexibility needed for competitive returns.

Global Hooks Root:

  • Governance Managed: Updated by SuperGovernor with timelock

  • Protocol-Wide: Applies to all strategies

  • Guardian Veto: Can be vetoed by guardians to prevent malicious updates

Strategy Hooks Root:

  • Strategist Managed: Updated by primary strategist

  • Vault-Specific: Applies only to individual strategies

  • Guardian Veto: Can also be vetoed by guardians

function _validateSingleHook(
    address strategy,
    bytes calldata hookArgs,
    bytes32[] calldata globalProof,
    bytes32[] calldata strategyProof,
    bool globalVetoed,
    bool strategyVetoed
) internal view returns (bool) {
    // If both roots are vetoed, all hooks are invalid
    if (globalVetoed && strategyVetoed) return false;
    
    bytes32 leaf = keccak256(bytes.concat(keccak256(abi.encode(hookArgs))));
    
    // Try global root first
    if (!globalVetoed && _globalHooksRoot != bytes32(0)) {
        if (MerkleProof.verify(globalProof, _globalHooksRoot, leaf)) return true;
    }
    
    // Try strategy root
    if (!strategyVetoed && strategyRoot != bytes32(0)) {
        if (MerkleProof.verify(strategyProof, strategyRoot, leaf)) return true;
    }
    
    return false;
}

Emergency Mechanisms

Strategy Pausing

SuperVaultAggregator implements sophisticated checks for PPS updates. Besides checks for actives oracles, quorum requirements, and other validations, strategies can be automatically paused when:

  • PPS dispersion exceeds threshold

  • PPS deviation is too large

  • Validator participation is insufficient

  • Updates are too stale

// C2.1 Dispersion Check: stddev/mean ratio
if (dispersion > dispersionThreshold) {
    checksFailed = true;
    emit StrategyCheckFailed(strategy, "HIGH_PPS_DISPERSION");
}

// C2.2 Deviation Check: absolute change from current PPS  
if (relativeDeviation > deviationThreshold) {
    checksFailed = true;
    emit StrategyCheckFailed(strategy, "HIGH_PPS_DEVIATION");
}

// C2.3 M/N Check: validator participation rate
if (participationRate < mnThreshold) {
    checksFailed = true;
    emit StrategyCheckFailed(strategy, "INSUFFICIENT_VALIDATOR_PARTICIPATION");

Emergency Withdrawals

  • Proposal Phase: Strategist proposes emergency withdrawal capability

  • Timelock: 7-day delay before activation

  • Execution: Strategist can withdraw free assets to specified recipient

Guardian Veto Powers

  • Can veto global hooks root updates

  • Can veto strategy-specific hooks root updates

  • Provides rapid response to malicious activity

Access Controls

Role-based permissions allow for granular control of the strategy.

Role
Permission

Primary Strategist

Full strategy control (whitelisting strategy-level hooks, fees, processing deposits and redemptions)

Secondary Strategists

Day to day manager, everything the primary strategist can do minus whitelisting hooks and fees

SuperGovernor

Protocol governance that has strategy-level overrides (can take over strategist role), updates allowable global hook root for all strategies

Guardians

Threat monitoring network, veto powers for whitelisted hooks for security

Validators

$UP stakers that can update price-per-share with circuit breaker protections and slashing

Timelock Protections

  • Strategist Changes: 7-day timelock for primary strategist updates

  • Hook Roots: 15-minute timelock for strategy hooks, 7-day for global

  • Fee Updates: 7-day timelock for fee configuration changes

  • Emergency Features: 7-day timelock for emergency withdrawal activation

Economics

All fees taken are configurable by the strategist with a split to Superform that can be turned on by governance.

Fee Type
Description

Management

Configurable by the strategist, applied to the initial deposit amount

Performance

Configurable by the strategist, applied to profits above cost basis when users redeem

Upkeep

Strategists pay UP tokens for validators to update prices

PreviousHooksNextSuperAssets

Last updated