Contract Interfaces

Key interfaces for interacting with Reserve Folio contracts

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

1. User calls folio.bid() with withCallback = true
2. Folio transfers sell tokens to bidder
3. Folio calls bidder.bidCallback()
4. Bidder must transfer buy tokens to Folio before callback returns
5. 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