From e423622c79b0ca623c8007212e24010527093689 Mon Sep 17 00:00:00 2001 From: Olaoluwa Osuntokun Date: Wed, 6 Mar 2019 16:39:59 -0800 Subject: [PATCH] README: update README with install notes and diagram --- README.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) diff --git a/README.md b/README.md index 3d5c13b..23e3ab8 100644 --- a/README.md +++ b/README.md @@ -1 +1,106 @@ # Lightning Loop + +## Loop Out Swap (off -> on-chain) + +``` + loop out 500 + | + | + v + .-----------------------------. + | Loop CLI | + | ./cmd/loop | + | | + | | + | .-------------------. | .--------------. .---------------. + | | Loop Client (lib) | | | LND node | | Bitcoin node | + | | ./ |<-------------| |-------------------| | + | | | | | | on-chain | | + | | |------------->| | htlc | | + | | | | off-chain | | | | + | '-------------------' | htlc '--------------' '---------------' + '-----------------|-----------' | ^ + | | | + | v | + | .--. .--. + | _ -( )- _ _ -( )- _ + | .--,( ),--. .--,( ),--. + initiate| _.-( )-._ _.-( )-._ + swap | ( LIGHTNING NETWORK ) ( BITCOIN NETWORK ) + | '-._( )_.-' '-._( )_.-' + | '__,( ),__' '__,( ),__' + | - ._(__)_. - - ._(__)_. - + | | ^ + | | | + v v | + .--------------------. off-chain .--------------. .---------------. + | Loop Server | htlc | LND node | | Bitcoin node | + | |<-------------| | | | + | | | | on-chain | | + | | | | htlc | | + | |--------------| |----------------->| | + | | | | | | + '--------------------' '--------------' '---------------' + +``` + +## Setup + +LND and the swaplet are using go modules. Make sure that the `GO111MODULE` env +variable is set to `on`. + +In order to execute a swap, LND needs to be rebuilt with sub servers enabled. + +### LND + +* Checkout branch `master` + +- `make install tags="signrpc walletrpc chainrpc"` to build and install lnd + with required sub-servers enabled. + +- Make sure there are no macaroons in the lnd dir + `~/.lnd/data/chain/bitcoin/mainnet`. If there are, lnd has been started + before and in that case, it could be that `admin.macaroon` doesn't contain + signer permission. Delete `macaroons.db` and `*.macaroon`. + + DO NOT DELETE `wallet.db` ! + +- Start lnd + +### Loopd +- `git clone https://github.com/lightninglabs/loop.git +- `cd loopd/cmd` +- `go install ./...` + +## Execute a swap + +* Swaps are executed by a client daemon process. Run: + + `loopd` + + By default `loopd` attempts to connect to an 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. + +* To initiate a swap, run: + + `loop uncharge ` + + When the swap is initiated successfully, `loopd` will see the process through. + +* To query and track the swap status, run `loop` without arguments. + +## 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 `~/.swaplet//loopent.db`. + +## Multiple simultaneous swaps + +It is possible to execute multiple swaps simultaneously. +