Skip to content
Lightning Loop: A Non-Custodial Off/On Chain Bridge
Branch: master
Clone or download
Roasbeef Merge pull request #47 from alexbosworth/decrease-max-routing-fee
cmd/loop: reduce off-chain payment max-fee
Latest commit 893954e Apr 22, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmd Merge pull request #47 from alexbosworth/decrease-max-routing-fee Apr 22, 2019
docs docs: move out architecture diagram Mar 13, 2019
lndclient cmd/loopd+lndclient: based on the network, update the macaron path if… Apr 18, 2019
loopdb loopd: add loop in state InvoiceSettled Apr 2, 2019
looprpc loopd: add loop in state InvoiceSettled Apr 2, 2019
swap use np2wsh for loop in htlc Apr 4, 2019
sweep use np2wsh for loop in htlc Apr 4, 2019
test multi: loop in swap Mar 28, 2019
.gitignore git: update gitignore to include new loop related binaries Mar 6, 2019
.travis.yml build: add travis config Mar 7, 2019
LICENSE Initial commit Feb 16, 2019
Makefile Merge pull request #44 from lightninglabs/alexbosworth-patch-6 Apr 17, 2019
client.go loopd: fix nil ptr derefence for monitor Apr 11, 2019
client_test.go loopd: loop in from external address Apr 1, 2019
config.go multi: finalize rename from uncharge to loop out Mar 7, 2019
executor.go multi: finalize rename from uncharge to loop out Mar 7, 2019
go.mod build: go mod tidy Apr 18, 2019
go.sum multi: always supply chain params when decoding addresses Mar 26, 2019
interface.go use np2wsh for loop in htlc Apr 4, 2019
log.go loop: extract code from client package into new loop primary package Mar 7, 2019
loopin.go use np2wsh for loop in htlc Apr 4, 2019
loopin_testcontext_test.go multi: loop in swap Mar 28, 2019
loopout.go use np2wsh for loop in htlc Apr 4, 2019
loopout_test.go multi: finalize rename from uncharge to loop out Mar 7, 2019 release: add release script Mar 8, 2019
store_mock_test.go loopdb: add loop in Mar 28, 2019
swap.go use np2wsh for loop in htlc Apr 4, 2019
swap_server_client.go multi: loop in swap Mar 28, 2019
testcontext_test.go multi: loop in swap Mar 28, 2019

Lightning Loop

Lightning Loop is a non-custodial service offered by Lightning Labs to bridge on-chain and off-chain Bitcoin using submarine swaps. This repository is home to the Loop client and depends on the Lightning Network daemon lnd. All of lnd’s supported chain backends are fully supported when using the Loop client: Neutrino, Bitcoin Core, and btcd.

In the current iteration of the Loop software, only off-chain to on-chain swaps are supported, where the Loop client sends funds off-chain in exchange for the funds back on-chain. This is called a Loop Out.

The service can be used in various situations:

  • Acquiring inbound channel liquidity from arbitrary nodes on the Lightning network
  • Depositing funds to a Bitcoin on-chain address without closing active channels
  • Paying to on-chain fallback addresses in the case of insufficient route liquidity

Loop also allow offers an experimental testnet version of on-chain to off-chain swaps, called Loop In. This allows you to use on-chain funds to increase the local balance of a channel.

Potential uses for Loop In:

  • Refilling depleted channels with funds from cold-wallets or exchange withdrawals
  • Servicing off-chain Lightning withdrawals using on-chain payments, with no funds in channels required
  • As a failsafe payment method that can be used when channel liquidity along a route is insufficient

Development and Support

The Loop client is current in an early beta state, and offers a simple command line application. Future APIs will be added to support implementation or use of the Loop service.

The GitHub issue tracker can be used to request specific improvements or register and get help with any problems. Community support is also available in the LND Slack .

Setup and Install

LND and the loop client are using Go modules. Make sure that the GO111MODULE env variable is set to on.

In order to execute a swap, You need to run lnd 0.6.0+, or master built with sub-servers enabled.


If you are building from source, and not using a 0.6.0 or higher release of lnd, make sure that you are using the master branch of lnd. You can get this by git cloning the repository

git clone

Once the lnd repository is cloned, it will need to be built with special build tags that enable the swap. This enables the required lnd rpc services.

cd lnd
make install tags="signrpc walletrpc chainrpc invoicesrpc"

Check to see if you have already installed lnd. If you have, you will need to delete the .macaroon files from your lnd directory and restart lnd.

Do not delete any other files other than the .macaroon files

// Example on Linux to see macaroons in the default directory:
ls ~/.lnd/data/chain/bitcoin/mainnet

This should show no .macaroon files. If it does? Stop lnd, delete macaroons, restart lnd.

lncli stop

Now delete the .macaroon files and restart lnd. (don't delete any other files)


After lnd is installed, you will need to clone the Lightning Loop repo and install the command line interface and swap client service.

git clone
cd loop/cmd
go install ./...

Execute a Swap

After you have lnd and the Loop client installed, you can execute a Loop swap.

The Loop client needs its own short-lived daemon which will deal with the swaps in progress.

Command to start loopd::


// Or if you want to do everything in the same terminal and background loopd
loopd &

// For testnet mode, you'll need to specify the network as mainnet is the
loopd --network=testnet

By default loopd attempts to connect to the lnd instance running on localhost:10009 and reads the macaroon and tls certificate from ~/.lnd. This can be altered using command line flags. See loopd --help.

loopd only listens on localhost and uses an unencrypted and unauthenticated connection.

Now that loopd is running, you can initiate a simple Loop Out. This will pay out Lightning off-chain funds and you will receive Bitcoin on-chain funds in return. There will be some chain and routing fees associated with this swap.

loop out <amt_in_satoshis>

This will take some time, as it requires an on-chain confirmation. When the swap is initiated successfully, loopd will see the process through.

To query in-flight swap statuses, run loop monitor.


When loopd is terminated (or killed) for whatever reason, it will pickup pending swaps after a restart.

Information about pending swaps is stored persistently in the swap database. Its location is ~/.loopd/<network>/loop.db.

Multiple Simultaneous Swaps

It is possible to execute multiple swaps simultaneously. Just keep loopd running.

You can’t perform that action at this time.