PartyA Facet (0.8.4)

Party A Facet (0.8.4)

The Party A Facet is the primary interface for Party A users to interact with the SYMM protocol. It enables users to send trade quotes (with optional affiliate information), cancel quotes, and request the closure or cancellation of a position. The underlying logic is implemented in the PartyAFacetImpl library, while this contract serves as the external API and emits events to reflect state changes.

Note: This facet ensures that only eligible Party A users (i.e. not liquidated or suspended) can perform these actions. In addition, some events are emitted for backward compatibility and may be removed in future versions.

sendQuoteWithAffiliate()

Sends a new quote to the protocol with an affiliate. The Affiliate is the frontend's MultiAccount address. The quote is initially set to a pending state and includes parameters for allowed Party B addresses, symbol details, position and order types, pricing, risk parameters (such as CVA, liquidation fee, and maintenance margins), and a Muon signature for UPnL and price verification.

Frontends use sendQuoteWithAffiliate() to facilitate trades. This is primarily to help track fees.

Function Signature:

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 whenNotPartyAActionsPaused notLiquidatedPartyA(msg.sender) notSuspended(msg.sender) returns (uint256 quoteId);

Parameters:

  • partyBsWhiteList: Array of Party B addresses allowed to interact with this quote.

  • symbolId: Unique identifier for the trading symbol (e.g. BTCUSDT).

  • positionType: Position type, either LONG or SHORT.

enum PositionType {
	LONG, //0 for long
	SHORT //1 for short
}

  • orderType: Order type, either LIMIT or MARKET.

enum OrderType {
	LIMIT, //0 For limit
	MARKET //1 for market
}

  • price: For limit orders, the desired open price; for market orders, the price threshold.

  • quantity: The size of the position.

  • cva: Credit Valuation Adjustment value.

  • lf: Liquidation Fee, representing the penalty that the liquidated side must pay.

  • partyAmm: Party A Maintenance Margin value.

  • partyBmm: Party B Maintenance Margin value.

  • maxFundingRate: The maximum funding rate allowed.

  • deadline: Timestamp by which Party B must act on the quote.

  • affiliate: Address of the affiliate associated with this quote.

  • upnlSig: A structure containing the Muon signature for user UPnL and symbol price verification.

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

Example Usage:

address[] memory allowedPartyBs = new address[](2);
allowedPartyBs[0] = partyBAddress1;
allowedPartyBs[1] = partyBAddress2;
uint256 quoteId = diamond.sendQuoteWithAffiliate(
    allowedPartyBs,
    1,                   // symbolId
    0,                   // positionType
    1,                     // orderType
    1000,                // price
    10,                  // quantity
    50,                  // cva
    20,                  // lf
    500,                 // partyAmm
    300,                 // partyBmm
    1e18,                // maxFundingRate
    block.timestamp + 3600, // deadline
    affiliateAddress,    // affiliate
    upnlAndPriceSignature // upnlSig
);

Events Emitted:

  • SendQuote(address sender, uint256 quoteId, address[] partyBsWhiteList, uint256 symbolId, PositionType positionType, OrderType orderType, uint256 price, uint256 upnlPrice, uint256 quantity, uint256 cva, uint256 lf, uint256 partyAmm, uint256 partyBmm, uint256 tradingFee, uint256 deadline)

sendQuote()

Sends a new quote to the protocol without affiliate information. This function behaves similarly to sendQuoteWithAffiliate but sets the affiliate field to the zero address.

Function Signature:

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 whenNotPartyAActionsPaused notLiquidatedPartyA(msg.sender) notSuspended(msg.sender);

Parameters: The parameters are identical to sendQuoteWithAffiliate except that the affiliate parameter is omitted (and implicitly set to address(0)).

enum PositionType {
	LONG,
	SHORT
}
enum OrderType {
	LIMIT,
	MARKET
}

Example Usage:

uint256 quoteId = diamond.sendQuote(
allowedPartyBs,
    1,                   // symbolId
    0,                   // positionType
    1,                     // orderType
    1000e18,                // price
    10e18,                  // quantity
    50e16,                  // cva
    20e16,                  // lf
    10000e18,                 // partyAmm
    0,                 // partyBmm
    200e18,                // maxFundingRate
    block.timestamp + 3600, // deadline
    upnlAndPriceSignature // upnlSig
);

Events Emitted:

  • SendQuote(...) (The same event is emitted as in sendQuoteWithAffiliate.)

expireQuote()

Expires one or more quotes based on their deadlines. If a quote has expired, it will be canceled or marked as closed. The function iterates over an array of quote IDs and emits corresponding events for each quote depending on its new state.

Function Signature:

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

Parameters:

  • expiredQuoteIds: An array of quote IDs that are to be expired.

Example Usage:

uint256[] memory quotesToExpire = new uint256[](2);
quotesToExpire[0] = 101;
quotesToExpire[1] = 102;
diamond.expireQuote(quotesToExpire);

Events Emitted:

  • Depending on the resulting quote status:

    • ExpireQuoteClose(QuoteStatus, uint256, uint256) for quotes that are closed.

    • ExpireQuoteOpen(QuoteStatus, uint256) for quotes that are opened.

    • ExpireQuote(QuoteStatus, uint256) for backward compatibility.

requestToCancelQuote()

Allows Party A to request the cancellation of a quote. If the quote has not been locked, it is canceled immediately; if locked, the quote’s status is set to CANCEL_PENDING.

Function Signature:

function requestToCancelQuote(uint256 quoteId) external whenNotPartyAActionsPaused onlyPartyAOfQuote(quoteId) notLiquidated(quoteId);

Parameters:

  • quoteId: The identifier of the quote to cancel.

Example Usage:

diamond.requestToCancelQuote(101);

Events Emitted:

  • If the quote expires:

    • ExpireQuoteOpen(QuoteStatus, uint256, uint256) and ExpireQuote(QuoteStatus, uint256)

  • If canceled or pending cancellation:

    • RequestToCancelQuote(address partyA, address partyB, QuoteStatus quoteStatus, uint256 quoteId)

requestToClosePosition()

Requests the closure of an open position by specifying the desired close price, the quantity to close, the order type for closure, and a deadline. The quote’s status is updated to CLOSE_PENDING.

Function Signature:

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

Parameters:

  • quoteId: The ID of the quote associated with the position.

  • closePrice: The price at which Party A wishes to close the position.

  • quantityToClose: The quantity of the position to close.

  • orderType: The order type (LIMIT or MARKET) for closing.

  • deadline: The timestamp by which Party B must respond; otherwise, the close request may time out.

Example Usage:

diamond.requestToClosePosition(101, 990, 5, OrderType.LIMIT, block.timestamp + 1800);

Events Emitted:

  • RequestToClosePosition(address partyA, address partyB, uint256 quoteId, uint256 closePrice, uint256 quantityToClose, OrderType orderType, uint256 deadline, QuoteStatus quoteStatus, uint256 closeId)

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

requestToCancelCloseRequest()

Allows Party A to cancel a pending close request. If the close request has not been fulfilled and is within the deadline, the quote’s status is updated accordingly.

Function Signature:

function requestToCancelCloseRequest(uint256 quoteId) external whenNotPartyAActionsPaused onlyPartyAOfQuote(quoteId) notLiquidated(quoteId);

Parameters:

  • quoteId: The ID of the quote whose close request is to be canceled.

Example Usage:

diamond.requestToCancelCloseRequest(101);

Events Emitted:

  • If the quote reopens due to expiry:

    • ExpireQuoteClose(QuoteStatus, uint256, uint256) and ExpireQuote(QuoteStatus, uint256)

  • Otherwise, if the cancellation is pending:

    • RequestToCancelCloseRequest(address partyA, address partyB, uint256 quoteId, QuoteStatus quoteStatus, uint256 closeId)

    • (Also a backward compatibility event without closeId is emitted.)

PreviousLiquidations Facet (0.8.4)NextPartyB Group Actions Facet (0.8.4)

Last updated