From 974da15ead8fd6778098213973ba36ac16a3aea4 Mon Sep 17 00:00:00 2001 From: Alex Bosworth Date: Wed, 13 Mar 2019 16:11:04 -0700 Subject: [PATCH] docs: move out architecture diagram --- README.md | 57 +++++-------------------------------- docs/architecture.md | 67 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+), 50 deletions(-) create mode 100644 docs/architecture.md diff --git a/README.md b/README.md index 2748d21..c1326c6 100644 --- a/README.md +++ b/README.md @@ -43,56 +43,13 @@ problems. Community support is also available in the [LND Slack](https://join.slack.com/t/lightningcommunity/shared_invite/enQtMzQ0OTQyNjE5NjU1LWRiMGNmOTZiNzU0MTVmYzc1ZGFkZTUyNzUwOGJjMjYwNWRkNWQzZWE3MTkwZjdjZGE5ZGNiNGVkMzI2MDU4ZTE) . -## 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. +## Setup and Install + +LND and the loop client are using Go modules. Make sure that the `GO111MODULE` +env variable is set to `on`. + +In order to execute a swap, LND will need to be rebuilt with sub servers +enabled. ### LND diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..996f36c --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,67 @@ +# Loop Architecture + +Lightning Loop's architecture for orchestrating submarine swaps is based on a +client/server concept. + +The client has a swap execution daemon `loopd` controlled by a CLI application +`loop` which uses a gRPC API. The client daemon initiates swaps and handles +their progress through swap phases. To manage keys and the connection to the +LN/BTC network layers the client daemon connects to a local lnd wallet. + +Client daemons communicate with the Loop server daemon, which is opaque but +operates in a similar way. The server is not a trusted component in this +architecture; the client daemon validates that the terms of the swap are +acceptable and the server cannot access the swap funds unless the swap enters +the "complete" phase. + +## Loop Out Swap (off -> on-chain) + +Phases: + +1. Initiation: Client queries for terms of a swap +2. Fee: Client sends a small fee HTLC that is unrestricted +3. Funding: Client sends a funding HTLC locked to a preimage they generate +4. Payment: Server sends the funds on-chain locked to the funding preimage hash +5. Complete: Client uses the preimage to take the on-chain funds. +6. Final: The server uses the on-chain-revealed preimage to claim funding HTLC + +``` + 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 | | + | |--------------| |----------------->| | + | | | | | | + '--------------------' '--------------' '---------------' +```