T23 · Perp DEX

A Real-World Problem

Your perpetual trading venue has been live for three weeks. Most of your work went into matching: the order book, price-time priority, partial fills, cancellations, and event feeds. It runs cleanly. Latency is steady under load, and every fill is recorded.

Then one night the underlying asset drops 18% in twelve minutes.

The next morning, every subsystem log looks normal:

• Matching did not stall; every fill reached the database.
• The liquidation engine triggered 214 times, all successfully.
• The price source kept updating, and none of T21's four checks raised an alarm.

Yet the books do not balance.

A perpetual market is a zero-sum ledger: every dollar a long earns must be a dollar a short loses. The day's aggregate position P&L should be zero. Instead it is negative: the system owes users money.

You trace the difference. Thirty-one long positions were closed after their losses exceeded the margin they posted. The counterparties' gains are real, but the losing side has no funds left to pay. Not one line of your three-week matching implementation is wrong, and it cannot help.

Who owns the hole, and who fills it?

Thought Experiment

Strip away the exchange. Keep one sheet of paper and one person. The sheet says A is long ten units, B is short ten units, and the underlying price is 100. For each one-unit price move, one pays the other ten.

The person's job is not matching; A and B already matched. Their only job is to ensure every balance on the paper can always be paid. Now assume A and B posted only 50 margin each, rather than 1,000.

As price moves, four questions arise. They are the whole chapter.

First, how much does each person have right now? At 103, A has an unrealized gain of 30 and B an unrealized loss of 30. B has only 20 equity left. This must be computable at any moment, not only when the position closes.

Second, when must someone be removed? If B is removed only when equity reaches zero, price is at 105. Can the position close exactly at 105? No: execution takes time and price does not wait. The system must act earlier, while B still has money. The amount remaining at the trigger is a parameter you must write down.

Third, who covers a late close? Price jumps from 104 to 108, leaving B with negative 30 equity. A should receive 80, but B contributed only 50. Someone must provide that missing 30 for the ledger to balance. Leaving it pending makes A's balance fictional.

Fourth, what if everyone wants to go long? The sheet requires one long for each short. If a hundred want to go long and only three want to short, who takes the other ninety-seven?

The answer to the fourth question is the funding rate from Chapter 18: put a price on occupying the crowded side so payments encourage movement toward the scarce side. That chapter explained why funding holds the price near its anchor. This one asks how to implement it.

Together, the four questions define a machine that continuously reads prices, recalculates equity, closes positions before equity runs out, and finds someone to cover shortfalls when it acts too late.

Matching decides who trades with whom. This machine decides whether the venue can pay its debts.

Your Decision

Return to the thirty-one bankrupt positions. The shortfall is a definite number; someone must bear it today.

Who do you choose?

What Happens

The options all answer one question: who bears the zero-sum ledger's missing amount today?

The first row is the only truly wrong choice. The other three can be layers of one defense. In sequence they form the chapter's skeleton:

State the condition for bankruptcy as an inequality. It has the same shape as T22's:

A position goes bankrupt when:

    Mark-price movement between liquidation trigger and completed close
                >
    Maintenance margin rate + portion reserved for liquidation

Where:
  Left side = market speed × liquidation delay  ← not under your control
  Right side = your parameters                  ← design choices

Two differences from T22 are why this chapter exists: the right-hand buffer is an order of magnitude smaller (lending may have twenty-plus percentage points, while high-leverage perpetual maintenance margins may be a few percent or less), and the gap cannot be carried (a lender can account for bad debt over time; a perp venue must settle with a user today).

Therefore, a perpetual venue is fundamentally a continuously running risk engine; matching is its shell. Matching decides fill quality. The risk engine decides whether one night leaves it owing users money.

Build a Model

Consider five components in the order they respond to a price change.

1. Mark price: the foundation for every decision

A perpetual market has three prices. Confusing them is one of its costliest errors:

Liquidation must use the mark, not the last trade. The last trade is set by this venue's own order book, which one trade can move. Using it lets anyone willing to hit a thin book decide which positions liquidate.

The simplest mark uses the external index as an anchor and allows trades to deviate only within a band:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

uint256 constant BPS = 10_000;

/// Anchor the mark to the external index and allow only a small deviation
function markPrice() public view returns (uint256) {
    uint256 index = priceGuard.readPrice();   // Includes T21's four checks
    uint256 last = lastTradePrice;

    uint256 upper = index * (BPS + markBandBps) / BPS;   // Configurable; often tens to hundreds of bps
    uint256 lower = index * (BPS - markBandBps) / BPS;

    if (last > upper) return upper;
    if (last < lower) return lower;
    return last;
}

The snippet's value is raising attack cost from moving your own book to moving the external spot market. External market depth is the numerator of T21's safety margin. All of T21 lives inside readPrice(). If it returns a manipulated value, the next four components fail while executing normally and raising no error.

2. Positions and margin: equity available at any instant

int256 constant WAD = 1e18;

struct Position {
    int256 size;          // Positive for long, negative for short; underlying units
    uint256 margin;       // Margin posted for this position
    uint256 entryPrice;   // Mark price at opening
    int256 entryFunding;  // Cumulative funding index at opening; see next section
}

/// Unrealized P&L: signed size handles longs and shorts in one expression
function unrealizedPnl(Position memory p, uint256 mark) pure returns (int256) {
    return p.size * (int256(mark) - int256(p.entryPrice)) / WAD;
}

/// Notional = absolute position size × mark price
function notional(Position memory p, uint256 mark) pure returns (uint256) {
    int256 s = p.size >= 0 ? p.size : -p.size;
    return uint256(s) * mark / uint256(WAD);
}

A signed size is the important design choice: long and short P&L, funding, and liquidation share formulas instead of branching in every function. Branches almost inevitably create asymmetric boundary errors.

3. Funding: you cannot iterate over positions

Chapter 18 explained why funding anchors prices. Engineering imposes a hard constraint: you cannot iterate through every position every eight hours to collect payments. There may be tens of thousands; one onchain call has no such budget.

Use the same pattern as T22 interest: maintain a global cumulative index, and store its opening value in each position. Funding owed at any moment is a subtraction:

int256 public cumulativeFunding;  // Cumulative amount owed per unit of long size, signed
uint256 public lastFundingAt;

/// Accrue funding since the last update into the index. O(1) regardless of position count
function accrueFunding(uint256 mark, uint256 index) internal {
    uint256 elapsed = block.timestamp - lastFundingAt;
    if (elapsed == 0) return;

    // Premium: deviation of mark from index, scaled by WAD
    int256 premium = (int256(mark) - int256(index)) * WAD / int256(index);

    // Rate: premium spread per second plus interest term, then clamp it
    int256 rate = premium / int256(fundingPeriod) + interestPerSecond;
    if (rate > fundingCapPerSecond) rate = fundingCapPerSecond;
    if (rate < -fundingCapPerSecond) rate = -fundingCapPerSecond;

    cumulativeFunding += rate * int256(elapsed) * int256(index) / WAD;
    lastFundingAt = block.timestamp;
}

/// Positive means the position pays; negative means it receives
function fundingOwed(Position memory p, int256 cumulative) pure returns (int256) {
    return p.size * (cumulative - p.entryFunding) / WAD;
}

/// Equity = margin + unrealized P&L - funding owed
function equity(Position memory p, uint256 mark, int256 cumulative) pure returns (int256) {
    return int256(p.margin) + unrealizedPnl(p, mark) - fundingOwed(p, cumulative);
}

Three parameters need explicit decisions. All are configurable; none has a universal value:

The second row is often skipped. The cap is not just a safety setting; it limits the anchor's pull. Beyond it, a larger divergence no longer produces a larger payment. Arbitrageurs alone must restore price, precisely when they are most likely to retreat.

Another code requirement: accrue funding before checking liquidation. An idle position can cross maintenance purely through accumulated funding. Omit that update and apparently healthy positions may have needed liquidation long ago.

4. Liquidation: settle the ledger here

error NotLiquidatable();

/// Liquidatable when equity falls below the maintenance requirement
function isLiquidatable(
    Position memory p,
    uint256 mark,
    int256 cumulative,
    uint256 maintenanceBps    // Configurable maintenance rate, often tens to hundreds of bps, tiered by size
) pure returns (bool) {
    int256 e = equity(p, mark, cumulative);
    if (e <= 0) return true;
    return uint256(e) <= notional(p, mark) * maintenanceBps / BPS;
}

function liquidate(address trader) external {
    Position storage p = positions[trader];
    uint256 mark = markPrice();
    accrueFunding(mark, priceGuard.readPrice());          // Settle funding before the decision

    if (!isLiquidatable(p, mark, cumulativeFunding, maintenanceBps)) revert NotLiquidatable();

    int256 e = equity(p, mark, cumulativeFunding);
    uint256 fee = notional(p, mark) * liquidationFeeBps / BPS;   // The liquidator's entire incentive

    if (e > int256(fee)) {
        _payout(msg.sender, fee);                  // Fee to liquidator
        _payout(trader, uint256(e) - fee);         // Return remainder to trader
    } else if (e > 0) {
        _payout(msg.sender, uint256(e));           // Only part of fee can be paid
    } else {
        // Negative equity: bankruptcy. Find a payer for the gap in this transaction
        _coverShortfall(uint256(-e));
    }

    _closePosition(trader);
}

function _coverShortfall(uint256 gap) internal {
    emit ShortfallCovered(gap);
    if (insuranceFund >= gap) {
        insuranceFund -= gap;
        return;
    }
    uint256 remaining = gap - insuranceFund;
    insuranceFund = 0;
    _autoDeleverage(remaining);      // Rank winners by profit and leverage; force-close a portion
}

_coverShortfall is the one branch in the contract that must not revert. It may exhaust the fund and call the last defense, but it must return because the ledger must balance in this transaction.

Compare T22: lending's _recordBadDebt means “record now and resolve later.” Perpetuals' _coverShortfall means “find the funds now.” The same location has two different obligations.

5. Why liquidators arrive

As in T22, liquidators have no salary or duty. They appear only when notional times the liquidation fee exceeds gas plus slippage in closing the position. Thus the failure modes overlap: small positions are unprofitable, congestion destroys economics, and nine of ten competitors waste fees. The outcome differs: lending bad debt accumulates, while perpetuals can leave someone unable to withdraw today.

What It Is Called

Hands-on

Initial mark 100; choose your own maintenance margin rate

Three long batches: A at 5× leverage with 100 million notional,
                    B at 10× with 300 million,
                    C at 20× with 200 million
Depth assumption: each 50 million notional closed lowers the mark another 1%
Initial shock: mark falls to 96

Scenario: your market has N notional at a leverage tier; liquidation prices
          are d percent from the current mark

Step 1: Cost to push the mark by d
        The mark is anchored to external spot markets, so those are what must move
        T21 formula: about spot depth × (sqrt(1+d) - 1)

Step 2: Scale of liquidations triggered, and how much forced closing moves price again
        Use the cascade and your depth assumption

Step 3: What the attacker receives
        a) Gain on a pre-positioned opposite exposure
        b) Liquidation fees when acting as liquidator
        c) Discounted assets bought during forced closes

Step 4: Profit = Step 3 - Step 1 - fees - gas

AI Lab

Step one:
Design a funding-rate formula for a perpetual market. Give the complete
expression, define each term, explain cap selection, and implement it onchain
in O(1) without iterating through positions. What do the period and caps protect?

Step two:
Given historical spot and simultaneous perpetual trade prices, calculate
funding period by period. For each period output deviation, rate, annualized
holding cost for longs, and annualized receipts for shorts. Mark periods that
hit either cap.

Step three:
During periods at the upper cap, did deviation keep growing or converge?
If it kept growing, what does that mean? How would you change parameters,
and what would the new costs be?

Real-World Case

Change One Variable

Takeaway Questions

Chapter Check