On-chain → Lightning (submarine)
Failure states:
invoice.failedToPay, transaction.lockupFailed (wrong amount), swap.expired. In each case, refund your lockup.
Lightning → on-chain (reverse)
Failure states:
invoice.expired and swap.expired (nothing was paid), transaction.failed and transaction.refunded (the maker’s lockup failed or was refunded; your Lightning payment is released).
Chain → chain
Failure states:
transaction.lockupFailed, swap.expired, transaction.failed, transaction.refunded. Refund your lockup. If you locked a different amount than quoted, the maker may offer a re-quote instead; see Move funds between chains.
Deadlines
Every lockup has atimeoutBlockHeight.
- Claims must confirm before it. After the deadline, the other side can refund. The SDK’s claim helpers stop 6 blocks early on Bitcoin and 60 on Liquid by default.
- Refunds through the script path open at it. Before it, a refund needs the maker to co-sign.
- Chain swaps have two deadlines: the source chain’s for your refund, the destination chain’s for your claim.
Following a swap
WebSocket
isConnected() and fall back to polling.
Polling
client.swap(id) (get_swap in Python) returns the current status. Poll it on start, on resume, and after a reconnect.
A status is the maker’s report, not proof. Before you claim, check the lockup on your own chain backend. Before you refund, check the chain tip against the deadline. See Trust model.