Introduction

Protocol Overview

MetaVault is an advanced implementation of the ERC7540 standard enabling cross-chain yield aggregation through integration with the Superform protocol. Built on ERC4626 principles, the vault manages assets across multiple blockchain networks while providing advanced performance tracking, fee distribution systems, and robust risk management controls. Github: https://github.com/VerisLabs/metavault

Technical Architecture

Core Components

1. MetaVault (Core)

   • ERC7540-compliant vault with ERC4626 base functionality

   • Asset allocation and tracking through NFT-based positions

   • Performance-based fee system with high watermark tracking

   • Cross-chain position management via Superform integration

2. ERC7540Engine

   • Asynchronous withdrawal request processing

   • Priority-based withdrawal queue implementation

   • Receiver contract system for cross-chain settlements

   • Optimized multi-chain withdrawal routing

3. AssetsManager

   • Direct and cross-chain portfolio allocation

   • ERC4626-compatible investment operations

   • Cross-chain debt and position tracking

   • Manager-controlled rebalancing and reconciliation

4. Gateway System

   • ERC20 asset bridging via Superform protocol

   • NFT-based position management (SuperPositions)

   • Cross-chain receiver contract deployment

   • Failed transaction recovery system

Key Technical Features

Cross-Chain Operations

// Cross-chain investment with receiver system and gas handling
function investSingleXChainSingleVault(SingleXChainSingleVaultStateReq calldata req)
    external
    payable
    onlyVault
    refundGas  // Important: Handles crosschain gas refunds
{
    // Validate vault in approved list
    if (!isVaultListed(vaultAddress)) revert VaultNotListed();
    
    // Deploy or retrieve receiver 
    address receiverAddress = getReceiver(key);
    ERC20Receiver(receiverAddress).setMinExpectedBalance(req.outputAmount);
    
    // Track pending investment
    pendingXChainInvests[superformId] += amount;
    totalpendingXChainInvests += amount;
    
    // Initiate cross-chain transfer with gas refund
    gateway.investSingleXChainSingleVault{value: msg.value}(req);
}

• Asynchronous settlement system via receiver contracts

• NFT-based position tracking through SuperPositions

• Cross-chain message verification

• Bridge failure recovery mechanisms

Risk Management

// Emergency controls with recovery system
modifier noEmergencyShutdown() {
    if (emergencyShutdown) {
        revert VaultShutdown();
    }
    _;
}

function setRecoveryAddress(address _recoveryAddress) external onlyRoles(ADMIN_ROLE) {
    if (_recoveryAddress == address(0)) revert InvalidRecoveryAddress();
    recoveryAddress = _recoveryAddress;
}

• Emergency shutdown with recovery procedures

• Share locking with time-based restrictions

• Minimum output protection for all operations

• Multi-level oracle price validation

Performance Tracking

// High watermark with fee calculation
modifier updateGlobalWatermark() {
    _;
    uint256 sp = sharePrice();
    assembly {
        let spwm := sload(sharePriceWaterMark.slot)
        if lt(spwm, sp) { sstore(sharePriceWaterMark.slot, sp) }
    }
}

function hurdleRate() public view returns (uint256) {
    return _hurdleRateOracle.getRate(asset());
}

• Performance fee calculation using high watermark

• Dynamic hurdle rate tracking

• Cross-chain price aggregation

• Protocol-level yield optimization

Security Model

Access Control

uint256 public constant ADMIN_ROLE = _ROLE_0;      // Protocol administration
uint256 public constant EMERGENCY_ADMIN_ROLE = _ROLE_1; // Emergency controls
uint256 public constant ORACLE_ROLE = _ROLE_2;     // Price updates
uint256 public constant MANAGER_ROLE = _ROLE_3;    // Investment operations
uint256 public constant RELAYER_ROLE = _ROLE_4;    // Settlement processing

• Role-based permission system

• Relayer-specific settlement controls

• Role-restricted administrative functions

• Emergency override capabilities

Asset Safety

// Core safety with receiver validation
error InsufficientAssets();
error VaultNotListed();
error RequestNotSettled();
error SharesLocked();
error InvalidRecoveryAddress();
error InvalidReceiver();

• Receiver contract validation system

• Cross-chain settlement verification

• Minimum output enforcement

• Recovery address system for failed operations

• Minimum balance requirements for receiver contracts

• Gas refund protection mechanisms

• Withdrawal queue size constraints (30 vaults max)

Gas Management

• refundGas modifier ensures cross-chain operations don't strand ETH

• Calculates and refunds unused bridge fees

Integration Points

Superform Protocol

ISuperformGateway public gateway;
ISuperPositions public superPositions;

// Initialization requires
function initialize(
    VaultConfig memory config
) {
    gateway = config.gateway;
    superPositions = config.superPositions;
    asset().safeApprove(address(gateway), type(uint256).max);
}

• ERC20 asset bridging capabilities

• NFT position management

• Cross-chain message routing

• Settlement verification system

Oracle System

IHurdleRateOracle public _hurdleRateOracle;
ISharePriceOracle public oracle;

function setHurdleRateOracle(IHurdleRateOracle hurdleRateOracle) external onlyRoles(ADMIN_ROLE) {
    _hurdleRateOracle = hurdleRateOracle;
}

• Asset-specific hurdle rates

• Cross-chain price verification

• Performance benchmarking

• Oracle reward distribution

Protocol Parameters

// Critical protocol constants
uint256 public constant WITHDRAWAL_QUEUE_SIZE = 30; // Maximum vaults per queue
uint24 public constant REQUEST_REDEEM_DELAY = 1 days; // Withdrawal processing delay

Network Support

uint64[N_CHAINS] public DST_CHAINS = [
    1,     // Ethereum Mainnet
    137,   // Polygon
    56,    // BNB Chain
    10,    // Optimism
    8453,  // Base
    42161, // Arbitrum One
    43114  // Avalanche
];

Fee Configuration

uint16 public managementFee;    // Base management fee (time-based)
uint16 public performanceFee;   // Above hurdle rate fee
uint16 public oracleFee;        // Price update incentive
uint256 public sharePriceWaterMark; // High watermark tracking

Technical Considerations for Auditors

Critical Components

1. Receiver contract deployment and validation

2. Cross-chain settlement verification

3. Asset and debt tracking accuracy

4. Fee calculation precision with watermark

Key Invariants

1. Total assets = idle assets + allocated assets + pending cross-chain assets

2. Share price updates maintain a high watermark

3. Fee calculations respect hurdle rates

4. Cross-chain positions match SuperPositions balances

Security Checkpoints

1. Recovery mechanism for failed transactions

2. Role-based access enforcement

3. Settlement verification process

4. Oracle price validation

Protocol Constraints and Limitations

• Maximum number of vaults per chain: WITHDRAWAL_QUEUE_SIZE (30)

• Asset types supported: ERC20 only

• Maximum cross-chain operation timeout: determined by bridge

• Price oracle update frequency requirements

Role Access Matrix

Function	ADMIN	MANAGER	RELAYER	EMERGENCY_ADMIN
addVault	✓
investSingleDirectSingleVault		✓
processRedeemRequest			✓
settleLiquidation			✓
setEmergencyShutdown				✓

Protocol Constants

uint256 public constant WITHDRAWAL_QUEUE_SIZE = 30;
uint256 public constant SECS_PER_YEAR = 31_556_952;
uint256 public constant MAX_BPS = 10_000;
uint24 public constant REQUEST_REDEEM_DELAY = 1 days;

Getting Started

For detailed implementation guidelines and integration examples, refer to the subsequent sections covering specific protocol components and operations.