Truth Auction

Operational Lifecycle

For any child pool with a collateral shortfall, the truth auction can only begin after fork migration has closed. The migration window lasts SecurityPoolUtils.MIGRATION_TIME - 8 weeks from the parent universe fork time. Until that window ends, vault holders can still choose which child universe to support, so the protocol cannot know the final collateral shortfall.

After migration closes, anyone may call startTruthAuction. The forker then starts the underlying auction for the affected child pool, using the pool's ETH repair target and REP sale cap. Bidders submit ETH directly to the auction during the one-week bidding window.

When bidding ends, anyone may call finalizeTruthAuction. Finalization clears the batch auction, sends the raised ETH into the repair path, and computes the accounting rates used to settle bidders.

After finalization, winning bids are written into child-pool vault accounting. Winners receive ownership in the repaired child pool plus their proportional share of the auctioned security-bond allowance, rather than a direct REP token transfer.

The direct auction finalize path allows finalization at auctionStarted + AUCTION_TIME. The public finalizeTruthAuction wrapper is slightly stricter and requires the timestamp to be greater than truthAuctionStarted + SecurityPoolUtils.AUCTION_TIME.

How Clearing Works

Bidders submit ETH at discrete price ticks, where each tick encodes an ETH-per-REP limit price. The auction then walks demand from the highest price downward. A bid above the clearing tick wins in full, a bid below it loses in full, and bids at the clearing tick share the last fill. In the uniform-clearing branch that last fill is First in First Out within the tick, so earlier same-tick bids are consumed before later ones.

The tick math follows the contract's tickToPrice function. Tick 0 means 1 ETH/REP. Each step up multiplies price by roughly 1.0001, and each step down divides by the same factor, so the price at tick tickIndex is approximately 1.0001tickIndex ETH/REP. In other words, a higher tick means the bidder is willing to pay more ETH per REP, which is why higher ticks are evaluated first during clearing.

Two caps define the uniform-clearing stopping point. The first cap is ethRaiseCap, the amount of ETH the child pool is trying to restore. The second cap is maxRepBeingSold, the maximum child-universe REP inventory the pool is willing to sell. As soon as cumulative demand is enough to hit either cap at some price, that price becomes the clearing tick and all winning bids settle from it at one price. That is a valid uniform clearing even when the REP cap binds before the ETH repair target is fully met. The contract finds that result by descending aggregate subtree totals, not by looping over every bid one by one.

When demand never reaches a full clearing price, the auction switches into the underfunded branch. Finalization then walks demand from the highest tick downward, fixes the largest winning prefix whose synthetic execution price does not exceed the lowest winning tick's limit, stores that lowest winning tick as clearingTick, refunds lower ticks, and, when that winning prefix is non-empty, sells the full REP cap at underfundedThreshold. If no winning prefix exists, every bid refunds instead. Winners still settle at one synthetic uniform price; the difference is that the winner set is the finalized prefix boundary rather than a threshold-only price test.

The interactive example below is where those branches become concrete. The Binding condition output reports one of four outcomes: ETH cap, REP cap, both caps, or underfunded. The first three are uniform-clearing outcomes, while underfunded is the weak-demand path.

Under weak demand, the auction is designed to maximize retained ETH while still clearing the full REP cap. In the underfunded branch, the contract does not sell only the fraction of REP matched by submitted ETH. It finds the largest high-to-low winning prefix whose members can all accept one synthetic all-REP price, then clears the full REP cap against that prefix. This branch only applies while normal funded clearing still fails. If adding a lower positive bid would make the REP cap bind at that lower tick, the contract does not stay underfunded with a narrower winner set. It switches into the normal funded-clearing branch at that lower tick instead.

Worked Underfunded Examples

The examples below use the intended weak-demand rule: sell all REP to the largest feasible high-to-low winning prefix, then settle that prefix pro rata by winning ETH. In all three examples, maxRepBeingSold = 100 REP and ethRaiseCap = 1,000 ETH, so the ETH cap never binds and the auction stays underfunded only if cumulative demand remains below the REP cap at every active tick.

Boundary note: if a lower positive bid would make cumulative demand reach the REP cap at that lower tick, the auction no longer stays in the underfunded branch. It becomes a normal funded clearing at that tick, with the marginal lower-price tick filled only up to the REP cap. If that tick contributes more ETH than the cap accepts, the unfilled remainder is refunded.

Gas and Spam Bounds

The main spam risk is a bidder trying to fill bid slots or tick levels cheaply enough to block later demand. The auction avoids that failure mode by not capping total bids or active price levels at all.

Finalization remains bounded without those caps because it does not iterate over raw bids. Same-tick bids append to per-tick arrays for later batched withdrawal. Read helpers expose bounded offset/limit slices of bids at one tick or for one bidder, and settlement later uses selected TickIndex references from those reads to process bids in bounded batches. Clearing itself uses aggregate ETH totals stored in an AVL tree keyed by tick. The tree exists so the contract can keep all valid price levels open during bidding, yet still find the highest winning region by descending aggregate subtree totals instead of scanning every submitted bid. Finalization therefore pays for tree descent across the finite tick domain rather than for the total number of bids in the auction. The valid tick range is finite: [-524288, 524288], or 1,048,577 possible price levels. An AVL tree containing every possible tick has maximum height 28, so finalize() descends bounded tree paths and pruned subtrees instead of risking an out-of-gas loop over every submitted bid.

The gas tests cover both funded and underfunded finalization over a synthetic max-depth tree for the full tick domain. They assert each path remains below 20,000,000 gas and print measured gas values in the test output, so the documented worst case is a max-depth AVL-tree finalization path that still stays under that bound.

Settlement Modes

Currently losing bids can be refunded before finalization once current demand is enough to find a clearing tick. Only ticks below that found clearing tick can be withdrawn through the pre-finalization refund path; binding or potentially winning bids stay in the auction.

In the underfunded branch, finalization computes underfundedThreshold from the finalized underfundedWinningEth after the winning prefix is fixed. If underfundedWinningEth > 0, the stored clearingTick marks the lowest winning tick and underfunded withdrawals settle bids at ticks >= clearingTick. If no winning prefix exists, the contract leaves totalRepPurchased at zero, sets underfundedThreshold to type(uint256).max, and refunds every bid. The contract still records aggregate submitted ethRaised, but only underfundedWinningEth is retained after losing bids are refunded.

That settlement is why a winning bid buys more than a token transfer. The forker withdraws finalized bid results, converts purchased REP into pool ownership with auctionPoolOwnershipPerRep, and adds the matching slice of auctionedSecurityBondAllowance to the bidder's vault. In other words, the bidder is buying a share of the repaired child-pool vault state, including the debt-bearing allowance that still has to be backed.

Zero-effective-price ticks are rejected when bids are submitted, so underfunded settlement cannot assign REP to bids whose rounded ETH/REP price is zero.

Both finalized allocation paths carry division dust across paged withdrawals. Normal clearing carries clearingRemainder through the uniform-price ETH-to-REP division, and underfunded clearing uses that same remainder carry while dividing the full REP cap across winning ETH. Later withdrawals may receive remainder carried from earlier integer division so bid-level withdrawals reconcile to the aggregate finalized REP allocation.

Interactive Clearing Example

The slider example shows the uniform-clearing path, the underfunded path, and how the same bid ladder reacts when the ETH cap, REP cap, and bid sizes change.