Settlement formula

This page is the precise version. If you only need the idea, read Selling first.

The formula#

settlement price = min( oracle average , realized TWAP )

settled value    = quantity × settlement price
fee              = settled value × nights × fee per night
balance          = max( 0 , settled value − fee − advance )

seller receives  = advance (at night) + balance (at the open)

With the current parameters:

The two prices#

Oracle average#

After the opening bell, EVE waits for the first fresh Chainlink price: a round written after the bell, not the frozen value left from the previous close. From that first fresh round, it averages every round written during the window, which lasts between 5 to 15 minutes.

Why average, and not take the first print:

• The first minutes after the open are the noisiest of the day. The opening auction, wide spreads and a rush of orders produce prints that do not last.
• A single price is easier to move than an average.
• An average over several minutes is closer to a price at which size can really be traded.

Why a window of at most 15 minutes: sellers should be paid quickly, and the longer the window, the more the "opening price" drifts into being just "the morning price".

Realized TWAP#

In parallel, the pool sells the stocks it bought during the night. It sells in equal slices across the first 30 minutes of the session. The realized TWAP is simply what it got:

realized TWAP = total USDC received ÷ total shares sold

It is a realized price, not a quoted one. It includes slippage and trading costs, because those are real.

Why the lower of the two#

the lower price is the true one.

The pool pays out against a price. If that price is higher than what the pool can actually sell at, depositors lose the difference. Taking the lower of the two removes that possibility:

• If the pool realizes less than the oracle says (thin liquidity, slippage, a fast-moving open), the seller is paid the realized price. The pool paid out exactly what it received, minus the fee. Depositors are whole.
• If the pool realizes more than the oracle says, the seller is paid the oracle price and the difference stays in the protocol as a surplus, which goes to: reserve todo.

Be clear about what this means for a seller: the rule is asymmetric, and it is asymmetric in the pool's favour. That is deliberate. It is the reason depositors can fund the night without taking a view on the stock, and the reason the fee can be a fraction of a percent. The difference between the two prices is normally small, since both are measured over the same minutes of the same market.

The fee#

The fee is 0.25% of the settled value per calendar night between the close and the open. It is deducted from the balance, never from the advance. See Fees for the schedule and the split.

When the haircut is not enough#

Normally the settled value is comfortably above the advance, because of the haircut. If the stock gaps down by more than the haircut, it is not. Then:

balance        = 0                                  (the seller keeps the advance)
fee collected  = whatever is left above the advance, up to the fee due
shortfall      = advance − realized proceeds         (if positive)
reserve pays   = min( shortfall , reserve balance )
depositors pay = shortfall − reserve pays            (only if the reserve is empty)

The order of protection is always the same: haircut, then reserve, then depositors.

How far the stock can fall before the haircut is used up depends on the advance rate and the fee:

largest absorbed drop = 1 − advance rate ÷ (1 − fee rate)

Order of operations at the open#

1. The opening bell rings. Nothing settles on the frozen overnight price.
2. The first fresh Chainlink round after the bell arrives. The oracle window starts.
3. The pool starts selling the night's stocks in equal slices over 30 minutes.
4. The oracle window ends. The oracle average is known.
5. The TWAP window ends. The realized TWAP is known.
6. For each sale: settlement price, settled value, fee, balance.
7. Balances are paid to sellers. Fees are split. Any shortfall is drawn from the reserve.
8. Queued depositor withdrawals are served from the USDC that came back.

Who triggers these steps: not decided todo.

Worked examples#

All four use illustrative prices. Every line is computed by the settlement code.

A normal night#

A weekend#

Here the oracle average is the lower price. The pool realized slightly more than it paid out, and that surplus goes to: reserve todo.

A holiday weekend#

Four calendar nights, so four nightly fees.

A big gap#

The seller keeps the advance. The pool sold the shares for less than it advanced, and the reserve makes up the difference.

An earnings night#

The same kind of drop as the big gap, but the reduced advance left a cushion wide enough to absorb it. No reserve needed.

Edge cases#

No fresh price. If no Chainlink round is written after the bell (a halted stock, an unscheduled market closure, an oracle outage), there is no oracle average and therefore no settlement. The sale stays open until a fresh price exists. See Oracles.

The pool cannot sell everything in the window. The volume cap exists to prevent this. What happens to unsold inventory after 30 minutes is not decided.

Rounding. USDC has six decimals. Amounts are rounded to that precision; rounding remainders go to the reserve.

Several sales of the same ticker. Every sale of a ticker on the same night settles at the same settlement price.

In code#

The formula lives in one pure function. This is the one the simulator and the worked examples above call:

import { settle } from "@/lib/protocol";

const result = settle({
  qty: 10,
  advance: 1620,        // paid at night: 10 × 180.00 × 90%
  feeBps: 25,           // one night
  oraclePrice: 181.2,   // fresh Chainlink price, averaged
  twapPrice: 181.05,    // what the pool realized
  reserveBefore: 25_000,
});

result.settlementPrice; // 181.05  (the lower of the two)
result.settledValue;    // 1810.50
result.feeCollected;    // 4.52625
result.balance;         // 185.97375
result.sellerTotal;     // 1805.97375

Source: src/lib/protocol/settlement.ts. Tests: src/lib/protocol/__tests__/settlement.test.ts, including a property test of 5,000 random settlements that checks the invariants: the lower price always binds, the seller never pays back, cash is conserved, and depositors lose only once the reserve is empty.