Settlement

The Settlement Facet allows PartyB to realize unrealized PnL (uPnL) from open positions by adjusting the openedPrice of selected quotes. This transfers value between PartyA's and PartyB's allocated balances without closing positions, enabling scenarios where one party needs additional available balance to proceed with other operations (e.g., filling a close request when the counterparty lacks funds). The underlying logic is implemented in the SettlementFacetImpl library.

Note: In v0.8.5, a new settleUpnlUnified function replaces the legacy settleUpnl as the preferred settlement method. Key differences:

• Unified Signature Format: settleUpnlUnified uses UnifiedSettlementSig which works for both cross-mode and isolated-mode PartyBs with a single signature format.

• Multi-PartyA Support: The unified function settles quotes for a single PartyB across one or more PartyAs, which is essential for cross-mode where funds are pooled.

• Cross-Mode Nonce Handling: In cross mode, the signature nonce is zero (allowing parallel operations with different PartyAs), while in isolated mode, the per-PartyA nonce is used.

• Solvency Check Scope: In cross mode, solvency is checked against the aggregated cross bucket (address(0)). In isolated mode, solvency is checked per PartyA.

The legacy settleUpnl is kept for backward compatibility with integrations that have not migrated.

---

Overview

The Settlement Facet defines functions for both:

• Legacy Settlement: Settles uPnL for a single PartyA using the legacy SettlementSig format (settleUpnl). Deprecated in favor of settleUpnlUnified.

• Unified Settlement: Settles uPnL across one or more PartyAs for a single PartyB using the UnifiedSettlementSig format (settleUpnlUnified). Supports both cross-mode and isolated-mode PartyBs.

---

Settlement Use Cases

Scenario 1 — PartyA lacks funds for a close: PartyA has a position to close but insufficient available balance. PartyB settles PartyA's profitable positions with this PartyB (or any other PartyB in cross mode), realizing positive uPnL. This increases PartyA's allocated balance so the close can proceed.

Scenario 2 — PartyB lacks funds for a close: PartyA requests a close but PartyB lacks available balance to pay. PartyB settles its own profitable positions — the settlement realizes PartyB's positive uPnL, moving funds into its allocation bucket. This is a PartyB-initiated action and does not require PartyA's participation.

---

settleUpnl()

DEPRECATED: Use settleUpnlUnified instead, which supports both cross-mode and isolated-mode PartyBs with a unified signature format.

Legacy settlement function. Settles uPnL for a specific PartyA by adjusting the openedPrice of selected quotes. The Muon SettlementSig contains quote IDs, uPnL of both parties, and market prices.

Function Signature:

function settleUpnl(
    SettlementSig memory settlementSig,
    uint256[] memory updatedPrices,
    address partyA
) external whenNotPartyBActionsPaused onlyPartyB notLiquidatedPartyA(partyA);

Parameters:

• settlementSig: The Muon settlement signature containing quote settlement data and uPnL values.

• updatedPrices: New prices to set as openedPrice for the specified quotes.

• partyA: The address of PartyA whose positions are being settled.

Access: Only callable by PartyB. PartyA must not be in liquidation.

Events Emitted:

• SettleUpnl(QuotesSettlementsData[] data, uint256[] updatedPrices, address partyA, uint256 newPartyAAllocatedBalance, uint256[] newPartyBsAllocatedBalances)

---

settleUpnlUnified()

Unified settlement function that works for both cross-mode and isolated-mode PartyBs. Settles quotes for a single PartyB across one or more PartyAs using the UnifiedSettlementSig format.

In cross mode, the settlement affects the shared address(0) pool regardless of which PartyAs' positions are settled. In isolated mode, each PartyA's settlement affects only that PartyA's allocation bucket.

Function Signature:

function settleUpnlUnified(
    UnifiedSettlementSig memory sig,
    uint256[] memory updatedPrices
) external whenNotPartyBActionsPaused onlyPartyB;

Parameters:

• sig: The UnifiedSettlementSig containing quote settlement data, uPnL values, the PartyB address, and the array of PartyA addresses involved.

• updatedPrices: New prices to set as openedPrice for the specified quotes.

Access: Only callable by PartyB.

Events Emitted:

• SettleUpnlUnified(bytes reqId, QuotesSettlementsData[] data, uint256[] updatedPrices, address partyB, address[] partyAs, uint256[] newPartyAsAllocatedBalances, uint256 newPartyBAllocatedBalance)