Folio Contract

Overview

The Folio contract is the heart of the Reserve Folio protocol. It’s a backed ERC20 token that allows permissionless minting and redemption while maintaining a flexible basket of underlying assets. The contract supports semi-permissioned rebalancing through a sophisticated auction mechanism.

Key Features

Flexible Basket: Supports multiple ERC20 tokens of any denomination
Permissionless Mint/Redeem: Anyone can mint or redeem shares proportionally
Dutch Auction Rebalancing: Uses exponential decay curves for efficient price discovery
Fee System: TVL fees and mint fees with DAO revenue sharing
Role-Based Access: Three main roles for governance and operations

Architecture

Folio implements:

ERC20Upgradeable (share token)
AccessControlEnumerableUpgradeable (role management)
ReentrancyGuardUpgradeable (security)

Roles

The Folio contract operates with three primary roles:

DEFAULT_ADMIN_ROLE

bytes32

Can set assets, fees, auction parameters, and deprecate the Folio

REBALANCE_MANAGER

bytes32

Can start/end rebalances and manage individual auctions (typically a timelock)

AUCTION_LAUNCHER

bytes32

Can open auctions and end rebalances/auctions (typically an EOA or multisig)

BRAND_MANAGER

bytes32

Optional role for off-chain use with no on-chain permissions

Minting and Redeeming

Mint

Mint new Folio shares by depositing the basket of tokens proportionally.

uint256

Amount of shares to mint (before fees)

receiver

address

Address to receive the minted shares

minSharesOut

uint256

Minimum shares to receive after fees (slippage protection)

Folio.sol

function mint(
    uint256 shares,
    address receiver,
    uint256 minSharesOut
) external returns (address[] memory _assets, uint256[] memory _amounts)

Minting incurs fees: (1) DAO fee shares, (2) fee recipient shares, (3) self-fee shares that are burned.

Redeem

Burn Folio shares to receive the underlying basket proportionally.

uint256

Amount of shares to burn

receiver

address

Address to receive the underlying tokens

assets

address[]

Array of asset addresses (must match basket)

minAmountsOut

uint256[]

Minimum amounts of each asset to receive

Folio.sol

function redeem(
    uint256 shares,
    address receiver,
    address[] calldata assets,
    uint256[] calldata minAmountsOut
) external returns (uint256[] memory _amounts)

Rebalancing

Start Rebalance

Initiate a new rebalancing operation with target basket weights and prices.

tokens

TokenRebalanceParams[]

Rebalance parameters for each token including weights and price ranges

limits

RebalanceLimits

Target basket unit (BU) limits: low, spot, and high

auctionLauncherWindow

uint256

Time (in seconds) that AUCTION_LAUNCHER has exclusive access

ttl

uint256

Total time-to-live for the entire rebalance

Folio.sol

function startRebalance(
    TokenRebalanceParams[] calldata tokens,
    RebalanceLimits calldata limits,
    uint256 auctionLauncherWindow,
    uint256 ttl
) external onlyRole(REBALANCE_MANAGER)

Open Auction (Restricted)

AUCTION_LAUNCHER opens an auction with specific parameters.

rebalanceNonce

uint256

Nonce of the target rebalance

tokens

address[]

Subset of rebalance tokens to include in this auction

newWeights

WeightRange[]

New basket weight ranges (can be progressively tightened)

newPrices

PriceRange[]

New price ranges (subject to PriceControl setting)

newLimits

RebalanceLimits

New BU limits (must be within existing range)

auctionLength

uint256

Desired auction length in seconds

Folio.sol

function openAuction(
    uint256 rebalanceNonce,
    address[] calldata tokens,
    WeightRange[] calldata newWeights,
    PriceRange[] calldata newPrices,
    RebalanceLimits calldata newLimits,
    uint256 auctionLength
) external onlyRole(AUCTION_LAUNCHER) returns (uint256 auctionId)

Bidding

Participate in an ongoing auction by swapping tokens.

auctionId

uint256

ID of the auction to bid on

sellToken

IERC20

Token being sold by the Folio

buyToken

IERC20

Token being bought by the Folio

sellAmount

uint256

Amount of sell token to receive

maxBuyAmount

uint256

Maximum amount of buy token willing to pay

withCallback

bool

If true, uses callback pattern (caller must implement IBidderCallee)

data

bytes

Arbitrary data passed to callback

Folio.sol

function bid(
    uint256 auctionId,
    IERC20 sellToken,
    IERC20 buyToken,
    uint256 sellAmount,
    uint256 maxBuyAmount,
    bool withCallback,
    bytes calldata data
) external returns (uint256 boughtAmt)

Bidding requires rebalance.bidsEnabled to be true. Check this before attempting to bid.

Fee Management

Set TVL Fee

Set the annual TVL fee (demurrage fee on AUM).

_newFee

uint256

New annual fee as D18 (e.g., 0.1e18 = 10%)

Folio.sol

function setTVLFee(uint256 _newFee) external onlyRole(DEFAULT_ADMIN_ROLE)

Set Mint Fee

Set the fee charged on minting operations.

_newFee

uint256

New mint fee as D18 (e.g., 0.01e18 = 1%)

Folio.sol

function setMintFee(uint256 _newFee) external onlyRole(DEFAULT_ADMIN_ROLE)

Distribute Fees

Distribute accumulated fees to DAO and fee recipients.

Folio.sol

function distributeFees() public

Fees accumulate as “pending shares” and are distributed proportionally based on the configured fee recipients and DAO split.

View Functions

Total Assets

Get all assets and amounts held by the Folio.

Folio.sol

function totalAssets() external view returns (
    address[] memory _assets,
    uint256[] memory _amounts
)

To Assets

Convert shares to underlying asset amounts.

uint256

Number of shares to convert

rounding

Math.Rounding

Rounding direction (Floor or Ceil)

Folio.sol

function toAssets(
    uint256 shares,
    Math.Rounding rounding
) external view returns (
    address[] memory _assets,
    uint256[] memory _amounts
)

Get Rebalance

Get current rebalance state.

Folio.sol

function getRebalance() external view returns (
    uint256 nonce,
    PriceControl priceControl,
    TokenRebalanceParams[] memory tokens,
    RebalanceLimits memory limits,
    RebalanceTimestamps memory timestamps,
    bool bidsEnabled_
)

Events

AuctionOpened

event

Emitted when a new auction is openedParameters:

rebalanceNonce - Rebalance nonce
auctionId - New auction ID
tokens - Tokens in auction
weights - Weight ranges
prices - Price ranges
limits - BU limits
startTime - Auction start timestamp
endTime - Auction end timestamp

AuctionBid

event

Emitted when a bid is placedParameters:

auctionId - Auction ID
sellToken - Token sold
buyToken - Token bought
sellAmount - Amount sold
buyAmount - Amount bought

RebalanceStarted

event

Emitted when rebalancing beginsParameters:

nonce - Rebalance nonce
priceControl - Price control setting
tokens - Token parameters
limits - BU limits
startedAt - Start timestamp
restrictedUntil - Restricted period end
availableUntil - Total expiration
bidsEnabled - Whether bids are enabled

FolioFeePaid

event

Emitted when fees are distributedParameters:

recipient - Fee recipient address
amount - Shares distributed

Constants

D18

uint256

default:"1e18"

18-decimal fixed point scaling factor

D27

uint256

default:"1e27"

27-decimal fixed point scaling factor (for high precision)

MAX_MINT_FEE

uint256

default:"0.05e18"

Maximum mint fee: 5%

MAX_TVL_FEE

uint256

default:"0.1e18"

Maximum annual TVL fee: 10%

AUCTION_WARMUP

uint256

default:"30"

Auction warmup period in seconds

Core Contracts

Governance

Staking

Registry & Fees

Utilities

Interfaces

Overview

Key Features

Architecture

Roles

Minting and Redeeming

Mint

Redeem

Rebalancing

Start Rebalance

Open Auction (Restricted)

Bidding

Fee Management

Set TVL Fee

Set Mint Fee

Distribute Fees

View Functions

Total Assets

To Assets

Get Rebalance

Events

Constants

Build docs developers (and LLMs) love

Core Contracts

Governance

Staking

Registry & Fees

Utilities

Interfaces

Documentation Index

​Overview

​Key Features

​Architecture

​Roles

​Minting and Redeeming

​Mint

​Redeem

​Rebalancing

​Start Rebalance

​Open Auction (Restricted)

​Bidding

​Fee Management

​Set TVL Fee

​Set Mint Fee

​Distribute Fees

​View Functions

​Total Assets

​To Assets

​Get Rebalance

​Events

​Constants

Build docs developers (and LLMs) love

Overview

Key Features

Architecture

Roles

Minting and Redeeming

Mint

Redeem

Rebalancing

Start Rebalance

Open Auction (Restricted)

Bidding

Fee Management

Set TVL Fee

Set Mint Fee

Distribute Fees

View Functions

Total Assets

To Assets

Get Rebalance

Events

Constants