Technical details

Rebalance lifecycle

In order to rebalance a DTF, the REBALANCE_MANAGER must first start a rebalance. This will set the new basket, per-token limit ranges, and price ranges. The REBALANCE_MANAGER will also set the restricted window during which only the AUCTION_LAUNCHER can open auctions, and the total time-to-live for the rebalance.

Once a rebalance auction is opened by the AUCTION_LAUNCHER, every surplus token in the auction will be sold down to its target basket ratio, and every deficit token will be bought up to its target basket ratio. An auction can include every surplus and deficit token in the basket, or a subset of them. Bidders can bid on any surplus:deficit pair in the auction until they reach their respective target ratios.

1. Rebalance Initiation: The REBALANCE_MANAGER starts a new rebalance, specifying new basket tokens, target ratios (limits), and price ranges for each asset.

2. Auction Launcher Window: For a restricted period, only the AUCTION_LAUNCHER can open auctions, with the ability to fine-tune parameters within governance-set bounds. The AUCTION_LAUNCHER can:

   • select a sell limit within the approved sell limit range

   • select a buy limit within the approved buy limit range

   • raise starting price by up to 100x

   • raise ending price arbitrarily (can cause auction not to clear, same end result as closing auction)

3. Permissionless Auctions: After the restricted window, anyone can open auctions using the pre-approved parameters.

4. Bidding: Anyone can bid in open auctions, exchanging tokens at a price determined by an exponential decay curve. Every successful bid will move the DTF closer to the target basket ratio.

5. Auction Close: Auctions end when their time elapses or their limits are reached. The rebalance technically ends when the rebalance period expires.

Key concepts and structs

• BasketRange: { spot, low, high } — Target, minimum, and maximum ratios of a token to DTF (Folio) shares (D27 precision).

• Prices: { low, high } — Price range for each asset (D27 precision).

• RebalanceDetails: { inRebalance, limits, prices } — Per-token rebalance state.

• Auction: { rebalanceNonce, sellToken, buyToken, sellLimit, buyLimit, startPrice, endPrice, startTime, endTime } — State of a single auction.

Auction pricing

For each token supplied to the rebalance, the REBALANCE_MANAGER provides a low and high price estimate. These should be set such that in the vast majority (99.9%+) of scenarios, the asset's price on secondary markets lies within the provided range. The maximum allowable price range for a token is 1e2: high / low must be <= 1e2.

If the price of an asset rises above its high price, this can result in a loss of value for Folio holders due to the auction price curve on a token pair starting at too-low-a-price.

When an auction is started, the low and high prices for both assets are used to calculate a startPrice and endPrice for the auction.

There are 2 ways to price assets, depending on the risk tolerance of the REBALANCE_MANAGER:

1. Priced

• The REBALANCE_MANAGER provides a list of NONZERO prices for each token. No token price can be 0.

• The AUCTION_LAUNCHER can always choose to raise the starting price up to 100x from the natural starting price, or raise the ending price arbitrarily (up to the starting price). They cannot lower either price.

1. Unpriced

• The REBALANCE_MANAGER provides ALL 0 prices for each token. This allows the AUCTION_LAUNCHER to set prices freely and prevents auctions from being opened permissionlessly.

Overall the price range for any dutch auction (startPrice / endPrice) must be less than 1e6 to prevent precision issues.

Price curve

Note: The first block may not have a price of exactly startPrice if it does not occur on the start timestamp. Similarly, the endPrice may not be exactly endPrice in the final block if it does not occur on the end timestamp.

All auctions use an exponential decay price curve from startPrice to endPrice over the auction duration. The price at any time t is:

P(t) = startPrice * exp(-k * t)

Where k is calculated so that P(auction.endTime) = endPrice.

Lot sizing

Auctions are sized by the difference between current balances and the basket ratios provided by the limits.

The auction sellAmount represents the single largest quantity of sell token that can be transacted without violating the limits of either tokens in the pair.

In general, it is possible for the sellAmount to either increase or decrease over time, depending on whether the surplus of the sell token or deficit of the buy token is the limiting factor.

1. If the surplus of the sell token is the limiting factor, the sellAmount will increase over time.

2. If the deficit of the buy token is the limiting factor, the sellAmount will decrease over time.

Auction participation

Anyone can bid in any auction up to and including the sellAmount size, as long as the price exchange rate is met.

/// @return sellAmount {sellTok} The amount of sell token on sale in the auction at a given timestamp/// @return bidAmount {buyTok} The amount of buy tokens required to bid for the full sell amount/// @return price D27{buyTok/sellTok} The price at the given timestamp as an 27-decimal fixed pointfunction getBid(   uint256 auctionId,   uint256 timestamp,   uint256 maxSellAmount) external view returns (uint256 sellAmount, uint256 bidAmount, uint256 price);