From f295dc9c94ae45f7e361927ab07721658106bba8 Mon Sep 17 00:00:00 2001 From: Justin OBrien Date: Sun, 21 Mar 2021 09:10:17 -1000 Subject: [PATCH] Address comments Added faqs with fees explainer, regtest section from Oli's PR, and several other tweaks --- README.md | 57 +++++++++++++++++++++++++++++------------------- docs/faqs.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 22 deletions(-) create mode 100644 docs/faqs.md diff --git a/README.md b/README.md index b43408c..11adda8 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,9 @@ bitcoin into and out of the Lightning Network. ## 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 -- Convert outbound liquidity into inbound liquidity -- Refill depleted Lightning channels +- 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 ## Installation Download the latest binaries from the [releases](https://github.com/lightninglabs/loop/releases) page. @@ -25,26 +25,14 @@ The Loop client needs its own short-lived daemon to facilitate swaps. To start ` loopd ``` -To use Loop in testnet, simply pass the network flag: -``` -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`. -## 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: - -``` -make install tags="signrpc walletrpc chainrpc invoicesrpc" -``` - ## Usage ### AutoLoop -AutoLoop makes it easy to keep your channels balanced. Checkout our [autoloop documentation](https://github.com/lightninglabs/loop/blob/master/docs/autoloop.md) for details. +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. @@ -69,6 +57,37 @@ To execute a Loop In: loop in ``` +### More info +For more information about using Loop checkout our [Loop FAQs](./docs/faqs.md). + +## Development + +### 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). + +### Testnet +To use Loop in testnet, simply pass the network flag: +``` +loopd --network=testnet +``` + +### Submit feature requests +The [GitHub issue tracker](https://github.com/lightninglabs/loop/issues) can be +used to request specific improvements or report bugs. + +### 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. + +## 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: + +``` +make install tags="signrpc walletrpc chainrpc invoicesrpc" +``` ## API The Loop daemon exposes a [gRPC API](https://lightning.engineering/loopapi/#lightning-loop-grpc-api-reference) @@ -99,9 +118,3 @@ git clone https://github.com/lightninglabs/loop.git cd loop/cmd go install ./... ``` - -## Development and Support -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). 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.