Trade Facet

The Trade Facet manages the lifecycle of trades once they exist as live positions. It handles:

• Transferring trade ownership between parties (with optional NFT synchronisation)

• Executing trades that have reached their expiration

• Minting NFTs to represent trade ownership on-chain.

Key Concepts:

• Trade Transfer: PartyA can transfer ownership of their side of an open trade to another address. The new address steps into PartyA's role for all protocol purposes — including receiving settlement proceeds and being responsible for margin.

• Trade NFT: An optional ERC-721 that represents PartyA's ownership of a specific trade on-chain. When an NFT exists for a trade, transferring the NFT also transfers the trade — keeping ownership in sync between the NFT contract and protocol storage.

• Settlement Price Signature: A Muon oracle signature containing the verified price of the underlying at the option's expiration time, plus the collateral price. This is the trusted input used to determine whether an option is exercised or expires worthless.

• Exercised vs. Expired: When executeTrades() settles a batch of trades, each trade is assessed against the settlement price and results in the option being exercised (in-the-money, PartyA receives proceeds) or expired (out-of-the-money, the option is worthless).

transferTrade()

Transfers ownership of a trade's PartyA role to a new address. After the transfer, the receiver becomes the effective PartyA.

Function Signature:

function transferTrade(
    address receiver,
    uint256 tradeId
) external nonReentrant whenPartyNotPaused(msg.sender) onlyPartyAOfTrade(tradeId) whenNotSuspended(msg.sender) whenNotSuspended(receiver);

Parameters:

• receiver: The address that will become the new PartyA for this trade. Must not be suspended.

• tradeId: The unique identifier of the trade to transfer. The caller must currently be the PartyA of this trade.

Internal Logic:

• Event: Emits TransferTradeByPartyA with the old owner (msg.sender), the new owner (receiver), and the tradeId.

---

transferTradeFromNFT()

The inverse flow of transferTrade() — instead of PartyA initiating the protocol-side transfer and the NFT following, here the NFT contract has already transferred and is now notifying the protocol to catch up. This function is intended to be called exclusively by the trade NFT contract itself as part of its transfer hook.

Function Signature:

function transferTradeFromNFT(
    address sender,
    address receiver,
    uint256 tradeId
) external whenPartyNotPaused(sender) whenNotSuspended(sender) whenNotSuspended(receiver);

Parameters:

• sender: The previous owner of the trade and NFT.

• receiver: The new owner who will receive the protocol-side trade ownership.

• tradeId: The trade whose ownership record needs to be updated.

---

executeTrades()

Settles a batch of options trades that have reached their expiration timestamp. The caller provides a Muon-signed settlement price for the underlying symbol, and the protocol independently determines whether each trade in the batch is exercised (in-the-money) or expires worthless.

Function Signature:

function executeTrades(
    uint256[] calldata tradeIds,
    SettlementPriceSig calldata settlementPriceSig
) external whenNotThirdPartyActionsPaused;

Parameters:

• tradeIds: An array of trade IDs to settle. All trades in the batch must reference the same symbol, since a single settlement price signature is provided for the call.

• settlementPriceSig: A SettlementPriceSig struct containing:

  • The settlement price of the underlying at expiration, verified by the Muon oracle network.

  • The collateral price at the time of settlement, used for calculating payout values.

  • A signature over the above data that the protocol validates before proceeding.

Internal Logic:

• For each trade in the batch, the library compares the settlement price against the trade's strike price and tradeSide to determine the outcome:

  • Exercised: The option is in-the-money. P&L is calculated and cross balances are settled between PartyA and PartyB accordingly.

  • Expired: The option is out-of-the-money or at-the-money (depending on the option type). The position closes with no payout to the option holder.

• Returns: Two parallel boolean arrays — exercised[] and expired[] — indicating the outcome for each trade in the input batch. The facet passes these directly to the event.

• Event: Emits ExecuteTrades with the caller, the full tradeIds array, the exercised and expired boolean arrays, the settlement price, and the collateral price.

---

mintNFTForTrade()

Creates an ERC-721 NFT representing PartyA's ownership of a specific trade. Once minted, the NFT and the trade are linked. Transferring the NFT will automatically trigger transferTradeFromNFT() to keep protocol ownership in sync.

Function Signature:

function mintNFTForTrade(uint256 tradeId) external nonReentrant onlyPartyAOfTrade(tradeId);

Parameters:

• tradeId: The unique identifier of the trade to mint an NFT for. The caller must be the current PartyA of this trade.

---

Events

event TransferTradeByPartyA(address indexed sender, address indexed receiver, uint256 indexed tradeId);
event ExecuteTrades(
    address indexed caller,
    uint256[] tradeIds,
    bool[] exercised,
    bool[] expired,
    uint256 settlementPrice,
    uint256 collateralPrice
);