ClearingHouse Facet

The Clearing House Facet is the protocol's liquidation engine. It handles flagging parties for liquidation, executing the liquidation itself, confiscating collateral, and redistributing it to affected counterparties. All of the functions in this facet are restricted to the CLEARING_HOUSE_ROLE. This is an entirely privileged facet and regular user's won't call this facet. The clearing house operator is responsible for monitoring solvency and triggering these actions when thresholds are breached.

Key Concepts:

• Isolated vs. Cross Liquidation: PartyB can hold collateral in two modes — isolated (their own standalone balance for a given collateral) and cross (shared across a specific PartyA relationship). Each mode has its own flag/liquidate flow.

• Liquidation ID: A unique identifier assigned to a liquidation event. Used to track which collateral seizures and trade closures belong to a specific liquidation instance.

• Flagging: Before a party can be liquidated, they must first be flagged. This two-step design gives the system a chance to verify the state and revert if conditions change before the liquidation is fully committed.

• MarginType: Indicates whether the action applies to isolated or cross margin. Used in confiscation and distribution to correctly target the right balance bucket.

• Confiscation: The act of seizing collateral from an insolvent party — either from their trading balance or from a pending withdrawal.

• Distribution: After confiscation, the seized collateral is redistributed to the counterparties who were owed it.

---

Overview

The Clearing House Facet controls liquidations across two party types (PartyA and PartyB) and two margin modes (isolated and cross).

ISOLATED:

• Party B's margin is pooled globally across all Party A's

• Only need to check Party B's overall solvency in that collateral

• One liquidation = Party B loses all isolated positions

CROSS:

• Party B's margin is per-party-relationship (Party B ↔ Party A)

• Party B can be solvent with Party A but insolvent with Party C

• Must liquidate specific pairings separately

• Different Party A's might liquidate different Party B's independently

The general flow for any liquidation is:

1. A monitoring system detects that a party has fallen below their margin threshold

2. The clearing house flags the party for liquidation via flagIsolatedPartyBLiquidation(), flagCrossPartyBLiquidation(), or flagPartyALiquidation()

3. If conditions have changed or the flag was an error, it can be reversed with the corresponding unflag function

4. The liquidation is executed with liquidateIsolatedPartyB(), liquidateCrossPartyB(), or liquidateCrossPartyA()

5. Open and close intents are cancelled via cancelOpenIntents() and cancelCloseIntents()

6. Active trades are closed at liquidation prices via closeTrades()

7. Collateral is seized from the insolvent party via confiscate() or confiscateWithdrawal()

8. Seized collateral is redistributed to affected counterparties via distributeCollateral()

---

flagIsolatedPartyBLiquidation()

Marks a PartyB as pending liquidation for their isolated collateral position. This is the first step in the isolated liquidation flow — no funds are moved yet, but the flag prevents the party from making further balance changes while the liquidation is being prepared.

Function Signature:

function flagIsolatedPartyBLiquidation(
    address partyB,
    address collateral
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• partyB: The address of the PartyB being flagged for liquidation.

• collateral: The collateral token address associated with the isolated position being flagged.

---

unflagIsolatedPartyBLiquidation()

Reverses the liquidation flag for a PartyB's isolated position. Used when the flag was applied in error, or if the party's health recovered before the liquidation was executed.

Function Signature:

function unflagIsolatedPartyBLiquidation(
    address partyB,
    address collateral
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• partyB: The address of the PartyB whose liquidation flag is being cleared.

• collateral: The collateral token address of the position being untagged.

---

liquidateIsolatedPartyB()

Executes the isolated liquidation of a previously flagged PartyB. This records the UPnL at the moment of liquidation and the collateral price, which are used to calculate how much is owed to affected counterparties in the subsequent distribution step.

Function Signature:

function liquidateIsolatedPartyB(
    address partyB,
    address collateral,
    int256 upnl,
    uint256 collateralPrice
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• partyB: The address of the PartyB being liquidated.

• collateral: The collateral token address for the isolated position being liquidated.

• upnl: The unrealized P&L of PartyB at the time of liquidation. Can be negative (loss) or positive (gain).

• collateralPrice: The price of the collateral token at the time of liquidation, used for value calculations.

---

confiscate()

Seizes a specified amount of collateral from an insolvent party's balance as part of an active liquidation. The margin type determines whether the funds are taken from isolated or cross margin.

The amount is tracked in LiquidationDetail.confiscatedAmount and Later distributed via distributeCollateral() which adds it user balances.

Function Signature:

function confiscate(
    uint256 liquidationId,
    uint256 amount,
    address party,
    address counterParty,
    MarginType marginType
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• liquidationId: The unique identifier of the liquidation event this confiscation belongs to.

• amount: The amount of collateral to seize.

• party: The address of the insolvent party whose collateral is being seized.

• counterParty: The address of the counterparty involved in the positions being liquidated.

• marginType: An enum value specifying whether to seize from isolated or cross margin.

---

confiscateWithdrawal()

Seizes collateral that is currently sitting in a pending withdrawal request, blocking it from being completed.

Function Signature:

function confiscateWithdrawal(
    uint256 withdrawId
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• withdrawId: The unique identifier of the withdrawal request to confiscate.

---

distributeCollateral()

Redistributes previously confiscated collateral to the counterparties who were owed it. Called after confiscation to complete the value transfer from the insolvent party to those on the winning side of their positions.

Function Signature:

function distributeCollateral(
    uint256 liquidationId,
    address partyB,
    address collateral,
    MarginType marginType,
    address[] calldata partyAs,
    uint256[] calldata amounts
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• liquidationId: The liquidation event this distribution is associated with.

• partyB: The PartyB whose confiscated collateral is being distributed.

• collateral: The collateral token address being distributed.

• marginType: Whether the distribution comes from isolated or cross margin funds.

• partyAs: An array of PartyA addresses that will receive collateral.

• amounts: A parallel array of amounts corresponding to each PartyA in partyAs. Must be the same length.

---

flagCrossPartyBLiquidation()

Flags a PartyB for liquidation within a specific cross margin relationship with a given PartyA. Unlike isolated liquidation, cross liquidation is scoped to a particular PartyA/PartyB pair.

Function Signature:

function flagCrossPartyBLiquidation(
    address partyB,
    address partyA,
    address collateral
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• partyB: The address of the PartyB being flagged.

• partyA: The specific PartyA counterparty within whose cross relationship this flag applies.

• collateral: The collateral token address for the cross position being flagged.

---

unflagCrossPartyBLiquidation()

Removes the cross margin liquidation flag for a specific PartyA/PartyB/collateral combination.

Function Signature:

function unflagCrossPartyBLiquidation(
    address partyB,
    address partyA,
    address collateral
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• partyB: The address of the PartyB being untagged.

• partyA: The specific PartyA counterparty for the cross relationship.

• collateral: The collateral token address of the position.

Internal Logic:

• State Reversal: Clears the cross liquidation flag for the partyA/partyB/collateral triplet, allowing the relationship to resume normal operation.

• Event: Emits UnflagCrossPartyBLiquidation with the caller, partyB, partyA, and collateral.

---

liquidateCrossPartyB()

Executes the cross margin liquidation of a flagged PartyB within a specific PartyA relationship. Records the UPnL and collateral price at the moment of execution.

Function Signature:

function liquidateCrossPartyB(
    address partyB,
    address partyA,
    address collateral,
    int256 upnl,
    uint256 collateralPrice
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• partyB: The address of the PartyB being liquidated.

• partyA: The PartyA counterparty for this cross relationship.

• collateral: The collateral token address for the cross position.

• upnl: PartyB's unrealized P&L at the time of liquidation.

• collateralPrice: The price of the collateral token at liquidation time.

Internal Logic:

• Prerequisite: The partyA/partyB/collateral combination must already be flagged for cross liquidation.

• Snapshot: LibClearingHouse.liquidateCrossPartyB() records the UPnL and price, establishing the accounting basis for confiscation and distribution on this specific pair.

• Event: Emits LiquidateCrossPartyB with the caller, partyB, partyA, collateral, UPnL, and collateral price.

---

flagPartyALiquidation()

Flags a PartyA for liquidation within a specific cross relationship with a given PartyB and collateral. Initiates the PartyA-side liquidation flow.

Function Signature:

function flagPartyALiquidation(
    address partyA,
    address partyB,
    address collateral
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• partyA: The address of the PartyA being flagged for liquidation.

• partyB: The counterparty PartyB in the relevant cross relationship.

• collateral: The collateral token address for the cross position.

Internal Logic:

• Flags the PartyA Side: Unlike the PartyB flag functions, this targets a PartyA account. LibClearingHouse.flagPartyALiquidation() applies the flag to the partyA/partyB/collateral triplet.

• Event: Emits FlagPartyALiquidation with the caller, partyA, partyB, and collateral.

---

unflagPartyALiquidation()

Removes the liquidation flag from a PartyA within a specific cross relationship.

Function Signature:

function unflagPartyALiquidation(
    address partyA,
    address partyB,
    address collateral
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• partyA: The address of the PartyA being untagged.

• partyB: The counterparty PartyB in the cross relationship.

• collateral: The collateral token address of the position.

---

liquidateCrossPartyA()

Executes the cross margin liquidation of a flagged PartyA. This operates on an existing liquidation ID.

Function Signature:

function liquidateCrossPartyA(
    uint256 liquidationId,
    address partyA,
    address partyB,
    address collateral,
    int256 upnl,
    uint256 collateralPrice
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• liquidationId: The unique identifier for this liquidation event.

• partyA: The address of the PartyA being liquidated (used for event emission).

• partyB: The counterparty PartyB (used for event emission).

• collateral: The collateral token address (used for event emission).

• upnl: PartyA's unrealized P&L at the time of liquidation.

• collateralPrice: The price of the collateral token at liquidation time.

---

closeTrades()

Closes a batch of active trades at specified prices as part of a liquidation. This settles the positions of the liquidated party at the prices determined by the clearing house at liquidation time.

Function Signature:

function closeTrades(
    uint256 liquidationId,
    uint256[] calldata tradeIds,
    uint256[] calldata prices
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• liquidationId: The liquidation event these trade closures belong to.

• tradeIds: An array of trade/position IDs to be closed.

• prices: A parallel array of prices at which each trade is being closed. Must match the length of tradeIds.

Internal Logic:

• Batch Processing: LibClearingHouse.closeTrades() iterates over both arrays, closing each trade at its corresponding liquidation price and settling P&L accordingly.

• Parallel Arrays: tradeIds and prices must be the same length.

• Event: Emits CloseTradesForLiquidation with the caller, liquidationId, tradeIds, and prices.

---

allocateFromReserveToCross()

Moves collateral from a party's reserve balance into their cross balance with a specific counterparty. Used during liquidation to tap reserve funds before a party is fully declared insolvent.

Function Signature:

function allocateFromReserveToCross(
    address party,
    address counterParty,
    address collateral,
    uint256 amount
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• party: The address of the party whose reserve balance is being drawn from.

• counterParty: The counterparty whose cross relationship will be topped up.

• collateral: The collateral token address being moved.

• amount: The amount to move from reserve to cross balance.

---

cancelOpenIntents()

Cancels a batch of open (unfilled) intents belonging to a party being liquidated. Prevents new positions from being opened against an insolvent party during the liquidation process.

Function Signature:

function cancelOpenIntents(
    uint256[] calldata intentIds
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• intentIds: An array of open intent IDs to cancel.

---

cancelCloseIntents()

Cancels a batch of pending close intents during a liquidation. These are positions that were in the process of being closed but hadn't settled yet.

Function Signature:

function cancelCloseIntents(
    uint256[] calldata intentIds
) external whenNotLiquidationPaused onlyRole(LibAccessibility.CLEARING_HOUSE_ROLE);

Parameters:

• intentIds: An array of close intent IDs to cancel.