Contract Interfaces

Overview

Reserve Folio defines several interfaces that enable contract interaction, custom integrations, and extensibility. Understanding these interfaces is crucial for building on the protocol.

IFolio

Core interface for Folio contracts.

Key Enums

PriceControl

Defines how much control AUCTION_LAUNCHER has over pricing.

enum PriceControl {
    NONE,          // Cannot change prices from initial
    PARTIAL,       // Can adjust within initial price bounds
    ATOMIC_SWAP    // PARTIAL + can set startPrice = endPrice
}

ATOMIC_SWAP enables instant rebalancing at fixed prices without a Dutch auction curve.

Key Structs

FolioBasicDetails

Basic configuration for creating a Folio.

name

string

Name of the Folio token

symbol

string

Symbol of the Folio token

assets

address[]

Initial basket token addresses

amounts

uint256[]

Initial deposit amounts for each token

initialShares

uint256

Number of shares to mint initially

RebalanceLimits

Basket Unit (BU) limits for rebalancing operations.

low

uint256

Lower BU limit - buy assets up to this level (D18 format)

spot

uint256

Point estimate for unrestricted callers (D18 format)

high

uint256

Upper BU limit - sell assets down to this level (D18 format)

Must satisfy: 0 < low <= spot <= high <= MAX_LIMIT

WeightRange

Token weight range for basket definition.

low

uint256

Minimum weight - buy up to this (D27 format: tok/BU)

spot

uint256

Point estimate weight (D27 format)

high

uint256

Maximum weight - sell down to this (D27 format)

PriceRange

Price range for a token in the Unit of Account (UoA).

low

uint256

Lower price bound (D27 format: UoA/tok)

high

uint256

Upper price bound (D27 format: UoA/tok)

Must satisfy: 0 < low < high <= MAX_TOKEN_PRICE and high <= MAX_TOKEN_PRICE_RANGE * low

TokenRebalanceParams

Complete parameters for a token in rebalancing.

token

address

Token address

weight

WeightRange

Weight range for this token

price

PriceRange

Price range for this token

maxAuctionSize

uint256

Maximum amount that can be traded in a single auction

inRebalance

bool

Whether this token is part of the rebalance

FeeRecipient

Defines a fee recipient and their share.

recipient

address

Address to receive fees

portion

uint96

Share of fees (D18 format, must sum to 1e18 across all recipients)

struct FeeRecipient {
    address recipient;
    uint96 portion;  // D18{1}
}

Fee recipients must be sorted by address in ascending order with no duplicates.

Key Function

function distributeFees() external;

Distribute accumulated fees to DAO and fee recipients. Called automatically before fee configuration changes.

IBidderCallee

Interface for contracts that want to participate in auctions using callbacks.

interface IBidderCallee {
    function bidCallback(
        address buyToken,
        uint256 buyAmount,
        bytes calldata data
    ) external;
}

buyToken

address

Token that needs to be transferred to the Folio

buyAmount

uint256

Amount of buy token to transfer

data

bytes

Arbitrary data passed from bid() call

Callback Pattern: Allows bidders to receive sell tokens before paying, useful for flash loan integrations or atomic arbitrage.

Callback Flow

User calls folio.bid() with withCallback = true
Folio transfers sell tokens to bidder
Folio calls bidder.bidCallback()
Bidder must transfer buy tokens to Folio before callback returns
Folio verifies payment and completes bid

contract MyBidder is IBidderCallee {
    function bidCallback(
        address buyToken,
        uint256 buyAmount,
        bytes calldata data
    ) external override {
        // Folio has already sent us sell tokens
        // Now we must send buy tokens back
        
        // Decode data if needed
        // Execute arbitrage, flash loan, etc.
        
        // Transfer required amount
        IERC20(buyToken).transfer(msg.sender, buyAmount);
    }
}

IGovernanceDeployer

Interface for deploying governance systems.

GovParams Struct

votingDelay

uint48

Delay before voting starts (seconds)

votingPeriod

uint32

Duration of voting period (seconds)

proposalThreshold

uint256

Minimum voting power to create proposals (D18)

quorumThreshold

uint256

Minimum voting power for quorum (D18)

timelockDelay

uint256

Delay before executing approved proposals (seconds)

guardians

address[]

Addresses with proposal cancellation powers

struct GovParams {
    uint48 votingDelay;
    uint32 votingPeriod;
    uint256 proposalThreshold;
    uint256 quorumThreshold;
    uint256 timelockDelay;
    address[] guardians;
}

IFolioDAOFeeRegistry

Interface for querying DAO fee configuration.

function getFeeDetails(address fToken) external view returns (
    address recipient,
    uint256 feeNumerator,
    uint256 feeDenominator,
    uint256 feeFloor
);

Fee calculation: daoFee = max(totalFee * feeNumerator / feeDenominator, feeFloor)

IFolioVersionRegistry

Interface for version management.

function getLatestVersion() external view returns (
    bytes32 versionHash,
    string memory version,
    IFolioDeployer folioDeployer,
    bool deprecated
);

function getImplementationForVersion(
    bytes32 versionHash
) external view returns (address folio);

IFolioDeployer

Interface for Folio factory contracts.

interface IFolioDeployer {
    function folioImplementation() external view returns (address);
    
    function deployFolio(
        IFolio.FolioBasicDetails calldata basicDetails,
        IFolio.FolioAdditionalDetails calldata additionalDetails,
        IFolio.FolioRegistryIndex calldata registryIndex,
        IFolio.FolioFlags calldata flags,
        address[4] calldata roles,
        bytes32 salt
    ) external returns (address folio);
}

IRoleRegistry

Interface for protocol-wide role management.

interface IRoleRegistry {
    function isOwner(address account) external view returns (bool);
    function isOwnerOrEmergencyCouncil(address account) external view returns (bool);
}

Usage Examples

Implementing a Bidder with Callback

contract ArbitrageBidder is IBidderCallee {
    function executeBid(
        IFolio folio,
        uint256 auctionId,
        IERC20 sellToken,
        IERC20 buyToken,
        uint256 sellAmount,
        uint256 maxBuyAmount
    ) external {
        folio.bid(
            auctionId,
            sellToken,
            buyToken,
            sellAmount,
            maxBuyAmount,
            true,  // withCallback
            abi.encode(msg.sender)  // custom data
        );
    }
    
    function bidCallback(
        address buyToken,
        uint256 buyAmount,
        bytes calldata data
    ) external override {
        address originalCaller = abi.decode(data, (address));
        
        // We received sell tokens, now execute arbitrage
        // ...
        
        // Transfer buy tokens to Folio
        IERC20(buyToken).transfer(msg.sender, buyAmount);
    }
}

Checking Version Before Deployment

function deployIfVersionValid(
    IFolioVersionRegistry registry,
    IFolio.FolioBasicDetails memory details
) external returns (address folio) {
    (
        ,
        string memory version,
        IFolioDeployer deployer,
        bool deprecated
    ) = registry.getLatestVersion();
    
    require(!deprecated, "Latest version deprecated");
    
    // Deploy using latest version
    folio = deployer.deployFolio(/* ... */);
}

Interface Files

All interfaces are located in /contracts/interfaces/:

IFolio.sol - Core Folio interface
IBidderCallee.sol - Bidder callback interface
IGovernanceDeployer.sol - Governance deployment
IFolioDAOFeeRegistry.sol - DAO fee configuration
IFolioVersionRegistry.sol - Version management
IFolioDeployer.sol - Folio factory
IRoleRegistry.sol - Role management

Core Contracts

Governance

Staking

Registry & Fees

Utilities

Interfaces

Overview

IFolio

Key Enums

PriceControl

Key Structs

FolioBasicDetails

RebalanceLimits

WeightRange

PriceRange

TokenRebalanceParams

FeeRecipient

Key Function

IBidderCallee

Callback Flow

IGovernanceDeployer

GovParams Struct

IFolioDAOFeeRegistry

IFolioVersionRegistry

IFolioDeployer

IRoleRegistry

Usage Examples

Implementing a Bidder with Callback

Checking Version Before Deployment

Interface Files

Build docs developers (and LLMs) love

Core Contracts

Governance

Staking

Registry & Fees

Utilities

Interfaces

Documentation Index

​Overview

​IFolio

​Key Enums

​PriceControl

​Key Structs

​FolioBasicDetails

​RebalanceLimits

​WeightRange

​PriceRange

​TokenRebalanceParams

​FeeRecipient

​Key Function

​IBidderCallee

​Callback Flow

​IGovernanceDeployer

​GovParams Struct

​IFolioDAOFeeRegistry

​IFolioVersionRegistry

​IFolioDeployer

​IRoleRegistry

​Usage Examples

​Implementing a Bidder with Callback

​Checking Version Before Deployment

​Interface Files

Build docs developers (and LLMs) love

Overview

IFolio

Key Enums

PriceControl

Key Structs

FolioBasicDetails

RebalanceLimits

WeightRange

PriceRange

TokenRebalanceParams

FeeRecipient

Key Function

IBidderCallee

Callback Flow

IGovernanceDeployer

GovParams Struct

IFolioDAOFeeRegistry

IFolioVersionRegistry

IFolioDeployer

IRoleRegistry

Usage Examples

Implementing a Bidder with Callback

Checking Version Before Deployment

Interface Files