feat(finance): implement ERC-4626 tokenized vault standard

[jose-compu]

Why this matters

ERC-4626 (Tokenized Vaults) is the most widely deployed yield-bearing primitive in DeFi after ERC-20 itself. It reached Final in 2022 and is now the integration surface for lending markets, yield aggregators, structured products, and RWA vaults across every major chain.

Traction signals:

• 760+ vault deployments cross-chain
• Billions in TVL (Yearn, Aave, Maker, Morpho, Pendle, and most DeFi stacks)
• Required reading for any protocol integrating deposit/withdraw flows against external vaults

OpenZeppelin ships a solid ERC4626 implementation — which is exactly why it sits in Tier 1 of our research. But this repo exists to give developers a single, Foundry-native, audited library with consistent patterns across standards. Today our finance/ module only covers ERC-3156 (flash loans). Vault semantics — share/asset conversion, preview functions, rounding direction, inflation-attack mitigations — are absent, forcing consumers to mix OZ imports with Curated ERC contracts.

Adding ERC-4626 here is not about reinventing the wheel. It is about:

1. Completeness — vaults are core DeFi infrastructure, not an optional extension
2. Consistency — same NatSpec style, custom errors, fuzz coverage, and ERC-7201 upgradeable storage as every other standard in this repo
3. Foundation for extensions — ERC-7540 (async vaults) and ERC-7575 (multi-asset vaults) both extend 4626; see feat(finance): implement ERC-7540 and ERC-7575 async/multi-asset vaults #25. Implementing the base in-repo avoids split dependencies and mismatched rounding/conversion semantics
4. RWA pipeline — async and regulated vault flows (7540, 7943-adjacent use cases) assume a canonical 4626 base developers can extend without leaving the library

Spec: https://github.com/ethereum/ERCs/blob/master/ERCS/erc-4626.md
Discussions: https://ethereum-magicians.org/t/eip-4626-yield-bearing-vault-standard/7900
Requires: ERC-20, ERC-2612 (permit optional but recommended)

Scope

Per the per-ERC workflow:

Interfaces (src/finance/ERC4626/)

• IERC4626.sol — full vault interface (asset, totalAssets, convertToShares/convertToAssets, maxDeposit/maxMint/maxWithdraw/maxRedeem, preview functions, deposit/mint/withdraw/redeem, events)

Non-upgradeable implementation

• ERC4626.sol — abstract ERC-20 + ERC-4626 base
  • Virtual offset / decimal offset for inflation-attack mitigation (follow OZ semantics, document in NatSpec)
  • Internal hooks: _deposit, _withdraw for subclasses to override fee/yield logic
  • Rounding: deposit/mint round down shares; withdraw/redeem round up shares (per spec)

Upgradeable implementation

• ERC4626Upgradeable.sol — Initializable + ERC-7201 namespaced storage

Tests (test/finance/ERC4626.t.sol)

• Unit tests: deposit, mint, withdraw, redeem (happy paths + zero amounts)
• Conversion/preview parity: preview* matches executed amounts within rounding bounds
• Fuzz: arbitrary deposit/withdraw sequences preserve share/asset invariants
• Edge cases: first depositor, empty vault, max uint bounds, non-standard decimals
• Upgradeable init + storage layout isolation test

Documentation

• Full NatSpec on all public/external functions and events
• Inline notes on rounding direction and virtual-share mitigation

Implementation notes

• Do not copy OZ verbatim — use the OZ implementation as a semantic reference, write from scratch for licensing cleanliness (same approach as other standards here)
• Abstract base — like ERC3156FlashLender, expose hooks rather than a monolithic deployable vault; ship a minimal concrete mock in tests only
• Permit (ERC-2612) — optional extension on the share token; document whether the base includes it or leaves it to subclasses
• Fee-on-transfer / rebasing assets — document unsupported; revert or guard explicitly rather than silently mis-account
• Security focus areas: first-depositor inflation, rounding favoring the vault, reentrancy on deposit/withdraw, preview vs execution drift

Relationship to other issues

• Blocks / unblocks feat(finance): implement ERC-7540 and ERC-7575 async/multi-asset vaults #25 — ERC-7540 and ERC-7575 should extend our in-repo ERC4626, not an external OZ import
• Complements ERC-3156 (flash loans) in src/finance/ as the two core DeFi liquidity primitives

Acceptance criteria

• IERC4626, ERC4626, and ERC4626Upgradeable implemented under src/finance/ERC4626/
• forge test passes with unit + fuzz coverage of conversion invariants and rounding
• forge fmt --check clean
• ROADMAP.md updated (add ERC-4626 to implemented/planned section)
• Internal security review completed (inflation attack, rounding, reentrancy)