> For the complete documentation index, see [llms.txt](https://docs.symm.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.symm.io/contract-documentation/symmio-perps-v0.8.5/diamond-core-facets/settlement.md).

# 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.

{% hint style="info" %}
**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.
  {% endhint %}

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:**

```solidity
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:**

```solidity
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)`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.symm.io/contract-documentation/symmio-perps-v0.8.5/diamond-core-facets/settlement.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.