Auction Participation

Overview

Folio auctions use a Dutch auction mechanism where prices move from optimistic to pessimistic over time. All token pairs trade simultaneously, and bidders can participate by:

Direct bidding - Swap tokens at the current auction price
Callback bidding - Execute custom logic before transferring tokens
Trusted fills - Use aggregators like CowSwap for complex routing

Auctions have a 30-second warmup period to ensure fair competition. This is skipped for atomic swaps where start price equals end price.

Understanding Auction Mechanics

Surplus and Deficit

Auctions only allow trading between:

Surplus tokens: Tokens above the high basket limit
Deficit tokens: Tokens below the low basket limit

// Example: Check if a pair is tradeable
(uint256 sellAmount, uint256 bidAmount, uint256 price) = folio.getBid(
    auctionId,
    IERC20(weth),  // Must be in surplus
    IERC20(usdc),  // Must be in deficit
    type(uint256).max
);

if (sellAmount == 0) {
    // No surplus/deficit for this pair
}

Price Discovery

Prices follow an exponential decay curve:

Start: Most optimistic prices (favorable to Folio)
End: Most pessimistic prices (favorable to bidders)
Current: Interpolated based on time elapsed

Direct Bidding

The simplest way to participate in auctions.

Query Available Bids

Find profitable opportunities:

// Get current bid for selling WETH to buy USDC
(uint256 sellAmount, uint256 bidAmount, uint256 price) = folio.getBid(
    auctionId,
    IERC20(weth),    // Sell token
    IERC20(usdc),    // Buy token
    10e18            // Max WETH you want to receive
);

// Price is in D27 format: {buyToken/sellToken}
// Example: price = 2300e27 means 1 WETH = 2300 USDC

Compare the auction price against external markets (Uniswap, etc.) to identify arbitrage opportunities.

Approve Tokens

The Folio needs allowance to pull buy tokens from you:

IERC20(usdc).approve(address(folio), bidAmount);

Execute Bid

Submit your bid:

uint256 actualBidAmount = folio.bid(
    auctionId,
    IERC20(weth),      // Sell token (you receive)
    IERC20(usdc),      // Buy token (you pay)
    sellAmount,        // Exact amount of WETH you want
    bidAmount,         // Max USDC you're willing to pay
    false,             // withCallback = false for direct bid
    ""                 // No callback data needed
);

// You now have 'sellAmount' of WETH
// Folio took 'actualBidAmount' of USDC from you

After the bid:

Your WETH balance increases by sellAmount
Your USDC balance decreases by actualBidAmount
actualBidAmount should be ≤ bidAmount (your max)

Arbitrage on External Markets

Immediately trade your received tokens for profit:

// Example: Sell WETH on Uniswap for more USDC
ISwapRouter(uniswapRouter).exactInputSingle(
    ISwapRouter.ExactInputSingleParams({
        tokenIn: address(weth),
        tokenOut: address(usdc),
        fee: 3000,
        recipient: msg.sender,
        deadline: block.timestamp,
        amountIn: sellAmount,
        amountOutMinimum: bidAmount + minProfit,
        sqrtPriceLimitX96: 0
    })
);

Callback Bidding

For advanced strategies, use callbacks to execute custom logic within the bid transaction.

Implement IBidderCallee Interface

Your contract must implement the callback interface:

import { IBidderCallee } from "@interfaces/IBidderCallee.sol";

contract MyArbitrageur is IBidderCallee {
    function bidderCallback(
        IERC20 sellToken,
        IERC20 buyToken,
        uint256 sellAmount,
        uint256 buyAmount,
        bytes calldata data
    ) external override {
        // 1. Receive sellToken from Folio
        // 2. Execute your strategy (e.g., swap on DEX)
        // 3. Transfer buyToken back to Folio

        // Example: Flash arbitrage
        // Sell received sellToken on Uniswap
        _swapOnUniswap(sellToken, buyToken, sellAmount);

        // Transfer buyAmount back to Folio
        buyToken.transfer(msg.sender, buyAmount);
    }
}

Call Bid with Callback

bytes memory strategyData = abi.encode(
    uniswapPoolAddress,
    minProfitThreshold
);

folio.bid(
    auctionId,
    IERC20(weth),
    IERC20(usdc),
    sellAmount,
    bidAmount,
    true,          // withCallback = true
    strategyData   // Passed to your callback
);

Callback Flow:

Folio transfers sellAmount of sell token to you
Folio calls bidderCallback() on your contract
Your callback executes and transfers buyAmount to Folio
Folio verifies it received the tokens

Security Considerations:

Always validate msg.sender is the Folio in your callback
Set slippage limits to protect against sandwich attacks
Ensure callback execution is atomic (reverts return everything)

Trusted Filler Integration

Trusted fillers enable async execution using specialized solvers like CowSwap.

Create Trusted Fill

Instead of bidding directly, create a trusted fill order:

IBaseTrustedFiller filler = folio.createTrustedFill(
    auctionId,
    IERC20(weth),        // Sell token
    IERC20(usdc),        // Buy token
    cowSwapFillerAddr,   // Target filler (e.g., CowSwapFiller)
    keccak256(abi.encode(msg.sender, block.timestamp)) // Unique salt
);

// Folio has approved the filler to spend sellToken
// Filler now has entire block to execute the swap

The Folio will automatically close and claim tokens from the trusted filler at the next state-changing call.

Execute Fill (Solver Side)

The trusted filler contract handles the actual swap:

// CowSwap example: Create order on CoW Protocol
GPv2Order.Data memory order = GPv2Order.Data({
    sellToken: weth,
    buyToken: usdc,
    sellAmount: sellAmount,
    buyAmount: buyAmount,
    // ... other CowSwap parameters
});

// Submit to CowSwap for async settlement
cowSettlement.settle(orders, ...);

Monitor Fill Status

Check if the async swap is still active:

(bool syncActive, bool asyncActive) = folio.stateChangeActive();

if (asyncActive) {
    // Trusted fill is still executing
    // Wait before performing state-dependent operations
}

Bidding Requirements

Permissionless Bids Enabled

If bidsEnabled is true for the rebalance, anyone can bid on auctions.

(, , , , , bool bidsEnabled) = folio.getRebalance();
require(bidsEnabled, "Permissionless bids disabled");

Deprecation Status

Bids cannot be placed on deprecated Folios:

require(!folio.isDeprecated(), "Folio deprecated");

Auction Timing

Bids are only valid during the auction’s active period:

After warmup period (30 seconds, or 0 for atomic swaps)
Before end time

// getBid() will revert if auction is not ongoing
(uint256 sellAmt, , ) = folio.getBid(...);
require(sellAmt > 0, "No surplus/deficit");

Token Pairs

You can only trade pairs where:

Sell token is in surplus (above high limit)
Buy token is in deficit (below low limit)

Not all tokens in an auction can be traded together at all times.

Advanced Strategies

Multi-Hop Arbitrage

Bid on multiple pairs in sequence:

// 1. Get WETH from Folio auction (pay USDC)
folio.bid(auctionId, IERC20(weth), IERC20(usdc), ...);

// 2. Trade WETH for DAI on Uniswap
uniswapRouter.swap(weth, dai, ...);

// 3. Get more USDC from Folio auction (pay DAI)
folio.bid(auctionId, IERC20(usdc), IERC20(dai), ...);

// Net: Started with X USDC, ended with X + profit USDC

Flash Loan Arbitrage

Use flash loans to amplify profits:

function executeFlashArbitrage() external {
    // 1. Flash borrow USDC from Aave
    aaveLendingPool.flashLoan(
        address(this),
        [address(usdc)],
        [borrowAmount],
        ...
    );
}

function executeOperation(
    address[] calldata assets,
    uint256[] calldata amounts,
    uint256[] calldata premiums,
    ...
) external override returns (bool) {
    // 2. Bid on Folio auction
    folio.bid(..., IERC20(weth), IERC20(usdc), ...);

    // 3. Sell WETH on external market
    _swapWETHForUSDC(...);

    // 4. Repay flash loan + premium
    IERC20(usdc).approve(address(aaveLendingPool), amounts[0] + premiums[0]);

    return true;
}

Monitoring Events

Listen to auction events for opportunities:

event AuctionOpened(
    uint256 indexed rebalanceNonce,
    uint256 indexed auctionId,
    address[] tokens,
    WeightRange[] weights,
    PriceRange[] prices,
    RebalanceLimits limits,
    uint256 startTime,
    uint256 endTime
);

event AuctionBid(
    uint256 indexed auctionId,
    address indexed sellToken,
    address indexed buyToken,
    uint256 sellAmount,
    uint256 buyAmount
);

Code Reference

Bid execution: contracts/Folio.sol:794-813
Get bid parameters: contracts/Folio.sol:776-783
Trusted fill creation: contracts/Folio.sol:816-847
Bid callback interface: contracts/interfaces/IBidderCallee.sol

Next Steps

Managing Rebalances

Learn how to start and configure rebalances

Minting & Redeeming

Understand how to mint and redeem Folio shares

Get Started

Core Concepts

Guides

Advanced

Development

Overview

Understanding Auction Mechanics

Surplus and Deficit

Price Discovery

Direct Bidding

Callback Bidding

Trusted Filler Integration

Bidding Requirements

Advanced Strategies

Multi-Hop Arbitrage

Flash Loan Arbitrage

Monitoring Events

Code Reference

Next Steps

Managing Rebalances

Minting & Redeeming

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

Development

Documentation Index

​Overview

​Understanding Auction Mechanics

​Surplus and Deficit

​Price Discovery

​Direct Bidding

​Callback Bidding

​Trusted Filler Integration

​Bidding Requirements

​Advanced Strategies

​Multi-Hop Arbitrage

​Flash Loan Arbitrage

​Monitoring Events

​Code Reference

​Next Steps

Managing Rebalances

Minting & Redeeming

Build docs developers (and LLMs) love

Overview

Understanding Auction Mechanics

Surplus and Deficit

Price Discovery

Direct Bidding

Callback Bidding

Trusted Filler Integration

Bidding Requirements

Advanced Strategies

Multi-Hop Arbitrage

Flash Loan Arbitrage

Monitoring Events

Code Reference

Next Steps