Stage: Confirm Settlement & Failure Handling

📝 Overview After a successful payment confirmation (confirmPayment()), the trade advances to the CONFIRM_SETTLEMENT stage. During this finalization phase, the MPC is responsible for settling the trade by releasing the locked funds to the selected PMM on the source chain. Once the release transaction is executed, the MPC finalizes the trade by calling confirmSettlement(), submitting the corresponding releaseTxId, and transitioning the trade to the COMPLETED stage. However, if unexpected issues arise—such as a network failure and the user already claiming a refund—the MPC must report the failure using the report() function. This marks the trade as FAILURE, permanently halting its progression.

Key responsibilities of the MPC in this stage:

  • Initiates settlement by releasing funds to the PMM.

  • Confirms successful settlement via confirmSettlement().

  • Flags a failed trade through report() if settlement cannot be completed.

⚠️ Important: When a failure is reported, the MPC is penalized and held accountable for compensating the PMM’s loss.

Possible Scenarios

✅ Successful Settlement Confirmation

  • The MPC successfully releases funds to the PMM on the source chain.

  • It then calls confirmSettlement(), providing the releaseTxId.

  • The trade progresses to the COMPLETED stage.

  • A SettlementConfirmed event is emitted, recording final transaction details.

  • The trade is finalized and can no longer be modified.

❌ Settlement Failure

  • If the MPC cannot complete the settlement (e.g., due to network failure and if the user has already claimed a refund), it must call report().

  • The trade is marked as FAILURE, and further actions are disallowed.

  • A FailureReported event is emitted to ensure transparency and traceability.

  • The MPC includes the failed transaction details for auditing purposes.

✅ On Successful Settlement: confirmSettlement()

function confirmSettlement(bytes32 tradeId, bytes calldata releaseTxId, bytes calldata signature) external;

🔐 Permissioned Execution

  • Only callable through the Router contract.

  • The requester must be an authorized MPC Node.

🔎 Trade Stage Validation

  • Ensures the trade is in the CONFIRM_SETTLEMENT stage.

  • scriptTimeout is not checked at this stage.

🔑 Signature Validation

  • Uses EIP-712 signing with a domain separator to ensure data integrity and prevents spoofing or tampering.

  • Validates that the signer is an MPC signer for the specified source chain.

🔁 Trade State Transition

  • Updates the trade stage to COMPLETED.

  • Stores the releaseTxId in the finalization record.

  • Removes the trade from the pending queue.

📢 Event Emission

  • Emits a SettlementConfirmed event, containing relevant information, which signals the completion of the trade.

❌ On Unexpected Incidents

function report(bytes32 tradeId, bytes calldata msgError, bytes calldata signature) external;

📝 Note When settlement cannot be completed, the MPC must report the failure to terminate the trade gracefully and responsibly.

🔐 Permissioned Execution

  • Can only be called through the Router contract.

  • The requester must be an authorized MPC Node.

🔎 Constraints & Behavior

  • The trade must not already be in a final state (COMPLETED, FAILURE, or REFUNDED).

  • Reporting transitions the trade immediately without delay.

⚠️ Valid Reasons to Report Failure

  • Chain-level issues preventing settlement.

  • Internal MPC coordination failure.

  • Refund already claimed by the user.

🔑 Signature Verification

  • The failure message is signed using EIP-712 format to ensure authenticity.

  • The signer must be a valid MPC signer for the relevant source chain.

🔁 Trade State Transition

  • Stores the failure reason and marks the stage in which the failure occurred (CONFIRM_SETTLEMENT).

  • Transitions the trade to the FAILURE stage, leading to a final REFUNDED status if appropriate.

📢 Event Emission

  • Emits a FailureReported event including the failed stage and error message, providing transparency for off-chain monitoring and analysis.

Queryable Trade Data

📝 Note After the settlement confirmation phase—whether the trade advances to COMPLETED or transitions to FAILURE—several public view functions become available to query related data and track trade progress. These are essential for frontend rendering, auditability, and off-chain monitoring.

✅ On Successful Settlement

🔍 Get Trade Stage

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

Returns the current stage of the trade (e.g., COMPLETED).

🔍 Get Trade Finalization

function getTradeFinalization(bytes32 tradeId) external view returns (TradeFinalization memory);

Returns the finalization details for the trade, including paymentTxId and releaseTxId, to support future audits.

❌ On Unexpected Incidents

🔍 Get Trade Stage

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

Returns the current stage of the trade (e.g., FAILURE).

🔍 Get failure details

function getFailureInfo(bytes32 tradeId) external view returns (FailureDetails memory)

Returns the error metadata associated with the failed trade, including the stage and reason for failure.

PreviousStage: Confirm Payment & Failure HandlingNextStage: Refund