yield-vault-patterns

# ERC-4626 Tokenized Vault Patterns ## Overview ERC-4626 standardizes yield-bearing vaults. Depositors receive shares proportional to their deposit. Shares appreciate as the vault earns yield. **Core Invariant**: `shares * totalAssets / totalShares = user's assets` ## Share Price Math ``` deposit: shares = assets * totalSupply / totalAssets (round DOWN) mint: assets = shares * totalAssets / totalSupply (round UP) withdraw: shares = assets * totalSupply / totalAssets (round UP) redeem: assets = shares * totalAssets / totalSupply (round DOWN) ``` **Rounding rule**: Always round in favor of the vault (against the user) to prevent value extraction. ## Complete ERC-4626 Implementation ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.20; import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol"; import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol"; import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol"; import {Math} from "@openzeppelin/contracts/utils/math/Math.sol"; import {IERC4626} from "@openzeppelin/contracts/interfaces/IERC4626.sol"; contract YieldVault is ERC20, IERC4626 { using SafeERC20 for IERC20; using Math for uint256; IERC20 public immutable asset_; uint8 private immutable _decimals; // Virtual shares/assets to prevent first depositor attack uint256 internal constant VIRTUAL_SHARES = 1e3; uint256 internal constant VIRTUAL_ASSETS = 1; constructor(IERC20 _asset, string memory name, string memory symbol) ERC20(name, symbol) { asset_ = _asset; _decimals = ERC20(address(_asset)).decimals(); } function asset() external view returns (address) { return address(asset_); } function decimals() public view override returns (uint8) { return _decimals; } function totalAssets() public view returns (uint256) { return asset_.balanceOf(address(this)); } function convertToShares(uint256 assets) public view returns (uint256) { return assets.mulDiv( totalSupply() + VIRTUAL_SHARES, totalAssets() + VIRTUAL_ASSETS, Math.Rounding.Floor ); } function convertToAssets(uint256 shares) public view returns (uint256) { return shares.mulDiv( totalAssets() + VIRTUAL_ASSETS, totalSupply() + VIRTUAL_SHARES, Math.Rounding.Floor ); } function maxDeposit(address) external pure returns (uint256) { return type(uint256).max; } function maxMint(address) external pure returns (uint256) { return type(uint256).max; } function maxWithdraw(address owner) external view returns (uint256) { return convertToAssets(balanceOf(owner)); } function maxRedeem(address owner) external view returns (uint256) { return balanceOf(owner); } function previewDeposit(uint256 assets) public view returns (uint256) { return convertToShares(assets); } function previewMint(uint256 shares) public view returns (uint256) { return shares.mulDiv( totalAssets() + VIRTUAL_ASSETS, totalSupply() + VIRTUAL_SHARES, Math.Rounding.Ceil // round UP against user ); } function previewWithdraw(uint256 assets) public view returns (uint256) { return assets.mulDiv( totalSupply() + VIRTUAL_SHARES, totalAssets() + VIRTUAL_ASSETS, Math.Rounding.Ceil // round UP against user ); } function previewRedeem(uint256 shares) public view returns (uint256) { return convertToAssets(shares); } function deposit(uint256 assets, address receiver) external returns (uint256 shares) { shares = previewDeposit(assets); require(shares > 0, "zero shares"); asset_.safeTransferFrom(msg.sender, address(this), assets); _mint(receiver, shares); emit Deposit(msg.sender, receiver, assets, shares); } function mint(uint256 shares, address receiver) external returns (uint256 assets) { assets = previewMint(shares); asset_.safeTransferFrom(msg.sender, address(this), assets); _mint(receiver, shares); emit Deposit(msg.sender, receiver, assets, shares); } function withdraw(uint256 assets, address receiver, address owner_) external returns (uint256 shares) { shares = previewWithdraw(assets); if (msg.sender != owner_) { _spendAllowance(owner_, msg.sender, shares); } _burn(owner_, shares); asset_.safeTransfer(receiver, assets); emit Withdraw(msg.sender, receiver, owner_, assets, shares); } function redeem(uint256 shares, address receiver, address owner_) external returns (uint256 assets) { assets = previewRedeem(shares); if (msg.sender != owner_) { _spendAllowance(owner_, msg.sender, shares); } _burn(owner_, shares); asset_.safeTransfer(receiver, assets); emit Withdraw(msg.sender, receiver, owner_, assets, shares); } } ``` ## First Depositor Attack Mitigation Without protection, an attacker can: 1. Deposit 1 wei to get 1 share 2. Donate a large amount directly to inflate `totalAssets` 3. Next depositor gets 0 shares due to rounding **Virtual shares/assets** solve this by ensuring the exchange rate always has a floor: ```solidity uint256 internal constant VIRTUAL_SHARES = 1e3; uint256 internal constant VIRTUAL_ASSETS = 1; // Share calculation uses (totalSupply + VIRTUAL_SHARES) / (totalAssets + VIRTUAL_ASSETS) // Cost of attack = VIRTUAL_SHARES * donation_amount / VIRTUAL_ASSETS ``` OpenZeppelin's ERC4626 uses `_decimalsOffset()` which is equivalent. ## Yield Strategy Integration ```solidity function totalAssets() public view override returns (uint256) { // Include assets deployed to yield strategies return asset_.balanceOf(address(this)) + _deployedAssets(); } function harvest() external { // Collect yield from strategy, increasing totalAssets // Share price automatically increases for all holders strategy.claim(); } ``` ## Checklist - [ ] Round DOWN for `deposit` and `redeem` (favors vault) - [ ] Round UP for `mint` and `withdraw` (favors vault) - [ ] Implement first depositor attack mitigation (virtual shares or minimum deposit) - [ ] `totalAssets()` includes all assets under management (not just balance) - [ ] `preview*` functions match actual execution (same rounding) - [ ] `max*` functions account for strategy liquidity limits - [ ] Handle ERC-20 tokens with non-standard decimals - [ ] Test share price manipulation via direct token transfers - [ ] Emit `Deposit` and `Withdraw` events per spec