Skip to main content

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 a timeoutBlockHeight.
  • 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.
Your app must be running to claim. Check open swaps on start, on resume, and on a schedule.

Following a swap

WebSocket

A dead socket reports no error, which happens on mobile after the app is backgrounded. Check 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.
Lost your local records? See Keys and recovery.