# PartyA Facet

The PartyA Facet is the primary interface for users (PartyA) to manage their trading lifecycle — sending quotes, requesting cancellations, requesting position closures, and expiring stale quotes. The underlying logic is implemented in the `PartyAFacetImpl` library.

{% hint style="info" %}
**Note:** In v0.8.5, the following key changes apply to the PartyA Facet:

* **Instant Action Mode Guard:** All quote and close functions include a `whenInstantModeIsNotActive` modifier. When a PartyA has activated instant action mode (via the BindingFacet), these functions cannot be called directly on-chain — instead, operations must go through the Instant Layer using signed operations and batched execution.
* **Custom Quote Data:** A new `sendQuoteWithAffiliateAndData` function allows PartyA to attach arbitrary bytes to a quote. This enables persisting off-chain commitments (e.g., `tempQuoteId` from solver instant modes) directly within the quote on-chain.
* **New SendQuote Event:** A second `SendQuote` event is emitted alongside the legacy one, containing an `affiliate` address, ABI-encoded `paramsData` (to avoid stack-too-deep), and the custom `data` field.
* **maxFundingRate Deprecated:** The `maxFundingRate` parameter is retained in `sendQuote` and `sendQuoteWithAffiliate` for backward compatibility but is unused. Funding caps are postponed to a later version.
  {% endhint %}

***

### Overview

The PartyA Facet provides the following key functionalities:

* **Send Quote:** PartyA submits a quote request specifying the symbol, position type, order type, price, quantity, and margin parameters. The quote enters `PENDING` status and is visible to whitelisted PartyBs.
* **Cancel Quote:** PartyA requests cancellation of a pending quote. If not yet locked by a PartyB, it is cancelled immediately. If locked, it enters `CANCEL_PENDING` for PartyB to decide.
* **Request Close Position:** PartyA requests to close an open position at a specified price and quantity.
* **Cancel Close Request:** PartyA requests cancellation of a pending close request.
* **Expire Quotes:** Anyone can expire quotes or close requests that have passed their deadline.

***

### sendQuote()

Sends a quote to the protocol with no affiliate. The quote enters `PENDING` status. This is the legacy version — `sendQuoteWithAffiliate` or `sendQuoteWithAffiliateAndData` are preferred for new integrations.

**Function Signature:**

```solidity
function sendQuote(
    address[] memory partyBsWhiteList,
    uint256 symbolId,
    PositionType positionType,
    OrderType orderType,
    uint256 price,
    uint256 quantity,
    uint256 cva,
    uint256 lf,
    uint256 partyAmm,
    uint256 partyBmm,
    uint256 maxFundingRate,
    uint256 deadline,
    SingleUpnlAndPriceSig memory upnlSig
) external whenInstantModeIsNotActive(signer) whenNotPartyAActionsPaused notLiquidatedPartyA(signer) notSuspended(signer);
```

**Parameters:**

* `partyBsWhiteList`: Addresses of PartyBs allowed to act on this quote. Empty array means all PartyBs are allowed.
* `symbolId`: The unique identifier for the trading symbol (e.g., BTCUSDT).
* `positionType`: `LONG` (0) or `SHORT` (1).
* `orderType`: `LIMIT` (0) or `MARKET` (1).
* `price`: For limit orders, the requested price. For market orders, the price threshold the user is willing to accept.
* `quantity`: Size of the position.
* `cva`: Credit Valuation Adjustment — penalty the liquidated side pays to the other.
* `lf`: Liquidation Fee paid to the liquidator.
* `partyAmm`: PartyA's Maintenance Margin behind the position.
* `partyBmm`: PartyB's Maintenance Margin behind the position.
* `maxFundingRate`: Unused (kept for backward compatibility). Funding caps are postponed.
* `deadline`: Expiration timestamp for the quote request.
* `upnlSig`: Muon signature containing the user's uPnL and the symbol's current price.

**Events Emitted:**

* `SendQuote(address partyA, uint256 quoteId, address[] partyBsWhiteList, uint256 symbolId, PositionType positionType, OrderType orderType, uint256 price, uint256 marketPrice, uint256 quantity, uint256 cva, uint256 lf, uint256 partyAmm, uint256 partyBmm, uint256 tradingFee, uint256 deadline)` — legacy event
* `SendQuote(address partyA, uint256 quoteId, address[] partyBsWhiteList, address affiliate, bytes paramsData, bytes data)` — new event with `affiliate = address(0)` and empty `data`

***

### sendQuoteWithAffiliate()

Sends a quote with an associated affiliate address. Identical to `sendQuote` but includes the affiliate parameter. The `maxFundingRate` parameter is unused and kept for backward compatibility.

**Function Signature:**

```solidity
function sendQuoteWithAffiliate(
    address[] memory partyBsWhiteList,
    uint256 symbolId,
    PositionType positionType,
    OrderType orderType,
    uint256 price,
    uint256 quantity,
    uint256 cva,
    uint256 lf,
    uint256 partyAmm,
    uint256 partyBmm,
    uint256 maxFundingRate,
    uint256 deadline,
    address affiliate,
    SingleUpnlAndPriceSig memory upnlSig
) external whenInstantModeIsNotActive(signer) whenNotPartyAActionsPaused notLiquidatedPartyA(signer) notSuspended(signer) returns (uint256 quoteId);
```

**Parameters:**

* All parameters from `sendQuote`, plus:
* `affiliate`: The affiliate address associated with this quote.

**Returns:** The ID of the newly created quote.

**Events Emitted:**

* Legacy `SendQuote(...)` event
* New `SendQuote(...)` event with the affiliate address and empty `data`

***

### sendQuoteWithAffiliateAndData()

Sends a quote with an affiliate and arbitrary custom data attached. The custom data is stored in the quote's `data` field and emitted in the new `SendQuote` event. This is useful for persisting off-chain commitments (e.g., solver `tempQuoteId`) on-chain.

Unlike the other send functions, this variant does **not** include the deprecated `maxFundingRate` parameter.

**Function Signature:**

```solidity
function sendQuoteWithAffiliateAndData(
    address[] memory partyBsWhiteList,
    uint256 symbolId,
    PositionType positionType,
    OrderType orderType,
    uint256 price,
    uint256 quantity,
    uint256 cva,
    uint256 lf,
    uint256 partyAmm,
    uint256 partyBmm,
    uint256 deadline,
    address affiliate,
    SingleUpnlAndPriceSig memory upnlSig,
    bytes memory data
) external whenInstantModeIsNotActive(signer) whenNotPartyAActionsPaused notLiquidatedPartyA(signer) notSuspended(signer) returns (uint256 quoteId);
```

**Parameters:**

* All standard quote parameters (without `maxFundingRate`), plus:
* `affiliate`: The affiliate address associated with this quote.
* `data`: Arbitrary ABI-encoded data to attach to the quote.

**Returns:** The ID of the newly created quote.

**Example:**

```solidity
// Attach a tempQuoteId to the quote
bytes memory data = abi.encode(uint256(123), "hello-world");
uint256 quoteId = symmDiamond.sendQuoteWithAffiliateAndData(
    partyBsWhiteList, symbolId, positionType, orderType,
    price, quantity, cva, lf, partyAmm, partyBmm,
    deadline, affiliate, upnlSig, data
);
```

**Events Emitted:**

* Legacy `SendQuote(...)` event
* New `SendQuote(address partyA, uint256 quoteId, address[] partyBsWhiteList, address affiliate, bytes paramsData, bytes data)` — with the custom `data` included

***

### expireQuote()

Expires quotes or close requests that have passed their deadline. Can be called by anyone. For each quote ID provided:

* If the quote is in a pending state and past its deadline, it is expired (cancelled).
* If the quote has an expired close request, the close request is removed and the position returns to `OPENED` status.

**Function Signature:**

```solidity
function expireQuote(uint256[] memory expiredQuoteIds) external whenNotPartyAActionsPaused;
```

**Parameters:**

* `expiredQuoteIds`: An array of quote IDs to check and expire.

**Events Emitted (per quote):**

* `ExpireQuoteOpen(QuoteStatus status, uint256 quoteId)` — when a pending quote is expired
* `ExpireQuoteClose(QuoteStatus status, uint256 quoteId, uint256 closeId)` — when a close request is expired

***

### requestToCancelQuote()

Requests cancellation of a pending quote. The outcome depends on the quote's current status:

* **Not yet locked** (PENDING): The quote is cancelled immediately (status → `CANCELED` or `EXPIRED`).
* **Already locked** (LOCKED): The quote enters `CANCEL_PENDING` status. PartyB then decides whether to accept the cancellation or proceed with opening the position.

**Function Signature:**

```solidity
function requestToCancelQuote(uint256 quoteId) external whenInstantModeIsNotActive(signer) whenNotPartyAActionsPaused onlyPartyAOfQuote(quoteId) notLiquidated(quoteId);
```

**Parameters:**

* `quoteId`: The ID of the quote to cancel.

**Events Emitted:**

* `RequestToCancelQuote(address partyA, address partyB, QuoteStatus status, uint256 quoteId)` — when cancellation is requested or immediately cancelled
* `ExpireQuoteOpen(QuoteStatus status, uint256 quoteId)` — when the quote has expired

***

### requestToClosePosition()

Requests to close an open position. The quote must be in `OPENED` status. The close request enters `CLOSE_PENDING` status, waiting for PartyB to fill the close.

**Function Signature:**

```solidity
function requestToClosePosition(
    uint256 quoteId,
    uint256 closePrice,
    uint256 quantityToClose,
    OrderType orderType,
    uint256 deadline
) external whenInstantModeIsNotActive(signer) whenNotPartyAActionsPaused onlyPartyAOfQuote(quoteId) notLiquidated(quoteId);
```

**Parameters:**

* `quoteId`: The ID of the quote associated with the position to close.
* `closePrice`: The closing price. For limit orders, the exact price; for market orders, a price threshold.
* `quantityToClose`: The quantity of the position to close (can be partial).
* `orderType`: `LIMIT` (0) or `MARKET` (1).
* `deadline`: Expiration timestamp for the close request.

**Example:**

```solidity
// Request to close 50% of a position at a limit price
symmDiamond.requestToClosePosition(quoteId, closePrice, quantity / 2, OrderType.LIMIT, deadline);
```

**Events Emitted:**

* `RequestToClosePosition(address partyA, address partyB, uint256 quoteId, uint256 closePrice, uint256 quantityToClose, OrderType orderType, uint256 deadline, QuoteStatus status, uint256 closeId)`

***

### requestToCancelCloseRequest()

Requests cancellation of a pending close request. The outcome depends on the current state:

* **Close request expired:** The close request is removed immediately and the position returns to `OPENED`.
* **Close request still active:** The quote enters `CANCEL_CLOSE_PENDING` status. PartyB then decides whether to accept the cancellation or proceed with filling the close.

**Function Signature:**

```solidity
function requestToCancelCloseRequest(uint256 quoteId) external whenInstantModeIsNotActive(signer) whenNotPartyAActionsPaused onlyPartyAOfQuote(quoteId) notLiquidated(quoteId);
```

**Parameters:**

* `quoteId`: The ID of the quote whose close request should be cancelled.

**Events Emitted:**

* `RequestToCancelCloseRequest(address partyA, address partyB, uint256 quoteId, QuoteStatus status, uint256 closeId)` — when cancellation is requested
* `ExpireQuoteClose(QuoteStatus status, uint256 quoteId, uint256 closeId)` — when the close request has expired