erc4626-patterns

# ERC-4626 Tokenized Vault Patterns ## Core Interface ERC-4626 standardizes yield-bearing vaults. Users deposit assets and receive shares: ```solidity interface IERC4626 is IERC20 { function asset() external view returns (address); function totalAssets() external view returns (uint256); // Deposit flow: user specifies assets function deposit(uint256 assets, address receiver) external returns (uint256 shares); function mint(uint256 shares, address receiver) external returns (uint256 assets); // Withdraw flow: user specifies assets or shares function withdraw(uint256 assets, address receiver, address owner) external returns (uint256 shares); function redeem(uint256 shares, address receiver, address owner) external returns (uint256 assets); // Preview functions (simulate without executing) function previewDeposit(uint256 assets) external view returns (uint256 shares); function previewMint(uint256 shares) external view returns (uint256 assets); function previewWithdraw(uint256 assets) external view returns (uint256 shares); function previewRedeem(uint256 shares) external view returns (uint256 assets); // Limits function maxDeposit(address receiver) external view returns (uint256); function maxMint(address receiver) external view returns (uint256); function maxWithdraw(address owner) external view returns (uint256); function maxRedeem(address owner) external view returns (uint256); function convertToShares(uint256 assets) external view returns (uint256); function convertToAssets(uint256 shares) external view returns (uint256); } ``` ## Secure Implementation with Virtual Shares ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.20; import {ERC4626} from "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol"; import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol"; import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol"; import {Math} from "@openzeppelin/contracts/utils/Math.sol"; import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol"; contract SecureVault is ERC4626 { using SafeERC20 for IERC20; constructor(IERC20 asset_) ERC4626(asset_) ERC20("Vault Shares", "vASSET") {} /// @dev OpenZeppelin ERC4626 already uses virtual shares/assets /// (decimalsOffset = 0 by default, but _decimalsOffset() can be overridden). /// Override to add +3 offset for first-depositor attack mitigation: function _decimalsOffset() internal pure override returns (uint8) { return 3; } } ``` ## Share Math and Rounding Rules The fundamental equation: `shares * totalAssets == assets * totalSupply` ``` shares = assets * totalSupply / totalAssets (deposit, round DOWN → favor vault) assets = shares * totalAssets / totalSupply (redeem, round DOWN → favor vault) ``` **Rounding convention** (always favor the vault to prevent rounding exploits): | Operation | User sends | User receives | Round | |-----------|-----------|---------------|-------| | deposit | assets | shares | DOWN (fewer shares) | | mint | assets | shares | UP (more assets) | | withdraw | shares | assets | UP (more shares burned) | | redeem | shares | assets | DOWN (fewer assets) | ```solidity // OpenZeppelin handles rounding internally: function _convertToShares(uint256 assets, Math.Rounding rounding) internal view virtual returns (uint256) { return assets.mulDiv(totalSupply() + 10 ** _decimalsOffset(), totalAssets() + 1, rounding); } ``` ## First Depositor Attack Mitigation The attack: first depositor mints 1 share, then donates large amount of assets directly to the vault. Subsequent depositors get 0 shares due to rounding. **Solution 1: Virtual shares/assets (recommended)** OpenZeppelin adds virtual offset to prevent manipulation: ```solidity function _decimalsOffset() internal pure override returns (uint8) { return 3; // 1000 virtual shares — cost of attack becomes prohibitive } ``` **Solution 2: Dead shares on first deposit** ```solidity function _afterDeposit(uint256 assets, uint256 shares) internal virtual { if (totalSupply() == shares) { // First deposit: burn minimum shares to address(1) uint256 deadShares = 10 ** decimals() / 1000; _mint(address(1), deadShares); } } ``` ## Yield Strategy Integration ```solidity contract YieldVault is ERC4626 { ILendingPool public immutable lendingPool; constructor(IERC20 asset_, ILendingPool pool_) ERC4626(asset_) ERC20("Yield Vault", "yASSET") { lendingPool = pool_; asset_.approve(address(pool_), type(uint256).max); } function totalAssets() public view override returns (uint256) { return lendingPool.balanceOf(address(this)); } function _deposit(address caller, address receiver, uint256 assets, uint256 shares) internal override { super._deposit(caller, receiver, assets, shares); IERC20(asset()).safeTransfer(address(lendingPool), assets); lendingPool.deposit(assets); } function _withdraw( address caller, address receiver, address owner, uint256 assets, uint256 shares ) internal override { lendingPool.withdraw(assets); super._withdraw(caller, receiver, owner, assets, shares); } } ``` ## Max Functions and Access Control ```solidity // Pausable vault example function maxDeposit(address) public view override returns (uint256) { return paused() ? 0 : type(uint256).max; } function maxMint(address) public view override returns (uint256) { return paused() ? 0 : type(uint256).max; } // Deposit caps uint256 public depositCap; function maxDeposit(address) public view override returns (uint256) { uint256 remaining = depositCap > totalAssets() ? depositCap - totalAssets() : 0; return paused() ? 0 : remaining; } ``` ## Testing ERC-4626 ```solidity function test_depositAndRedeem_roundTrip() public { uint256 assets = 1e18; deal(address(token), alice, assets); vm.startPrank(alice); token.approve(address(vault), assets); uint256 shares = vault.deposit(assets, alice); assertEq(vault.balanceOf(alice), shares); assertEq(vault.convertToAssets(shares), assets); uint256 redeemed = vault.redeem(shares, alice, alice); assertEq(redeemed, assets); vm.stopPrank(); } function test_previewMatchesActual() public { uint256 assets = 1e18; uint256 previewShares = vault.previewDeposit(assets); deal(address(token), alice, assets); vm.startPrank(alice); token.approve(address(vault), assets); uint256 actualShares = vault.deposit(assets, alice); vm.stopPrank(); assertEq(actualShares, previewShares, "Preview must match actual"); } ``` ## Security Checklist - [ ] Use virtual shares (`_decimalsOffset >= 3`) to prevent first depositor attack - [ ] Rounding always favors the vault (never the user) - [ ] Preview functions are accurate (match actual operations) - [ ] `totalAssets` cannot be manipulated via direct token transfers - [ ] Max functions return 0 when vault is paused or at capacity - [ ] Handle fee-on-transfer tokens if supported - [ ] Reentrancy guards on deposit/withdraw (especially with external protocol calls) - [ ] Test with zero deposits, dust amounts, and very large amounts