Force Actions Facet (0.8.4)

The Force Actions Facet enables users to take action in situations where counterparties are unresponsive or when market conditions require intervention. It includes methods for:

• Forcing the cancellation of quotes or close requests.

• Forcing the closure of positions.

• Settling UPnLs for the hedger and then forcing the closure of a position.

These functions help protect the system from prolonged exposure to risk and ensure that positions can be closed even when normal procedures fail.

---

forceCancelQuote()

Forces the cancellation of a quote when Party B is unresponsive. This function requires that the quote is in a CANCEL_PENDING state and that the force-cancellation cooldown has elapsed. It then updates the quote’s status to CANCELED and returns any locked fees to Party A.

Function Signature:

function forceCancelQuote(uint256 quoteId) external notLiquidated(quoteId) whenNotPartyAActionsPaused;

Parameters:

• quoteId: The unique identifier of the quote to be canceled.

Example Usage:

// Force cancel a quote with ID 42
diamond.forceCancelQuote(42);

Events Emitted:

• ForceCancelQuote(uint256 quoteId, QuoteStatus quoteStatus)

---

forceCancelCloseRequest()

Force-cancels a pending close request when Party B fails to respond within the designated cooldown period. This function updates the quote status back to OPENED (thus canceling the close request) and resets associated close parameters.

Function Signature:

function forceCancelCloseRequest(uint256 quoteId) external notLiquidated(quoteId) whenNotPartyAActionsPaused;

Parameters:

• quoteId: The unique identifier of the quote for which the close request is to be canceled.

Example Usage:

// Force cancel the close request for quote ID 42
diamond.forceCancelCloseRequest(42);

Events Emitted:

• ForceCancelCloseRequest(uint256 quoteId, QuoteStatus quoteStatus, uint256 closeId)

• (For backward compatibility, an additional event is emitted without the closeId.)

---

forceClosePosition()

Force‑closes an open position when market conditions satisfy the force‑close criteria and Party B is either unresponsive or fails to maintain sufficient allocated balance. This function ensures that the quote is in a CLOSE_PENDING state and that all force‑close conditions are met. The conditions include:

• Cooldown Periods:

  • The startTime specified in the HighLowPriceSig must be at least quote.statusModifyTimestamp + forceCloseFirstCooldown, ensuring that the hedger had enough time to consider the close request.

  • The endTime must be less than or equal to both quote.deadline and block.timestamp - forceCloseSecondCooldown, ensuring that the hedger had sufficient time to fill the close.

• Timeframe Requirement: If the force‑close results in using the average price (to protect against extreme market moves), the timeframe (endTime - startTime) must exceed forceCloseMinSigPeriod.

• Price Verification Based on Position Type:

  • For LONG positions: The function checks whether the highest price in the specified timeframe meets or exceeds the requested close price plus a gap ratio (a percentage buffer that accounts for market fluctuations).

    • If true, the close price is set to the requested close price plus a penalty ratio.

    • The final close price is then the higher value between this computed price and the average price over the timeframe.

  • For SHORT positions: The function verifies that the lowest price is less than or equal to the requested close price minus the gap ratio.

    • If true, the close price is computed as the requested close price minus the penalty ratio.

    • The final close price is the lower value between this computed price and the average price.

• Signature Verification: The function uses the new HighLowPriceSig structure to verify that the market data (high, low, average, and current prices) is authentic and within the acceptable timeframe. This signature is obtained via the priceRange method on Muon.

After all validations pass, the function updates nonce counters for both Party A and Party B, and then calls an internal helper to close the quote. If conditions fail (for example, if the market does not meet the necessary thresholds), Party B may instead be liquidated.

---

Function Signature:

function forceClosePosition(uint256 quoteId, HighLowPriceSig memory sig)
    external
    notLiquidated(quoteId)
    whenNotPartyAActionsPaused;

Parameters:

• quoteId: The unique identifier of the quote associated with the position.

• HighLowPriceSig:

struct HighLowPriceSig {
	bytes reqId;
	uint256 timestamp;
	uint256 symbolId;
	uint256 highest;
	uint256 lowest;
	uint256 averagePrice;
	uint256 startTime;
	uint256 endTime;
	int256 upnlPartyB;
	int256 upnlPartyA;
	uint256 currentPrice;
	bytes gatewaySignature;
	SchnorrSign sigs;
}

---

Events Emitted:

LiquidatePartyB: If the validations determine that Party B is insolvent (e.g., if closing the position would leave Party B with insufficient funds), an event is emitted to indicate liquidation:

event LiquidatePartyB(address initiator, address partyB, address partyA, uint256 partyBAllocatedBalance, int256 upnlPartyB);

ForceClosePosition: If the force‑close operation completes successfully, the following event is emitted:

event ForceClosePosition(
    uint256 quoteId,
    address partyA,
    address partyB,
    uint256 filledAmount,
    uint256 closedPrice,
    QuoteStatus quoteStatus,
    uint256 closeId
);

(A backward compatibility event without closeId is also emitted.)

---

settleAndForceClosePosition()

This method extends the force close mechanism to handle cases where the hedger (Party B) lacks sufficient allocated balance to close the position. In such scenarios, the function first settles the UPnL (unrealized profit and loss) for Party B, thereby adjusting the balances, and then force-closes the position.

Function Signature:

function settleAndForceClosePosition(
    uint256 quoteId,
    HighLowPriceSig memory highLowPriceSig,
    SettlementSig memory settleSig,
    uint256[] memory updatedPrices
) external notLiquidated(quoteId) whenNotPartyAActionsPaused;

Parameters:

• quoteId: The unique identifier of the quote corresponding to the position.

• highLowPriceSig: A HighLowPriceSig structure containing market price data (including high, low, average, and current prices) and the associated timing information.

struct HighLowPriceSig {
	bytes reqId;
	uint256 timestamp;
	uint256 symbolId;
	uint256 highest;
	uint256 lowest;
	uint256 averagePrice;
	uint256 startTime;
	uint256 endTime;
	int256 upnlPartyB;
	int256 upnlPartyA;
	uint256 currentPrice;
	bytes gatewaySignature;
	SchnorrSign sigs;
}

• settleSig: A SettlementSig structure that includes data required for settling UPnLs (such as settlement values, quotes settlements data, etc.).

struct SettlementSig {
	bytes reqId;
	uint256 timestamp;
	QuoteSettlementData[] quotesSettlementsData;
	int256[] upnlPartyBs;
	int256 upnlPartyA;
	bytes gatewaySignature;
	SchnorrSign sigs;
}

• updatedPrices: An array of updated prices to be applied as the new opened prices for the specified quotes during settlement.

Example Usage:

// Settle and force close a position with updated price data
HighLowPriceSig memory highLowSig = /* obtain high/low signature data */;
SettlementSig memory settleSig = /* obtain settlement data */;
uint256[] memory newPrices = new uint256[](1);
newPrices[0] = updatedPrice;
diamond.settleAndForceClosePosition(42, highLowSig, settleSig, newPrices);

Events Emitted:

• If Party B is liquidated during the process, the event: LiquidatePartyB(address initiator, address partyB, address partyA, uint256 partyBAllocatedBalance, int256 upnlPartyB) is emitted.

• Otherwise, two key events are emitted:

  • SettleUpnl(...): Emitted with details of the settlement, including the settlement data, updated prices, and new allocated balances.

  • ForceClosePosition(...): Emitted to indicate the successful force closure of the position (with both the current and a backward compatibility version).