T23 · Perp DEX

穿仓发生的条件：

    标记价格在「触发清算」到「仓位平完」之间的移动幅度
                >
    维持保证金率 + 预留给清算的那部分

其中：
  左边 = 市场的速度 × 你的清算延迟     ← 你控制不了的部分
  右边 = 你设的参数                    ← 你能设计的部分

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

uint256 constant BPS = 10_000;

/// 标记价格：以外部指数价为基准，只允许围绕它小幅偏离
function markPrice() public view returns (uint256) {
    uint256 index = priceGuard.readPrice();   // T21 的四个检查在这个函数里面
    uint256 last = lastTradePrice;

    uint256 upper = index * (BPS + markBandBps) / BPS;   // markBandBps 可配置，典型量级是几十到几百
    uint256 lower = index * (BPS - markBandBps) / BPS;

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

int256 constant WAD = 1e18;

struct Position {
    int256 size;          // 正数是多头，负数是空头，单位是标的数量
    uint256 margin;       // 这个仓位押上的保证金
    uint256 entryPrice;   // 开仓时的标记价格
    int256 entryFunding;  // 开仓时的累计资金费指数，见下一节
}

/// 未实现盈亏：size 带符号，所以多空两种情况用同一行算完
function unrealizedPnl(Position memory p, uint256 mark) pure returns (int256) {
    return p.size * (int256(mark) - int256(p.entryPrice)) / WAD;
}

/// 名义价值 = 仓位绝对值 × 标记价格
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);
}

int256 public cumulativeFunding;  // 每一单位多头仓位累计应付的金额，带符号
uint256 public lastFundingAt;

/// 把上次到现在的资金费累进指数里。O(1)，和仓位数量无关
function accrueFunding(uint256 mark, uint256 index) internal {
    uint256 elapsed = block.timestamp - lastFundingAt;
    if (elapsed == 0) return;

    // 溢价项：标记价相对指数价偏离多少，放大 WAD 倍
    int256 premium = (int256(mark) - int256(index)) * WAD / int256(index);

    // 费率 = 溢价项摊到每秒 + 利率项，然后必须夹在上下限之内
    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;
}

/// 欠的资金费：正数表示这个仓位要付出去，负数表示它在收钱
function fundingOwed(Position memory p, int256 cumulative) pure returns (int256) {
    return p.size * (cumulative - p.entryFunding) / WAD;
}

/// 账户净值 = 保证金 + 未实现盈亏 − 欠的资金费
function equity(Position memory p, uint256 mark, int256 cumulative) pure returns (int256) {
    return int256(p.margin) + unrealizedPnl(p, mark) - fundingOwed(p, cumulative);
}

error NotLiquidatable();

/// 可清算的条件：净值跌到维持要求以下
function isLiquidatable(
    Position memory p,
    uint256 mark,
    int256 cumulative,
    uint256 maintenanceBps    // 维持保证金率，典型量级是几十到几百 bps，通常随仓位规模分档，必须可配置
) 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());          // 先结资金费，再做判断

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

    int256 e = equity(p, mark, cumulativeFunding);
    uint256 fee = notional(p, mark) * liquidationFeeBps / BPS;   // 清算人的全部动机

    if (e > int256(fee)) {
        _payout(msg.sender, fee);                  // 清算费给清算人
        _payout(trader, uint256(e) - fee);         // 剩下的退还用户
    } else if (e > 0) {
        _payout(msg.sender, uint256(e));           // 只够付一部分清算费
    } else {
        // 净值已经是负数：穿仓。缺口必须在这一笔交易里找到承担方
        _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);      // 按盈利与杠杆排序，强制平掉盈利方的一部分
}