How to Build a Vault — Commercial & Technical Guide

interface IERC4626 is IERC20, IERC20Metadata {
    // ── Core accounting ──────────────────────────────────────────
    function asset() external view returns (address);
    function totalAssets() external view returns (uint256);

    // ── Conversion (view only, no state changes) ─────────────────
    function convertToShares(uint256 assets) external view returns (uint256);
    function convertToAssets(uint256 shares) external view returns (uint256);

    // ── Deposit flow: assets in, shares out ──────────────────────
    function maxDeposit(address receiver) external view returns (uint256);
    function previewDeposit(uint256 assets) external view returns (uint256);
    function deposit(uint256 assets, address receiver) external returns (uint256 shares);

    // ── Mint flow: specify shares to receive, pay assets ─────────
    function maxMint(address receiver) external view returns (uint256);
    function previewMint(uint256 shares) external view returns (uint256 assets);
    function mint(uint256 shares, address receiver) external returns (uint256 assets);

    // ── Withdraw flow: specify assets out, burn calculated shares ─
    function maxWithdraw(address owner) external view returns (uint256);
    function previewWithdraw(uint256 assets) external view returns (uint256 shares);
    function withdraw(uint256 assets, address receiver, address owner)
        external returns (uint256 shares);

    // ── Redeem flow: specify shares in, receive calculated assets ─
    function maxRedeem(address owner) external view returns (uint256);
    function previewRedeem(uint256 shares) external view returns (uint256 assets);
    function redeem(uint256 shares, address receiver, address owner)
        external returns (uint256 assets);
}

// 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 {SafeERC20}  from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import {Ownable}    from "@openzeppelin/contracts/access/Ownable.sol";
import {Pausable}   from "@openzeppelin/contracts/utils/Pausable.sol";
import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";

contract SimpleVault is ERC4626, Ownable, Pausable, ReentrancyGuard {

    uint256 public deployedAssets; // capital held in strategy
    address public feeRecipient;

    constructor(
        IERC20 asset_,
        string memory name_,
        string memory symbol_,
        address feeRecipient_
    )
        ERC4626(asset_)
        ERC20(name_, symbol_)
        Ownable(msg.sender)
    {
        feeRecipient = feeRecipient_;
    }

    // ── Inflation attack protection ───────────────────────────────
    // Adds 1e6 virtual shares/assets to share price calculations.
    // An attacker needs 1,000,000x more capital to manipulate the
    // initial share price.
    function _decimalsOffset() internal pure override returns (uint8) {
        return 6;
    }

    // ── Core accounting ───────────────────────────────────────────
    // totalAssets = idle assets in vault + capital deployed to strategy
    function totalAssets() public view override returns (uint256) {
        return IERC20(asset()).balanceOf(address(this)) + deployedAssets;
    }

    // ── Deposit / redeem gates ────────────────────────────────────
    function deposit(uint256 assets, address receiver)
        public override nonReentrant whenNotPaused returns (uint256)
    {
        _accrueManagementFee();
        return super.deposit(assets, receiver);
    }

    function redeem(uint256 shares, address receiver, address owner)
        public override nonReentrant whenNotPaused returns (uint256)
    {
        _accrueManagementFee();
        return super.redeem(shares, receiver, owner);
    }

    // ── Admin ─────────────────────────────────────────────────────
    function pause()   external onlyOwner { _pause(); }
    function unpause() external onlyOwner { _unpause(); }

    function setFeeRecipient(address r) external onlyOwner {
        require(r != address(0));
        feeRecipient = r;
    }

    // ── Fee stub (see Fee Architecture section) ───────────────────
    function _accrueManagementFee() internal virtual {}
}

// Management fee: mint shares to fee recipient over time.
// 1% annual management fee on $10M AUM = ~$100K/year in fee shares.

uint256 public managementFeeBps = 100;        // 1.00% annual
uint256 public constant MAX_MGMT_FEE = 500;   // hard cap at 5%
uint256 public lastFeeTimestamp;

function _accrueManagementFee() internal override {
    if (managementFeeBps == 0 || feeRecipient == address(0)) return;

    uint256 elapsed = block.timestamp - lastFeeTimestamp;
    if (elapsed == 0) return;
    lastFeeTimestamp = block.timestamp;

    uint256 supply = totalSupply();
    if (supply == 0) return;

    // shares_to_mint = supply × fee_rate × elapsed / 1 year
    // Derived from: new_ratio = fee_rate × elapsed/year
    // new_supply = supply / (1 - ratio) ≈ supply × (1 + ratio)
    uint256 sharesToMint = (supply * managementFeeBps * elapsed)
        / (10_000 * 365 days);

    if (sharesToMint > 0) {
        _mint(feeRecipient, sharesToMint);
    }
}

function setManagementFee(uint256 feeBps) external onlyOwner {
    require(feeBps <= MAX_MGMT_FEE, "Exceeds cap");
    _accrueManagementFee(); // settle existing fee before changing rate
    managementFeeBps = feeBps;
}

// Performance fee with high-water mark.
// 20% of profits above HWM on $10M AUM earning 8% gross = $160K/year.

uint256 public performanceFeeBps = 2000;        // 20%
uint256 public highWaterMarkPerShare;            // assets per 1e18 shares
uint256 public constant MAX_PERF_FEE = 3000;    // hard cap at 30%

// Call this after yield is harvested / totalAssets() increases.
function _accruePerformanceFee() internal {
    if (performanceFeeBps == 0 || totalSupply() == 0) return;

    // Price = assets per 1e18 shares (using 1e18 as fixed-point unit)
    uint256 currentPrice = convertToAssets(1e18);

    if (currentPrice <= highWaterMarkPerShare) return; // no new profit

    uint256 gainPerShare  = currentPrice - highWaterMarkPerShare;
    uint256 feePerShare   = (gainPerShare * performanceFeeBps) / 10_000;

    // Total fee in assets = feePerShare × totalSupply / 1e18
    uint256 totalFeeAssets = (feePerShare * totalSupply()) / 1e18;

    // Move HWM up by the net gain (after fee)
    highWaterMarkPerShare = currentPrice - feePerShare;

    // Convert fee to shares at current price and mint to recipient
    uint256 feeShares = convertToShares(totalFeeAssets);
    if (feeShares > 0) {
        _mint(feeRecipient, feeShares);
        emit PerformanceFeeMinted(feeShares, totalFeeAssets);
    }
}

event PerformanceFeeMinted(uint256 shares, uint256 assets);

import {IPool}   from "@aave/core-v3/contracts/interfaces/IPool.sol";
import {IAToken} from "@aave/core-v3/contracts/interfaces/IAToken.sol";

contract AaveVault is SimpleVault {

    IPool  public immutable aavePool;
    IAToken public immutable aToken; // e.g. aUSDC

    constructor(
        IERC20 asset_,
        IPool  pool_,
        IAToken aToken_,
        address feeRecipient_
    )
        SimpleVault(asset_, "Aave USDC Vault", "avUSDC", feeRecipient_)
    {
        aavePool = pool_;
        aToken   = aToken_;
        // Approve Aave pool once — use SafeERC20 to handle non-standard tokens
        SafeERC20.forceApprove(IERC20(asset()), address(aavePool), type(uint256).max);
    }

    // ── Accounting ────────────────────────────────────────────────
    function totalAssets() public view override returns (uint256) {
        return IERC20(asset()).balanceOf(address(this))  // idle
             + aToken.balanceOf(address(this));           // deployed to Aave
    }

    // ── Harvest: deposit idle capital into Aave ───────────────────
    function harvest() external onlyOwner {
        _accrueManagementFee();
        _accruePerformanceFee(); // charges fee on new Aave yield
        uint256 idle = IERC20(asset()).balanceOf(address(this));
        if (idle > 0) {
            aavePool.supply(asset(), idle, address(this), 0);
        }
    }

    // ── Withdraw path: pull from Aave if vault is short ──────────
    function _withdraw(
        address caller,
        address receiver,
        address owner,
        uint256 assets,
        uint256 shares
    ) internal override {
        uint256 idle = IERC20(asset()).balanceOf(address(this));
        if (idle < assets) {
            // Withdraw exact shortfall from Aave; Aave may revert if illiquid
            aavePool.withdraw(asset(), assets - idle, address(this));
        }
        super._withdraw(caller, receiver, owner, assets, shares);
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {Test}     from "forge-std/Test.sol";
import {MockERC20} from "./mocks/MockERC20.sol";
import {SimpleVault} from "../src/SimpleVault.sol";

contract VaultTest is Test {
    MockERC20   asset;
    SimpleVault vault;
    address     alice = makeAddr("alice");
    address     bob   = makeAddr("bob");
    address      fees = makeAddr("fees");

    function setUp() public {
        asset = new MockERC20("USD Coin", "USDC", 6);
        vault = new SimpleVault(asset, "Test Vault", "tvUSDC", fees);

        asset.mint(alice, 10_000e6);
        asset.mint(bob,   10_000e6);
        vm.prank(alice); asset.approve(address(vault), type(uint256).max);
        vm.prank(bob);   asset.approve(address(vault), type(uint256).max);
    }

    function test_depositMintsSharesToReceiver() public {
        vm.prank(alice);
        uint256 shares = vault.deposit(1_000e6, alice);
        assertGt(shares, 0, "No shares minted");
        assertEq(vault.balanceOf(alice), shares);
    }

    function test_redeemBurnsSharesAndReturnsAssets() public {
        vm.prank(alice); vault.deposit(1_000e6, alice);
        uint256 shares = vault.balanceOf(alice);
        vm.prank(alice);
        uint256 assets = vault.redeem(shares, alice, alice);
        assertApproxEqRel(assets, 1_000e6, 1e14); // within 0.01%
        assertEq(vault.balanceOf(alice), 0);
    }

    function test_sharePriceRisesWithYield() public {
        vm.prank(alice); vault.deposit(1_000e6, alice);
        uint256 priceBefore = vault.convertToAssets(1e6); // 1 share in assets

        // Simulate yield: donate 100 USDC directly to vault
        asset.mint(address(vault), 100e6);

        uint256 priceAfter = vault.convertToAssets(1e6);
        assertGt(priceAfter, priceBefore, "Share price didn't rise");
    }

    // Fuzz: deposit any amount and immediately redeem — should get >= assets back
    function testFuzz_depositRedeem(uint256 assets) public {
        assets = bound(assets, 1, 1_000_000e6);
        asset.mint(alice, assets);
        vm.startPrank(alice);
        asset.approve(address(vault), assets);
        uint256 shares = vault.deposit(assets, alice);
        uint256 out    = vault.redeem(shares, alice, alice);
        vm.stopPrank();
        // After fees, output may be slightly less — but check no free money
        assertLe(out, assets + 1, "Got more than deposited");
    }
}

// Invariant tests: forge runs hundreds of random sequences of calls
// and checks these properties hold after every sequence.

import {StdInvariant} from "forge-std/StdInvariant.sol";
import {VaultHandler}  from "./handlers/VaultHandler.sol";

contract VaultInvariantTest is StdInvariant, Test {
    SimpleVault  vault;
    VaultHandler handler;

    function setUp() public {
        // ... setup vault ...
        handler = new VaultHandler(vault, asset);
        targetContract(address(handler));
    }

    // 1. Share price never falls (unless fees were charged)
    function invariant_sharePriceMonotone() public view {
        if (vault.totalSupply() == 0) return;
        assertGe(
            vault.convertToAssets(1e6),
            handler.lowestSharePrice(),
            "Share price fell unexpectedly"
        );
    }

    // 2. Total assets >= user-redeemable assets (vault is solvent)
    function invariant_vaultSolvent() public view {
        assertGe(
            vault.totalAssets(),
            vault.convertToAssets(vault.totalSupply()),
            "Vault insolvent"
        );
    }

    // 3. maxWithdraw is always achievable
    function invariant_maxWithdrawRespected() public {
        address user = handler.lastDepositor();
        uint256 max  = vault.maxWithdraw(user);
        if (max == 0 || vault.balanceOf(user) == 0) return;
        vm.prank(user);
        vault.withdraw(max, user, user); // must not revert
    }
}

// Foundry deployment script with proxy + timelock
import {Script}   from "forge-std/Script.sol";
import {ERC1967Proxy}         from "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";
import {TimelockController}   from "@openzeppelin/contracts/governance/TimelockController.sol";

contract DeployVault is Script {
    function run() external {
        address multisig    = vm.envAddress("MULTISIG");
        address feeRecipient = vm.envAddress("FEE_RECIPIENT");
        address asset       = vm.envAddress("USDC");

        vm.startBroadcast();

        // 1. Deploy implementation
        AaveVault impl = new AaveVault(
            IERC20(asset), IPool(AAVE_POOL), IAToken(A_USDC), feeRecipient
        );

        // 2. Deploy proxy pointing to implementation
        bytes memory initData = abi.encodeCall(impl.initialize, (multisig));
        ERC1967Proxy proxy = new ERC1967Proxy(address(impl), initData);

        // 3. Deploy timelock: 48h delay, multisig as proposer + executor
        address[] memory proposers = new address[](1);
        address[] memory executors = new address[](1);
        proposers[0] = multisig;
        executors[0] = multisig;
        TimelockController timelock = new TimelockController(
            48 hours, proposers, executors, address(0)
        );

        // 4. Transfer vault ownership to timelock
        AaveVault(address(proxy)).transferOwnership(address(timelock));

        vm.stopBroadcast();
    }
}