Folio Contract

Core ERC20 token with permissionless minting/redemption and semi-permissioned rebalancing

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.

shares · 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.

shares · 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.

shares · 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 opened

Parameters:

• 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 placed

Parameters:

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

RebalanceStarted · event

Emitted when rebalancing begins

Parameters:

• 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 distributed

Parameters:

• 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