Dutch Auction Mechanism

UNINITIALIZED → PENDING → WARMUP → OPEN → CLOSED

/// @param rebalanceNonce The nonce of the target rebalance
/// @param tokens Subset of tokens from the rebalance to include
/// @param newWeights D27{tok/BU} New basket weight ranges
/// @param newPrices D27{UoA/tok} New price ranges (must obey PriceControl)
/// @param newLimits D18{BU/share} New BU limits
/// @param auctionLength {s} Desired auction length
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)

/// Open auction on all tokens in rebalance with spot values and initial prices
function openAuctionUnrestricted(
    uint256 rebalanceNonce
) external returns (uint256 auctionId)

// For a token pair (sell/buy)
startPrice = (sellToken.low * buyToken.high) / 1e27  // Most optimistic
endPrice = (sellToken.high * buyToken.low) / 1e27    // Most pessimistic

// Price at time t decays exponentially
function priceAt(uint256 t) returns (uint256) {
    if (t <= startTime + WARMUP) return type(uint256).max; // No bidding
    if (t >= endTime) return endPrice;
    
    // Exponential decay between startPrice and endPrice
    uint256 progress = (t - startTime - WARMUP) / (endTime - startTime - WARMUP);
    return startPrice * (endPrice / startPrice) ** progress;
}

struct TokenRebalanceParams {
    address token;
    WeightRange weight;
    PriceRange price;
    uint256 maxAuctionSize; // {tok} Max amount to sell in any single auction
    bool inRebalance;
}

/// @param auctionId The auction ID
/// @param sellToken The token being sold by the Folio
/// @param buyToken The token being bought by the Folio
/// @param maxSellAmount {sellTok} Max amount bidder wants to buy
/// @return sellAmount {sellTok} Amount of sell token available
/// @return bidAmount {buyTok} Amount of buy token required
/// @return price D27{buyTok/sellTok} Current price
function getBid(
    uint256 auctionId,
    IERC20 sellToken,
    IERC20 buyToken,
    uint256 maxSellAmount
) external view returns (
    uint256 sellAmount, 
    uint256 bidAmount, 
    uint256 price
)

/// @param auctionId The auction ID
/// @param sellToken Token the bidder receives from Folio
/// @param buyToken Token the bidder provides to Folio
/// @param sellAmount {sellTok} Amount of sell token to buy
/// @param maxBuyAmount {buyTok} Maximum amount bidder will pay
/// @param withCallback If true, uses callback for token transfer
/// @param data Arbitrary data passed to callback
/// @return boughtAmt {buyTok} Actual amount paid
function bid(
    uint256 auctionId,
    IERC20 sellToken,
    IERC20 buyToken,
    uint256 sellAmount,
    uint256 maxBuyAmount,
    bool withCallback,
    bytes calldata data
) external returns (uint256 boughtAmt)

/// @param auctionId The auction ID
/// @param sellToken Token Folio is selling
/// @param buyToken Token Folio is buying
/// @param targetFiller Address of the trusted filler implementation
/// @param deploymentSalt Salt for deterministic deployment
function createTrustedFill(
    uint256 auctionId,
    IERC20 sellToken,
    IERC20 buyToken,
    address targetFiller,
    bytes32 deploymentSalt
) external returns (IBaseTrustedFiller filler)

/// Close an auction at any point in its lifecycle
/// Callable by: DEFAULT_ADMIN_ROLE, REBALANCE_MANAGER, or AUCTION_LAUNCHER
function closeAuction(uint256 auctionId) external

// Auction 1: Wide ranges for price discovery
openAuction(tokens, wideWeights, widePrices, wideLimits, 3600);
// ... wait for auction to complete or close it

// Auction 2: Narrower ranges based on results
openAuction(tokens, narrowWeights, narrowPrices, narrowLimits, 1800);
// ... repeat as needed

// Final auction: Tight ranges to complete rebalance
openAuction(tokens, finalWeights, finalPrices, finalLimits, 1800);