Liquidation Funding Observability

v0.8.6 adds dedicated events for observing quote-level funding and price PnL calculations and their final aggregate settlement during PartyA liquidation.

Summary

PartyA liquidation calculates funding and price PnL while processing individual quotes, then settles them through an aggregate PartyA/PartyB bucket. v0.8.6 adds events at both points so indexers can observe the quote calculations and reconcile them with the final aggregate balance movement.

Quote funding and PnL event

event QuoteLiquidationFundingCalculated(
    address indexed partyA,
    address indexed partyB,
    uint256 indexed quoteId,
    uint256 symbolId,
    int256 rawFunding,
    int256 rawPnl,
    bytes liquidationId
);

The contract emits this event when one open quote is processed during PartyA liquidation. It identifies the quote, market, counterparties, liquidation, raw funding, and raw price PnL calculated from the liquidation snapshot.

rawFunding and rawPnl are signed from PartyB's perspective: a positive value means PartyB receives that component, and a negative value means PartyB pays it.

Aggregate settlement event

event LiquidationFundingSettled(
    address indexed partyA,
    address indexed partyB,
    address indexed allocationKey,
    int256 rawFunding,
    int256 settledFunding,
    int256 rawPnl,
    int256 settledPnl,
    uint256 scaleNumerator,
    uint256 scaleDenominator,
    bytes liquidationId
);

The contract emits this event when the PartyA/PartyB settlement bucket is finalized. It reports the raw and final aggregate funding and price PnL applied to PartyB's allocation bucket.

  • rawFunding is the signed funding total before the final settlement adjustment.
  • settledFunding is the signed aggregate funding actually credited or debited.
  • rawPnl is the signed sum of the quote-level raw price PnL values.
  • settledPnl is the signed aggregate price PnL actually credited or debited.
  • scaleNumerator and scaleDenominator expose the adjustment applied to funding.
  • allocationKey identifies the PartyB balance bucket that changed.

The event's scale operands come from the settlement state. The expected amount is the full PartyA-perspective funding-plus-PnL total accumulated while processing quotes. The final amount is the PartyA-perspective amount the bucket will actually settle after any deficit or dispute adjustment and any isolated-mode balance cap. These are internal operands; the event reports their ratio and the resulting PartyB-perspective components.

Normally the final amount matches the expected amount and the scale is 1 / 1. A haircut, dispute override, or isolated-mode payout cap can reduce the final amount. When it reduces the amount without changing its direction, the scale is abs(final amount) / abs(expected amount); a zero or direction-changing override reduces funding to zero. The contract applies that scale to rawFunding, then assigns the rest of the final bucket movement to settledPnl. Thus settledFunding + settledPnl equals the final PartyB-perspective balance change; settledPnl is not independently scaled.

Non-zero settled components are accompanied by the corresponding typed FUNDING_FEE_IN/OUT and REALIZED_PNL_IN/OUT PartyB balance-change events.

Clearing House boundary

event LiquidationFundingSettlementAbandoned(
    address indexed partyA,
    address indexed partyB,
    int256 rawFunding,
    bytes liquidationId
);

If the Clearing House takes over before a pending normal settlement is completed, this event marks the normal funding settlement as abandoned. Observers should then reconcile the takeover through ClearingHouseSettlementComponent and ClearingHouseAccountSettlement instead of treating the earlier raw quote calculations as a completed normal settlement.

What indexers can reconstruct

The events expose:

  • Raw liquidation funding and price PnL per quote and symbol.
  • Raw and final aggregate funding and price PnL per PartyA/PartyB settlement bucket.
  • The PartyB allocation key affected by the final settlement.
  • The adjustment ratio used for the aggregate settlement.
  • An explicit boundary when normal settlement is superseded by a Clearing House takeover.

The typed PartyB balance-change events supply the corresponding storage deltas, so indexers can reconcile these records without an additional on-chain publication step.