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

// 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.

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+)

// 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.

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);