Cancel

Cancelling a settlement stops an open exchange and returns locked assets to the original senders. Use cancellation before execution or expiry when the exchange should no longer proceed. The contract either cancels immediately or records a cancel vote, depending on whether the settlement is armed for external flows.

What cancellation does

Cancellation is final. Once a settlement is cancelled, it cannot execute and the locked assets are refunded from escrow to the senders that provided them.

The cancellation rule depends on settlement state:

Where to go next

Different readers need different next steps from the cancellation model:

How to cancel

Call the cancel endpoint with the settlement contract address. The API queues a transaction that calls the settlement contract's proposeCancel function.

PUT /xvp/cancel
Content-Type: application/json

{
  "settlementAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
  "walletVerification": {
    "secretVerificationCode": "YOUR_PINCODE"
  }
}

For local settlements and HTLC settlements that are not fully approved, the call cancels the settlement immediately. No other participant approval is required.

For armed HTLC settlements, the same endpoint records the caller's cancel vote. The settlement remains open until every local participant has voted to cancel. The final required vote cancels the settlement and refunds the locked assets.

Production checks

Before you cancel, check the settlement state and choose the correct action:

• If the settlement has not executed, has not expired, and has no revealed secret, use cancellation.
• If the settlement has external flows and every local sender has approved, treat cancellation as a unanimous vote.
• If the settlement has expired, do not retry cancellation. The contract rejects cancel attempts after the cutoff with XvPSettlementExpired; use Withdraw expired instead.
• If a participant has voted to cancel an armed HTLC settlement and the secret has not been revealed, they can retract their vote with the withdraw-cancel endpoint.
• If the secret has been revealed, cancellation and cancel-vote withdrawal are no longer available.

For step-by-step procedures, use the settlement-specific guides:

Audit notes

Cancellation is constrained on-chain:

• The caller must be a local participant.
• The settlement must be open: not executed, not cancelled, and before the cutoff.
• The contract rejects cancellation after the HTLC secret is revealed.
• Armed HTLC cancellation votes are tracked on-chain with cancel-vote cast and withdrawal events.
• A cancel vote can be withdrawn only for an armed external-flow settlement that is fully approved, still open, and has no revealed secret.