#### Redeem Queue Serving as the counterpart to the Deposit Queue, it manages withdrawal requests. Redemptions are processed in two phases: 1. Oracle pricing – reports are processed in batches, with each batch assigned a specific conversion price derived from its corresponding Oracle report. 2. Liquidity settlement – Vault liquidity is pulled asynchronously, allowing the curator to finalize withdrawals and perform asset swaps before processing user redemption requests. This separation allows asynchronous liquidity management, gas efficiency, and protection against griefing. Unlike deposit requests, withdrawal requests in the Redeem Queue cannot be canceled to prevent yield-griefing. * **Technical Details** **Redeem flow**: * **Step 1: User redeems** * User submits `redeem` request, vault shares are immediately locked in the share manager. They are burned when an oracle report prices the request. * The vault curator monitors and manages liquidity across connected Subvaults, pulling funds and swapping assets as needed to fulfill redemption requests. * **Step 2: Oracle report** * Valid and non-suspicious `Oracle` `report` arrives. * Anyone, usually the vault curator or a keeper, invokes `handleBatches(n)` on the `RedeemQueue`. * This triggers the movement of required assets from the vault (and associated subvaults) to process redemption requests. * **Step 3: User claims** * Users call `claim(receiver, timestamps)` to withdraw assets. #### Assumptions & Properties 1. Non-Cancellable Requests Prevents griefing where a user requests redemption, causing curator to pull liquidity, then cancels. 2. Time-sensitive request handling Oracle reports can only process a redemption request if at least `redeemInterval` seconds have passed since the request was submitted – i.e., `report.timestamp` must be greater than or equal to `request.timestamp + redeemInterval`. 3. Asynchronous Fulfillment Liquidity can be managed independently of oracle report submission.\ \\
#### Signature Deposit and Redeem Queues Signature Queues allow deposits and redemptions to be processed instantly, bypassing the standard time-buffered flow. That happens when a trusted consensus group issues offchain-signed approvals. Key Features: * **Instant execution** without waiting for Oracle price reports * **Nonce-based signature protection** to prevent replay attacks * **EIP-712/EIP-1271 compatible** signed orders * **Oracle price validation** enforced onchain * **Stateless and removable** (does not accumulate shares or process claims) * **Fee-bypass**: No Deposit Fee or Redeem Fee is charged for actions via this queue * **Technical Details** **Signature Queue flow:** * **Step 1: Offchain signing** * Offchain consensus actors (operators, curators, admins) generate signed `Order` messages. * **Step 2: Onchain execution** * A user submits this order to the `SignatureQueue` contract for execution. * The queue: * Verifies the order signature * Validates nonce, queue address, asset match, deadline, and caller * Computes the implied asset/share price and checks it against the vault's oracle * If all checks pass, the order is executed atomically. #### Assumptions & Properties * Only **trusted offchain actors** (consensus group) are authorized to sign orders. * Price quotes must be valid and non-suspicious. * Users cannot reuse old signatures due to nonce tracking. * Orders must be executed before `deadline`.\ \\
#### Sync Deposit and Redeem Queues Sync Queues settle deposits and redemptions instantly at the latest oracle price, without signatures and without a claim step. Any eligible user can call them directly. Key Features: * **Instant execution** at the latest stored oracle report * **Freshness check**: the report must be non-suspicious and no older than `maxAge` * **Optional penalty** (`penaltyD6`) that reduces the shares minted or the assets paid out, in favor of remaining holders * **Fees apply**: the vault's deposit and redeem fees are charged as in the async queues * **Redemption safeguards**: `SyncRedeemQueue` also checks vault liquidity and a leaky-bucket daily limit in shares * **Technical Details** **Sync deposit flow:** * User calls `deposit(assets, referral, merkleProof)` on the `SyncDepositQueue`. * The queue checks the whitelist and the oracle report, moves the assets into the vault, mints shares to the user and the fee recipient, and runs the deposit hook. **Sync redeem flow:** * User calls `redeem(shares, receiver)` on the `SyncRedeemQueue`. * The queue checks the oracle report, liquidity and daily limit, burns the shares, runs the redeem hook to pull liquidity, and sends the assets to `receiver`. #### Assumptions & Properties * Prices can be up to `maxAge` old, so `maxAge` should stay close to the oracle's reporting cadence. * Sync redemptions do not reserve liquidity for priced async redemptions. When both queue types are active, the curator must keep enough liquid assets for both. * See [SyncDepositQueue](/core-vaults/architecture/queues/syncdepositqueue) and [SyncRedeemQueue](/core-vaults/architecture/queues/syncredeemqueue) for details.\ \\
#### Hooks Hooks are contracts that a vault runs with `delegatecall` whenever a queue moves assets in or out. Deposit hooks route or convert incoming assets, for example forwarding them into subvaults or wrapping ETH into wstETH. Redeem hooks pull liquidity back from subvaults and report how much is available for redemptions. Each queue uses its own custom hook if one is set, or the vault's default deposit or redeem hook. See [Hooks](/core-vaults/architecture/hooks/index) for the available implementations. #### Vault The Vault contract serves as the central entry point into the Core Vault system. It is configured by four internal modules: * **BaseModule**: Implements different auxiliary interfaces such as `onERC721Received`, `getStorageAt` and `receive` callback * **ACLModule:** Role-based access control for system components * **ShareModule:** Management of shares, fees, deposit and redeem queues lifecycle, `Oracle` report handling * **VaultModule:** Subvaults management, pushing and pulling of assets in subvaults\ \\
#### Subvault The Subvault contract is a vault component designed to manage delegated asset strategies, acting as a controlled execution unit within a system. Like the Vault contract, it is configured by modules: * **BaseModule**: Implements different auxiliary interfaces such as `onERC721Received`, `getStorageAt` and `receive` callback. * **SubvaultModule:** Represents an isolated child vault within a modular vault system, responsible for securely holding and releasing assets upon authenticated requests. * **VerifierModule:** is an abstract extension of the Base Module designed to provide standardized access to a Verifier contract. * **CallModule:** Enables arbitrary low-level calls to external contracts (used by curator of the vault), and verification through a verifier module.\ \\
#### Verifier Each Subvault is paired with a Verifier contract, which validates function calls and ensures only pre-approved actions from valid actors are permitted across vault-connected modules. While each Subvault is expected to have its own dedicated Verifier contract, it is still possible for the same Verifier to be shared across multiple Subvaults. * **Technical Details** Verifier allows multiple types of verification: * **ONCHAIN\_COMPACT**: Checks `CompactCall` (who | where | selector) hash against internal admin-controlled set * **MERKLE\_COMPACT**: Verifies Merkle proof of `CompactCall` (who | where | selector) hash * **MERKLE\_EXTENDED**: Verifies Merkle proof of `ExtendedCall` (who | where | value | callData) hash * **CUSTOM\_VERIFIER:** Delegates full verification to an external verifier Two admin-owned parameters are saved in the state of the Verifier contract: `compactCallHashes` that defines all allowed calls for **ONCHAIN\_COMPACT** verification type `compactCalls` is an optional mapping for reverse lookup of call metadata by hash `merkleRoot` that defines all allowed calls for **MERKLE\_COMPACT, MERKLE\_EXTENDED** and **CUSTOM\_VERIFIER**\ \\
#### Oracle The Oracle contract handles secure and configurable price reporting for supported assets. Closely integrated with the `ShareModule`, it provides price validation, deviation monitoring, and time-restricted report submissions. It enforces strict guarantees around **report timing** and **trust minimization** using role permissions and deviation thresholds. This oracle ensures consistent pricing across all queue, share, and limit-related calculations. Key considerations: * Only authorized roles can submit price updates * Suspicious reports require explicit approval before acceptance * Price validation is performed locally without relying on external oracle feeds * Manipulation is prevented through absolute and relative deviation limits * **Technical Details** Oracle Configurable Security Parameters: * **Absolute Deviation**: Hard limits on price delta in price units * **Relative Deviation**: Tolerance as a percentage (e.g., 5% = 0.05e18) * **Timeout**: Minimum time between valid reports (ignored if the previous report is suspicious) * **depositInterval**: Minimum age required for a deposit to be processed * **redeemInterval**: Same, but for redemptions **Reporting flow**: * **Step 1: Report is submitted:** * Each asset is checked for support * The previous report state is evaluated: * If `timeout` has not passed, and the report is not suspicious → revert `TooEarly` * Price is compared against previous: * `maxAbsolute` → revert `InvalidPrice` * `maxRelative` → flagged `isSuspicious` * If the report is valid and non-suspicious (deviation \< suspicious && deviation \< max), it is immediately accepted * If the report is suspicious it will be accepted only after validation from the Admin (ACCEPT\_REPORT\_ROLE holder) * **Step 2: Accepted report propagation:** * Triggers `vault.handleReport(...)`, processing deposit requests and pending redeem requests * Emits `ReportsSubmitted` **Validation Logic:** Reports are validated by: * Calculating **absolute deviation (**`maxAbsolute` ) * Calculating **relative deviation (**`maxRelative` ) * Comparing against `max` and `suspicious` thresholds A report is: * **Rejected** if either deviation exceeds max * **Accepted but marked as suspicious** if above the suspicious threshold, flagging the report * **Accepted as normal** if within all limits Used by: * `SignatureDepositQueue`, `SignatureRedeemQueue`, `DepositQueue` and `RedeemQueue` contracts * `SyncDepositQueue` and `SyncRedeemQueue` contracts * Vault's limit accounting (`RiskManager`)\ \\
#### Share Manager The Share Manager is an upgradeable contract responsible for managing vault share issuance, allocation, whitelisting, permissions, and lockups within a modular vault system. Key responsibilities include: * Tracking total and active share supply * Managing global and targeted account lockups * Verifying whitelist status and transfer permissions * Enforcing mint, burn, and transfer pauses * Handling share allocation and claims through queues * Whitelisting for implementing KYC & compliance features **Technical Details** Share Manager relies on a compact bitmask (`flags`) for enabling/disabling features and supports configurable per-account permissions. Controlled via `ShareManagerFlagLibrary`: * `hasMintPause` * `hasBurnPause` * `hasTransferPause` * `hasWhitelist` * `hasTransferWhitelist` * `globalLockup` * `targetedLockup` Lockups are enforced in `updateChecks`. Share Manager operates under the control of defined roles: * `SET_FLAGS_ROLE`: Allows changing global flags (e.g., mint pause, whitelist enforcement). * `SET_ACCOUNT_INFO_ROLE`: Grants permission to set per-account configuration. * `SET_WHITELIST_MERKLE_ROOT_ROLE`: Grants permission to set new whitelist merkle root.\\
#### Fee Manager The Fee Manager oversees the calculation and management of multiple fee types within the vault system. Currently, it supports four fee-acquiring methods: * **Deposit Fee:** Charged on asset deposits * **Redeem Fee:** Applied on share redemptions * **Performance Fee:** Based on decreases in share price (assets × price = shares) * **Protocol Fee:** Time-based fee accrued per vault All fees are paid in vault shares rather than the underlying assets. Admin can update recipient and fee parameters. **Technical Details** Fee Manager will require identifying the base asset of the vault. `setBaseAsset`: Called once per vault to register its performance reference token. `updateState(asset, price)`: Vaults call this to refresh timestamp and minimum price. Performance and Protocol fees are activated by a fresh Oracle report on the base asset. #### Fee Calculation Logic: * **Deposit fee** – applied linearly and calculated as `shares * depositFeeD6 / 1e6`, deducted during the oracle report handling process. * **Redeem fee** – applied linearly and calculated as `shares * redeemFeeD6 / 1e6`, deducted when shares are requested for redemption. * **Performance fee** – due to the use of a non-standard pricing mechanism (`price = shares / assets`), delegation yield will result in a lower reported price by the oracle; if `priceD18` falls below `minPriceD18`, the fee is charged as `(minPriceD18 - priceD18) * performanceFeeD6 * totalShares / 1e24` to capture the implied yield. * **Protocol fee** – a continuously accruing time-based fee calculated as `totalShares * protocolFee * (block.timestamp - timestamps[vault]) / (365 * 24 * 3600 * 1e6)`, proportional to both share supply and elapsed time since the last timestamp update.\\
#### Risk Manager The Risk Manager contract defines and enforces asset deposit limits across the Vault and its associated Subvaults. It maintains internal accounting of balances, limits, and approved assets for each subvault. This module is responsible for: * Setting and enforcing share limits (practically representing approximate deposit limits) at both vault and subvault levels * Permitting or restricting specific assets to be pulled into the Subvaults * Tracking pending balances for Deposits that are not yet finalized * Validating limits using Oracle price reports **Technical Details** * **Vault Limit**: Global cap across all assets managed by the vault (in shares). * **Subvault Limit**: Individual cap per subvault, enforced independently (in shares). * **Allowed Assets**: Only explicitly allowlisted assets are permitted for push / pull operations in a given subvault. * **Pending Assets**: Temporarily tracked assets, e.g., during deposit queueing * **Shares Conversion**: All balances are internally tracked in shares, calculated using latest report in the `Oracle` contract. All vault and subvault-level limits are treated as **approximate** and computed using the most recent Oracle report available **at the time of the state update** (on Subvault pull/push event or Deposit/Redeem operations). If actual balances deviate significantly from the stored `balance` values due to oracle drift, delayed execution, or protocol-side changes, a **trusted actor** can apply a 'corrections' to mitigate the difference: * `modifyVaultBalance` for the Vault, or * `modifySubvaultBalance` for individual Subvaults. Since the system is expected to hold only correlated assets, such manual adjustments are assumed to be **rare** under normal operating conditions.\\
#### Access Control Granular Access Control (MellowACL) is a lightweight yet extensible layer built on an OpenZeppelin contract. It adds automatic tracking and enumeration of *active roles* to enhance governance transparency and enable dynamic role management. Responsibilities include: * Granting and revoking access control roles to addresses * Maintaining a dedicated set of all active (assigned) roles * Providing enumerable functions for external auditing of granted roles * Emitting events when roles are assigned or fully revoked\\
### Supported protocols and integrations The Core Vaults architecture supports integration with a wide range of apps, including both DeFi protocols and centralized exchanges. Most of the protocol integrations can work out of the box. For the current, canonical list of supported execution venues, see [Execution venues](/mellow-vaults-overview#execution-venues). #### **CEXes** via custodial off-exchange solutions (Copper ClearLoop and Ceffu) * Deribit * Bybit * Binance * Most of tier 1 and 2 CEXes ## Case Study **Prerequisites:** The flow occurs within a Core Vault under the following conditions: 1. Two subvaults representing different yield sources: a delta-neutral trading strategy and restaking 2. Liquidity is evenly allocated 50%-50% between the subvaults 3. 1% management fee and 15% performance fee 4. Annual Percentage Rate (APR) of 10% **Initial Action:** A Liquidity Provider (LP) deposits 1,000,000 USDC into the Mellow Core Vault. **Process Flow:** 1. Deposits are processed and transferred into the vault after passing through the time-buffered Deposit Queue. 2. The LP receives receipt tokens representing the 1,000,000 USDC position. 3. The LP can use these receipt tokens as collateral in various DeFi protocols to generate additional yield, such as leverage looping on Gearbox. 4. Liquidity is allocated from the Vault to the Subvaults according to the limit-based rules. 5. 50% of unallocated funds are pulled into a Subvault 1 by a Curator. 6. 50% of unallocated funds are pulled into a Subvault 2 by a Curator. 7. The Curator allocates funds from Subvault 1 to the delta-neutral strategy through integrated centralized exchanges. 8. Funds from Subvault 2 are allocated to the restaking strategy via Symbiotic. 9. After 12 months, the LP requests a full withdrawal. 10. Throughout the holding period, Protocol and Performance Fees are automatically accrued with each Oracle update, resulting in a management fee of 10,000 USDC and a performance fee of 15,000 USDC – both paid in vault receipt tokens. 11. The withdrawal request is queued and detected onchain. 12. At the end of the withdrawal interval, the Curator transfers 1,075,000 USDC (principal plus accrued yield) from the Subvaults back to the Core Vault Contract. 13. The LP redeems the full amount directly from the Redeem Queue. *Process Flow for Curator Allocation:* 1. Curator asks Admin to add 2 subvaults with correct verifier configs: * First one allowing liquidity transfer into a Copper ClearLoop or Ceffu account * Second one allowing deposits, withdrawals, withdrawal claims and reward claims & swaps from Symbiotic 1. Curator pushes unallocated funds: `Vault.pushAssets(USDC, *500000*)`. 2. Allocates assets in Subvault 1 (Delta-Neutral strategy on Bybit via Copper ClearLoop). * In UI, Curator clicks **New Call** → sets target to **Copper Subvault** → selects **USDC** asset and **Bybit** as destination. * Generate `VerificationPayload` via Mellow API. * Executes call: ```solidity theme={null} subvault1.call( asset, // address of the asset (USDC) to be sent to the Copper account 0, // eth value abi.encodeCall( IERC20.transfer, // transfer call encoding (copperAccountAddress, 5e11) // (recipient, amount) ), verificationPayload // extra data for Verifier contract ) ``` * Inside Bybit UI, strategy is realized by the Curator, with settlements occurring every few hours in the Copper Clearloop. 3. Allocate to Subvault 2 (Symbiotic Restaking). * Pushes unallocated funds to the second subvault: `vault.pushAssets(subvault2, asset, 5e11)`. * Clicks **New Call** → target = **Restaking Subvault** → calls `deposit(subvault, 5e11)` * Gets the verification result and `VerificationPayload` from the Mellow API for this call. * Executes call: ```solidity theme={null} subvault2.call( symbioticVault, // address of the symbiotic vault 0, // eth value abi.encodeCall( ISymbioticVault.deposit, // deposit call encoding (subvault, 5e11) // (onBehalfOf, amount) ), verificationPayload // extra data for Verifier contract ) ``` 4. Curator regularly claims rewards from Symbiotic Restaking and swaps them into assets before depositing them using `subvault2.call` 5. Curator monitors Performance & Exit upon user request by repeating **New Call** steps to withdraw according to net returns. # FenwickTreeLibrary Source: https://docs.mellow.finance/core-vaults/architecture/libraries/fenwicktreelibrary This library implements a **0-indexed** Fenwick Tree for tracking cumulative values over a dynamic array. It is suitable for systems where frequent prefix sum queries and point updates are required, such as time-based accounting, queuing systems, or share tracking. ### Design Characteristics * `O(log n)` complexity for both updates and prefix sum queries. * Storage-efficient using a `mapping(uint256 => int256)`, instead of an array. * Only supports lengths that are exact powers of two (`2^k`), which simplifies internal logic and allows future extensions via `extend()`. ### Invariants and Constraints * The tree must be initialized with a power-of-two length > 0 via `initialize(...)`. * Index bounds are enforced – access beyond the current capacity reverts with `IndexOutOfBounds()`. * To support dynamic resizing, `extend()` can double the current tree length (up to a safe limit). * Use of negative values is supported in `modify(...)`, allowing decrement operations. ### Data Structures ```solidity theme={null} struct Tree { mapping(uint256 index => int256) _values; // Internal Fenwick Tree nodes. uint256 _length; // Capacity of the tree (must be power of two). } ``` ### Functions ### `initialize(Tree storage tree, uint256 length_)` Initializes the tree with the specified length. * Reverts with `InvalidLength()` if `length_ == 0` or not a power of two. * Only callable once (re-initialization is not allowed). ### `length(Tree storage tree) → uint256` Returns the current capacity of the tree. ### `extend(Tree storage tree)` Doubles the tree's capacity. * Preserves prefix sum structure. * Reverts with `InvalidLength()` on overflow. ### `modify(Tree storage tree, uint256 index, int256 value)` Increments or decrements the value at a given index by `value`. * Performs `tree[index] += value`. * Reverts if index is out of bounds. * No-op if `value == 0`. ### `get(Tree storage tree, uint256 index) → int256` Returns the **prefix sum** for the range `[0, index]`. * If `index >= length`, it is clamped to `length - 1`. ### `get(Tree storage tree, uint256 from, uint256 to) → int256` Returns the sum over the range `[from, to]` (inclusive). * Returns `0` if `from > to`. ### Internals ### `_modify(...)` Low-level implementation of Fenwick update using bitwise operations: * Updates `tree[index]` and propagates changes upward via `index |= index + 1`. ### `_get(...)` Assembly-optimized prefix sum computation: * Aggregates values by descending via `index := and(index, index + 1) - 1`. ### References * [CP Algorithms: Fenwick Tree](https://cp-algorithms.com/data_structures/fenwick.html) * [Wikipedia: Binary Indexed Tree](https://en.wikipedia.org/wiki/Fenwick_tree) # Libraries Source: https://docs.mellow.finance/core-vaults/architecture/libraries/index In this directory, you will find a detailed per-contract overview of the libraries used in Core Vaults, including the following: [FenwickTreeLibrary](/core-vaults/architecture/libraries/fenwicktreelibrary) [ShareManagerLibrary](/core-vaults/architecture/libraries/sharemanagerlibrary) [SlotLibrary](/core-vaults/architecture/libraries/slotlibrary) [TransferLibrary](/core-vaults/architecture/libraries/transferlibrary) # ShareManagerLibrary Source: https://docs.mellow.finance/core-vaults/architecture/libraries/sharemanagerlibrary This library helps pack multiple boolean flags and lockup durations into a compact `uint256` bitmask. It enables efficient storage and quick access to share manager configuration in vault systems. Designed for the `ShareManager` component to control: * Whether minting, burning, or transfers are paused * Whether deposit/transfer whitelists are active * How long global or user-specific lockups last All data is packed into a single `uint256` using bit-level encoding for optimal storage and gas efficiency. ### Bitmask Layout | Bit Range | Purpose | | - | - | | `[0]` | `hasMintPause` (bool) | | `[1]` | `hasBurnPause` (bool) | | `[2]` | `hasTransferPause` (bool) | | `[3]` | `hasWhitelist` (bool) | | `[4]` | `hasTransferWhitelist` (bool) | | `[5..36]` | `globalLockup` (uint32) | | `[37..68]` | `targetedLockup` (uint32) | ### Functions ### `hasMintPause(uint256 mask) → bool` Returns `true` if minting is paused (bit 0 is set). ### `hasBurnPause(uint256 mask) → bool` Returns `true` if burning is paused (bit 1 is set). ### `hasTransferPause(uint256 mask) → bool` Returns `true` if transfers are paused (bit 2 is set). ### `hasWhitelist(uint256 mask) → bool` Returns `true` if a deposit whitelist is enabled (bit 3 is set). ### `hasTransferWhitelist(uint256 mask) → bool` Returns `true` if a transfer whitelist is enabled (bit 4 is set). ### `getGlobalLockup(uint256 mask) → uint32` Returns the **global lockup duration** in seconds (timestamp), encoded in bits `[5..36]`. ### `getTargetedLockup(uint256 mask) → uint32` Returns the **targeted lockup duration** in seconds, encoded in bits `[37..68]`. ### `createMask(IShareManager.Flags calldata f) → uint256` Encodes the values in a `Flags` struct into a single bitmask: ```solidity theme={null} struct Flags { bool hasMintPause; bool hasBurnPause; bool hasTransferPause; bool hasWhitelist; bool hasTransferWhitelist; uint32 globalLockup; uint32 targetedLockup; } ``` # SlotLibrary Source: https://docs.mellow.finance/core-vaults/architecture/libraries/slotlibrary This library generates unique and collision-resistant storage slots for use in upgradeable Solidity contracts. It ensures that different modules or instances do not unintentionally overwrite each other's storage, even when used via proxy or delegate calls. ### Storage Slot Strategy * Based on EIP-7201 * Inputs include: * Contract name (`contractName`) * Human-readable name (`name`) * Version number (`version`) * Final slot: ```solidity theme={null} keccak256( abi.encode( uint256( keccak256( abi.encodePacked( "mellow.flexible-vaults.storage.", contractName, name, version ) ) ) - 1 ) ) & ~bytes32(uint256(0xff)); ``` This structure ensures: * **Namespacing:** Prevents overlap between different modules (`ShareModule`, `FeeManager`, etc.) * **Instance separation:** Multiple deployments with different names produce distinct slots * **Versioning:** Upgrades can cleanly migrate to new versions without collision ### Function ### `getSlot(string contractName, string name, uint256 version) → bytes32` **Description:** Computes a deterministic, collision-resistant storage slot for a contract module. **Parameters:** * `contractName`: Logical name of the module (e.g., `"ShareModule"`) * `name`: Instance identifier or label (e.g., `"Mellow"`) * `version`: Numeric version for versioned slot separation **Returns:** * A `bytes32` value representing the computed storage slot **Example:** ```solidity theme={null} bytes32 slot = SlotLibrary.getSlot("FeeManager", "Mellow", 1); ``` # TransferLibrary Source: https://docs.mellow.finance/core-vaults/architecture/libraries/transferlibrary This utility abstracts away the differences between transferring native ETH and ERC20 tokens by introducing a unified interface for both sending and receiving assets. It also standardizes how native ETH is represented onchain to simplify integration logic across different components. ### ETH Representation The constant `ETH = 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` ([\*\*EIP-7528](https://ethereum-magicians.org/t/eip-7528-eth-native-asset-address-convention/15989))\*\* is used as a sentinel value to distinguish native ETH from ERC20 tokens. ### Errors * `InvalidValue()`: Thrown when the contract expects a specific `msg.value` (for native ETH transfers) but receives a different amount. ### Constants * `ETH`: Reserved address used to represent native Ether. When passed to `sendAssets` or `receiveAssets`, the function will process ETH instead of calling token functions. ### Functions ### `sendAssets(address asset, address to, uint256 assets)` Sends the specified asset (`assets` amount) to the recipient `to`. * If `asset == ETH`, the function uses `Address.sendValue` to transfer native ETH. * If `asset` is an ERC20 token, it uses `IERC20.safeTransfer`. **Parameters:** * `asset`: Address of the asset to transfer. Should be `ETH` for native Ether or the ERC20 token address. * `to`: Address to send the asset to. * `assets`: Amount of the asset to transfer. **Reverts if:** ETH transfer fails or ERC20 transfer fails via `SafeERC20`. ### `receiveAssets(address asset, address from, uint256 assets)` Receives assets from the caller (or a third-party) into the current contract. * If `asset == ETH`, verifies that `msg.value == assets`. * If `asset` is an ERC20 token, calls `IERC20.safeTransferFrom` from `from` to the current contract. **Parameters:** * `asset`: Address of the asset to receive. Use `ETH` for native Ether or an ERC20 token address. * `from`: Address sending the ERC20 tokens (ignored for ETH). * `assets`: Expected amount of the asset to receive. **Reverts if:** * The contract receives an incorrect `msg.value` for ETH. * The ERC20 transfer fails. > Calling `receiveAssets(0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE, from, assets)` multiple times within a single function call will result in incorrect asset accounting. > > **DO NOT** use this function in scenarios like the following: ```solidity theme={null} function func() external payable { TransferLibrary.receiveAssets(0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE, msg.sender, 1 ether); TransferLibrary.receiveAssets(0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE, msg.sender, 1 ether); ... } ``` # BasicShareManager Source: https://docs.mellow.finance/core-vaults/architecture/managers/basicsharemanager ### Overview `BasicShareManager` is a concrete implementation of the abstract `ShareManager`, designed to provide native ERC20-style share accounting within a modular vault system. It handles minting, burning, and tracking balances of vault shares directly through a local ERC20-compatible storage layout, without exposing standard ERC20 interfaces. This contract is intended for setups where shares are not tokenized onchain as ERC20s but are still tracked internally using the ERC20Upgradeable storage schema. ### Key Features * Uses `ShareManager` for permissioning, allocation, and whitelisting logic. * Maintains balances and total supply using `ERC20Upgradeable.ERC20Storage`. * Internal mint/burn logic emits `IERC20.Transfer` events (for transparency or compatibility). * Fully decoupled from standard `ERC20` interface – share transfers are governed by vault queues and mint/burn logic only. ### Storage ERC20-style balances and supply are stored at a fixed storage slot allowing for migrations BasicShareManager ↔ TokenizedShareManager: ```solidity theme={null} bytes32 private constant ERC20StorageLocation = 0x52c6...ce00; ``` ### Initialization ```solidity theme={null} function initialize(bytes calldata data) external initializer ``` * Expects a single `bytes32 whitelistMerkleRoot` (used by `ShareManager`). ### View Functions * `activeShares()`: Returns `_totalSupply` from ERC20 storage. * `activeSharesOf(account)`: Returns balance of `account`. ### Internal Logic ### `_mintShares(address, uint256)` * Checks if minting is allowed via `updateChecks`. * Increments total supply and receiver's balance. * Emits `IERC20.Transfer(address(0), account, value)`. Reverts if: * `account == address(0)` * Minting is paused or restricted by lockup, whitelist, or blacklist ### `_burnShares(address, uint256)` * Checks if burning is allowed via `updateChecks`. * Decreases sender's balance and total supply. * Emits `IERC20.Transfer(account, address(0), value)`. Reverts if: * `account == address(0)` * `value > account balance` * Burning is paused or blocked ### Design Notes * This module deliberately avoids exposing the ERC20 interface, preventing any unintended external transfers or integrations. * It is intended for internal share accounting within vault systems, where shares are tracked but not tokenized onchain. * All permissioning logic, including minting, burning, whitelisting, and lockup enforcement, is delegated to the inherited `ShareManager`. * This implementation is ideal when the vault owner requires non-transferable shares for internal logic, without compliance to ERC20 or ERC4626 standards. * It is **not appropriate** for setups where shares must be externally transferable, interoperable with third-party protocols, or conform to token standards. # BurnableTokenizedShareManager Source: https://docs.mellow.finance/core-vaults/architecture/managers/burnabletokenizedsharemanager ### Overview `BurnableTokenizedShareManager` extends [`TokenizedShareManager`](/core-vaults/architecture/managers/tokenizedsharemanager) with two ERC20 burn functions, in the style of OpenZeppelin's `ERC20Burnable`. Holders can destroy their own vault shares, or shares they have an allowance for, without going through a redeem queue. Everything else, including minting, locking, whitelists, lockups and transfer rules, is inherited unchanged from `TokenizedShareManager` and `ShareManager`. In the standard deployment, the share manager factory registers it as version `2`, after `TokenizedShareManager` (version `0`) and `BasicShareManager` (version `1`). ### Functions ### `burn(uint256 value)` Burns `value` shares from the caller's balance. ### `burnFrom(address account, uint256 value)` Spends `value` of the caller's ERC20 allowance from `account`, then burns `value` shares from `account`. Both functions are public and need no vault role. They are separate from the queue-only `burn(address account, uint256 value)` inherited from `ShareManager`, which redeem queues use. ### Checks on burn Burns go through the token's `_update` hook, so the usual `ShareManager.updateChecks(from, address(0))` rules apply: * Reverts with `GlobalLockupNotExpired` while the global lockup is active * Reverts with `Blacklisted` if the holder is blacklisted * Reverts with `BurnPaused` if the burn pause flag is set Before the burn, `TokenizedShareManager` claims any shares the holder has waiting in deposit queues, as it does for every balance change. ### Effect on the vault Burning shares with these functions does not return any assets to the holder. The vault's assets stay in place while the share supply shrinks, so the value of the burned shares is shared among the remaining holders from the next oracle report. These public burns do not emit the `ShareManager` `Burn` event. Indexers see a standard ERC20 `Transfer(account, address(0), value)` event. ### When to use it Use `BurnableTokenizedShareManager` when shares must be destroyable outside the redemption flow. Examples are buyback-and-burn programs, or integrations that expect an `ERC20Burnable`-compatible token. If you do not need public burning, use `TokenizedShareManager`. # FeeManager Source: https://docs.mellow.finance/core-vaults/architecture/managers/feemanager **Modular, upgradeable fee management contract for vaults.** The `FeeManager` is responsible for managing and calculating various fee types in a vault system, including deposit, redemption, performance, and protocol fees. It uses a flexible architecture with deterministic storage slots (via `SlotLibrary`) and supports per-vault configurations. ### Key Responsibilities * Configures and stores global fee settings (in D6 precision). * Tracks vault-specific state (base asset, min price, timestamp). * Computes: * **Deposit Fee**: Fee charged on asset deposit. * **Redeem Fee**: Fee charged on share redemption. * **Performance Fee**: Fee based on drop in price (`assets * price = shares`) * **Protocol Fee**: Time-based fee accrued per vault. * Provides administrative controls to update fee settings and vault metadata. ### Storage Uses an isolated storage slot per deployment instance, computed deterministically using `SlotLibrary.getSlot("FeeManager", name, version)`, ensuring safety and upgradability. Each vault is associated with: * `baseAsset`: Reference token used for performance fee calculation. * `minPriceD18`: Minimum price recorded (used for performance fee calculation). * `timestamps`: Last update timestamp for time-based fee accrual. ### Fee Calculation Logic ### `calculateDepositFee(uint256 shares) → uint256` Computes a linear fee as `shares * depositFeeD6 / 1e6`. ### `calculateRedeemFee(uint256 shares) → uint256` Computes a linear fee as `shares * redeemFeeD6 / 1e6`. ### `calculateFee(...) → uint256 shares` Calculates the total fee to be charged based on: * Performance: If current `priceD18` below `minPriceD18`, applies `performanceFeeD6` as `(minPriceD18 - priceD18) * performanceFeeD6 * totalShares / (priceD18 * 1e6)`. * Protocol: Time-weighted fee based on `block.timestamp - timestamps[vault]`, computed as `totalShares * protocolFee * (block.timestamp - timestamps[vault]) / (365 * 24 * 3600 * 1e6)` All fees are paid in **shares** of the vault (not assets). ### Access Control * Only the `owner` (defined during initialization) can modify fee parameters or vault configurations. * Calls to `initialize(...)` must come from the factory and include all required setup parameters. ### Events * `Initialized(bytes data)`: Emitted after initialization. * `SetFeeRecipient(address feeRecipient)`: On recipient update. * `SetFees(...)`: On any fee change. * `SetBaseAsset(...)`: When base asset is configured per vault. * `UpdateState(...)`: On state update used for protocol/performance fees. ### Errors * `ZeroAddress()`: Thrown if an address input is zero. * `InvalidFees(...)`: When the combined fee rate exceeds 100% (`1e6` D6). * `BaseAssetAlreadySet(...)`: Prevents base asset override if already set. ### Lifecycle 1. **Constructor**: Sets storage slot based on name/version. 2. **Initialization** (via `initialize(bytes)`): Sets owner, recipient, and fees. 3. **Fee Updates**: Admin can update recipient and fee parameters. 4. **Vault Hooks**: * `updateState(asset, price)`: Vaults call this to refresh timestamp and min price. * `setBaseAsset`: Called once per vault to register its performance reference token. # Managers Source: https://docs.mellow.finance/core-vaults/architecture/managers/index In this directory, you will find a detailed per-contract overview of the "Managers" contract category, including the following contracts: [FeeManager](/core-vaults/architecture/managers/feemanager) [RiskManager](/core-vaults/architecture/managers/riskmanager) [ShareManager](/core-vaults/architecture/managers/sharemanager) [BasicShareManager](/core-vaults/architecture/managers/basicsharemanager) [TokenizedShareManager](/core-vaults/architecture/managers/tokenizedsharemanager) [BurnableTokenizedShareManager](/core-vaults/architecture/managers/burnabletokenizedsharemanager) # RiskManager Source: https://docs.mellow.finance/core-vaults/architecture/managers/riskmanager **Onchain risk control and allocation policy manager for modular vaults.** The `RiskManager` contract defines and enforces asset deposit limits across a `Vault` and its associated `Subvaults`. It maintains internal accounting of balances, limits and allowed subvault assets. ### Purpose This contract is a centralized module responsible for: * Defining and enforcing **deposit limits** at vault and subvault levels. * Allowlisting or disallowing **specific assets** per subvault. * Tracking **pending balances** (deposits/withdrawals that are not yet finalized). * Validating risk assumptions through **oracle price reports**. ### Core Concepts * **Vault Limit**: Global cap across all assets managed by the vault (in shares). * **Subvault Limit**: Individual cap per subvault, enforced independently (in shares). * **Allowed Assets**: Only explicitly allowlisted assets are permitted in a given subvault. * **Pending Assets**: Temporarily tracked assets, e.g., during deposit queueing * **Shares Conversion**: All balances are internally tracked in shares, calculated using latest report in the `Oracle` contract. ### Storage Slot Utilizes a deterministic storage slot computed via `SlotLibrary.getSlot("RiskManager", name, version)` to ensure safe upgrades and modular deployment. ### Roles and Permissions The contract uses fine-grained access roles: * `SET_VAULT_LIMIT_ROLE`: Can modify global vault capacity. * `SET_SUBVAULT_LIMIT_ROLE`: Can change limits on individual subvaults. * `ALLOW_SUBVAULT_ASSETS_ROLE`: Can whitelist assets for specific subvaults. * `DISALLOW_SUBVAULT_ASSETS_ROLE`: Can revoke asset approval from subvaults. * `MODIFY_PENDING_ASSETS_ROLE`: Can manipulate pending balance delta. * `MODIFY_VAULT_BALANCE_ROLE`: Can update the vault's live balance. * `MODIFY_SUBVAULT_BALANCE_ROLE`: Can update a subvault's internal balance. Roles are verified via the vault's ACL module (`IACLModule`) or allowed queues (`IShareModule`). ### Key Methods ### View * `vault()`: Returns the vault address. * `vaultState()`: Returns the global vault state (limit, balance). * `pendingBalance()`: Returns the pending share balance across all assets and deposit queues. * `subvaultState(address)`: Returns per-subvault state. * `pendingAssets(address)`: Returns currently pending asset amount. * `pendingShares(address)`: Returns share-equivalent of pending assets. * `allowedAssets(address)`: Count of allowed assets in subvault. * `allowedAssetAt(address, index)`: Indexed lookup of allowed asset. * `isAllowedAsset(address, asset)`: Checks asset permission for subvault. * `convertToShares(asset, value)`: Converts amount to share units using oracle. * `maxDeposit(subvault, asset)`: Calculates max deposit amount given limits and prices. ### Mutable * `initialize(bytes data)`: Initializes vault-wide limit. * `setVault(address)`: Assigns the vault address (one-time only). * `setVaultLimit(int256 limit)`: Updates vault's global limit. * `setSubvaultLimit(address, int256)`: Updates limit for a specific subvault. * `allowSubvaultAssets(address, address[])`: Adds assets to subvault's allowlist. * `disallowSubvaultAssets(address, address[])`: Removes assets from allowlist. * `modifyPendingAssets(address, int256)`: Adjusts pending assets and updates internal shares. * `modifyVaultBalance(address, int256)`: Applies a delta to vault's current balance (with limit checks). * `modifySubvaultBalance(address, asset, int256)`: Same as above, but scoped to a specific subvault. ### Internal Mechanics ### Conversion to Shares Conversion is done with oracle price data, where: ```solidity theme={null} shares = (value * priceD18) / 1e18 ``` ### Assumptions The system assumes that: * The vault and its subvaults operate exclusively with **correlated assets**, and * Protocol-level delegations performed by the curator **do not introduce extreme APR variance or significant principal loss**. Given this, all vault- and subvault-level limits are treated as **approximate** and are computed using the most recent oracle report available **at the time of the state update** (e.g., on pull/push or deposit/redeem operations). If actual balances deviate significantly from the stored `balance` values due to oracle drift, delayed execution, or protocol-side changes, a **trusted actor** can apply a 'corrections' to mitigate the difference: * `modifyVaultBalance` for the Vault, or * `modifySubvaultBalance` for individual Subvaults. Since the system is expected to hold only correlated assets, such manual adjustments are assumed to be **rare** under normal operating conditions. # ShareManager Source: https://docs.mellow.finance/core-vaults/architecture/managers/sharemanager ### Overview The `ShareManager` is an abstract upgradeable contract responsible for managing vault share issuance, allocation, whitelisting, permissions, and lockups in a modular vault system. It relies on a compact bitmask (`flags`) for enabling/disabling features and supports configurable per-account permissions. ### Key Responsibilities * Tracking total and active share supply * Managing global and per-account lockups * Verifying whitelist and transfer permissions * Enforcing mint/burn/transfer pauses * Allocating and claiming shares through queues * Emitting granular control events on state transitions ### Storage Storage is accessed via a deterministic slot generated by `SlotLibrary.getSlot("ShareManager", name, version)`. ```solidity theme={null} struct ShareManagerStorage { address vault; uint256 flags; // Encodes permissions and lockup durations uint256 allocatedShares; bytes32 whitelistMerkleRoot; mapping(address => AccountInfo) accounts; } ``` ### Permission System Controlled through roles defined as: * `SET_FLAGS_ROLE`: Allows changing global flags (e.g., mint pause, whitelist enforcement). * `SET_ACCOUNT_INFO_ROLE`: Grants permission to set per-account configuration. * `SET_WHITELIST_MERKLE_ROOT_ROLE`: Grants permission to set new whitelist merkle root. * All share-related actions are guarded via: * `onlyQueue()` * `onlyVaultOrQueue()` * `onlyRole(...)` ### View Functions * `vault()`: Returns the vault address. * `sharesOf(account)`: Total shares (active + claimable). * `activeSharesOf(account)`: Abstract; must be implemented by child. * `claimableSharesOf(account)`: Reads from the `IShareModule`. * `totalShares()`: `allocatedShares + activeShares()` * `accounts(account)`: Returns `AccountInfo` struct (deposit/transfer flags, lockups, blacklisting). * `flags()`: Decoded bitmask as `Flags` struct. * `whitelistMerkleRoot()`: Current root used for off-chain whitelist proof verification. * `isDepositorWhitelisted(account, proof)`: Verifies Merkle proof or checks local permission flags. * `updateChecks(from, to)`: Reverts on violations (paused actions, lockups, blacklisting, etc.). ### Mutable Functions * `setVault(...)`: One-time vault initialization. * `setFlags(...)`: Updates global bitmask configuration. * `setWhitelistMerkleRoot(…)`: Updates whitelist merkle root. * `setAccountInfo(...)`: Sets access rights for an individual address. * `claimShares(...)`: Claims shares from the vault's `IShareModule`. * `allocateShares(...)`: Allocates shares for future minting (only callable by a queue). * `mintAllocatedShares(...)`: Mints shares from allocated pool to user. * `mint(...)`: Mints shares to a user with optional lockup. * `burn(...)`: Burns a user's shares (only queue). * `__ShareManager_init(...)`: Sets Merkle root at construction or upgrade. ### Internal Hooks (Implemented by Child) ```solidity theme={null} function _mintShares(address account, uint256 value) internal virtual; function _burnShares(address account, uint256 value) internal virtual; ``` These abstract functions allow concrete implementations to define how share balances are recorded or tokenized. ### Bitmask-Controlled Features Controlled via `ShareManagerFlagLibrary`: * `hasMintPause` * `hasBurnPause` * `hasTransferPause` * `hasWhitelist` * `hasTransferWhitelist` * `globalLockup` * `targetedLockup` Lockups are enforced in `updateChecks`. # TokenizedShareManager Source: https://docs.mellow.finance/core-vaults/architecture/managers/tokenizedsharemanager ### Overview * This module extends `ShareManager` and `ERC20Upgradeable`, making vault shares externally transferable and fully compliant with the ERC20 standard. * It is intended for vaults that require tokenized shares usable across external protocols, wallets, or DeFi integrations. * Core share logic (minting, burning, whitelisting, lockups) is delegated to the inherited `ShareManager`, preserving consistent permission enforcement. * Whitelist enforcement, lockup mechanics, and share claim logic are integrated into the overridden `_update` hook, which ensures all token transfers pass necessary checks and call `claimShares` for non-zero actors. * Suitable for use cases where share liquidity, composability, or token standard compatibility (e.g., ERC20, ERC4626 wrappers) is required. # ACLModule Source: https://docs.mellow.finance/core-vaults/architecture/modules/aclmodule ### Overview Abstract module integrating role-based access control via `MellowACL`, providing permission management functionality. ## Internal Functions ### `__ACLModule_init` ```solidity theme={null} function __ACLModule_init(address admin_) internal onlyInitializing ``` ### Description Initializes the module with an admin address by assigning the `DEFAULT_ADMIN_ROLE`. This sets up the foundational RBAC structure. ### Parameters * `admin_`: Address to be granted the `DEFAULT_ADMIN_ROLE`. ### Requirements * `admin_` must not be the zero address. * Callable only during initialization (`onlyInitializing`). # BaseModule Source: https://docs.mellow.finance/core-vaults/architecture/modules/basemodule ## Overview `BaseModule` is an abstract contract that acts as a foundational layer for modules within the system. It integrates shared logic such as initializer protection, reentrancy guard, IERC721Receiver compliance and low level storage access. This module is intended to be inherited and extended by other functional modules. ## Constructor ```solidity theme={null} constructor() { _disableInitializers(); } ``` Prevents the contract from being initialized outside of proxy context. Ensures secure upgradeable deployments. ## Public & External Functions ### `getStorageAt(bytes32 slot)` ```solidity theme={null} function getStorageAt(bytes32 slot) external pure returns (StorageSlot.Bytes32Slot memory) ``` Returns a reference to a custom storage slot. Enables advanced access to shared storage across upgradeable modules using the `StorageSlot` pattern. **Parameters:** * `slot` - The `bytes32` identifier of the storage slot. **Returns:** * A `StorageSlot.Bytes32Slot` struct pointing to the slot. ### `onERC721Received(...)` ```solidity theme={null} function onERC721Received(address, address, uint256, bytes calldata) external pure returns (bytes4) ``` ERC721 receiver hook implementation to support safe transfers of NFTs to the module. Returns the selector as required by `IERC721Receiver`. **Returns:** * `IERC721Receiver.onERC721Received.selector` - confirms compliance. ### `receive()` ```solidity theme={null} receive() external payable {} ``` Allows the contract to receive native ETH transfers. This is typically used for vaults handling native tokens directly. ## Internal Functions ### `__BaseModule_init()` ```solidity theme={null} function __BaseModule_init() internal onlyInitializing ``` Initializes internal dependencies and base upgradeable components. Should be called from derived contract initializers. **Side Effects:** * Calls `__ReentrancyGuard_init()` to initialize reentrancy protection. # CallModule Source: https://docs.mellow.finance/core-vaults/architecture/modules/callmodule ### Overview Abstract contract extending `VerifierModule`, implementing low-level contract calls with verification via a pluggable verifier. ### `call` ```solidity theme={null} function call( address where, uint256 value, bytes calldata data, IVerifier.VerificationPayload calldata payload ) external nonReentrant returns (bytes memory response) ``` ### Description Executes a low-level call to a target contract after validating the call parameters through an external `Verifier` contract. The verification logic is determined by the verification type specified in the `Verifier` contract. For details on available verification types, refer to the [Verifier specification](/core-vaults/architecture/permissions/verifier). ### Parameters * `where`: The address of the target contract. * `value`: The ETH value to send along with the call. * `data`: Calldata to pass to the target contract. * `payload`: Encoded verification payload used to authorize the call. ### Returns * `response`: The raw returned data from the target contract call. ### Requirements * All the provided parameters must be externally verified via `verifier().verifyCall`. * Reentrancy is prevented via `nonReentrant` modifier. # Modules Source: https://docs.mellow.finance/core-vaults/architecture/modules/index In this directory, you will find a detailed per-contract overview of the "Modules" contract category, including the following modules: [VerifierModule](/core-vaults/architecture/modules/verifiermodule) [ACLModule](/core-vaults/architecture/modules/aclmodule) [CallModule](/core-vaults/architecture/modules/callmodule) [ShareModule](/core-vaults/architecture/modules/sharemodule) [VaultModule](/core-vaults/architecture/modules/vaultmodule) [SubvaultModule](/core-vaults/architecture/modules/subvaultmodule) # ShareModule Source: https://docs.mellow.finance/core-vaults/architecture/modules/sharemodule ### Purpose `ShareModule` is a core module responsible for managing user interactions with a vault through structured deposit and redeem queues. It provides governance over queue creation, hook configurations, oracle-driven settlement, and fee accounting. ### Key Responsibilities * Tracks and validates all deposit/redeem queue operations. * Coordinates price reporting with oracle. * Facilitates dynamic queue configuration and lifecycle. * Integrates hooks for deposit/redeem processing customization. * Central hub for protocol and performance fee minting, share claim logic and report handling. ### Roles * `SET_HOOK_ROLE`: Grants the ability to modify per-queue and default hook addresses. * `CREATE_QUEUE_ROLE`: Allows creation of new deposit/redeem queues. * `SET_QUEUE_STATUS_ROLE`: Permits pausing/unpausing individual queues. * `SET_QUEUE_LIMIT_ROLE`: Enables setting the max number of total queues. * `REMOVE_QUEUE_ROLE`: Allows safe removal of queues with `canBeRemoved()` check. ### Core Storage Layout (`ShareModuleStorage`) * `shareManager`: Reference to contract handling share minting/burning. * `feeManager`: Reference to contract that calculates fees and stores fee-related data. * `oracle`: Oracle contract providing price data and asset support status. * `defaultDepositHook` / `defaultRedeemHook`: Global fallback hooks used by default in case custom hooks are not defined. * `customHooks`: Per-queue override for custom hook logic. * `queueCount`: Total existing queues. * `queueLimit`: Global max limit for queues. * `isDepositQueue`: Distinguishes deposit queues from redeem ones. * `isPausedQueue`: Tracks paused queues. * `queues`: Asset → queues mapping. * `assets`: Registry of all assets with registered queues. ### View Functions * `shareManager()`: Returns the `IShareManager` instance. * `feeManager()`: Returns the `IFeeManager` instance. * `oracle()`: Returns the `IOracle` instance. * `depositQueueFactory()` / `redeemQueueFactory()`: Queue factory contracts. * `queueLimit()`: Max allowed queues. * `claimableSharesOf(account)`: Sum of claimable shares across all deposit queues for the `account`. * `getLiquidAssets()`: Called by redeem queues to determine liquidity available for handling redemptions. Returns the redeem hook's `getLiquidAssets(asset)`, or the vault's own balance if the queue has no hook. Reverts with `Forbidden` if the caller is not a registered redeem queue. * `defaultDepositHook()` / `defaultRedeemHook()`: Global default hooks. * `getHook(queue)`: Resolves hook for queue (custom or default fallback as a fallback). * Asset/Queue helpers: * `getAssetCount()`, `assetAt(index)`, `hasAsset(asset)` * `hasQueue(queue)`, `isDepositQueue(queue)`, `isPausedQueue(queue)` * `getQueueCount()` / `getQueueCount(asset)` * `queueAt(asset, index)` ### Mutable Functions * `claimShares(account)`: Claims all claimable shares from deposit queues for the specific account. * `callHook(assets)`: Calls the queue's associated hook. Transfers assets to the queue if redeem. * `setCustomHook(queue, hook)`: Assigns per-queue hook. * `setDefaultDepositHook(hook)` / `setDefaultRedeemHook(hook)`: Sets global hooks. * `setQueueLimit(limit)`: Updates global queue cap. * `setQueueStatus(queue, isPaused)`: Pauses/unpauses a queue. * `createQueue(version, isDeposit, owner, asset, data)`: Deploys new queue for asset. `version` selects the queue implementation in the deposit or redeem queue factory. In the standard deployment, `0` is the async queue, `1` the signature queue and `2` the sync queue. See [SyncQueue](/core-vaults/architecture/queues/syncqueue#creating-a-sync-queue). * `removeQueue(queue)`: Removes a queue that passed `canBeRemoved()`. * `handleReport(asset, priceD18, depositTimestamp, redeemTimestamp)`: * Called by the oracle. * Distributes protocol fees. * Propagates price report to all queues and calls hooks. ### Events * `SharesClaimed(account)` * `CustomHookSet(queue, hook)` * `QueueCreated(queue, asset, isDepositQueue)` * `QueueRemoved(queue, asset)` * `HookCalled(queue, asset, assets, hook)` * `QueueLimitSet(limit)` * `SetQueueStatus(queue, isPaused)` * `DefaultHookSet(hook, isDepositHook)` * `ReportHandled(asset, priceD18, depositTimestamp, redeemTimestamp, fees)` # SubvaultModule Source: https://docs.mellow.finance/core-vaults/architecture/modules/subvaultmodule ### Purpose The `SubvaultModule` represents an isolated child vault within a modular vault system. It is tightly controlled by its parent vault (typically a `VaultModule`) and is responsible for securely holding and releasing assets upon authenticated requests. ### Responsibilities * Store and isolate a portion of vault assets * Allow trusted actor (curator) to delegate liquidity from the Subvault to external protocol based on the `Verifier` setup for this specific subvault * Respond to `pullAssets` calls from the parent vault only ### Storage Layout (`SubvaultModuleStorage`) ```solidity theme={null} struct SubvaultModuleStorage { address vault; } ``` * `vault`: Address of the root vault that controls this subvault. Only this address can request asset withdrawals. The layout is stored in a deterministic custom slot derived using: ```solidity theme={null} SlotLibrary.getSlot("SubvaultModule", name_, version_) ``` ### View Functions ### `vault() → address` Returns the address of the parent vault that instantiated this subvault. ### Mutable Functions ### `pullAssets(asset: address, value: uint256)` Allows the parent vault to withdraw a specified amount of an asset. * **Access Control**: Can only be called by the `vault()` address * **Reverts**: With `NotVault()` if the caller is not the vault * **Transfer Behavior**: Uses `TransferLibrary.sendAssets()` to forward tokens or native ETH to the `Vault.sol` address * **Emits**: `AssetsPulled(asset, vault, value)` ### Internal Initialization ### `__SubvaultModule_init(address vault_)` Internal setup method to be called during construction or proxy initialization. ### Events ### `event AssetsPulled(address indexed asset, address indexed to, uint256 value)` Triggered when assets are withdrawn by the parent vault. * `asset`: Address of the ERC20 token or native ETH * `to`: Always equals the `vault()` address * `value`: Amount of the asset transferred ### Error Handling * **`NotVault()`**: Raised when a non-vault caller attempts to call `pullAssets()` # VaultModule Source: https://docs.mellow.finance/core-vaults/architecture/modules/vaultmodule ### Purpose `VaultModule` is a core component of the modular vault architecture. It manages liquidity routing between the [`Vault`](/core-vaults/architecture/vaults/vault) and its connected [`Subvaults`](/core-vaults/architecture/vaults/subvault), enabling flexible strategy composition and modular upgrades. It supports hot-swapping of subvault contracts and enforces contract-level control over asset movement. ### Responsibilities * Orchestrate liquidity push/pull operations between the vault and subvaults * Create, disconnect, and reconnect subvaults * Verify creations, removals and reconnections using external `Factory` contracts and local state * Track and update risk exposure via `RiskManager` ### Roles * `CREATE_SUBVAULT_ROLE`: Allows creation of new subvaults * `DISCONNECT_SUBVAULT_ROLE`: Allows disconnection of active subvaults * `RECONNECT_SUBVAULT_ROLE`: Allows reattachment of disconnected or new properly configured subvaults * `PULL_LIQUIDITY_ROLE`: Grants permission to pull assets from subvaults * `PUSH_LIQUIDITY_ROLE`: Grants permission to send assets to subvaults ### Storage Layout (`VaultModuleStorage`) ```solidity theme={null} struct VaultModuleStorage { address riskManager; EnumerableSet.AddressSet subvaults; } ``` * `riskManager`: Module used to track and limit exposure per asset/subvault * `subvaults`: Enumerable set of currently connected subvaults ### View Functions * `subvaultFactory()`: Returns `IFactory` used to deploy and check deployed subvaults * `verifierFactory()`: Returns `IFactory` used to deploy and check deployed verifiers * `subvaults()`: Returns the total number of connected subvaults * `subvaultAt(index)`: Returns the subvault address at a specific index * `hasSubvault(address)`: Checks if a given address is an active subvault * `riskManager()`: Returns the address of the risk manager ### Mutable Functions ### Subvault Management * `createSubvault(version, owner, verifier)`: * Deploys a new subvault via the `subvaultFactory` * Links it to the provided `verifier` * Adds it to the vault's subvault list * Emits `SubvaultCreated` * `disconnectSubvault(subvault)`: * Removes a subvault from the vault registry * Emits `SubvaultDisconnected` * Reverts with `NotConnected` if not already linked * `reconnectSubvault(subvault)`: * Re-adds a subvault to the vault registry * Validates via `subvaultFactory` and `verifierFactory` * Emits `SubvaultReconnected` * Reverts with `InvalidSubvault`, `NotEntity`, or `AlreadyConnected` if checks fail ### Liquidity Movement * `pushAssets(subvault, asset, value)`: * Transfers assets from vault to subvault * Updates internal risk manager state (adds exposure) * Emits `AssetsPushed` * `pullAssets(subvault, asset, value)`: * Retrieves assets from a subvault * Updates internal risk manager state (reduces exposure) * Emits `AssetsPulled` ### Internal Liquidity Hooks These can only be invoked by the vault itself (via hooks): * `hookPushAssets(subvault, asset, value)` * `hookPullAssets(subvault, asset, value)` ### Error Conditions * `AlreadyConnected(subvault)`: When attempting to reconnect an already connected subvault * `NotConnected(subvault)`: When attempting to disconnect a subvault that isn't connected * `NotEntity(address)`: Provided contract is not a valid `IFactory`deployed entity * `InvalidSubvault(address)`: Subvault fails verification (incorrect `subvault.vault()` address) * `ZeroAddress()`: Passed `RiskManager` address is zero (used in `__VaultModule_init`) * `Forbidden()`: Caller is not authorized (used in internal checks) ### Events * `SubvaultCreated(subvault, version, owner, verifier)` * `SubvaultDisconnected(subvault)` * `SubvaultReconnected(subvault, verifier)` * `AssetsPulled(asset, subvault, value)` * `AssetsPushed(asset, subvault, value)` ### Security Considerations * All critical functions gated by role-based ACL * Uses factory-verified deployments for submodules * Internal state (risk exposure) updated on every asset movement * Only the vault contract itself may invoke `hook*` liquidity functions ### Initialization ```solidity theme={null} function __VaultModule_init(address riskManager_) internal onlyInitializing ``` * Sets the `riskManager` address (must be non-zero) * Should be invoked during deployment or upgrade setup # VerifierModule Source: https://docs.mellow.finance/core-vaults/architecture/modules/verifiermodule ## Overview `VerifierModule` is an abstract extension of `BaseModule` designed to provide standardized access to a `Verifier` contract. It manages internal storage using a deterministic slot derived via `SlotLibrary`, supporting secure modular composition across multiple vault systems. ## Constructor ```solidity theme={null} constructor(string memory name_, uint256 version_) ``` Computes and stores the custom storage slot used for verifier configuration based on a unique `(name_, version_)` pair. **Parameters:** * `name_` - Unique identifier used to namespace the storage slot. * `version_` - Version number used for slot derivation. ## Public & External Functions ### `verifier()` ```solidity theme={null} function verifier() public view returns (IVerifier) ``` Returns the address of the configured `Verifier` contract. It is retrieved from internal storage using a fixed slot. **Returns:** * `IVerifier` - The verifier contract associated with the module. ## Internal Functions ### `__VerifierModule_init(address verifier_)` ```solidity theme={null} function __VerifierModule_init(address verifier_) internal onlyInitializing ``` Initializes the verifier module with the given verifier contract address. Validates non-zero address to prevent misconfiguration. **Parameters:** * `verifier_` - Address of the verifier contract. **Reverts:** * `ZeroAddress()` if verifier address is zero. ## Private Functions ### `_verifierModuleStorage()` ```solidity theme={null} function _verifierModuleStorage() private view returns (VerifierModuleStorage storage) ``` Internal function to access the `VerifierModuleStorage` struct using the precomputed custom slot. Utilizes inline assembly for direct storage access. **Returns:** * `VerifierModuleStorage` - Storage struct holding verifier address. # Oracle Source: https://docs.mellow.finance/core-vaults/architecture/oracle #### Overview The `Oracle` contract is responsible for secure and configurable **price reporting** for supported assets. It is tightly coupled with a vault module (implementing `IShareModule`) and provides **price validation**, **deviation tracking**, and **rate-limited report submission**. It enforces strong assumptions around **data integrity**, **report timing**, and **trust minimization** through roles and deviation thresholds. This oracle ensures consistent pricing across all queue, share, and vault-related computations. #### Key Responsibilities * **Report Submission**: Allows trusted accounts to submit price updates * **Deviation Analysis**: Compares new prices against the last report for suspicious behavior * **Timestamp-based Rate Limiting**: Prevents frequent or premature reports * **Supported assets**: Controls which tokens are supported by the oracle * **Oracle Price Validation**: Used by other modules (e.g., `SignatureQueue`) to verify incoming prices #### Roles | Role | Description | | - | - | | `SUBMIT_REPORTS_ROLE` | Permission to submit regular price reports | | `ACCEPT_REPORT_ROLE` | Permission to accept suspicious reports | | `SET_SECURITY_PARAMS_ROLE` | Can modify validation rules and intervals | | `ADD_SUPPORTED_ASSETS_ROLE` | Can whitelist new assets for reporting | | `REMOVE_SUPPORTED_ASSETS_ROLE` | Can remove assets and delete associated state | #### **`SecurityParameters`** ```solidity theme={null} struct SecurityParams { uint224 maxAbsoluteDeviation; uint224 suspiciousAbsoluteDeviation; uint64 maxRelativeDeviationD18; uint64 suspiciousRelativeDeviationD18; uint32 timeout; uint32 depositInterval; uint32 redeemInterval; } ``` * **Absolute Deviation**: Hard limits on price delta in price units * **Relative Deviation**: Tolerance as a percentage (e.g., 5% = 0.05e18) * **Timeout**: Minimum time between valid reports (ignored if the previous report is suspicious) * **depositInterval**: Minimum age required for a deposit to be processed * **redeemInterval**: Same, but for redemptions #### **`Reports`** ```solidity theme={null} struct Report { address asset; uint224 priceD18; } struct DetailedReport { uint224 priceD18; uint32 timestamp; bool isSuspicious; } ``` Used to validate asset prices and coordinate cross-queue processing. #### Key Functions #### View | Function | Description | | - | - | | `vault()` | Returns the linked vault (must implement `IShareModule`) | | `securityParams()` | Current oracle thresholds and intervals | | `supportedAssets()` | Count of whitelisted tokens | | `supportedAssetAt(index)` | Token at a given index | | `isSupportedAsset(address)` | Whether an asset is valid for reporting | | `getReport(asset)` | Returns last report (price, timestamp, suspicious flag) | | `validatePrice(priceD18, asset)` | Validates a given price against the current report and security params | #### Mutable | Function | Description | | - | - | | `initialize(params)` | Initializes with assets and security settings | | `setVault(vault)` | Registers the vault for report consumption | | `submitReports(reports[])` | Batch-submits prices for multiple assets | | `acceptReport(asset, price, timestamp)` | Marks a previously suspicious report as trusted | | `setSecurityParams(params)` | Updates thresholds and timing rules | | `addSupportedAssets(assets[])` | Adds tokens to the supported set | | `removeSupportedAssets(assets[])` | Removes tokens and clears their reports | #### Reporting Logic When calling `submitReports(...)`: 1. Each asset is checked for support 2. The previous report is evaluated: * If `timeout` has not passed, and the report is not suspicious → **revert** `TooEarly` 3. Price is compared against previous: * Too far off → **revert** `InvalidPrice` * Moderately off → flagged `isSuspicious` 4. If the report is accepted: * Triggers `vault.handleReport(...)` with adjusted deposit and redeem timestamps * Emits `ReportsSubmitted` #### Validation Logic Prices are validated by: * Calculating **absolute deviation** * Calculating **relative deviation** * Comparing against `max` and `suspicious` thresholds A price is: * **Rejected** if either deviation exceeds max * **Accepted but suspicious** if above suspicious threshold * **Accepted as normal** if within all limits Used by: * `SignatureDepositQueue`, `SignatureRedeemQueue`, `DepositQueue` and `RedeemQueue` contracts * `SyncDepositQueue` and `SyncRedeemQueue`, which price instant deposits and redemptions with `getReport(asset)` * Vault's limit accounting (RiskManager) #### Events | Event | Purpose | | - | - | | `ReportsSubmitted(Report[])` | Emitted when new prices are posted | | `ReportAccepted(asset, price, timestamp)` | Suspicious report accepted | | `SecurityParamsSet(params)` | Oracle thresholds changed | | `SupportedAssetsAdded(addresses[])` | New tokens added | | `SupportedAssetsRemoved(addresses[])` | Tokens delisted | | `SetVault(address)` | Vault set | #### Security Considerations * Only trusted roles can push prices * Suspicious reports cannot be accepted without explicit approval * No pricing logic oracles trust external feeds – price validation is local * Prevents manipulation by enforcing absolute & relative deviation constraints #### Related contracts * [`OracleSubmitter`](/core-vaults/architecture/oracles/oraclesubmitter): wrapper that forwards reports to the `Oracle`, keeps a report history and exposes the share price as a Chainlink-style feed * [`OracleHelper`](/core-vaults/architecture/oracles/oraclehelper): view helper that computes the prices to report from vault TVL * [`PermissionedChainlinkOracle`](/core-vaults/architecture/oracles/permissionedchainlinkoracle): owner-controlled price feed for assets without a Chainlink feed # OracleHelper Source: https://docs.mellow.finance/core-vaults/architecture/oracles/oraclehelper ### Overview `OracleHelper` is a stateless, view-only contract that computes the prices an oracle reporter should submit for a vault. You give it the vault's total value in the base asset and the price of each asset in base asset terms. It returns the `priceD18` values to pass to `Oracle.submitReports`. The helper accounts for two things that are easy to get wrong offchain: * **Pending redemptions.** Assets already owed to priced async redemptions are excluded from TVL. * **Fee dilution.** Fee shares minted when the report is handled are included, so the reported price already reflects them. ### Function ```solidity theme={null} function getPricesD18(Vault vault, uint256 totalAssets, AssetPrice[] calldata assetPrices) external view returns (uint256[] memory pricesD18) ``` ```solidity theme={null} struct AssetPrice { address asset; uint256 priceD18; // 0 for the base asset; otherwise the value of 1 asset in base asset units, 1e18 precision } ``` **Inputs:** * `vault`: the vault to price. * `totalAssets`: the vault's total value, expressed in the base asset. * `assetPrices`: every asset to report, sorted by address in strictly ascending order. Exactly one entry must have `priceD18 = 0`, and that entry is the base asset. For the other entries, `1e18` means 1 asset equals 1 base asset, and `0.5e18` means 1 asset equals 0.5 base assets. The result has one price per entry, in the same order, ready to submit. ### Calculation 1. **Validate input.** Reverts if the assets are not strictly ascending, or if more than one asset has price 0. 2. **Subtract redeem demand.** For every redeem queue that still has unprocessed requests or unsettled batches (`canBeRemoved()` is `false`), reads `totalDemandAssets` from `getState()`. This is the amount owed to priced but unsettled batches. It converts that demand to the base asset with the given prices and subtracts it from `totalAssets`. Sync and signature redeem queues are skipped because they hold no outstanding demand. Every queue asset must appear in `assetPrices`. 3. **Price the base asset.** Computes: ```solidity theme={null} basePriceD18 = (totalShares + fee) * 1e18 / totalAssets ``` `fee` is `feeManager.calculateFee(vault, baseAsset, minPriceD18, totalShares - feeRecipientShares)`. No performance fee applies at `minPriceD18`, so this is the protocol fee accrued since the last report. 4. **Resolve the performance fee.** If the result is below `minPriceD18`, the share price has reached a new high and a performance fee applies, which in turn depends on the reported price. The helper binary-searches between the result and `minPriceD18` for the smallest price that covers its own fee shares. 5. **Price the other assets.** Each non-base price is `basePriceD18 * assetPrice / 1e18`. 6. **Check the output.** Reverts if any price is 0 or does not fit in `uint224`. If the fee manager has a base asset configured, the zero-priced entry must be that asset, or the call reverts with `OracleHelper: invalid base asset`. ### Errors The helper reverts with string messages: | Message | Reason | | - | - | | `OracleHelper: invalid asset order` | `assetPrices` is not sorted by address in ascending order | | `OracleHelper: multiple base assets` | More than one entry has `priceD18 = 0` | | `OracleHelper: asset not found` | A vault queue asset is missing from `assetPrices` | | `OracleHelper: invalid base asset` | Zero-priced asset differs from the fee manager base asset | | `OracleHelper: invalid price` | A computed price is 0 or exceeds `uint224` | ### Usage notes * The helper only computes prices. It does not submit them, and it holds no roles. * The result is only as accurate as `totalAssets` and the input prices, which come from the offchain valuation. * Call it in the same block, or close to it, as the report submission. Queue demand, total shares and fee state change over time. # OracleSubmitter Source: https://docs.mellow.finance/core-vaults/architecture/oracles/oraclesubmitter ### Overview `OracleSubmitter` is a thin wrapper that sits between offchain reporters and a vault's [`Oracle`](/core-vaults/architecture/oracle). Reports pass through it to the oracle, and it adds two things: * An onchain **history of every report** submitted through it, per asset. * A **Chainlink-style price feed** of the vault share price, denominated in the vault's base asset. The feed lets external protocols, such as lending markets, read the share price with the standard `latestRoundData()` interface instead of integrating the `Oracle` directly. ### Setup ```solidity theme={null} constructor(address admin_, address submitter_, address accepter_, address oracle_) ``` * Reads the vault from `oracle.vault()` and the base asset from `feeManager.baseAsset(vault)`. Reverts with `ZeroBaseAsset` if the vault has no base asset. * Sets `decimals` to the base asset's decimals, or 18 for native ETH. * Grants `DEFAULT_ADMIN_ROLE` to `admin_`. * Grants the oracle's `SUBMIT_REPORTS_ROLE` to `submitter_` and `ACCEPT_REPORT_ROLE` to `accepter_`. These roles are held **in the `OracleSubmitter`**, using the same role IDs as the `Oracle`. For the wrapper to work, the `OracleSubmitter` contract itself must hold `SUBMIT_REPORTS_ROLE` and `ACCEPT_REPORT_ROLE` on the **vault**. The `Oracle` checks roles against the vault, and the wrapper is the account that calls it. Mellow's deployment scripts grant both roles to the submitter contract at vault creation. ### Functions ### `submitReports(IOracle.Report[] reports)` Callable by holders of `SUBMIT_REPORTS_ROLE` in the `OracleSubmitter`. 1. Reverts with `InvalidOrder` unless the first report is for the base asset. 2. Forwards the batch to `oracle.submitReports(reports)`. All oracle checks apply, including timeout, deviation limits and suspicious flags. 3. For each asset, reads back the stored `DetailedReport` and appends it to that asset's history. 4. If the base asset report is not suspicious, updates the share price feed. ### `acceptReports(address[] assets, uint224[] pricesD18, uint32[] timestamps)` Callable by holders of `ACCEPT_REPORT_ROLE` in the `OracleSubmitter`. 1. Calls `oracle.acceptReport(asset, priceD18, timestamp)` for each entry. 2. If an entry is for the base asset, it must be the first entry, or the call reverts with `InvalidOrder`. Accepting the base asset report updates the share price feed. 3. Records the acceptance time in `acceptedAt[asset][index]` for the asset's latest stored report. ### Share price feed The feed stores the inverse of the oracle price: ```solidity theme={null} latestAnswer = 1e36 / priceD18; ``` The oracle's `priceD18` is the number of shares per unit of base asset. `latestAnswer` is therefore the value of one full share (`1e18` share units) in base asset units, using the base asset's `decimals`. | Function | Returns | | - | - | | `latestRoundData()` | `(0, latestAnswer, updatedAt, updatedAt, 0)`. Round IDs are always `0` | | `latestAnswer()` | Latest share price in base asset units | | `getRate()` | `latestAnswer` as `uint256` | | `decimals()` | Decimals of the base asset | | `updatedAt()` | Time the feed was last updated | Suspicious base asset reports do not update the feed until they are accepted. Consumers should check `updatedAt` for staleness, as with any Chainlink feed. ### Report history | Function | Description | | - | - | | `reports(asset)` | Number of reports stored for `asset` | | `reportAt(asset, index)` | The `DetailedReport` (price, timestamp, suspicious flag) at `index` | | `acceptedAt(asset, index)` | Time the report at `index` was accepted, or `0` if it was never accepted | Only reports submitted through this contract are recorded. Reports sent directly to the `Oracle` do not appear in the history. ### Errors | Error | Reason | | - | - | | `ZeroBaseAsset()` | The vault has no base asset configured in the `FeeManager` | | `InvalidOrder()` | The base asset report is not the first entry | ### Deployments `OracleSubmitter` addresses for live vaults are listed on the deployment pages, for example [Lido Earn](/lido-earn/deployments). # PermissionedChainlinkOracle Source: https://docs.mellow.finance/core-vaults/architecture/oracles/permissionedchainlinkoracle ### Overview `PermissionedChainlinkOracle` is a minimal, owner-controlled price feed that implements the `latestRoundData()` part of Chainlink's `AggregatorV3` interface. It provides prices for assets that have no native Chainlink feed. Its main use is as a price source for custom `AaveOracle` deployments. The [`SwapModule`](/core-vaults/architecture/utils/swapmodule) reads those `AaveOracle` deployments to value assets and enforce minimum swap output.
Instances Addresses for the Lido Earn vaults, earnETH, earnUSD, earnUSDc and earnUSDe, are on the [Lido Earn deployments](/lido-earn/deployments) page. Addresses for the USDG Yield Vault, rUSDG, are on the [USDG Yield Vault deployments](/usdg-vault/deployments) page.
| Component | Address | | - | - | | Vault | 0x014e6DA8F283C4aF65B2AA0f201438680A004452 | | DepositQueue (USDC) | 0xC75E7E73B25fEa8bB23EB55CC48BA55067b5be76 | | SyncDepositQueue (USDC) | 0xf6AFAf6afcAe116dD37A779D50fE6c5fa6f8C8f5 | | AsyncDepositQueue (USDe) | 0xeec37568b01e0c4d5028501a49e024b475e2d7ca | | RedeemQueue (USDC) | 0x9e36A74FE278906a76e7615263e46a83fC40c47F | | DepositQueue (USDT) | 0xEeC5041c47Cba1e31321AC6941Bf09Ad60645B73 | | SyncDepositQueue (USDT) | 0x534d0bEb82C47cf703BFb9E959297658b65Ec8E9 | | AsyncRedeemQueue (USDT) | 0x95092A7a86715246Be6395b8D514B3d60A270Cd3 | | Oracle | 0x827044735c9708a2cf850e7Ea37EBa43bc786028 | | ShareManager | 0x4Ce1ac8F43E0E5BD7A346A98aF777bF8fbeA1981 | | FeeManager | 0x72fa23f40e08eB9E45953233b2Dd9665E347e8Dc | | RiskManager | 0x7b1e06C46d4510277FC37a37bBeF65F3794fdDE4 | | Subvault 0 | 0x77B9441d5Cb89fca435190A9B6D108ad4B00ccFd | | Verifier 0 | 0xB65A8E0937c77a76C3f4F86A1110f81A299CB481 | | Timelock Controller | 0xdA6Da82DFF8cD29D828e4775Cc003f504A968845 | | OracleSubmitter | 0xB105DaEeFEb1390ce49172c99E3e12C607367156 |
| Parameter | Description | Unit | Default value |
|---|---|---|---|
| maxTokensPerVault | Maximum different tokens that a vault can manage | # | 10 |
| governanceDelay | The delay that has to pass for updating a certain class of params (delayed) | secs | 86400 |
| protocolTreasury | The treasury address for protocol fees | address | |
| forceAllowMask | If a bit in this mask is set, the permission is allowed for all addresses | bitmask (uint256) | 0 |
| withdrawLimit | The maximum withdrawal per block. The hardcoded minimum value is 200\_000 USD | USD | 200\_000 |
| unitPrices | Token price estimates, used for withdrawLimit. For new token can be set immediately, for updates a cool-down period of 14 days is used. | address (token) => units of token per 1 USD | USDC => 10 ^ 6 ETH => 10 ^ 18 / 3000 BTC => 10 ^ 8 / 45000 |
| Vault | Address |
|---|---|
| Gearbox Root Vault | 0xD3442BA55108d33FA1EB3F1a3C0876F892B01c44 |
| ERC20 Vault | 0x27E3E8E275523850236485FE2341e55689a81Bb1 |
| Gearbox Vault | 0x3e80E11C8fD3e05221fE63BE3487f9f0A4316Dc8 |
| chainId | block | user | amount | vault | protocol\_address |
|---|---|---|---|---|---|
| 1 | 1 | 0x01 | 100 | 0x0 | 0x0 |
| 1 | 1 | 0x02 | 200 | 0x0 | 0x0 |
| 1 | 1 | 0x03 | 50 | 0x0 | 0x0 |
| 1 | 3 | 0x03 | 20 | 0x0 | 0x0 |
| 1 | 4 | 0x01 | 150 | 0x0 | 0x0 |
| 1 | 5 | 0x02 | 0 | 0x0 | 0x0 |
**Decentralized Validator Vault** Incentives from Obol are updated on a weekly basis and incentives from SSV are updated on a monthly basis, while Mellow point updates will be reflected once an hour. Rewards from Obol and SSV for users are calculated based on ETH placed in the Vault, which is used for validators within the Lido protocol. As more DVT based validators are activated, the amount of incentives will increase. Incentives are claimable as SSV and Obol tokens. \ \ Current APR formula is (we consider a 3-day interval to provide a stable and sufficiently accurate spot APR calculation):\ `reward_rate := latest_report_reward_amount / report_range_in_seconds;` `reward_estimation := reward_rate * 3 days;` `reward_estimation_in_eth := reward_estimation * avg(reward_price_in_eth, 3 days);` `reward_apr := reward_estimation_in_eth / avg(vault_tvl_in_eth, 3 days) * 365 / 3 * 100%;` The vault APR is computed as: `vault_apr := reward_apr(SSV) + reward_apr(OBOL) + stETH_yield;`\ where `reward_rate_per_1_eth_per_second` is derived from the latest reward distribution. To dissuade possibly harmful effects to the Lido on the Ethereum protocol, cross-team analysis will be conducted on Vault participants, and certain potentially abusive actions may render the user completely or partially ineligible for consideration for points. In order to be eligible to potentially receive Obol and SSV incentives for the capital provided, Vault participants must: 1. Hold a position for a minimum of 3 days in the vault through the conclusion of the Snapshot period. 2. Not unstake existing stETH or wstETH that is then restaked via the vault from the moment of vault launch. The incentives are calculated on the basis of ETH staked to and persisting within the vault during the relevant snapshot period, minus any stETH withdrawn after the launch of the vault. 3. Do not sell existing stETH on DEXs/CEXs. This condition does not exclude stakers from all incentives, but reduces the corresponding amount of capital provided by the volume of sold ETH. Similar to the above, the incentives would be calculated on the base of non-swapped ETH staked to and persisting within the vault during the relevant snapshot period. ### **Loyalty Points logic for curators** Curators serve as the primary intermediary between the restaking middleware and passive restakers. Mellow plans to aid LRT curators to launch permissionless LRTs with deployment, maintenance, DeFi integrations and Loyalty Points Offering Loyalty Points to Mellow curators is strategic because it: • Makes curating vaults more profitable and therefore more attractive\ • Aligns risk curators with the success of Mellow\ • Encourages them to focus on providing the best product for users rather than direct revenue (thus encouraging lower fees)\ • Provides them with resources to participate in the future governance of Mellow LRTs
\\
\\
# Points in Symbiotic pre-deposit contracts Source: https://docs.mellow.finance/points/points-in-symbiotic-pre-deposit-contracts Legacy points methodology for deposits before and after Symbiotic limits were reached, including 1.5x Mellow boost, DeFi multipliers, and anti-gaming rules.
[^1]: **APY (Annual Percentage Yield)**\ \&#xNAN;*"The effective annual return that includes compounding of rewards. Unlike APR, it shows the actual growth of your deposit if earnings are reinvested."* # strETH deployment Source: https://docs.mellow.finance/strategy-vault/streth-deployment strETH contract addresses across Mainnet, Arbitrum, Plasma – vault, deposit/redeem queues, oracle, share/fee/risk managers, 8 subvaults with verifiers, swap modules, timelock controllers, admin roles