Utility Libraries

Overview

Reserve Folio uses three primary utility libraries that implement core protocol logic. These libraries are used via delegatecall from Folio contracts to reduce deployment size and improve code reusability.

Library Overview

FolioLib: Fee calculations and governance operations
RebalancingLib: Auction mechanics and rebalancing logic
MathLib: Fixed-point math operations

FolioLib

Handles fee calculations and fee recipient management.

Set Fee Recipients

Configure the fee recipient table for a Folio.

FolioLib.sol

function setFeeRecipients(
    IFolio.FeeRecipient[] storage feeRecipients,
    IFolio.FeeRecipient[] calldata _feeRecipients
) external

Fee recipients must be provided in ascending address order with no duplicates. Portions must sum to exactly 1e18 (100%). An empty table results in all fees going to the DAO.

Compute Fee Shares

Calculate TVL fee shares owed to DAO and fee recipients.

FolioLib.sol

function computeFeeShares(
    FeeSharesParams calldata params,
    IFolioDAOFeeRegistry daoFeeRegistry
) external view returns (
    uint256 _daoPendingFeeShares,
    uint256 _feeRecipientsPendingFeeShares
)

Parameters:

currentDaoPending: Existing DAO pending shares
currentFeeRecipientsPending: Existing recipient pending shares
tvlFee: Per-second TVL fee rate (D18)
folioFeeForSelf: Fraction of recipient shares to burn (D18)
supply: Current total supply
elapsed: Time elapsed since last fee calculation

Set TVL Fee

Convert annual TVL fee to per-second rate.

FolioLib.sol

function setTVLFee(
    uint256 _newFeeAnnually
) external returns (uint256 _tvlFee)

Converts annual percentage to per-second using formula: 1 - (1 - feeAnnually)^(1/31536000). This ensures accurate compounding over time.

Compute Mint Fees

Calculate fee shares for minting operations.

FolioLib.sol

function computeMintFees(
    MintFeeParams calldata params,
    IFolioDAOFeeRegistry daoFeeRegistry
) external returns (
    uint256 sharesOut,
    uint256 daoFeeShares,
    uint256 feeRecipientFeeShares
)

Parameters:

shares: Total shares being minted (before fees)
mintFee: Mint fee percentage (D18)
folioFeeForSelf: Fraction of recipient fees to burn (D18)
minSharesOut: Minimum shares caller must receive

RebalancingLib

Implements auction mechanics and rebalancing operations.

Start Rebalance

Initiate a new rebalancing operation.

RebalancingLib.sol

function startRebalance(
    address[] calldata oldTokens,
    IFolio.RebalanceControl storage rebalanceControl,
    IFolio.Rebalance storage rebalance,
    IFolio.TokenRebalanceParams[] calldata tokens,
    IFolio.RebalanceLimits calldata limits,
    uint256 auctionLauncherWindow,
    uint256 ttl,
    bool bidsEnabled
) external

Validates all token parameters, weights, prices, and limits. Reverts if any are inconsistent or out of bounds.

Open Auction

Open a new auction within an ongoing rebalance.

RebalancingLib.sol

function openAuction(
    IFolio.Rebalance storage rebalance,
    mapping(uint256 auctionId => IFolio.Auction) storage auctions,
    uint256 auctionId,
    address[] memory tokens,
    IFolio.WeightRange[] memory weights,
    IFolio.PriceRange[] calldata prices,
    IFolio.RebalanceLimits calldata limits,
    uint256 auctionLength
) external

Auctions begin after a 30-second warmup period (AUCTION_WARMUP). Atomic swaps (constant price) start and end at the same timestamp.

Get Bid

Calculate bid parameters for a token pair at current timestamp.

RebalancingLib.sol

function getBid(
    IFolio.Rebalance storage rebalance,
    IFolio.Auction storage auction,
    IERC20 sellToken,
    IERC20 buyToken,
    GetBidParams memory params
) external view returns (
    uint256 sellAmount,
    uint256 bidAmount,
    uint256 price
)

Returns:

sellAmount: Amount of sell token to transfer (in sellTok)
bidAmount: Amount of buy token required (in buyTok)
price: Current Dutch auction price (D27 format)

Bid

Execute a bid in an ongoing auction.

RebalancingLib.sol

function bid(
    IFolio.Auction storage auction,
    uint256 auctionId,
    IERC20 sellToken,
    IERC20 buyToken,
    uint256 sellAmount,
    uint256 bidAmount,
    bool withCallback,
    bytes calldata data
) external returns (bool shouldRemoveFromBasket)

If withCallback is true, the caller must implement IBidderCallee.bidCallback(). Otherwise, the caller must have pre-approved the buy token.

Price Calculation

Internal function for Dutch auction pricing using exponential decay:

P(t) = P_0 * e^(-kt)

Where:

P_0: Starting price (sellPriceHigh / buyPriceLow)
P_t: Ending price (sellPriceLow / buyPriceHigh)
k: Decay constant = ln(P_0 / P_t) / auctionLength
t: Time elapsed since auction start

MathLib

Fixed-point mathematical operations using PRBMath.

Power

Raise a number to a fractional power.

MathLib.sol

function pow(uint256 x, uint256 y) external pure returns (uint256 z)

uint256

Base (D18 fixed point)

uint256

Exponent (D18 fixed point)

Used for compound interest calculations: (1 - fee)^time

Power (Unsigned)

Raise a number to an integer power.

MathLib.sol

function powu(uint256 x, uint256 y) external pure returns (uint256 z)

uint256

Base (D18 fixed point)

uint256

Exponent (whole number, not fixed point)

Natural Logarithm

Compute the natural logarithm of a number.

MathLib.sol

function ln(uint256 x) internal pure returns (uint256 z)

uint256

Input (D18 fixed point)

Used in Dutch auction price decay calculations.

Exponential

Compute e raised to a power.

MathLib.sol

function exp(int256 x) internal pure returns (uint256 z)

int256

Exponent (D18 fixed point, can be negative)

Used for exponential decay in auction pricing: P_0 * e^(-kt)

Constants

Key constants used across libraries:

Fixed Point Scaling

D18

uint256

default:"1e18"

18-decimal fixed point (standard for fees and ratios)

D27

uint256

default:"1e27"

27-decimal fixed point (high precision for weights and prices)

Fee Limits

MAX_TVL_FEE

uint256

default:"0.1e18"

Maximum annual TVL fee: 10%

MIN_MINT_FEE

uint256

default:"0.0003e18"

Minimum mint fee: 3 bps

MAX_FEE_RECIPIENTS

uint256

default:"10"

Maximum number of fee recipients

Rebalancing Limits

MAX_WEIGHT

uint256

default:"1e54"

Maximum token weight (D27 * 1e27)

MAX_LIMIT

uint256

default:"1e27"

Maximum BU limit per share

MAX_TOKEN_PRICE

uint256

default:"1e45"

Maximum token price (D27 * 1e18)

MAX_TOKEN_PRICE_RANGE

uint256

default:"1000"

Maximum ratio between high and low price

MAX_TOKEN_BUY_AMOUNT

uint256

default:"1e36"

Maximum single token purchase amount

Auction Settings

AUCTION_WARMUP

uint256

default:"30"

Warmup period before auction bidding opens (seconds)

MAX_TTL

uint256

default:"30 days"

Maximum rebalance time-to-live

Time Constants

ONE_OVER_YEAR

uint256

1/31536000 in D18 format (for annual to per-second conversion)

Usage in Contracts

Libraries are typically used with using directives:

contract Folio {
    using FolioLib for *;
    using RebalancingLib for *;
    using MathLib for *;
    
    // Library functions become available
    function setFees(...) external {
        tvlFee = FolioLib.setTVLFee(newFeeAnnually);
    }
}

Library functions that modify storage must be called with the correct storage pointers. Ensure you pass storage references, not memory copies.

Core Contracts

Governance

Staking

Registry & Fees

Utilities

Interfaces

Overview

Library Overview

FolioLib

Set Fee Recipients

Compute Fee Shares

Set TVL Fee

Compute Mint Fees

RebalancingLib

Start Rebalance

Open Auction

Get Bid

Bid

Price Calculation

MathLib

Power

Power (Unsigned)

Natural Logarithm

Exponential

Constants

Fixed Point Scaling

Fee Limits

Rebalancing Limits

Auction Settings

Time Constants

Usage in Contracts

Build docs developers (and LLMs) love

Core Contracts

Governance

Staking

Registry & Fees

Utilities

Interfaces

Documentation Index

​Overview

​Library Overview

​FolioLib

​Set Fee Recipients

​Compute Fee Shares

​Set TVL Fee

​Compute Mint Fees

​RebalancingLib

​Start Rebalance

​Open Auction

​Get Bid

​Bid

​Price Calculation

​MathLib

​Power

​Power (Unsigned)

​Natural Logarithm

​Exponential

​Constants

​Fixed Point Scaling

​Fee Limits

​Rebalancing Limits

​Auction Settings

​Time Constants

​Usage in Contracts

Build docs developers (and LLMs) love

Overview

Library Overview

FolioLib

Set Fee Recipients

Compute Fee Shares

Set TVL Fee

Compute Mint Fees

RebalancingLib

Start Rebalance

Open Auction

Get Bid

Bid

Price Calculation

MathLib

Power

Power (Unsigned)

Natural Logarithm

Exponential

Constants

Fixed Point Scaling

Fee Limits

Rebalancing Limits

Auction Settings

Time Constants

Usage in Contracts