Truth Auction

Operational Lifecycle

Security assumptions: A02 viable operating costs, A11 practical migration, A03 independent bidders, A12 efficient REP conversion, A16 timely inclusion, A06 lifecycle executors, A20 bid-data availability, A25 safe immutable parameters, and A22 native-ETH recipient compatibility.

For any child pool with a collateral shortfall, the truth auction can only begin after fork migration has closed. The migration window lasts through forkActivationTime + SecurityPoolUtils.MIGRATION_TIME, inclusive. forkActivationTime is recorded when this parent pool enters PoolForked; it is pool-local and can be later than Zoltar's universe forkTime. See FORK-05 for the canonical timing invariant. 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. The child activates with legitimate migration collateral plus retained bid ETH, even when that total is below the original fork snapshot. Full repair is not guaranteed, and the remaining impairment is borne by the affected child's open-interest holders. This is the security model's EG02 full-repair exclusion. Finalization rejects caller contribution ETH, and forced ETH remains unaccounted surplus. On the underfunded path, qualifying bidders collectively receive maxRepBeingSold; when no bid qualifies, no REP is sold. Any unsold REP remains behind inherited ownership. A zero-migration full-cap sale is the special case where every auctionable REP is sold and the inherited denominator has no live child owner; see Zero-migration full-cap ownership.

After finalization, winning bids are written into child-pool vault accounting. Winners receive ownership in the 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

Security assumptions: A01 bidder incentives, A12 efficient REP conversion, and A13 REP liquidity.

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.

Underfunded Clearing

When demand never reaches a full clearing price, the auction switches into the underfunded branch. Finalization computes underfundedThreshold = ceil(ethRaiseCap · 1e18 / maxRepBeingSold), stores the lowest tick whose price reaches that qualification threshold as clearingTick. Only bids at or above the cap-implied qualification threshold are retained; lower ticks refund. Qualifying bidders collectively purchase maxRepBeingSold for underfundedWinningEth, so the common effective price is their retained ETH divided by the REP cap. That effective price can be lower than the qualification threshold; the threshold is not an execution-price floor. If no ETH qualifies, every bid refunds.

The child activates with the ETH actually routed during migration plus the ETH retained by the auction. It may remain undercollateralized, and open-interest holders are not guaranteed to be made whole. That shortfall is the intended consequence of insufficient demand: non-migrating security positions lose the auctioned economic value, while users of the affected child bear any remaining collateral impairment.

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.

The comparison table and examples apply the branch rule above at the binding level and its boundaries. After clearing, SecurityPoolForker.claimAuctionProceeds maps that purchased REP into the corresponding pool-ownership credit and auctioned allowance share for the child branch.

Worked Underfunded Examples

The examples below use maxRepBeingSold = 10 REP and ethRaiseCap = 20 ETH, so the formula above gives 2 ETH/REP. Figures use human-unit approximations; the contract floors per-bid allocations in atomic units.

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

Security assumption: A02 viable operating costs.

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

Security assumption: A22 native-ETH recipient compatibility.

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.

Refund delivery is independent from bid settlement. The auction first marks each selected bid and fixes its REP and allowance result, then attempts to push any positive ETH refund with an explicit gas: 30,000 call argument. Because the call transfers nonzero value, the EVM adds its 2,300-gas value-transfer stipend, giving recipient code an effective maximum of 32,300 gas. If the bidder rejects, reverts, or exhausts that bounded callback budget, settlement remains complete and the ETH is added to pendingEthRefunds. The bidder can later pull the complete balance with withdrawPendingEthRefund; that caller-initiated transfer is not subject to the push cap, and a rejected pull leaves the balance unchanged. The auction emits the balance clear before that callback, so a reentrant settlement's new deferred refund follows the clear in receipt order.

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. Any auction that purchases REP assigns the complete unmigrated allowance among its winners; a zero-REP auction assigns none. Allowance uses the same fixed cumulative retained-ETH ordering, so its integer remainder also has a deterministic recipient independent of claim order. Because REP and allowance use independent integer numerators, a winning dust bid whose REP share rounds to zero can still receive a positive allowance share; settlement credits that allowance without requiring positive REP in the same claim. Finalization rejects explicit repair contributions. 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.

Before a winner claims, its reserved auction allowance remains part of the child's fork balance sheet but is not assigned to a responsible vault. It therefore does not accrue fees, affect retention utilization, or secure newly minted complete sets. Claim settlement adds that allowance to the bidder vault and to feeEligibleSecurityBondAllowance atomically.

Zero-migration full-cap ownership. When no vault REP migrated into the child and the auction sells every auctionable REP, there is no live child owner behind the parent's inherited denominator. The forker therefore sets auctionPoolOwnershipPerRep to PRICE_PRECISION and sets the final denominator to repAvailable * PRICE_PRECISION. Each winner's ownership then round-trips through poolOwnershipToRep to its full purchased REP, and later direct REP deposits join the same live scale. When REP remains unsold behind an inherited denominator, the forker instead derives the ownership rate from that residual REP.

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 derive each bid's REP from its fixed cumulative winning-ETH position. The bid receives the difference between rounded cumulative REP after and before that position. The companion allowance allocation differences cumulative floors over the same position. This reconciles paged withdrawals to both aggregate allocations while making rounding independent of claim order.

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.