library-patterns

# Library Patterns ## Internal vs External Libraries | Feature | Internal (embedded) | External (deployed) | |---------|-------------------|-------------------| | Deployment | Inlined into calling contract | Deployed separately, linked | | Call type | JUMP (cheap) | DELEGATECALL (expensive) | | State access | Reads caller's storage | Reads caller's storage via delegatecall | | Gas cost | Lower per call | Higher per call, lower deploy if shared | | Use case | Small utilities, math | Large shared code across many contracts | ```solidity // Internal library — inlined at compile time library SafeCast { error SafeCast_Overflow(); function toUint128(uint256 value) internal pure returns (uint128) { if (value > type(uint128).max) revert SafeCast_Overflow(); return uint128(value); } function toUint96(uint256 value) internal pure returns (uint96) { if (value > type(uint96).max) revert SafeCast_Overflow(); return uint96(value); } function toInt256(uint256 value) internal pure returns (int256) { if (value > uint256(type(int256).max)) revert SafeCast_Overflow(); return int256(value); } } ``` ## Using-For Directives Attach library functions to types for cleaner syntax. ```solidity using SafeCast for uint256; using FixedPointMathLib for uint256; function calculateShares(uint256 assets, uint256 totalAssets, uint256 totalShares) internal pure returns (uint256) { return assets.mulDivDown(totalShares, totalAssets); } function packTimestamp(uint256 timestamp) internal pure returns (uint48) { return timestamp.toUint48(); } ``` ### Global Using-For (Solidity 0.8.13+) ```solidity // In a shared file, apply globally to all files that import it using SafeCast for uint256 global; using FixedPointMathLib for uint256 global; ``` ## Math Libraries ### Solmate FixedPointMathLib The gold standard for fixed-point math. Gas-optimized with assembly. ```solidity import {FixedPointMathLib} from "solmate/utils/FixedPointMathLib.sol"; using FixedPointMathLib for uint256; // Multiply then divide, rounding down — prevents phantom overflow uint256 shares = assets.mulDivDown(totalShares, totalAssets); // Multiply then divide, rounding up — useful for debt calculations uint256 debt = borrowed.mulDivUp(interestRate, PRECISION); // WAD math (18 decimal fixed point) uint256 result = a.mulWadDown(b); // (a * b) / 1e18, round down uint256 result = a.divWadUp(b); // (a * 1e18) / b, round up // Square root uint256 sqrtPrice = FixedPointMathLib.sqrt(price); ``` ### When to Round Up vs Down | Context | Direction | Reason | |---------|-----------|--------| | Minting shares from assets | Round down | Fewer shares protects vault | | Burning shares for assets | Round down | Fewer assets protects vault | | Calculating debt owed | Round up | More debt protects lender | | Calculating collateral required | Round up | More collateral protects protocol | | Fee calculation | Round up | Ensures protocol collects at least the fee | ## Struct Libraries Encapsulate operations on custom types in libraries. ```solidity struct Position { uint128 collateral; uint128 debt; uint48 lastUpdate; uint16 healthFactor; } library PositionLib { using SafeCast for uint256; using FixedPointMathLib for uint256; error Position_Undercollateralized(); function addCollateral(Position storage self, uint256 amount) internal { self.collateral += amount.toUint128(); self.lastUpdate = uint48(block.timestamp); } function addDebt(Position storage self, uint256 amount) internal { self.debt += amount.toUint128(); self.lastUpdate = uint48(block.timestamp); } function healthFactor(Position storage self, uint256 price) internal view returns (uint256) { if (self.debt == 0) return type(uint256).max; return uint256(self.collateral).mulDivDown(price, uint256(self.debt)); } function isHealthy(Position storage self, uint256 price, uint256 minHealth) internal view returns (bool) { return healthFactor(self, price) >= minHealth; } } ``` Usage: ```solidity using PositionLib for Position; mapping(address => Position) public positions; function addCollateral(uint256 amount) external { positions[msg.sender].addCollateral(amount); // ... } ``` ## Enumerable Set / Map Libraries For onchain iteration requirements, use OpenZeppelin's EnumerableSet. ```solidity import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol"; using EnumerableSet for EnumerableSet.AddressSet; EnumerableSet.AddressSet private _whitelistedTokens; function addToken(address token) external onlyOwner { if (!_whitelistedTokens.add(token)) revert AlreadyWhitelisted(); } function isWhitelisted(address token) external view returns (bool) { return _whitelistedTokens.contains(token); } function getWhitelistedTokens() external view returns (address[] memory) { return _whitelistedTokens.values(); } ``` ## Library Design Guidelines 1. **Pure/view functions only** — libraries should not have side effects beyond the storage pointer passed to them 2. **Single responsibility** — one library per type or domain 3. **Internal functions preferred** — avoids DELEGATECALL overhead 4. **Revert on invalid input** — don't return sentinel values 5. **Custom errors over require strings** — consistent with protocol patterns 6. **Gas-test critical paths** — math libraries are hot paths, benchmark them ## Library Design Checklist - [ ] Library has a single, focused responsibility - [ ] All functions are `internal` unless deployment sharing is needed - [ ] `using-for` applied to relevant types - [ ] Math operations use audited libraries (Solmate, OpenZeppelin) - [ ] Rounding direction explicitly chosen and documented - [ ] Safe casting used for all type narrowing - [ ] Custom errors defined within the library - [ ] NatSpec on all public-facing functions