HTLC settlements
Learn how to cancel an HTLC settlement. Before arming, any participant can cancel. After arming, all local participants must vote to cancel unanimously.
Cancelling an HTLC settlement returns all locked assets to their original senders. The cancellation process depends on whether the settlement is armed (all approvals received).
Cancellation rules
| Settlement state | Who can cancel | How |
|---|---|---|
| Pending (not all approved) | Any local participant | Unilateral |
| Armed (all approved) | All local participants must agree | Voting (propose cancel) |
| Secret revealed | Cannot cancel | - |
| Executed | Cannot cancel | - |
| Expired | N/A - use withdraw | - |
Before armed (pending state)
When not all parties have approved, any local participant can cancel unilaterally.
Steps
Open the settlement
Navigate to Settlements and find the HTLC settlement you want to cancel.
Cancel the settlement
Click Cancel on the settlement detail page.
Review the confirmation and click Confirm.
Verify cancellation
The settlement status changes to Cancelled and all locked assets are returned.
After armed (voting mechanism)
Once an HTLC settlement enters the Armed state (all local senders have approved), unilateral cancellation is no longer allowed. This protects parties who have already committed assets on other chains.
Instead, cancellation requires unanimous agreement from all local participants through a voting mechanism.
All participants must vote
Every local participant (sender and recipient in local flows) must propose cancellation. The settlement is cancelled only when the final vote is received.
How the voting mechanism works
- Any local participant can propose cancellation
- The settlement tracks how many participants have voted
- Participants can withdraw their proposal before the final vote
- When ALL local participants have voted, the settlement is automatically cancelled
Steps to propose cancellation
Open the settlement
Navigate to Settlements and find the armed HTLC settlement.
Propose cancellation
Click Propose Cancel on the settlement detail page.
Confirm the transaction. Your vote is recorded on-chain.
Wait for other participants
The settlement shows the current vote count. Contact other participants and ask them to also propose cancellation.
Final vote triggers cancellation
When the last participant proposes cancellation, the settlement is automatically cancelled and all assets are returned.
Withdrawing a cancel proposal
If you change your mind before the final vote, you can withdraw your proposal:
- Open the armed settlement
- Click Withdraw Cancel Proposal
- Confirm the transaction
Your vote is removed and the settlement remains armed.
What happens after cancellation
- All escrowed assets are returned to their original sender addresses
- The settlement permanently enters Cancelled state
- No further actions can be taken on this settlement
Why armed settlements require unanimous voting
The voting requirement exists because:
- Parties may have already committed assets on other chains
- Unilateral cancellation could leave counterparties stranded
- Unanimous agreement ensures all parties consent to unwinding the settlement
If you cannot reach unanimous agreement, wait for the cutoff date to pass and use Withdraw expired.
Troubleshooting
| Issue | Solution |
|---|---|
| Cancel button not visible | You must be a local participant (sender or recipient in a local flow) |
| "Propose Cancel" shown instead of "Cancel" | Settlement is armed - all local participants must vote to cancel |
| Settlement not cancelling | Not all participants have voted yet - check the vote count |
| Cannot propose cancel | Secret may have been revealed, making cancellation impossible |
| Want to undo my cancel vote | Click "Withdraw Cancel Proposal" before the final vote is cast |