diff --git a/README.md b/README.md index 17f8474..337f1da 100644 --- a/README.md +++ b/README.md @@ -1,342 +1,103 @@ # Lightning Loop - Lightning Loop is a non-custodial service offered by -[Lightning Labs](https://lightning.engineering/) 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](https://github.com/lightningnetwork/lnd). All of lnd’s supported chain -backends are fully supported when using the Loop client: Neutrino, Bitcoin -Core, and btcd. +[Lightning Labs](https://lightning.engineering/) that makes it easy to move +bitcoin into and out of the Lightning Network. -In the current iteration of the Loop software, two swap types are supported: - * off-chain to on-chain, where the Loop client sends funds off-chain in - * on-chain to off-chain, where the Loop client sends funds to an on-chain - address using an off-chain channel +## Features +- Automated channel balancing +- Privacy-forward non-custodial swaps +- Opportunistic transaction batching to save on fees +- Progress monitoring of in-flight swaps -We call off-chain to on-chain swaps, a **Loop Out**. The service can be used -in various situations: +## Use Cases +- Automate channel balancing with AutoLoop ([Learn more](https://github.com/lightninglabs/loop/blob/master/docs/autoloop.md)) +- Deposit to a Bitcoin address without closing channels with Loop In +- Convert outbound liquidity into inbound liquidity with Loop Out +- Refill depleted Lightning channels with Loop In -- 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 +## Installation +Download the latest binaries from the [releases](https://github.com/lightninglabs/loop/releases) page. -We call our on-chain to off-chain swaps, a **Loop In**. This allows you to use -on-chain funds to increase the local balance of a channel, effectively -"refilling" an existing 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 currently 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 Loop daemon exposes a [gRPC API](https://lightning.engineering/loopapi/#lightning-loop-grpc-api-reference) -(defaults to port 11010) and a [REST API](https://lightning.engineering/loopapi/index.html#loop-rest-api-reference) -(defaults to port 8081). - -The [GitHub issue tracker](https://github.com/lightninglabs/loop/issues) can be -used to request specific improvements or register and get help with any -problems. Community support is also available in the -[LND Slack](https://lightning.engineering/slack.html) -. - -### Regtest Loop server - -To get started with local development against a stripped down dummy Loop server -running in a local `regtest` Bitcoin network, take a look at the -[`regtest` server environment example documentation](./regtest/README.md). - -## 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 a compatible lnd version built -with the correct sub-servers enabled.** - -### LND - -To run loop, you need a compatible version of `lnd` running. It is generally -recommended to always keep both `lnd` and `loop` updated to the most recent -released version. - -If you are building from source make sure you are using the latest tagged -version of lnd. You can get this by git cloning the repository and checking out -a specific tag: - -``` -git clone https://github.com/lightningnetwork/lnd.git -cd lnd -git checkout v0.x.x-beta -``` - -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. - -``` -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) - -### Loopd - -After lnd is installed, you will need to clone the Lightning Loop repo and -install the command line interface and swap client service. +## Execution +The Loop client needs its own short-lived daemon to facilitate swaps. To start `loopd`: ``` -git clone https://github.com/lightninglabs/loop.git -cd loop/cmd -go install ./... +loopd ``` -## 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`:: - +To use Loop in testnet, simply pass the network flag: ``` -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 -default: loopd --network=testnet ``` -By default `loopd` attempts to connect to the lnd instance running on +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. If you set `restlisten` variable `loop` will use TLS encryption -and macaroon authentication, see [Authentication and transport security](https://github.com/lightninglabs/loop#authentication-and-transport-security) -for more details. +## Usage -### Loop Out Swaps - -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. -``` -NAME: - loop out - perform an off-chain to on-chain swap (looping out) - -USAGE: - loop out [command options] amt [addr] - -DESCRIPTION: - - Attempts to loop out the target amount into either the backing lnd's - wallet, or a targeted address. - - The amount is to be specified in satoshis. - - Optionally a BASE58/bech32 encoded bitcoin destination address may be - specified. If not specified, a new wallet address will be generated. - -OPTIONS: - --channel value the 8-byte compact channel ID of the channel to loop out (default: 0) - --addr value the optional address that the looped out funds should be sent to, if let blank the funds will go to lnd's wallet - --amt value the amount in satoshis to loop out (default: 0) - --conf_target value the number of blocks from the swap initiation height that the on-chain HTLC should be swept within (default: 6) - --max_swap_routing_fee value the max off-chain swap routing fee in satoshis, if not specified, a default max fee will be used (default: 0) - --fast Indicate you want to swap immediately, paying potentially a higher fee. If not set the swap server might choose to wait up to 30 minutes before publishing the swap HTLC on-chain, to save on its chain fees. Not setting this flag therefore might result in a lower swap fee. -``` - -It's possible to receive more inbound capacity on a particular channel -(`--channel`), and also have the `loop` daemon send the coins to a target -address (`addr`). The latter option allows ones to effectively send on-chain -from their existing channels! +### AutoLoop +AutoLoop makes it easy to keep your channels balanced. Checkout our [autoloop documentation](https://docs.lightning.engineering/advanced-best-practices/advanced-best-practices-overview/autoloop) for details. +### Loop Out +Use Loop Out to move bitcoins on Lightning into an on-chain Bitcoin address. +To execute a Loop Out: ``` loop out ``` -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`. - -The loop client also has the ability to automatically dispatch loop out swaps on your behalf - see our [autoloop documentation](https://github.com/lightninglabs/loop/blob/master/docs/autoloop.md) for details. - -### Fees explained +Other notable options: +- Use the `--fast` flag to swap immediately (Note: This opts-out of fee savings made possible by transaction batching) +- Use the `--channel` flag to loop out on specific channels +- Use the `--addr` flag to specify the address the looped out funds should be sent to (Note: By default funds are sent to the lnd wallet) -The following is an example output of a 0.01 BTC fast (non-batched) Loop Out -swap from `testnet`: +Run `loop monitor` to monitor the status of a swap. -```bash -$ loop out --amt 1000000 --fast -Max swap fees for 1000000 sat Loop Out: 36046 sat -Fast swap requested. -CONTINUE SWAP? (y/n), expand fee detail (x): x +### Loop In +Use Loop In to convert on-chain bitcoin into spendable Lightning funds. -Estimated on-chain sweep fee: 149 sat -Max on-chain sweep fee: 14900 sat -Max off-chain swap routing fee: 20010 sat -Max off-chain prepay routing fee: 36 sat -Max no show penalty (prepay): 1337 sat -Max swap fee: 1100 sat -CONTINUE SWAP? (y/n): +To execute a Loop In: ``` - -Explanation: - -- **Max swap fees for sat Loop Out** (36046 sat): The absolute maximum in - fees that need to be paid. This includes on-chain and off-chain fees. This - represents the ceiling or worst-case scenario. The actual fees will likely be - lower. This is the sum of `14900 + 20010 + 36 + 1100` (see below). -- **Estimated on-chain sweep fee** (149 sat): The estimated cost to sweep the - HTLC in case of success, calculated based on the _current_ on-chain fees. - This value is called `miner_fee` in the gRPC/REST responses. -- **Max on-chain sweep fee** (14900 sat): The maximum on-chain fee the daemon - is going to allow for sweeping the HTLC in case of success. A fee estimation - based on the `--conf_target` flag is always performed before sweeping. The - factor of `100` times the estimated fee is applied in case the fees spike - between the time the swap is initiated and the time the HTLC can be swept. But - that is the absolute worst-case fee that will be paid. If there is no fee - spike, a normal, much lower fee will be used. -- **Max off-chain swap routing fee** (20010 sat): The maximum off-chain - routing fee that the daemon should pay when finding a route to pay the - Lightning invoice. This is a hard limit. If no route with a lower or equal fee - is found, the payment (and the swap) is aborted. This value is calculated - statically based on the swap amount (see `maxRoutingFeeBase` and - `maxRoutingFeeRate` in `cmd/loop/main.go`). -- **Max off-chain prepay routing fee** (36 sat): The maximum off-chain routing - fee that the daemon should pay when finding a route to pay the prepay fee. - This is a hard limit. If no route with a lower or equal fee is found, the - payment (and the swap) is aborted. This value is calculated statically based - on the prepay amount (see `maxRoutingFeeBase` and `maxRoutingFeeRate` in - `cmd/loop/main.go`). -- **Max no show penalty (prepay)** (1337 sat): This is the amount that has to be - pre-paid (off-chain) before the server publishes the HTLC on-chain. This is - necessary to ensure the server's on-chain fees are paid if the client aborts - and never completes the swap _after_ the HTLC has been published on-chain. - If the swap completes normally, this amount is counted towards the full swap - amount and therefore is actually a pre-payment and not a fee. This value is - called `prepay_amt` in the gRPC/REST responses. -- **Max swap fee** (1100 sat): The maximum amount of service fees we allow the - server to charge for executing the swap. The client aborts the swap if the - fee proposed by the server exceeds this maximum. It is therefore recommended - to obtain the maximum by asking the server for a quote first. The actual fees - might be lower than this maximum if user specific discounts are applied. This - value is called `swap_fee` in the gRPC/REST responses. - -#### Fast vs. batched swaps - -By default, Loop Outs are executed as normal speed swaps. This means the server -will wait up to 30 minutes until it publishes the HTLC on-chain to improve the -chances that it can be batched together with other user's swaps to reduce the -on-chain footprint and fees. The server offers a reduced swap fee for slow swaps -to incentivize users to batch more. - -If a swap should be executed immediately, the `--fast` flag can be used. Fast -swaps won't benefit from a reduced swap fee. - -### Loop In Swaps - -Additionally, Loop In is now also supported for mainnet as well. A Loop In swap -lets one refill their channel (ability to send more coins) by sending to a -special script on-chain. +loop in ``` -NAME: - loop in - perform an on-chain to off-chain swap (loop in) - -USAGE: - loop in [command options] amt - -DESCRIPTION: - Send the amount in satoshis specified by the amt argument off-chain. +### More info +For more information about using Loop checkout our [Loop FAQs](./docs/faqs.md). -OPTIONS: - --amt value the amount in satoshis to loop in (default: 0) - --external expect htlc to be published externally - --conf_target value the target number of blocks the on-chain htlc broadcast by the swap client should confirm within (default: 0) - --last_hop value the pubkey of the last hop to use for this swap -``` +## Development -The `--external` argument allows the on-chain HTLC transacting to be published -_externally_. This allows for a number of use cases like using this address to -withdraw from an exchange _into_ your Lightning channel! +### Regtest +To get started with local development against a stripped down dummy Loop server +running in a local `regtest` Bitcoin network, take a look at the +[`regtest` server environment example documentation](./regtest/README.md). -A Loop In swap can be executed a follows: +### Testnet +To use Loop in testnet, simply pass the network flag: ``` -loop in +loopd --network=testnet ``` -#### Fees explained +### Submit feature requests +The [GitHub issue tracker](https://github.com/lightninglabs/loop/issues) can be +used to request specific improvements or report bugs. -The following is an example output of a 0.01 BTC Loop In swap from `testnet`: +### Join us on Slack +Join us on the +[LND Slack](https://lightning.engineering/slack.html) and join the #loop +channel to ask questions and interact with the community. -```bash -$ loop in --amt 1000000 -Max swap fees for 1000000 sat Loop In: 1562 sat -CONTINUE SWAP? (y/n), expand fee detail (x): x +## LND +Note that Loop requires `lnd` to be built with **all of its subservers**. Download the latest [official release binary](https://github.com/lightningnetwork/lnd/releases/latest) or build `lnd` from source by following the [installation instructions](https://github.com/lightningnetwork/lnd/blob/master/docs/INSTALL.md). If you choose to build `lnd` from source, use the following command to enable all the relevant subservers: -Estimated on-chain HTLC fee: 154 sat -Max swap fee: 1100 sat -CONTINUE SWAP? (y/n): +``` +make install tags="signrpc walletrpc chainrpc invoicesrpc" ``` -Explanation: - -- **Estimated on-chain HTLC fee** (154 sat): The estimated on-chain fee that the - daemon has to pay to publish the HTLC. This is an estimation from `lnd`'s - wallet based on the available UTXOs and current network fees. This value is - called `miner_fee` in the gRPC/REST responses. -- **Max swap fee** (1100 sat): The maximum amount of service fees we allow the - server to charge for executing the swap. The client aborts the swap if the - fee proposed by the server exceeds this maximum. It is therefore recommended - to obtain the maximum by asking the server for a quote first. The actual fees - might be lower than this maximum if user specific discounts are applied. This - value is called `swap_fee` in the gRPC/REST responses. - -## Resume - -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//loop.db`. - -## Authentication and transport security +## API +The Loop daemon exposes a [gRPC API](https://lightning.engineering/loopapi/#lightning-loop-grpc-api-reference) +(defaults to port 11010) and a [REST API](https://lightning.engineering/loopapi/index.html#loop-rest-api-reference) +(defaults to port 8081). The gRPC and REST connections of `loopd` are encrypted with TLS and secured with macaroon authentication the same way `lnd` is. @@ -355,20 +116,10 @@ For more information on macaroons, **NOTE**: Loop's macaroons are independent from `lnd`'s. The same macaroon cannot be used for both `loopd` and `lnd`. -## Multiple Simultaneous Swaps - -It is possible to execute multiple swaps simultaneously. Just keep loopd -running. - -## API Support Level - -### Server - -The Loop server API and on-chain scripts are kept backwards compatible as long -as reasonably possible. - -### Client - -When breaking changes to the Loop client daemon API are made, old fields will be -marked as deprecated. Deprecated fields will remain supported until the next -minor release. +## Build from source +If you’d prefer to build from source: +``` +git clone https://github.com/lightninglabs/loop.git +cd loop/cmd +go install ./... +``` diff --git a/docs/faqs.md b/docs/faqs.md new file mode 100644 index 0000000..10a9aef --- /dev/null +++ b/docs/faqs.md @@ -0,0 +1,61 @@ + +# Frequently Asked Questions + +## How does Loop recover from a crash? +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//loop.db`. + +## Can Loop handle multiple simultaneous swaps? +It is possible to execute multiple swaps simultaneously. Just keep loopd +running. + +## What are the fees? + +You can pass the `--verbose` flag when using Loop to get a detailed fee +breakdown + +### Loop Out Fees + +An explanation of each fee: + +- **Estimated on-chain fee**: The estimated cost to sweep the + HTLC in case of success, calculated based on the _current_ on-chain fees. + This value is called `miner_fee` in the gRPC/REST responses. +- **Max on-chain fee**: The maximum on-chain fee the daemon + is going to allow for sweeping the HTLC in case of success. A fee estimation + based on the `--conf_target` flag is always performed before sweeping. The + factor of `100` times the estimated fee is applied in case the fees spike + between the time the swap is initiated and the time the HTLC can be swept. But + that is the absolute worst-case fee that will be paid. If there is no fee + spike, a normal, much lower fee will be used. +- **Max off-chain swap routing fee**: The maximum off-chain + routing fee that the daemon should pay when finding a route to pay the + Lightning invoice. This is a hard limit. If no route with a lower or equal fee + is found, the payment (and the swap) is aborted. This value is calculated + statically based on the swap amount (see `maxRoutingFeeBase` and + `maxRoutingFeeRate` in `cmd/loop/main.go`). +- **Max off-chain prepay routing fee**: The maximum off-chain routing + fee that the daemon should pay when finding a route to pay the prepay fee. + This is a hard limit. If no route with a lower or equal fee is found, the + payment (and the swap) is aborted. This value is calculated statically based + on the prepay amount (see `maxRoutingFeeBase` and `maxRoutingFeeRate` in + `cmd/loop/main.go`). +- **No show penalty (prepay)**: This is the amount that has to be + pre-paid (off-chain) before the server publishes the HTLC on-chain. This is + necessary to ensure the server's on-chain fees are paid if the client aborts + and never completes the swap _after_ the HTLC has been published on-chain. + If the swap completes normally, this amount is counted towards the full swap + amount and therefore is actually a pre-payment and not a fee. This value is + called `prepay_amt` in the gRPC/REST responses. + +### Loop In Fees + +An explanation of each fee: + +- **Estimated on-chain fee**: The estimated on-chain fee that the + daemon has to pay to publish the HTLC. This is an estimation from `lnd`'s + wallet based on the available UTXOs and current network fees. This value is + called `miner_fee` in the gRPC/REST responses.