# PartyB Group Actions Facet (0.8.4)

## PartyB Group Actions Facet (0.8.4)

The **PartyB Group Actions Facet** allows Party B users to secure a quote by locking it and then immediately opening a position using that locked quote. This atomic operation simplifies the process by combining two sequential steps—locking and opening—into a single transaction.

> **Context:**
>
> * **Lock Quote:**\
>   Once a user submits a quote, any Party B may lock the quote by providing sufficient funds based on their expected profit and loss. This reserves the quote so that no other Party B can act on it until the lock is released.
> * **Open Position:**\
>   After locking a quote, Party B may open a position. In doing so, they can choose to fill the entire requested amount or only a fraction. The process checks that the open portion of the quote meets the minimum value requirements, and it emits events based on the outcome (e.g., if a new quote is generated or if a cancellation request is accepted).

***

### lockAndOpenQuote()

The `lockAndOpenQuote` function is an atomic operation that first locks a specified quote and then opens a position for that quote. The function requires the caller to provide appropriate Muon signatures for both the locking and the opening steps.

Upon execution, it performs the following steps:

1. **Locking the Quote:**\
   It calls the internal `lockQuote` function (from the PartyBQuoteActionsFacetImpl) with a `SingleUpnlSig` signature to secure the quote. This step reserves the funds needed to open the position and prevents other Party B users from accepting the same quote.
   * Emits a `LockQuote` event with the Party B address and the quote ID.
2. **Opening the Position:**\
   It then calls the internal `openPosition` function (from the PartyBPositionActionsFacetImpl) with:
   * `filledAmount`: The amount with which Party B chooses to open the position. This can be the full amount requested or only a fraction.
   * `openedPrice`: The price at which the position is opened.
   * A `PairUpnlAndPriceSig` signature that includes both UPnL and price data for verification.
   * Emits an `OpenPosition` event with details including the quote ID, Party A and Party B addresses, the filled amount, and the opened price.
3. **Handling New Quotes:**\
   If the `openPosition` call returns a new quote ID (i.e. if a residual or new quote is generated due to partial filling), the function:
   * Emits a `SendQuote` event if the new quote remains in the pending state.
   * Otherwise, if the new quote has been canceled (indicating Party B accepted a cancel request), it emits an `AcceptCancelRequest` event.

**Function Signature:**

```solidity
function lockAndOpenQuote(
    uint256 quoteId,
    uint256 filledAmount,
    uint256 openedPrice,
    SingleUpnlSig memory upnlSig,
    PairUpnlAndPriceSig memory pairUpnlSig
) external whenNotPartyBActionsPaused onlyPartyB notLiquidated(quoteId);
```

**Parameters:**

* **quoteId:** The identifier of the quote to be locked and used for opening the position.
* **filledAmount:** The amount (or fraction) of the position that Party B chooses to open.
* **openedPrice:** The price at which the position is opened.
* **upnlSig:** A `SingleUpnlSig` structure containing the Muon signature for UPnL data, used during the locking step.

```solidity
struct SingleUpnlSig {
	bytes reqId;
	uint256 timestamp;
	int256 upnl;
	bytes gatewaySignature;
	SchnorrSign sigs;
}
```

* **pairUpnlSig:** A `PairUpnlAndPriceSig` structure containing the Muon signature for both UPnL and price data, used during the opening step.

```solidity
struct PairUpnlAndPriceSig {
	bytes reqId;
	uint256 timestamp;
	int256 upnlPartyA;
	int256 upnlPartyB;
	uint256 price;
	bytes gatewaySignature;
	SchnorrSign sigs;
}
```

**Example Usage:**

```solidity
// Example: Party B locks and opens a quote in one atomic operation.
uint256 quoteId = 101;
uint256 filledAmount = 100;  // Party B chooses to fill 100 units (can be a fraction of the requested amount)
uint256 openedPrice = 1050;  // The price at which the position is opened

// Assume upnlSig and pairUpnlSig are obtained through off-chain signing processes.
SingleUpnlSig memory upnlSig = /* obtain UPnL signature data */;
PairUpnlAndPriceSig memory pairUpnlSig = /* obtain UPnL and price signature data */;

diamond.lockAndOpenQuote(quoteId, filledAmount, openedPrice, upnlSig, pairUpnlSig);
```

```solidity
struct PairUpnlAndPriceSig {
	bytes reqId;
	uint256 timestamp;
	int256 upnlPartyA;
	int256 upnlPartyB;
	uint256 price;
	bytes gatewaySignature;
	SchnorrSign sigs;
}
```

**Events Emitted:**

* **LockQuote:**\
  Emitted immediately after the quote is successfully locked.

  ```solidity
  event LockQuote(address indexed partyB, uint256 quoteId);
  ```
* **OpenPosition:**\
  Emitted after opening the position, providing details such as the quote ID, Party A, Party B, filled amount, and opened price.

  ```solidity
  event OpenPosition(uint256 quoteId, address partyA, address partyB, uint256 filledAmount, uint256 openedPrice);
  ```
* **SendQuote (optional):**\
  If a new quote is generated and its status is PENDING, a `SendQuote` event is emitted with full quote details.
* **AcceptCancelRequest (optional):**\
  If the new quote is canceled, an `AcceptCancelRequest` event is emitted indicating that the cancellation was accepted.