Skip to content

Commit a6acfda

Browse files
guggeroguggero
authored
Merge pull request #359 from lightninglabs/regtest-server
docs+Docker: document how to use a regtest Loop server
2 parents dcef032 + e5a1914 commit a6acfda

File tree

5 files changed

+412
-0
lines changed

5 files changed

+412
-0
lines changed

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,12 @@ problems. Community support is also available in the
5252
[LND Slack](https://lightning.engineering/slack.html)
5353
.
5454

55+
### Regtest Loop server
56+
57+
To get started with local development against a stripped down dummy Loop server
58+
running in a local `regtest` Bitcoin network, take a look at the
59+
[`regtest` server environment example documentation](./regtest/README.md).
60+
5561
## Setup and Install
5662

5763
LND and the loop client are using Go modules. Make sure that the `GO111MODULE`

‎regtest/README.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# Local regtest setup
2+
3+
To help with development of apps that use the Loop daemon (`loopd`) for
4+
liquidity management, it is often useful to test it in controlled environments
5+
such as on the Bitcoin `regtest` network.
6+
7+
Lightning Labs provides a stripped down version of the Loop server that works
8+
only for `regtest` and is only published in compiled, binary form (currently as
9+
a Docker image).
10+
11+
The `docker-compose.yml` shows an example setup and is accompanied by a quick
12+
start script that should make getting started very easy.
13+
14+
## Requirements
15+
16+
To get this quick start demo environment operational, you need to have the
17+
following tools installed on your system:
18+
- Docker
19+
- `docker-compose`
20+
- `jq`
21+
- `git`
22+
23+
## Starting the environment
24+
25+
Simply download the Loop repository and run the `start` command of the helper
26+
script. This will boot up the `docker-compose` environment, mine some `regtest`
27+
coins, connect and create channels between the two `lnd` nodes and hook up the
28+
Loop client and servers to each other.
29+
30+
```shell
31+
$ git clone https://github.com/lightninglabs/loop
32+
$ cd loop/regtest
33+
$ ./regtest.sh start
34+
```
35+
36+
## Looping out
37+
38+
Looping out is the process of moving funds from your channel (off-chain) balance
39+
into your on-chain wallet through what is called a submarine swap. We use the
40+
`--fast` option here, otherwise the server would wait 30 minutes before
41+
proceeding to allow for batched swaps.
42+
43+
```shell
44+
$ ./regtest.sh loop out --amt 500000 --fast
45+
Send off-chain: 500000 sat
46+
Receive on-chain: 492688 sat
47+
Estimated total fee: 7312 sat
48+
49+
Fast swap requested.
50+
51+
CONTINUE SWAP? (y/n): y
52+
Swap initiated
53+
ID: f96b2e40fd75a63eba61a6ee1e0b17788d77804c0454beb5fbbe4a42a8a06245
54+
HTLC address: bcrt1qwgzsmag0579twr4d8hgfvarqxn27mdmdgfh7wc2hdlupsfqtxwyq5zltqn
55+
56+
Run `loop monitor` to monitor progress.
57+
```
58+
59+
The swap has been initiated now. Let's observe how it works:
60+
61+
```shell
62+
$ ./regtest.sh loop monitor
63+
Note: offchain cost may report as 0 after loopd restart during swap
64+
2021-03-19T17:01:39Z LOOP_OUT INITIATED 0.005 BTC - bcrt1qwgzsmag0579twr4d8hgfvarqxn27mdmdgfh7wc2hdlupsfqtxwyq5zltqn
65+
```
66+
67+
Leave the command running, it will update with every new event. Open a second
68+
terminal window in the same folder/location and mine one block:
69+
70+
```shell
71+
$ ./regtest.sh mine 1
72+
```
73+
74+
You should see your previous window with the `monitor` command update:
75+
76+
```shell
77+
2021-03-19T17:01:39Z LOOP_OUT INITIATED 0.005 BTC - bcrt1qwgzsmag0579twr4d8hgfvarqxn27mdmdgfh7wc2hdlupsfqtxwyq5zltqn
78+
2021-03-19T17:04:37Z LOOP_OUT PREIMAGE_REVEALED 0.005 BTC - bcrt1qwgzsmag0579twr4d8hgfvarqxn27mdmdgfh7wc2hdlupsfqtxwyq5zltqn
79+
```
80+
81+
As soon as the `PREIMAGE_REVEALED` message appears, you know the HTLC was
82+
published to the chain. Finish the process by mining yet another block (in the
83+
second terminal window):
84+
85+
```shell
86+
$ ./regtest.sh mine 1
87+
```
88+
89+
Your `monitor` window should now show the completion of the swap:
90+
91+
```shell
92+
2021-03-19T17:01:39Z LOOP_OUT INITIATED 0.005 BTC - bcrt1qwgzsmag0579twr4d8hgfvarqxn27mdmdgfh7wc2hdlupsfqtxwyq5zltqn
93+
2021-03-19T17:04:37Z LOOP_OUT PREIMAGE_REVEALED 0.005 BTC - bcrt1qwgzsmag0579twr4d8hgfvarqxn27mdmdgfh7wc2hdlupsfqtxwyq5zltqn
94+
2021-03-19T17:06:25Z LOOP_OUT SUCCESS 0.005 BTC - bcrt1qwgzsmag0579twr4d8hgfvarqxn27mdmdgfh7wc2hdlupsfqtxwyq5zltqn (cost: server 50, onchain 6687, offchain 0)
95+
```
96+
97+
Congratulations, you just did a loop out!
98+
99+
# Loop in
100+
101+
Looping in is very similar but does the opposite: swap your on-chain balance for
102+
off-chain (channel) balance:
103+
104+
```shell
105+
$ ./regtest.sh loop in --amt 500000
106+
Send on-chain: 500000 sat
107+
Receive off-chain: 492279 sat
108+
Estimated total fee: 7721 sat
109+
110+
CONTINUE SWAP? (y/n): y
111+
Swap initiated
112+
ID: d95167e33e79df292e5ffeda29d34614a5a087c9378ffae003b9a25bb0f1c2e4
113+
HTLC address (P2WSH): bcrt1q4p0pead4tfepm683fff8fl8g3kpx8spjztuquu2sctfzed9rufls2z0g2f
114+
115+
Run `loop monitor` to monitor progress.
116+
117+
118+
$ ./regtest.sh loop monitor
119+
Note: offchain cost may report as 0 after loopd restart during swap
120+
2021-03-19T17:17:13Z LOOP_IN HTLC_PUBLISHED 0.005 BTC - P2WSH: bcrt1q4p0pead4tfepm683fff8fl8g3kpx8spjztuquu2sctfzed9rufls2z0g2f
121+
```
122+
123+
In your second terminal window, go ahead and mine a block:
124+
125+
```shell
126+
$ ./regtest.sh mine 1
127+
```
128+
129+
You should see your previous window with the `monitor` command update:
130+
131+
```shell
132+
2021-03-19T17:17:13Z LOOP_IN HTLC_PUBLISHED 0.005 BTC - P2WSH: bcrt1q4p0pead4tfepm683fff8fl8g3kpx8spjztuquu2sctfzed9rufls2z0g2f
133+
2021-03-19T17:18:38Z LOOP_IN INVOICE_SETTLED 0.005 BTC - P2WSH: bcrt1q4p0pead4tfepm683fff8fl8g3kpx8spjztuquu2sctfzed9rufls2z0g2f (cost: server -499929, onchain 7650, offchain 0)
134+
```
135+
136+
After mining yet another block, the process should complete:
137+
138+
```shell
139+
$ ./regtest.sh mine 1
140+
```
141+
142+
```shell
143+
2021-03-19T17:17:13Z LOOP_IN HTLC_PUBLISHED 0.005 BTC - P2WSH: bcrt1q4p0pead4tfepm683fff8fl8g3kpx8spjztuquu2sctfzed9rufls2z0g2f
144+
2021-03-19T17:18:38Z LOOP_IN INVOICE_SETTLED 0.005 BTC - P2WSH: bcrt1q4p0pead4tfepm683fff8fl8g3kpx8spjztuquu2sctfzed9rufls2z0g2f (cost: server -499929, onchain 7650, offchain 0)
145+
2021-03-19T17:19:21Z LOOP_IN SUCCESS 0.005 BTC - P2WSH: bcrt1q4p0pead4tfepm683fff8fl8g3kpx8spjztuquu2sctfzed9rufls2z0g2f (cost: server 71, onchain 7650, offchain 0)
146+
```
147+
148+
# Using the Loop server in an existing setup
149+
150+
This `docker-compose` is only meant as a demo and quick start help. You can of
151+
course also integrate the Loop server Docker image into your existing `regtest`
152+
environment.
153+
154+
Simply pull the image and run it by pointing it to an existing `lnd` node:
155+
156+
```shell
157+
$ docker pull lightninglabs/loopserver:latest
158+
$ docker run -d \
159+
-p 11009:11009 \
160+
-v /some/dir/to/lnd:/root/.lnd \
161+
lightninglabs/loopserver:latest \
162+
daemon \
163+
--maxamt=5000000 \
164+
--lnd.host=some-lnd-node:10009 \
165+
--lnd.macaroondir=/root/.lnd/data/chain/bitcoin/regtest \
166+
--lnd.tlspath=/root/.lnd/tls.cert \
167+
```
168+
169+
An existing Loop client (`loopd`) can then be pointed to this server with:
170+
171+
```shell
172+
$ loopd \
173+
--network=regtest \
174+
--debuglevel=debug \
175+
--server.host=localhost:11009 \
176+
--server.notls \
177+
--lnd.host=some-other-lnd-node:10009 \
178+
--lnd.macaroonpath=/root/.lnd/data/chain/bitcoin/regtest/admin.macaroon \
179+
--lnd.tlspath=/root/.lnd/tls.cert
180+
```
181+
182+
The `--server.notls` is important here as the `regtest` version of the Loop
183+
server only supports insecure, non-TLS connections.
184+
185+
Also make sure you connect the Loop server and Loop client to a different `lnd`
186+
node each since an `lnd` node cannot pay itself. Obviously there also need to be
187+
some channels with enough liquidity between the server's and client's `lnd`
188+
nodes (direct or indirect doesn't matter).

‎regtest/docker-compose.yml‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
version: '3'
2+
services:
3+
bitcoind:
4+
image: ruimarinho/bitcoin-core:0.21-alpine
5+
restart: unless-stopped
6+
networks:
7+
- regtest
8+
command:
9+
- "-txindex"
10+
- "-regtest"
11+
- "-rest"
12+
- "-printtoconsole"
13+
- "-zmqpubrawblock=tcp://0.0.0.0:28332"
14+
- "-zmqpubrawtx=tcp://0.0.0.0:28333"
15+
- "-rpcport=18443"
16+
- "-rpcbind=0.0.0.0"
17+
# This is just the hashed string "lightning" with a salt.
18+
- "-rpcauth=lightning:8492220e715bbfdf5f165102bfd7ed4$$88090545821ed5e9db614588c0afbad575ccc14681fb77f3cae6899bc419af67"
19+
- "-rpcallowip=172.0.0.0/8"
20+
- "-rpcallowip=127.0.0.1"
21+
- "-fallbackfee=0.0002"
22+
- "-peerblockfilters=1"
23+
- "-blockfilterindex=1"
24+
- "-wallet=/home/bitcoin/.bitcoin/regtest/wallets/miner"
25+
environment:
26+
- HOME=/home/bitcoin
27+
28+
lndserver:
29+
image: lightninglabs/lnd:v0.12.1-beta
30+
restart: unless-stopped
31+
networks:
32+
- regtest
33+
volumes:
34+
- "lndserver:/root/.lnd"
35+
depends_on:
36+
- bitcoind
37+
command:
38+
- "--alias=lndserver"
39+
- "--rpclisten=0.0.0.0:10009"
40+
- "--noseedbackup"
41+
- "--bitcoin.active"
42+
- "--bitcoin.regtest"
43+
- "--bitcoin.node=bitcoind"
44+
- "--bitcoind.rpchost=regtest_bitcoind_1"
45+
- "--bitcoind.rpcuser=lightning"
46+
- "--bitcoind.rpcpass=lightning"
47+
- "--bitcoind.zmqpubrawblock=tcp://regtest_bitcoind_1:28332"
48+
- "--bitcoind.zmqpubrawtx=tcp://regtest_bitcoind_1:28333"
49+
- "--tlsextradomain=regtest_lndserver_1"
50+
51+
loopserver:
52+
image: lightninglabs/loopserver:latest
53+
restart: unless-stopped
54+
networks:
55+
- regtest
56+
volumes:
57+
- "lndserver:/root/.lnd"
58+
depends_on:
59+
- lndserver
60+
command:
61+
- "daemon"
62+
- "--maxamt=5000000"
63+
- "--lnd.host=regtest_lndserver_1:10009"
64+
- "--lnd.macaroondir=/root/.lnd/data/chain/bitcoin/regtest"
65+
- "--lnd.tlspath=/root/.lnd/tls.cert"
66+
67+
lndclient:
68+
image: lightninglabs/lnd:v0.12.1-beta
69+
restart: unless-stopped
70+
networks:
71+
- regtest
72+
volumes:
73+
- "lndclient:/root/.lnd"
74+
depends_on:
75+
- bitcoind
76+
command:
77+
- "--alias=lndclient"
78+
- "--rpclisten=0.0.0.0:10009"
79+
- "--noseedbackup"
80+
- "--bitcoin.active"
81+
- "--bitcoin.regtest"
82+
- "--bitcoin.node=bitcoind"
83+
- "--bitcoind.rpchost=regtest_bitcoind_1"
84+
- "--bitcoind.rpcuser=lightning"
85+
- "--bitcoind.rpcpass=lightning"
86+
- "--bitcoind.zmqpubrawblock=tcp://regtest_bitcoind_1:28332"
87+
- "--bitcoind.zmqpubrawtx=tcp://regtest_bitcoind_1:28333"
88+
- "--tlsextradomain=regtest_lndclient_1"
89+
90+
loopclient:
91+
image: loopd
92+
build:
93+
context: ../
94+
dockerfile: Dockerfile
95+
restart: unless-stopped
96+
networks:
97+
- regtest
98+
volumes:
99+
- "lndclient:/root/.lnd"
100+
depends_on:
101+
- lndclient
102+
command:
103+
- "loopd"
104+
- "--network=regtest"
105+
- "--debuglevel=debug"
106+
- "--server.host=regtest_loopserver_1:11009"
107+
- "--server.notls"
108+
- "--lnd.host=regtest_lndclient_1:10009"
109+
- "--lnd.macaroonpath=/root/.lnd/data/chain/bitcoin/regtest/admin.macaroon"
110+
- "--lnd.tlspath=/root/.lnd/tls.cert"
111+
112+
networks:
113+
regtest:
114+
115+
volumes:
116+
lndserver:
117+
lndclient:

0 commit comments

Comments
 (0)