Stage: Trade Initialization

📝 Overview The trade initialization is executed after the user deposits funds into the designated Vault on the source asset-chain network (e.g. Bitcoin, an EVM-compatible network, or Solana). The deposit does not need to be confirmed at this stage. A Solver submits the trade via the Router contract while the trade is still pending confirmation of the actual deposit.

function submitTrade(
    bytes32 tradeId,
    TradeData calldata tradeData,
    Affiliate calldata affiliateInfo,
    SettlementPresign[] calldata settlementPresigns,
    RefundPresign calldata refundPresign
) external;

🔐 Permissioned Execution

• Must be called via the Router contract.

• Caller must be an authorized Solver.

🔎 Trade Stage Validation

• Stage & Trade ID Validation:

  • Trade must be in the SUBMIT stage.

  • Validates that the provided tradeId matches the expected ID derived from session-specific inputs (e.g., solver, sessionId).

• Timeout Validation:

  • Verifies the trade has not expired (scriptTimeout).

• Token & Network Whitelisting:

  • Both source and destination chains/tokens must be whitelisted via the Management contract.

• MPC Key Validation:

  • Ensures mpcAssetPubkey is active and not expired.

• PMM Check:

  • Each participating PMM must be registered in the Management contract.

• Affiliate Fee Check:

  • Total affiliate fees must not exceed the protocol-defined maximum.

• Refund Presign:

  • Bitcoin trades: A valid refundPresign must be provided for MPC validation.

  • EVM/Solana: the pre-signature must be empty, and the refundAddress must match the address in tradeData.

  • MPC will verify them in the CONFIRM_DEPOSIT stage.

• Settlement Presigns:

  • User-submitted signatures are stored but not validated at this stage.

  • MPC will verify them in the CONFIRM_DEPOSIT stage.

💸 Fee Calculation:

• EVM/Solana trades:

  • Protocol and affiliate fees are computed and recorded at submission time.

• Bitcoin trades:

  • Protocol fee is deferred and calculated during PMM selection using committed_quote.

• Fee Details: pFeeAmount (Protocol Fee) and aFeeAmount (Affiliate Fee) both are derived from the trade amount and respective rates.

🔁 Trade State Transition

• Trade progresses to the CONFIRM_DEPOSIT stage.

• Trade details, pre-signatures, and fee amounts are recorded on-chain.

📢 Event Emission

• Emits a TradeInfoSubmitted event containing key trade information. This event serves as a signal for the MPC to begin monitoring and processing the next step.

Queryable Trade Data

📝 Note Once a trade is successfully submitted, the following trade-related information becomes queryable via public view functions. These can be used to retrieve the trade's state, configuration, and associated metadata:

🔍 Get Trade Stage

function getCurrentStage(bytes32 tradeId) external view returns (uint256);

Returns the current stage of the specified trade.

🔍 Get Trade Data

function getTradeData(bytes32 tradeId) external view returns (TradeData memory);

Returns all submitted trade information, including amounts, chains, addresses, and others.

🔍 Get Settlement Presigns

function getSettlementPresigns(bytes32 tradeId) external view returns (SettlementPresign[] memory);

Returns user-submitted settlement pre-signatures for the trade. These are validated by the MPC during the settlement phase.

🔍 Get Refund Presign

function getRefundPresigns(bytes32 tradeId) external view returns (RefundPresign memory);

Returns the refund presignature submitted during trade creation.

🔍 Get Affiliate Info

function getAffiliateInfo(bytes32 tradeId) external view returns (Affiliate memory);

Returns the affiliate configuration for the trade, including destination address and fee percentage.