Equilibrium

A bitcoin user (bob1) would like to receive funds on his off-chain Lightning wallet. In order to do that the user will generate a Lightning invoice and show it the to Swap Provider (alice1). The Swap Provider will prompt the user to pay an on-chain address (the P2WSH swap smart contract). Once the swap has been paid and confirmed, the Swap Provider is able to redeem the funds to his wallet and can pay the Lightning invoice of the user.

To learn more about how submarine swaps works you can read this nice article from Boltz exchange. For more info regarding the swap smart contract can be found in Alex Bosworth’s submarineswaps repository.

Requirements

• NodeJS >= 10.x

• JQ (JSON parser)

• Bitcoin Core >= 18.x

You need a work environment with Bitcoin Core on regtest and two LND nodes connected to it. One LND is the Swap Provider, the other is the Bitcoin user. For simplicity we create a direct channel between them.

 

Install dependencies

$ npm install

Generate a bunch of testing wallets and import the private keys in your running Bitcoin Core

$ npm run wallets

Swapping Process: On-Chain To Off-Chain

1. User generates a LN invoice asking for 1000 satoshis

$ lncli-user addinvoice 1000 [PREIMAGE]
PAYMENT_REQUEST

2. User shows the invoice to the Swap Provider

3. Swap Provider extract the payment hash - sha256(preimage)

lncli-sp decodepayreq PAYMENT_REQUEST

4. Swap Provider generates the P2WSH address from the swap witness script

node swap_p2wsh.js on2off PAYMENT_HASH  TIMELOCK  [PREIMAGE]

5. User sends 1200 satoshis to the P2WSH swap smart contract address

Note	User pays 200 satoshis more to compensate for the mining fees that the Swap Provider will have to pay to redeem the funds. bitcoin-cli gettransaction or getrawtransaction to get the output index (TX_VOUT) for step 7.

sendtoaddress P2WSH_ADDRESS 0.000012

6. Swap Provider must pay the invoice in order to get the preimage that allows him to redeem the on-chain funds

lncli-sp payinvoice PAYMENT_REQUEST

7. Happy case: swap provider redeems the funds locked in the P2WSH swap smart contract

Note	Get TX_ID and TX_VOUT from step 5

node spending_swap_tx.js claim on2off TX_ID TX_VOUT  WITNESS_SCRIPT  TIMELOCK  PREIMAGE
sendrawtransaction TX_HEX
getrawtransaction TX_ID

7 bis. Failure case: user redeems the funds locked in P2WSH swap smart contract

node spending_swap_tx.js refund on2off TX_ID TX_VOUT  WITNESS_SCRIPT  TIMELOCK
sendrawtransaction TX_HEX
getrawtransaction TX_ID

8. Mine a block

bitcoin-cli getnewaddress
bitcoin-cli generatetoaddress 1 ADDR

9. Check that the Swap Provider received his money on-chain

Note	Swap Provider redeem address is alice1 p2wpkh address

bitcoin-cli scantxoutset start '["addr(bcrt1qlwyzpu67l7s9gwv4gzuv4psypkxa4fx4ggs05g)"]'

10. Check that the user received his money off-chain

lncli-user channelbalance

Swapping Process: Off-Chain To On-Chain

1. Swap Provider generates a LN invoice asking for 1200 satoshis

lncli-sp addinvoice 1200 [PREIMAGE]
PAYMENT_REQUEST

2. Swap Provider generates the P2WSH address from the swap witness script

node swap_p2wsh.js off2on PAYMENT_HASH  TIMELOCK  [PREIMAGE]

3. Swap provider sends 1200 satoshis to the P2WSH swap smart contract address

Note	bitcoin-cli gettransaction or getrawtransaction to get the output index (TX_VOUT) for step 6

sendtoaddress P2WSH_ADDRESS 0.000012

4. Swap provider shows the invoice to the user

5. User must pay the invoice in order to get the preimage that allows him to redeem the on-chain funds

lncli-user payinvoice PAYMENT_REQUEST

6. Happy case: user redeems the funds locked in the P2WSH swap smart contract

Note	Input: 1200 sats → Output: 1000 sats

node spending_swap_tx.js claim off2on TX_ID TX_VOUT  WITNESS_SCRIPT  TIMELOCK  PREIMAGE
sendrawtransaction TX_HEX
getrawtransaction TX_ID

6 bis. Failure case: swap provider redeems the funds locked in the P2WSH swap smart contract

Note	Input: 1200 sats → Output: 1000 sats

node spending_swap_tx.js refund off2on TX_ID TX_VOUT  WITNESS_SCRIPT  TIMELOCK
sendrawtransaction TX_HEX
getrawtransaction TX_ID

7. Mine a block

bitcoin-cli getnewaddress
bitcoin-cli generatetoaddress 1 ADDRESS

8. Check that the user received his money on-chain

Note	User redeem address is bob1 p2wpkh address

bitcoin-cli scantxoutset start '["addr(bcrt1qlwyzpu67l7s9gwv4gzuv4psypkxa4fx4ggs05g)"]'

9. Check that the swap provider received his money off-chain

lncli-sp channelbalance