You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

366 lines
14 KiB

  1. # Lightning Loop
  2. Lightning Loop is a non-custodial service offered by
  3. [Lightning Labs](https://lightning.engineering/) to bridge on-chain and
  4. off-chain Bitcoin using submarine swaps. This repository is home to the Loop
  5. client and depends on the Lightning Network daemon
  6. [lnd](https://github.com/lightningnetwork/lnd). All of lnd’s supported chain
  7. backends are fully supported when using the Loop client: Neutrino, Bitcoin
  8. Core, and btcd.
  9. In the current iteration of the Loop software, two swap types are supported:
  10. * off-chain to on-chain, where the Loop client sends funds off-chain in
  11. * on-chain to off-chain, where the Loop client sends funds to an on-chain
  12. address using an off-chain channel
  13. We call off-chain to on-chain swaps, a **Loop Out**. The service can be used
  14. in various situations:
  15. - Acquiring inbound channel liquidity from arbitrary nodes on the Lightning
  16. network
  17. - Depositing funds to a Bitcoin on-chain address without closing active
  18. channels
  19. - Paying to on-chain fallback addresses in the case of insufficient route
  20. liquidity
  21. We call our on-chain to off-chain swaps, a **Loop In**. This allows you to use
  22. on-chain funds to increase the local balance of a channel, effectively
  23. "refilling" an existing channel.
  24. Potential uses for **Loop In**:
  25. - Refilling depleted channels with funds from cold-wallets or exchange
  26. withdrawals
  27. - Servicing off-chain Lightning withdrawals using on-chain payments, with no
  28. funds in channels required
  29. - As a failsafe payment method that can be used when channel liquidity along a
  30. route is insufficient
  31. ## Development and Support
  32. The Loop client is currently in an early beta state, and offers a simple command
  33. line application. Future APIs will be added to support implementation or use of
  34. the Loop service.
  35. The Loop daemon exposes a [gRPC API](https://lightning.engineering/loopapi/#lightning-loop-grpc-api-reference)
  36. (defaults to port 11010) and a [REST API](https://lightning.engineering/loopapi/index.html#loop-rest-api-reference)
  37. (defaults to port 8081).
  38. The [GitHub issue tracker](https://github.com/lightninglabs/loop/issues) can be
  39. used to request specific improvements or register and get help with any
  40. problems. Community support is also available in the
  41. [LND Slack](https://lightning.engineering/slack.html)
  42. .
  43. ## Setup and Install
  44. LND and the loop client are using Go modules. Make sure that the `GO111MODULE`
  45. env variable is set to `on`.
  46. In order to execute a swap, **you need to run a compatible lnd version built
  47. with the correct sub-servers enabled.**
  48. ### LND
  49. To run loop, you need a compatible version of `lnd` running. It is generally
  50. recommended to always keep both `lnd` and `loop` updated to the most recent
  51. released version.
  52. If you are building from source make sure you are using the latest tagged
  53. version of lnd. You can get this by git cloning the repository and checking out
  54. a specific tag:
  55. ```
  56. git clone https://github.com/lightningnetwork/lnd.git
  57. cd lnd
  58. git checkout v0.x.x-beta
  59. ```
  60. Once the lnd repository is cloned, it will need to be built with special build
  61. tags that enable the swap. This enables the required lnd rpc services.
  62. ```
  63. make install tags="signrpc walletrpc chainrpc invoicesrpc"
  64. ```
  65. Check to see if you have already installed lnd. If you have, you will need to
  66. delete the `.macaroon` files from your lnd directory and restart lnd.
  67. **Do not delete any other files other than the `.macaroon` files**
  68. ```
  69. // Example on Linux to see macaroons in the default directory:
  70. ls ~/.lnd/data/chain/bitcoin/mainnet
  71. ```
  72. This should show no `.macaroon` files. If it does? Stop lnd, delete macaroons,
  73. restart lnd.
  74. ```
  75. lncli stop
  76. ```
  77. Now delete the .macaroon files and restart lnd. (don't delete any other files)
  78. ### Loopd
  79. After lnd is installed, you will need to clone the Lightning Loop repo and
  80. install the command line interface and swap client service.
  81. ```
  82. git clone https://github.com/lightninglabs/loop.git
  83. cd loop/cmd
  84. go install ./...
  85. ```
  86. ## Execute a Swap
  87. After you have lnd and the Loop client installed, you can execute a Loop swap.
  88. The Loop client needs its own short-lived daemon which will deal with the swaps
  89. in progress.
  90. Command to start `loopd`::
  91. ```
  92. loopd
  93. // Or if you want to do everything in the same terminal and background loopd
  94. loopd &
  95. // For testnet mode, you'll need to specify the network as mainnet is the
  96. default:
  97. loopd --network=testnet
  98. ```
  99. By default `loopd` attempts to connect to the lnd instance running on
  100. `localhost:10009` and reads the macaroon and tls certificate from `~/.lnd`.
  101. This can be altered using command line flags. See `loopd --help`.
  102. `loopd` only listens on localhost and uses an unencrypted and unauthenticated
  103. connection.
  104. ### Loop Out Swaps
  105. Now that loopd is running, you can initiate a simple Loop Out. This will pay
  106. out Lightning off-chain funds and you will receive Bitcoin on-chain funds in
  107. return. There will be some chain and routing fees associated with this swap.
  108. ```
  109. NAME:
  110. loop out - perform an off-chain to on-chain swap (looping out)
  111. USAGE:
  112. loop out [command options] amt [addr]
  113. DESCRIPTION:
  114. Attempts to loop out the target amount into either the backing lnd's
  115. wallet, or a targeted address.
  116. The amount is to be specified in satoshis.
  117. Optionally a BASE58/bech32 encoded bitcoin destination address may be
  118. specified. If not specified, a new wallet address will be generated.
  119. OPTIONS:
  120. --channel value the 8-byte compact channel ID of the channel to loop out (default: 0)
  121. --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
  122. --amt value the amount in satoshis to loop out (default: 0)
  123. --conf_target value the number of blocks from the swap initiation height that the on-chain HTLC should be swept within (default: 6)
  124. --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)
  125. --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.
  126. ```
  127. It's possible to receive more inbound capacity on a particular channel
  128. (`--channel`), and also have the `loop` daemon send the coins to a target
  129. address (`addr`). The latter option allows ones to effectively send on-chain
  130. from their existing channels!
  131. ```
  132. loop out <amt_in_satoshis>
  133. ```
  134. This will take some time, as it requires an on-chain confirmation. When the
  135. swap is initiated successfully, `loopd` will see the process through.
  136. To query in-flight swap statuses, run `loop monitor`.
  137. 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.
  138. ### Fees explained
  139. The following is an example output of a 0.01 BTC fast (non-batched) Loop Out
  140. swap from `testnet`:
  141. ```bash
  142. $ loop out --amt 1000000 --fast
  143. Max swap fees for 1000000 sat Loop Out: 36046 sat
  144. Fast swap requested.
  145. CONTINUE SWAP? (y/n), expand fee detail (x): x
  146. Estimated on-chain sweep fee: 149 sat
  147. Max on-chain sweep fee: 14900 sat
  148. Max off-chain swap routing fee: 20010 sat
  149. Max off-chain prepay routing fee: 36 sat
  150. Max no show penalty (prepay): 1337 sat
  151. Max swap fee: 1100 sat
  152. CONTINUE SWAP? (y/n):
  153. ```
  154. Explanation:
  155. - **Max swap fees for <x> sat Loop Out** (36046 sat): The absolute maximum in
  156. fees that need to be paid. This includes on-chain and off-chain fees. This
  157. represents the ceiling or worst-case scenario. The actual fees will likely be
  158. lower. This is the sum of `14900 + 20010 + 36 + 1100` (see below).
  159. - **Estimated on-chain sweep fee** (149 sat): The estimated cost to sweep the
  160. HTLC in case of success, calculated based on the _current_ on-chain fees.
  161. This value is called `miner_fee` in the gRPC/REST responses.
  162. - **Max on-chain sweep fee** (14900 sat): The maximum on-chain fee the daemon
  163. is going to allow for sweeping the HTLC in case of success. A fee estimation
  164. based on the `--conf_target` flag is always performed before sweeping. The
  165. factor of `100` times the estimated fee is applied in case the fees spike
  166. between the time the swap is initiated and the time the HTLC can be swept. But
  167. that is the absolute worst-case fee that will be paid. If there is no fee
  168. spike, a normal, much lower fee will be used.
  169. - **Max off-chain swap routing fee** (20010 sat): The maximum off-chain
  170. routing fee that the daemon should pay when finding a route to pay the
  171. Lightning invoice. This is a hard limit. If no route with a lower or equal fee
  172. is found, the payment (and the swap) is aborted. This value is calculated
  173. statically based on the swap amount (see `maxRoutingFeeBase` and
  174. `maxRoutingFeeRate` in `cmd/loop/main.go`).
  175. - **Max off-chain prepay routing fee** (36 sat): The maximum off-chain routing
  176. fee that the daemon should pay when finding a route to pay the prepay fee.
  177. This is a hard limit. If no route with a lower or equal fee is found, the
  178. payment (and the swap) is aborted. This value is calculated statically based
  179. on the prepay amount (see `maxRoutingFeeBase` and `maxRoutingFeeRate` in
  180. `cmd/loop/main.go`).
  181. - **Max no show penalty (prepay)** (1337 sat): This is the amount that has to be
  182. pre-paid (off-chain) before the server publishes the HTLC on-chain. This is
  183. necessary to ensure the server's on-chain fees are paid if the client aborts
  184. and never completes the swap _after_ the HTLC has been published on-chain.
  185. If the swap completes normally, this amount is counted towards the full swap
  186. amount and therefore is actually a pre-payment and not a fee. This value is
  187. called `prepay_amt` in the gRPC/REST responses.
  188. - **Max swap fee** (1100 sat): The maximum amount of service fees we allow the
  189. server to charge for executing the swap. The client aborts the swap if the
  190. fee proposed by the server exceeds this maximum. It is therefore recommended
  191. to obtain the maximum by asking the server for a quote first. The actual fees
  192. might be lower than this maximum if user specific discounts are applied. This
  193. value is called `swap_fee` in the gRPC/REST responses.
  194. #### Fast vs. batched swaps
  195. By default, Loop Outs are executed as normal speed swaps. This means the server
  196. will wait up to 30 minutes until it publishes the HTLC on-chain to improve the
  197. chances that it can be batched together with other user's swaps to reduce the
  198. on-chain footprint and fees. The server offers a reduced swap fee for slow swaps
  199. to incentivize users to batch more.
  200. If a swap should be executed immediately, the `--fast` flag can be used. Fast
  201. swaps won't benefit from a reduced swap fee.
  202. ### Loop In Swaps
  203. Additionally, Loop In is now also supported for mainnet as well. A Loop In swap
  204. lets one refill their channel (ability to send more coins) by sending to a
  205. special script on-chain.
  206. ```
  207. NAME:
  208. loop in - perform an on-chain to off-chain swap (loop in)
  209. USAGE:
  210. loop in [command options] amt
  211. DESCRIPTION:
  212. Send the amount in satoshis specified by the amt argument off-chain.
  213. OPTIONS:
  214. --amt value the amount in satoshis to loop in (default: 0)
  215. --external expect htlc to be published externally
  216. --conf_target value the target number of blocks the on-chain htlc broadcast by the swap client should confirm within (default: 0)
  217. --last_hop value the pubkey of the last hop to use for this swap
  218. ```
  219. The `--external` argument allows the on-chain HTLC transacting to be published
  220. _externally_. This allows for a number of use cases like using this address to
  221. withdraw from an exchange _into_ your Lightning channel!
  222. A Loop In swap can be executed a follows:
  223. ```
  224. loop in <amt_in_satoshis>
  225. ```
  226. #### Fees explained
  227. The following is an example output of a 0.01 BTC Loop In swap from `testnet`:
  228. ```bash
  229. $ loop in --amt 1000000
  230. Max swap fees for 1000000 sat Loop In: 1562 sat
  231. CONTINUE SWAP? (y/n), expand fee detail (x): x
  232. Estimated on-chain HTLC fee: 154 sat
  233. Max swap fee: 1100 sat
  234. CONTINUE SWAP? (y/n):
  235. ```
  236. Explanation:
  237. - **Estimated on-chain HTLC fee** (154 sat): The estimated on-chain fee that the
  238. daemon has to pay to publish the HTLC. This is an estimation from `lnd`'s
  239. wallet based on the available UTXOs and current network fees. This value is
  240. called `miner_fee` in the gRPC/REST responses.
  241. - **Max swap fee** (1100 sat): The maximum amount of service fees we allow the
  242. server to charge for executing the swap. The client aborts the swap if the
  243. fee proposed by the server exceeds this maximum. It is therefore recommended
  244. to obtain the maximum by asking the server for a quote first. The actual fees
  245. might be lower than this maximum if user specific discounts are applied. This
  246. value is called `swap_fee` in the gRPC/REST responses.
  247. ## Resume
  248. When `loopd` is terminated (or killed) for whatever reason, it will pickup
  249. pending swaps after a restart.
  250. Information about pending swaps is stored persistently in the swap database.
  251. Its location is `~/.loopd/<network>/loop.db`.
  252. ## Authentication and transport security
  253. The gRPC and REST connections of `loopd` are encrypted with TLS and secured with
  254. macaroon authentication the same way `lnd` is.
  255. If no custom loop directory is set then the TLS certificate is stored in
  256. `~/.loop/<network>/tls.cert` and the base macaroon in
  257. `~/.loop/<network>/loop.macaroon`.
  258. The `loop` command will pick up these file automatically on mainnet if no custom
  259. loop directory is used. For other networks it should be sufficient to add the
  260. `--network` flag to tell the CLI in what sub directory to look for the files.
  261. For more information on macaroons,
  262. [see the macaroon documentation of lnd.](https://github.com/lightningnetwork/lnd/blob/master/docs/macaroons.md)
  263. **NOTE**: Loop's macaroons are independent from `lnd`'s. The same macaroon
  264. cannot be used for both `loopd` and `lnd`.
  265. ## Multiple Simultaneous Swaps
  266. It is possible to execute multiple swaps simultaneously. Just keep loopd
  267. running.
  268. ## API Support Level
  269. ### Server
  270. The Loop server API and on-chain scripts are kept backwards compatible as long
  271. as reasonably possible.
  272. ### Client
  273. When breaking changes to the Loop client daemon API are made, old fields will be
  274. marked as deprecated. Deprecated fields will remain supported until the next
  275. minor release.