Skip to content

Commit 6870982

Browse files
authored
Merge pull request #72 from lightninglabs/walkthrough-doc
doc: add walkthrough document
2 parents 28c9a96 + 243308f commit 6870982

16 files changed

+229
-0
lines changed

.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,6 @@ litd-debug
99

1010
# go code generated by statik
1111
/statik/statik.go
12+
13+
# MacOS junk
14+
.DS_Store

doc/WALKTHROUGH.md

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# Lightning Terminal Walkthrough
2+
3+
This document provides a brief overview of the information provided in Lightning Terminal
4+
along with step-by-step instructions on how to perform a Loop via the user interface.
5+
6+
We assume you already have a basic understanding of the Lightning Network, LND nodes, and
7+
channels. You should already have Lightning Terminal installed and can access the
8+
dashboard via a web browser. Installation instructions can be found in the
9+
[README](../README.md).
10+
11+
- [What is Loop](#what-is-loop)
12+
- [Visual Overview](#visual-overview)
13+
- [How to perform a Swap](#how-to-perform-a-swap)
14+
- [View Loop History](#view-loop-history)
15+
- [Manage UI Settings](#manage-ui-settings)
16+
17+
## What is Loop?
18+
19+
**Lightning Loop** is a non-custodial service offered by
20+
[Lightning Labs](https://lightning.engineering/) to move funds in and out of the Lightning
21+
Network from the Bitcoin blockchain. This allows you to easily alter the balances of your
22+
channels without needing to close and reopen them, which extends the lifetime of your
23+
channels. It also enables operations from multiple nodes to be _batched_ as well, which
24+
reduces the fees you need to pay.
25+
26+
Refer to the Loop daemon
27+
[documentation](https://github.com/lightninglabs/loop/blob/master/README.md) for a more
28+
detailed explanation.
29+
30+
### Terminology
31+
32+
- **Loop Out**: transfer funds from the local balance of one or more Lightning channels to
33+
your on-chain Bitcoin wallet to...
34+
- acquire inbound channel liquidity from arbitrary nodes on the Lightning network
35+
- deposit funds to a Bitcoin on-chain address without closing active channels
36+
- pay to on-chain fallback addresses in the case of insufficient route liquidity
37+
- **Loop In**: transfer funds from your on-chain Bitcoin wallet to the local balance of
38+
one or more of your Lightning channels to...
39+
- refill depleted channels with funds from cold-wallets or exchange withdrawals
40+
- service off-chain Lightning withdrawals using on-chain payments, with no funds in
41+
channels required
42+
- have a failsafe payment method that can be used when channel liquidity along a route
43+
is insufficient
44+
- **Swap**: a single instance of a transfer between your off-chain and on-chain balances,
45+
which can be either a Loop Out or Loop In
46+
47+
## Visual Overview
48+
49+
Here is an overview of what is displayed on screen after you first log in to the
50+
dashboard.
51+
52+
![loop](./images/loop.png)
53+
54+
1. The confirmed balances on the Lightning Network and on-chain
55+
1. The navigation menu containing links to the different screens
56+
57+
| Page | Description |
58+
| -------------- | ------------------------------------------------------------------------ |
59+
| Lightning Loop | displays a list of all of your channels and allows you to perform swaps |
60+
| History | displays a list of all of your past swaps |
61+
| Settings | change settings to customize the dashboard UI as well as view node info. |
62+
63+
1. Click the export icon to export your channels as a CSV file
64+
1. The amount of Bitcoin that the node can receive over your Lightning channels
65+
1. The amount of Bitcoin that the node can send over your Lightning channels
66+
1. Click the Loop button to begin creating a swap
67+
1. The list of open channels that the node has with other peers on the Lightning Network
68+
69+
| Column Name | Description |
70+
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
71+
| Can Receive | the amount that can be received over the channel |
72+
| Balance Bar | a visual representation of how much of the channel balance can be sent vs received |
73+
| Can Send | the amount that can be sent over this channel |
74+
| In Fee % | the routing fee rate charged by the peer to receive payments over the channel. The percent is rounded to two decimal places. Hover over the value to see the exact rate expressed as parts-per-million |
75+
| Up Time % | the uptime percentage of the channel peer |
76+
| Peer/Alias | the alias of the channel peer. Hover over this field to see the peer's pubkey |
77+
| Capacity | the total capacity of the channel |
78+
79+
Lightning Terminal uses a traffic light system to help you prioritize your actions.
80+
81+
| Color | Meaning |
82+
| ------------- | ------------------------------------------------------------------------------------ |
83+
| Red/Pink | highlights information that needs your immediate attention or a failure has occurred |
84+
| Yellow/Orange | highlights information that you should attend to soon |
85+
| Green | should tell you that all is well, and no extra attention is required |
86+
87+
## How to perform a Swap
88+
89+
Follow the steps below to perform a swap via the Lightning Terminal.
90+
91+
![swap1](./images/swap1.png)
92+
93+
1. Click on the **Loop** button to begin
94+
95+
![swap2](./images/swap2.png)
96+
97+
2. (Optional) Select one or more channels if you want the swap to only transfer funds over
98+
the chosen channels. This is helpful if you want to only adjust the balance of specific
99+
channels.
100+
101+
If you choose more than one channel, there's no guarantee how funds will be split
102+
amongst the channels. `lnd` will use its knowledge of the network to determine how best
103+
to split up the payment, if necessary. It's possible that only one of the channels will
104+
be used if the payment can be successfully routed through a single channel.
105+
106+
If no channels are specified, Lightning Loop will automatically select channels
107+
according to its own optimization algorithm.
108+
109+
3. Click on either the **Loop Out** or **Loop In** buttons depending on whether you want
110+
to transfer funds in or out of the Lightning Network.
111+
112+
> We'll click **Loop Out** in this walk through
113+
114+
![swap3](./images/swap3.png)
115+
116+
4. Drag the slider to adjust the amount you want to swap. The Loop server will vary the
117+
maximum you can swap based on the terms set by Lightning Labs as well as by the amount
118+
you have available in your channels.
119+
5. Confirm the selected channels that will be used, if any were chosen.
120+
6. Click the **Next** button.
121+
122+
![swap4](./images/swap4.png)
123+
124+
7. Review the Loop amount and the fee. Keep in mind that you will only be charged the fee.
125+
The Loop amount will remain on your node once the swap completes. The balance will just
126+
be shifted between your on-chain and Lightning balances.
127+
8. Click the **Confirm** button to submit the swap information to the server and begin the
128+
Loop process.
129+
130+
![swap5](./images/swap5.png)
131+
132+
You will see a loading animation for a few seconds while the information is being
133+
submitted.
134+
135+
9. (Optional) If you wish to abort the swap, you can click on the back arrow button before
136+
the loading animation goes away in 3-5 seconds.
137+
138+
![swap6](./images/swap6.png)
139+
140+
10. Your swap will now be displayed in the **Processing Loops** section. It shows you the
141+
swap id, amount, and current status as a progress bar.
142+
143+
Swaps require on-chain transactions, so you will need to wait for confirmations before
144+
they will complete successfully. For more detailed information about the swap process,
145+
take a look at the
146+
[Loop Out In-depth](https://lightning.engineering/posts/2019-04-15-loop-out-in-depth/)
147+
blog post.
148+
149+
11. If you selected a channel, it will be indicated with arrows to remind you that there
150+
is currently a pending swap using the channel.
151+
152+
> Notice that the local balance of this channel dropped by ~8,000,000 sats
153+
154+
12. To close the **Processing Loops** section while waiting for on-chain confirmations,
155+
click on the **Close** icon.
156+
157+
![swap7](./images/swap7.png)
158+
159+
You may perform more than one swap at a time, as long as you have the available funds.
160+
161+
13. To re-open the **Processing Loop** section after closing it, click on the **Maximize**
162+
icon.
163+
164+
![swap8](./images/swap8.png)
165+
166+
Once all swaps are complete, the green check icon is displayed in the **Processing Loop**
167+
section
168+
169+
> Notice that the node's Lightning balance decreased by ~8,000,000 sats and the on-chain
170+
> wallet balance increased by roughly the same amount.
171+
172+
Congratulations! We have just successfully completed our first **Loop Out**.
173+
174+
## View Loop History
175+
176+
![history](./images/history.png)
177+
178+
The **Loop History** page displays a chronological list of all the swaps that have been
179+
executed by your node.
180+
181+
## Manage UI Settings
182+
183+
![settings](./images/settings.png)
184+
185+
The **Settings** page allows you to configure UI settings and view some basic node
186+
information.
187+
188+
> Note: settings are currently stored in the browser and therefore will not persist across
189+
> multiple devices
190+
191+
### Bitcoin Unit
192+
193+
Change the unit of Bitcoin values displayed throughout the website.
194+
195+
| Unit | 1 Unit (in BTC) | Displayed As |
196+
| -------- | --------------- | ----------------- |
197+
| Satoshis | 0.00000001 BTC | 123,456,789 sats |
198+
| Bits | 0.00000100 BTC | 1,234,567.89 bits |
199+
| Bitcoin | 1.00000000 BTC | 1.23456789 BTC |
200+
201+
### Channel Balance Mode
202+
203+
This setting determines how channels are colored and sorted on the **Loop** page according
204+
to your node's operating mode.
205+
206+
Below are the same list of channels viewed using the different **Channel Balance Mode**
207+
options.
208+
209+
![receiving](./images/receiving.png)
210+
211+
**Optimize for Receiving**: For merchants who primarily receive inbound Lightning
212+
payments, the channels with high local balances will be shaded red. The goal is to keep
213+
your local balances as low as possible, so that you can receive more funds inbound.
214+
215+
![sending](./images/sending.png)
216+
217+
**Optimize for Sending**: For exchanges, fiat gateways, and other operators who primarily
218+
send outgoing Lightning payments, the channels with high local balances will be shaded
219+
red. The goal is to keep your local balances as high as possible, so that you can send
220+
more funds outbound.
221+
222+
![routing](./images/routing.png)
223+
224+
**Optimize for Routing**: For routing node operators, that want to keep their channels
225+
balanced close to 50%, the channels with a high balance in either direction will be
226+
flagged.

doc/images/history.png

54.3 KB
Loading

doc/images/loop.png

150 KB
Loading

doc/images/receiving.png

158 KB
Loading

doc/images/routing.png

158 KB
Loading

doc/images/sending.png

158 KB
Loading

doc/images/settings.png

63.8 KB
Loading

doc/images/swap1.png

28 KB
Loading

doc/images/swap2.png

105 KB
Loading

0 commit comments

Comments
 (0)