PartyB Position Actions

The PartyB Position Actions Facet is the primary interface for PartyB to act on quotes — opening positions, filling close requests, and accepting cancel requests. The underlying logic is implemented in the PartyBPositionActionsFacetImpl library.

Note: In v0.8.5, the following key changes apply:

• Close Fees: A new close fee is charged when positions are closed, in addition to the existing open fee. Close fees are configurable per affiliate, per symbol, and per user (see Affiliate Fees). The close fee is factored into solvency checks for all close paths.

• fillCloseRequestToLiquidation: A new function handles edge cases where fillCloseRequest would revert due to PartyA becoming insolvent after the close. It calculates and executes the maximum close amount that brings PartyA exactly to the liquidation threshold.

• Dual Events: Both OpenPosition and FillCloseRequest now emit two versions — the legacy event and a new one that includes LockedValues.

• Partial Open with Remainder: When openPosition partially fills a quote, a new remainder quote may be created. If the remainder enters PENDING status, SendQuote events are emitted for it. If the remainder is too small and gets cancelled, an AcceptCancelRequest event is emitted instead.

---

Overview

The PartyB Position Actions Facet provides the following key functionalities:

• Open Position: PartyB opens a position for a locked quote, optionally with partial fill.

• Fill Close Request: PartyB fills a close request from PartyA, with support for partial fills on LIMIT orders.

• Fill Close Request to Liquidation: PartyB fills a close request up to the maximum amount that keeps PartyA at the edge of liquidation, handling insolvency edge cases.

• Accept Cancel Close Request: PartyB accepts PartyA's request to cancel a pending close.

---

openPosition()

Opens a position for a locked quote. PartyB can fill the full requested amount or a fraction of it. The opened position's size cannot be excessively small or large.

When a partial fill occurs, the contract creates a new remainder quote for the unfilled amount. If the remainder is large enough, it enters PENDING status and SendQuote events are emitted for it. If the remainder is too small (below minimum thresholds), it is automatically cancelled.

Function Signature:

function openPosition(
    uint256 quoteId,
    uint256 filledAmount,
    uint256 openedPrice,
    PairUpnlAndPriceSig memory upnlSig
) external whenNotPartyBOpenPositionsPaused onlyPartyBOfQuote(quoteId) notLiquidated(quoteId);

Parameters:

• quoteId: The ID of the quote to open a position for.

• filledAmount: The amount to fill. Can be the full requested quantity or a partial amount.

• openedPrice: The opening price for the position.

• upnlSig: The Muon PairUpnlAndPriceSig containing uPnL of both parties and the current price.

Events Emitted:

• OpenPosition(uint256 quoteId, address partyA, address partyB, uint256 filledAmount, uint256 openedPrice) — legacy event

• OpenPosition(uint256 quoteId, address partyA, address partyB, uint256 filledAmount, uint256 openedPrice, LockedValues lockedValues) — new event with locked values

If a remainder quote is created:

• SendQuote(...) — both legacy and new events, if the remainder enters PENDING status

• AcceptCancelRequest(uint256 quoteId, QuoteStatus status) — if the remainder is too small and gets cancelled

---

fillCloseRequest()

Fills a close request from PartyA. For LIMIT orders, PartyB can fill in multiple steps, each at a different price. For MARKET orders, the close must be filled entirely in one step. A close fee is deducted from PartyA's available balance and factored into the solvency check.

Function Signature:

function fillCloseRequest(
    uint256 quoteId,
    uint256 filledAmount,
    uint256 closedPrice,
    PairUpnlAndPriceSig memory upnlSig
) external whenNotPartyBActionsPaused onlyPartyBOfQuote(quoteId) notLiquidated(quoteId);

Parameters:

• quoteId: The ID of the quote whose close request should be filled.

• filledAmount: The amount to fill. LIMIT orders support partial fills; MARKET orders must be filled fully.

• closedPrice: The closing price.

• upnlSig: The Muon PairUpnlAndPriceSig for solvency verification.

Access: Only callable by the PartyB of the quote. Neither party can be in liquidation.

Events Emitted:

• FillCloseRequest(uint256 quoteId, address partyA, address partyB, uint256 filledAmount, uint256 closedPrice, QuoteStatus status, uint256 closeId) — legacy event

• FillCloseRequest(uint256 quoteId, address partyA, address partyB, uint256 filledAmount, uint256 closedPrice, QuoteStatus status, uint256 closeId, LockedValues lockedValues) — new event with locked values

---

fillCloseRequestToLiquidation()

Fills a close request up to the maximum amount that keeps PartyA at the edge of liquidation (available balance ≈ 0). Use this when the standard fillCloseRequest would revert because closing the full amount pushes PartyA into insolvency.

With the introduction of close fees, this edge case becomes more likely — a user may appear solvent based on uPnL but become insolvent after the close due to the price difference and the close fee combined. This function calculates the safe partial amount instead of reverting.

Key behaviors:

• Only works with LIMIT orders (MARKET orders must be filled completely).

• If the full close is safe, it closes the full quantityToClose — identical behavior to fillCloseRequest.

• If the full close would make PartyA insolvent, it calculates and executes a partial close.

• Reverts if even a full close keeps PartyA insolvent (PartyA should be liquidated instead).

• Reverts if PartyA is already insolvent and closing would make it worse.

Function Signature:

function fillCloseRequestToLiquidation(
    uint256 quoteId,
    uint256 closedPrice,
    PairUpnlAndPriceSig memory upnlSig
) external whenNotPartyBActionsPaused onlyPartyBOfQuote(quoteId) notLiquidated(quoteId) returns (uint256 filledAmount);

Parameters:

• quoteId: The ID of the quote whose close request should be filled.

• closedPrice: The closing price.

• upnlSig: The Muon PairUpnlAndPriceSig for solvency verification.

Returns: filledAmount — the actual amount that was filled (may be less than quantityToClose).

Access: Only callable by the PartyB of the quote. Neither party can be in liquidation.

Preview View Function:

function getMaxCloseAmountToLiquidation(
    uint256 quoteId,
    uint256 closedPrice,
    uint256 marketPrice,
    int256 upnlPartyA
) external view returns (uint256 maxCloseAmount, bool canCloseAll);

Returns maxCloseAmount (the amount that will be filled) and canCloseAll (whether the full quantityToClose can be filled without insolvency). Solvers can call this before submitting a transaction to determine the expected fill.

Events Emitted:

• FillCloseRequest(...) — both legacy and new events, same as fillCloseRequest

---

acceptCancelCloseRequest()

Accepts PartyA's request to cancel a pending close. The position returns to OPENED status and the close request is removed.

Function Signature:

function acceptCancelCloseRequest(uint256 quoteId) external whenNotPartyBActionsPaused onlyPartyBOfQuote(quoteId) notLiquidated(quoteId);

Parameters:

• quoteId: The ID of the quote whose cancel close request should be accepted.

Access: Only callable by the PartyB of the quote. Neither party can be in liquidation.

Events Emitted:

• AcceptCancelCloseRequest(uint256 quoteId, QuoteStatus status, uint256 closeId)