DepositVault

Inherits: IDepositVault, AccessControl, ReentrancyGuard, Constants

Author: luoyhang003

This contract manages deposits of underlying assets in exchange for vault tokens.

It mints vault tokens to whitelisted users based on the asset’s oracle price and applies fees and caps. Supports deposit/mint functions, preview simulations, and admin control over assets.

State Variables

VAULT_ADMIN_ROLE

Role allowed to set new AssetsRouter

Only addresses with this role can call setAssetsRouter

Calculated as keccak256("VAULT_ADMIN_ROLE").

bytes32 public constant VAULT_ADMIN_ROLE = keccak256("VAULT_ADMIN_ROLE");

VAULT_OPERATOR_ROLE

Role allowed to manage underlying assets

Only addresses with this role can call addUnderlyingAsset and removeUnderlyingAsset

Calculated as keccak256("VAULT_OPERATOR_ROLE").

bytes32 public constant VAULT_OPERATOR_ROLE = keccak256("VAULT_OPERATOR_ROLE");

vaultToken

ERC20 vault token.

Minted when users deposit assets or mint shares.

Token public immutable vaultToken;

accessRegistry

Access registry for fetching whitelist and blacklist.

IAccessRegistry public accessRegistry;

oracleRegistry

Oracle registry for fetching asset and vault token prices.

IOracleRegistry public oracleRegistry;

paramRegistry

Parameter registry for fee rates, deposit caps, etc.

IParamRegistry public paramRegistry;

assetsRouter

Router to forward deposited assets into underlying strategies.

IAssetsRouter public assetsRouter;

underlyingAssets

List of all supported underlying assets.

address[] public underlyingAssets;

isUnderlyingAsset

Mapping of supported assets.

mapping(address => bool) public isUnderlyingAsset;

tokenDecimals

Cached decimals for supported tokens.

mapping(address => uint8) public tokenDecimals;

tokenDeposited

Tracks deposited amount per underlying asset (net of fees).

mapping(address => uint256) public tokenDeposited;

Functions

constructor

Deploys the DepositVault contract.

Ensures addresses are valid and assets have valid oracles/decimals. Grants infinite approval of assets to the router.

constructor(
    address _defaultAdmin,
    address _adminRole,
    address _operatorRole,
    address _vaultToken,
    address _accessRegistry,
    address _oracleRegistry,
    address _paramRegistry,
    address _assetsRouter,
    address[] memory _underlyingAssets
);

Parameters

Name	Type	Description
`_defaultAdmin`	`address`	Address to receive the DEFAULT_ADMIN_ROLE.
`_adminRole`	`address`	Address granted the VAULT_ADMIN_ROLE.
`_operatorRole`	`address`	Address granted the VAULT_OPERATOR_ROLE.
`_vaultToken`	`address`	Address of the vault token contract.
`_accessRegistry`	`address`	Address of the access registry contract.
`_oracleRegistry`	`address`	Address of the oracle registry contract.
`_paramRegistry`	`address`	Address of the parameter registry contract.
`_assetsRouter`	`address`	Address of the assets router contract.
`_underlyingAssets`	`address[]`	Initial list of supported assets.

deposit

Deposit an underlying asset and receive vault shares.

Equivalent to depositFor with msg.sender as receiver.

function deposit(address _asset, uint256 _amount) external returns (uint256 shares_);

Parameters

Name	Type	Description
`_asset`	`address`	Address of the asset to deposit.
`_amount`	`uint256`	Amount of asset to deposit.

Returns

Name	Type	Description
`shares_`	`uint256`	Number of shares minted.

depositFor

Deposit an underlying asset on behalf of another account.

Reverts if receiver is zero address.

function depositFor(address _asset, uint256 _amount, address _receiver) external returns (uint256 shares_);

Parameters

Name	Type	Description
`_asset`	`address`	Address of the asset to deposit.
`_amount`	`uint256`	Amount of asset to deposit.
`_receiver`	`address`	Recipient of the minted shares.

Returns

Name	Type	Description
`shares_`	`uint256`	Number of shares minted.

mint

Mint a specific number of shares by depositing assets.

Equivalent to mintFor with msg.sender as receiver.

function mint(address _asset, uint256 _shares) external returns (uint256 assets_);

Parameters

Name	Type	Description
`_asset`	`address`	Address of the asset to deposit.
`_shares`	`uint256`	Number of shares to mint.

Returns

Name	Type	Description
`assets_`	`uint256`	Amount of assets required.

mintFor

Mint a specific number of shares on behalf of another account.

Reverts if receiver is zero address.

function mintFor(address _asset, uint256 _shares, address _receiver) external returns (uint256 assets_);

Parameters

Name	Type	Description
`_asset`	`address`	Address of the asset to deposit.
`_shares`	`uint256`	Number of shares to mint.
`_receiver`	`address`	Recipient of the minted shares.

Returns

Name	Type	Description
`assets_`	`uint256`	Amount of assets required.

exchangePrice

Returns the cutoff vault token price (e.g. for settlement).

Fetches the cutoff price directly from the oracle registry.

function exchangePrice() external view returns (uint256 price_);

Returns

Name	Type	Description
`price_`	`uint256`	Current vault token cutoff price.

convertToShares

Converts underlying assets to equivalent vault shares.

Normalizes _amount to 18 decimals before conversion. Uses floor rounding to avoid overestimating shares.

function convertToShares(address _asset, uint256 _amount)
    public
    view
    returns (uint256 shares_, uint256 underlyingPrice_, uint256 vaultTokenPrice_);

Parameters

Name	Type	Description
`_asset`	`address`	Address of the underlying asset.
`_amount`	`uint256`	Amount of underlying asset.

Returns

Name	Type	Description
`shares_`	`uint256`	Equivalent vault shares.
`underlyingPrice_`	`uint256`	Price of the underlying asset.
`vaultTokenPrice_`	`uint256`	Price of the vault token.

convertToAssets

Converts vault shares to equivalent underlying assets.

Denormalizes values back from 18 decimals to asset decimals. Uses floor rounding to avoid overestimating asset returns.

function convertToAssets(address _asset, uint256 _shares)
    public
    view
    returns (uint256 assets_, uint256 underlyingPrice_, uint256 vaultTokenPrice_);

Parameters

Name	Type	Description
`_asset`	`address`	Address of the underlying asset.
`_shares`	`uint256`	Number of vault shares.

Returns

Name	Type	Description
`assets_`	`uint256`	Equivalent underlying asset amount.
`underlyingPrice_`	`uint256`	Price of the underlying asset.
`vaultTokenPrice_`	`uint256`	Price of the vault token.

previewDeposit

Previews deposit outcome including shares, fee, and prices.

Simulates deposit logic without state changes. Performs fee deduction, cap checks, and price fetches.

function previewDeposit(address _asset, uint256 _amount)
    public
    view
    returns (uint256 shares_, uint256 fee_, uint256 underlyingPrice_, uint256 vaultTokenPrice_);

Parameters

Name	Type	Description
`_asset`	`address`	Address of the underlying asset.
`_amount`	`uint256`	Deposit amount.

Returns

Name	Type	Description
`shares_`	`uint256`	Number of shares minted.
`fee_`	`uint256`	Fee charged on deposit.
`underlyingPrice_`	`uint256`	Price of the underlying asset.
`vaultTokenPrice_`	`uint256`	Price of the vault token.

previewMint

Previews mint outcome including assets, fee, and prices.

Simulates mint logic without state changes. Performs fee addition, cap checks, and price fetches.

function previewMint(address _asset, uint256 _shares)
    public
    view
    returns (uint256 assets_, uint256 fee_, uint256 underlyingPrice_, uint256 vaultTokenPrice_);

Parameters

Name	Type	Description
`_asset`	`address`	Address of the underlying asset.
`_shares`	`uint256`	Number of shares to mint.

Returns

Name	Type	Description
`assets_`	`uint256`	Required underlying assets.
`fee_`	`uint256`	Fee charged on mint.
`underlyingPrice_`	`uint256`	Price of the underlying asset.
`vaultTokenPrice_`	`uint256`	Price of the vault token.

getUnderlyings

Returns list of all supported underlying assets.

Returns storage array directly; use cautiously in gas-sensitive contexts.

function getUnderlyings() external view returns (address[] memory underlyings);

Returns

Name	Type	Description
`underlyings`	`address[]`	Array of supported assets.

addUnderlyingAsset

Adds a new underlying asset to the vault.

Only callable by operator role. Requires valid oracle and decimals <= 18. Grants infinite approval to router.

function addUnderlyingAsset(address _asset) external onlyRole(VAULT_OPERATOR_ROLE);

Parameters

Name	Type	Description
`_asset`	`address`	Address of the asset to add.

removeUnderlyingAsset

Removes an underlying asset from the vault.

Only callable by operator role. Resets approval to zero and updates storage.

function removeUnderlyingAsset(address _asset) external onlyRole(VAULT_OPERATOR_ROLE);

Parameters

Name	Type	Description
`_asset`	`address`	Address of the asset to remove.

forceRouteAssets

Forcefully routes a specified amount of an asset through the assets router.

This function can only be called by an account with the {VAULT_OPERATOR_ROLE}. It is typically used in exceptional or administrative cases where assets must be manually routed to the designated destination, bypassing standard user-driven flows. Reverts if the asset address is zero or the amount is zero.

function forceRouteAssets(address _asset, uint256 _amount) external onlyRole(VAULT_OPERATOR_ROLE);

Parameters

Name	Type	Description
`_asset`	`address`	The address of the underlying asset to be routed.
`_amount`	`uint256`	The amount of the underlying asset to be routed.

setAssetsRouter

Updates the asset router contract.

Only callable by admin role. Revokes approvals for old router and re-approves new one.

function setAssetsRouter(address _assetsRouter) external onlyRole(VAULT_ADMIN_ROLE);

Parameters

Name	Type	Description
`_assetsRouter`	`address`	New router address.

_depositFor

Internal deposit logic used by deposit and depositFor.

Applies fee, checks caps, transfers funds, and mints shares.

function _depositFor(address _asset, uint256 _amount, address _receiver)
    internal
    nonReentrant
    returns (uint256 shares_);

Parameters

Name	Type	Description
`_asset`	`address`	Address of asset to deposit.
`_amount`	`uint256`	Deposit amount.
`_receiver`	`address`	Recipient of vault shares.

Returns

Name	Type	Description
`shares_`	`uint256`	Number of shares minted.

_mintFor

Internal mint logic used by mint and mintFor.

Applies fee, checks caps, transfers funds, and mints shares.

function _mintFor(address _asset, uint256 _shares, address _receiver) internal nonReentrant returns (uint256 assets_);

Parameters

Name	Type	Description
`_asset`	`address`	Address of asset to deposit.
`_shares`	`uint256`	Number of shares to mint.
`_receiver`	`address`	Recipient of vault shares.

Returns

Name	Type	Description
`assets_`	`uint256`	Amount of assets transferred.

_normalize

Normalizes token amounts to base decimals (18).

Expands or compresses numbers depending on asset decimals.

function _normalize(uint256 _amount, uint256 _decimals) internal pure returns (uint256 normalized_);

Parameters

Name	Type	Description
`_amount`	`uint256`	Token amount in original decimals.
`_decimals`	`uint256`	Decimals of the token.

Returns

Name	Type	Description
`normalized_`	`uint256`	Amount scaled to 18 decimals.

_denormalize

Denormalizes token amounts from base decimals (18) to asset decimals.

Reverses normalization logic.

function _denormalize(uint256 _amount, uint256 _decimals) internal pure returns (uint256 denormalized_);

Parameters

Name	Type	Description
`_amount`	`uint256`	Amount in 18 decimals.
`_decimals`	`uint256`	Decimals of the asset.

Returns

Name	Type	Description
`denormalized_`	`uint256`	Amount scaled back to asset decimals.