> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/reserve-protocol/reserve-index-dtf/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

<Info>
  **ATOMIC\_SWAP** enables instant rebalancing at fixed prices without a Dutch auction curve.
</Info>

### Key Structs

#### FolioBasicDetails

Basic configuration for creating a Folio.

<ParamField path="name" type="string">
  Name of the Folio token
</ParamField>

<ParamField path="symbol" type="string">
  Symbol of the Folio token
</ParamField>

<ParamField path="assets" type="address[]">
  Initial basket token addresses
</ParamField>

<ParamField path="amounts" type="uint256[]">
  Initial deposit amounts for each token
</ParamField>

<ParamField path="initialShares" type="uint256">
  Number of shares to mint initially
</ParamField>

#### RebalanceLimits

Basket Unit (BU) limits for rebalancing operations.

<ParamField path="low" type="uint256">
  Lower BU limit - buy assets up to this level (D18 format)
</ParamField>

<ParamField path="spot" type="uint256">
  Point estimate for unrestricted callers (D18 format)
</ParamField>

<ParamField path="high" type="uint256">
  Upper BU limit - sell assets down to this level (D18 format)
</ParamField>

<Info>
  Must satisfy: `0 < low <= spot <= high <= MAX_LIMIT`
</Info>

#### WeightRange

Token weight range for basket definition.

<ParamField path="low" type="uint256">
  Minimum weight - buy up to this (D27 format: tok/BU)
</ParamField>

<ParamField path="spot" type="uint256">
  Point estimate weight (D27 format)
</ParamField>

<ParamField path="high" type="uint256">
  Maximum weight - sell down to this (D27 format)
</ParamField>

#### PriceRange

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

<ParamField path="low" type="uint256">
  Lower price bound (D27 format: UoA/tok)
</ParamField>

<ParamField path="high" type="uint256">
  Upper price bound (D27 format: UoA/tok)
</ParamField>

<Warning>
  Must satisfy: `0 < low < high <= MAX_TOKEN_PRICE` and `high <= MAX_TOKEN_PRICE_RANGE * low`
</Warning>

#### TokenRebalanceParams

Complete parameters for a token in rebalancing.

<ParamField path="token" type="address">
  Token address
</ParamField>

<ParamField path="weight" type="WeightRange">
  Weight range for this token
</ParamField>

<ParamField path="price" type="PriceRange">
  Price range for this token
</ParamField>

<ParamField path="maxAuctionSize" type="uint256">
  Maximum amount that can be traded in a single auction
</ParamField>

<ParamField path="inRebalance" type="bool">
  Whether this token is part of the rebalance
</ParamField>

#### FeeRecipient

Defines a fee recipient and their share.

<ParamField path="recipient" type="address">
  Address to receive fees
</ParamField>

<ParamField path="portion" type="uint96">
  Share of fees (D18 format, must sum to 1e18 across all recipients)
</ParamField>

```solidity theme={null}
struct FeeRecipient {
    address recipient;
    uint96 portion;  // D18{1}
}
```

<Info>
  Fee recipients must be sorted by address in ascending order with no duplicates.
</Info>

### Key Function

```solidity theme={null}
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.

```solidity theme={null}
interface IBidderCallee {
    function bidCallback(
        address buyToken,
        uint256 buyAmount,
        bytes calldata data
    ) external;
}
```

<ParamField path="buyToken" type="address">
  Token that needs to be transferred to the Folio
</ParamField>

<ParamField path="buyAmount" type="uint256">
  Amount of buy token to transfer
</ParamField>

<ParamField path="data" type="bytes">
  Arbitrary data passed from bid() call
</ParamField>

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

### 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

```solidity theme={null}
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

<ParamField path="votingDelay" type="uint48">
  Delay before voting starts (seconds)
</ParamField>

<ParamField path="votingPeriod" type="uint32">
  Duration of voting period (seconds)
</ParamField>

<ParamField path="proposalThreshold" type="uint256">
  Minimum voting power to create proposals (D18)
</ParamField>

<ParamField path="quorumThreshold" type="uint256">
  Minimum voting power for quorum (D18)
</ParamField>

<ParamField path="timelockDelay" type="uint256">
  Delay before executing approved proposals (seconds)
</ParamField>

<ParamField path="guardians" type="address[]">
  Addresses with proposal cancellation powers
</ParamField>

```solidity theme={null}
struct GovParams {
    uint48 votingDelay;
    uint32 votingPeriod;
    uint256 proposalThreshold;
    uint256 quorumThreshold;
    uint256 timelockDelay;
    address[] guardians;
}
```

## IFolioDAOFeeRegistry

Interface for querying DAO fee configuration.

```solidity theme={null}
function getFeeDetails(address fToken) external view returns (
    address recipient,
    uint256 feeNumerator,
    uint256 feeDenominator,
    uint256 feeFloor
);
```

<Info>
  Fee calculation: `daoFee = max(totalFee * feeNumerator / feeDenominator, feeFloor)`
</Info>

## IFolioVersionRegistry

Interface for version management.

```solidity theme={null}
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.

```solidity theme={null}
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.

```solidity theme={null}
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

```solidity theme={null}
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

```solidity theme={null}
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