How the swaps work
A swap moves value between Lightning and on-chain bitcoin without either side trusting the other to hand it over. Two locked legs share one secret, and releasing that secret is what pays both.
Two legs, one secret
A swap is two transfers joined by a single 32-byte number, the preimage. Its hash - the payment hash - is written into both legs before anything moves:
- the on-chain leg is an output locked to a script that pays whoever can produce the preimage;
- the Lightning leg is a BOLT11 invoice whose payment hash is that same hash.
Taking the on-chain leg means revealing the preimage on chain, and that same preimage is what settles the Lightning payment. Neither leg can be taken without the other, so there is no moment where one side has the money and the other has nothing.
The on-chain leg
The on-chain leg is a P2WSH hash time-locked contract: one output with exactly two ways to spend it.
- claim - anyone holding the preimage, signed by a key chosen for this swap;
- refund - the funder, signed by its own key, but only after a locktime has passed.
The funder can always get its money back once the timeout opens. The counterparty can always take it with the preimage. That asymmetry is the whole mechanism: nobody needs to be trusted, because either side can exit on its own. The script page walks through it opcode by opcode.
The Lightning leg
The Lightning leg is an ordinary BOLT11 invoice that both sides already agree on. The maker issues it as a hold invoice, which lets it accept the payment and then decide when, or whether, to reveal the preimage:
| State | Meaning |
|---|---|
| OPEN | the invoice exists, nothing is committed |
| ACCEPTED | the payer's funds are held, preimage still hidden |
| SETTLED | the preimage is revealed to the payer |
| CANCELED | the payer's funds are released, no preimage revealed |
Only the maker ever issues a hold invoice. The taker just pays a normal invoice, from an ordinary wallet.
The two directions
Pay Lightning, receive on chain
- You ask for a quote and the maker offers terms and a small bond.
-
You pay the bond over Lightning. It is not refundable, and its hash
is
sha256(sha256(preimage)), so paying it cannot reveal the secret that opens the on-chain leg. - The maker funds an HTLC that pays you, spendable with the preimage and refundable by the maker after a timeout.
- Your page rebuilds the HTLC address from public values and checks that the deposit really pays it - it does not take the coordinator's word for it.
- You pay the maker's hold invoice, which holds your funds.
- The maker settles the invoice, which reveals the preimage.
- Your page signs a claim with the preimage using a key generated in the page, and the coins are yours.
Pay on chain, receive Lightning
- You paste your own Lightning invoice; the page reads the payment hash out of it.
- The maker offers terms: the deposit (your invoice, its fee, and the fee to claim the deposit) and a locktime.
- Your page builds the HTLC itself - spendable by the maker with the preimage, refundable by you after the locktime.
- You send the deposit to that address.
- Once the deposit confirms, the maker pays your invoice; paying reveals the preimage, which is what lets the maker take the deposit.
There is no bond in this direction. Here your deposit is the collateral: walking away only parks your own money until the locktime, so the maker is not exposed the way it is when it funds first.
Why the timeouts differ
The two legs never unlock at the same height. Whoever funds first has the strictly longer timeout, with a margin of blocks on top - enough for a confirmation plus the other side's action on the slower chain.
Without that margin there is a gap where one side can refund a leg it has already been paid on, taking both. The rule is enforced when a swap is built, when it is read back off disk, and again by your page before it pays.
Roles
| Role | Who runs it | Holds |
|---|---|---|
| Taker | you | the per-swap claim key, the preimage once settled, swap state |
| Maker | the liquidity provider | inventory and channels, hold invoices, the per-swap refund key |
| Coordinator | whoever runs this site | no keys and no funds - quotes, state, chain observation |
The coordinator is not on the critical path. Once you hold a deposit and a preimage, you can claim through any relay without it.
Checking the deposit yourself
The page never believes the coordinator about the deposit. It rebuilds the HTLC script and address from public values - the payment hash, the two keys, the locktime - and asks the relay whether the transaction it was told about really pays that address. A lying coordinator or relay can hide the chain or refuse to broadcast, but it cannot make a deposit look like something it is not.
Getting out: recovery
If a swap stalls, the page works out what move is left from four things: the swap's state, whether the preimage has reached the page, whether the deposit is still unspent, and the current height against the HTLC's own locktime. The verdict is a judgement, not a service - nobody can claim for you - and the page acts on it without asking, because a claim only ever moves value towards you.
Passing the timeout is not the same as losing. The claim path has no locktime, so a claim is valid at any height; the timeout only opens the maker's refund. A swap past its deadline turns a safe claim into a race, and the page says so rather than calling it lost.
More
The bitcoin script describes the on-chain leg in full.