From d2cf45d8b9f0c2e180cd85aa034f370965adc11c Mon Sep 17 00:00:00 2001 From: Daniel Karzel Date: Tue, 23 Mar 2021 18:34:13 +1100 Subject: [PATCH 1/3] ASB CLI service provider overview diagram --- docs/asb/diagrams/cli-asb-overview.puml | 34 +++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 docs/asb/diagrams/cli-asb-overview.puml diff --git a/docs/asb/diagrams/cli-asb-overview.puml b/docs/asb/diagrams/cli-asb-overview.puml new file mode 100644 index 00000000..528a195e --- /dev/null +++ b/docs/asb/diagrams/cli-asb-overview.puml @@ -0,0 +1,34 @@ +@startuml + +package "Service Provider 1" { + + rectangle CLI as cli01 + rectangle CLI as cli02 + rectangle CLI as cli03 + + + rectangle ASB as asb01 + note right of asb01 + Service provider + advertising to + multiple users. + end note + + cli01 -> asb01 + cli02 --> asb01 + asb01 <-- cli03 + +} + +package "Service Provider 2" { + rectangle CLI as cli04 + rectangle ASB as asb02 + note right of asb02 + Service provider + advertising to + one single users. + end note + + cli04 -> asb02 +} +@enduml From 363ce1cdf6fe6478736ff91e1458d650c2319248 Mon Sep 17 00:00:00 2001 From: Daniel Karzel Date: Tue, 23 Mar 2021 18:53:39 +1100 Subject: [PATCH 2/3] ASB CLI component diagrams - Component diagram showcasing both ASB and CLI using public blockchain nodes - Component diagram showcasing ASB using self hosted blockchain nodes and CLI public --- .../cli-asb-components-asb-pub-nodes.puml | 57 ++++++++++++++++ .../cli-asb-components-asb-self-hosted.puml | 67 +++++++++++++++++++ 2 files changed, 124 insertions(+) create mode 100644 docs/asb/diagrams/cli-asb-components-asb-pub-nodes.puml create mode 100644 docs/asb/diagrams/cli-asb-components-asb-self-hosted.puml diff --git a/docs/asb/diagrams/cli-asb-components-asb-pub-nodes.puml b/docs/asb/diagrams/cli-asb-components-asb-pub-nodes.puml new file mode 100644 index 00000000..92e5e608 --- /dev/null +++ b/docs/asb/diagrams/cli-asb-components-asb-pub-nodes.puml @@ -0,0 +1,57 @@ +@startuml + +package "User Host" { + component [Monero Wallet RPC\n(auto installed)] as CliMonRpc + () RPC as MonRpcCli + component "swap" { + component [CLI] as CLI + component [Bitcoin Wallet] as CliBitWal + } + CliMonRpc - MonRpcCli + CLI - CliBitWal + MonRpcCli - CLI +} + +package "Public Monero Server" { + component "monerod" as Monerod +} + +package "Public Bitcoin Server" { + component "Electrum Server" as Electrum + component "bitcoind" as Bitcoind + () "RPC" as BitRPC + BitRPC -- Electrum + Electrum - Bitcoind +} + +package "Service Provider Host" { + component [Monero Wallet RPC] as AsbMonRpc + () RPC as MonRpcAsb + component "asb" { + component [ASB] as ASB + component [Bitcoin Wallet] as AsbBitWal + } + AsbMonRpc - MonRpcAsb + ASB - AsbBitWal + MonRpcAsb - ASB +} + +package "Public Price Server" { + component [CEX Price Ticker] as CEX + () "websocket" as Ticker + Ticker - CEX + Ticker -- ASB +} + +CliBitWal -- BitRPC +CliMonRpc -- Monerod + +AsbMonRpc -- Monerod +AsbBitWal -- BitRPC + +() "libp2p" as Libp2p +Libp2p -- CLI +ASB -- Libp2p + +footer XMR<>BTC swap CLI & ASB overview (public nodes)\nRendered with PlantUML version %version() +@enduml diff --git a/docs/asb/diagrams/cli-asb-components-asb-self-hosted.puml b/docs/asb/diagrams/cli-asb-components-asb-self-hosted.puml new file mode 100644 index 00000000..aba33020 --- /dev/null +++ b/docs/asb/diagrams/cli-asb-components-asb-self-hosted.puml @@ -0,0 +1,67 @@ +@startuml + +package "User Host" { + component [Monero Wallet RPC\n(auto installed)] as CliMonRpc + () RPC as MonRpcCli + component "swap" { + component [CLI] as CLI + component [Bitcoin Wallet] as CliBitWal + } + CliMonRpc - MonRpcCli + CLI - CliBitWal + MonRpcCli - CLI +} + +package "Public Monero Server" { + component "monerod" as Monerod +} + +package "Public Bitcoin Server" { + component "Electrum Server" as Electrum + component "bitcoind" as Bitcoind + () "RPC" as BitRPC + BitRPC -- Electrum + Electrum - Bitcoind +} + +package "Service Provider Host" { + component [Monero Wallet RPC] as AsbMonRpc + () RPC as MonRpcAsb + component "asb" { + component [ASB] as ASB + component [Bitcoin Wallet] as AsbBitWal + } + AsbMonRpc - MonRpcAsb + + component "monerod" as AsbMonerod + component "Electrum Server" as AsbElectrum + component "bitcoind" as AsbBitcoind + + AsbMonRpc -- AsbMonerod + + () "RPC" as AsbBitRPC + + AsbBitWal -- AsbBitRPC + AsbBitRPC -- AsbElectrum + AsbElectrum - AsbBitcoind + + ASB - AsbBitWal + ASB -- MonRpcAsb +} + +package "Public Price Server" { + component [CEX Price Ticker] as CEX + () "websocket" as Ticker + Ticker - CEX + Ticker -- ASB +} + +CliBitWal -- BitRPC +CliMonRpc -- Monerod + +() "libp2p" as Libp2p +Libp2p -- CLI +ASB -- Libp2p + +footer XMR<>BTC swap CLI & ASB overview\nRendered with PlantUML version %version() +@enduml From 1cac82d2127dfe84a4cc39dd470384edfe943557 Mon Sep 17 00:00:00 2001 From: Daniel Karzel Date: Tue, 23 Mar 2021 19:42:25 +1100 Subject: [PATCH 3/3] Document the setup of the ASB - How to run the ASB - ASB component interaction - ASB wallet management --- README.md | 10 ++-- docs/asb/README.md | 129 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 136 insertions(+), 3 deletions(-) create mode 100644 docs/asb/README.md diff --git a/README.md b/README.md index afd68d5f..4d710664 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,11 @@ This repository hosts an MVP for atomically swapping BTC to XMR. It implements the protocol described in section 3 of [this](https://arxiv.org/abs/2101.12332) paper. -## Quick start +More information about the protocol in this [presentation](https://youtu.be/Jj8rd4WOEy0) and this [blog post](https://comit.network/blog/2020/10/06/monero-bitcoin). -1. Download the [latest release](https://github.com/comit-network/xmr-btc-swap/releases/latest) for your operating system +## Quick start - CLI + +1. Download the [latest `swap` binary release](https://github.com/comit-network/xmr-btc-swap/releases/latest) for your operating system 2. Run the binary: `./swap buy-xmr --receive-address ` 3. Follow the instructions printed to the terminal @@ -18,7 +20,7 @@ For now, the MVP is limited to `testnet3` on Bitcoin and `stagenet` on Monero. This repository primarily hosts two components: - the `swap` CLI -- the `asb` service +- the [`asb` service](/docs/asb/README.md) ### swap CLI @@ -32,6 +34,8 @@ The main command is `buy-xmr` which automatically connects to an instance of `as The service acts as the counter-party for the `swap` CLI in the role of Alice. It provides the CLI with a quote and the liquidity necessary for swapping BTC into XMR. +For details on how to run the ASB please refer to the [ASB docs](/docs/asb/README.md). + ## Contact Feel free to reach out to us in the [COMIT-Monero Matrix channel](https://matrix.to/#/#comit-monero:matrix.org). diff --git a/docs/asb/README.md b/docs/asb/README.md new file mode 100644 index 00000000..06460df9 --- /dev/null +++ b/docs/asb/README.md @@ -0,0 +1,129 @@ +# XMR to BTC Atomic Swap - Automated Swap Backend (ASB) + +## Quick Start ASB + +1. Ensure that you have the Monero Wallet RPC running with `--wallet-dir` and `--disable-rpc-login`: + 1. `monero-wallet-rpc --stagenet --daemon-host STAGENET-NODE-URL --rpc-bind-port STAGENET-NODE-PORT --disable-rpc-login --wallet-dir PATH/TO/WALLET/DIR` +2. Run the ASB in terminal: `./asb start` +3. Follow the setup wizard in the terminal + +Public stagenet nodes: + +- `monero-stagenet.exan.tech:38081` +- `stagenet.community.xmr.to:38081` + +Run `./asb --help` for more information. + +## ASB Details + +The ASB is a long running daemon that acts as the trading partner to the swap CLI. +The CLI user is buying XMR (i.e. receives XMR, sends BTC), the ASB service provider is selling XMR (i.e. sends XMR, receives BTC). +The ASB can handle multiple swaps with different peers concurrently. +The ASB communicates with the CLI on various [libp2p](https://libp2p.io/)-based network protocols. + +Both the ASB and the CLI can be run by anybody. +The CLI is designed to run one specific swap against an ASB. +The ASB is designed to run 24/7 as a daemon that responds to CLIs connecting. +Since the ASB is a long running task we specify the person running an ASB as service provider. + +### ASB discovery + +Currently, there is no automated discovery for service providers running an ASB. +A service provider has to manually provide the connection details to users that will run the CLI. + +[Libp2p addressing](https://docs.libp2p.io/concepts/addressing/) is used to identify a service provider by multi-address and peer-id. +The Peer-ID is printed upon startup of the ASB. +The multi-address typically consists of IP-address or URL (if DNS entry configured) of the service provider. + +Each service provider running an ASB can decide how/where to share these connection details. + +![Service Provider scenarios](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/comit-network/xmr-btc-swap/d2cf45d8b9f0c2e180cd85aa034f370965adc11c/docs/asb/diagrams/cli-asb-overview.puml) + +Eventually, more elaborate discovery mechanisms can be added. + +The **CLI** user can specify a service providers's multiaddress and peer-id with `--seller-addr` and `--seller-peer`, see `./swap --help` for details. + +### Setup Details + +In order to understand the different components of the ASB and CLI better here is a component diagram showcasing the ASB and CLI setup using public Bitcoin and Monero infrastructure: + +![Service Provider scenarios](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/comit-network/xmr-btc-swap/363ce1cdf6fe6478736ff91e1458d650c2319248/docs/asb/diagrams/cli-asb-components-asb-pub-nodes.puml) + +Contrary, here is a diagram that showcases a service provider running it's own blockchain infrastructure for the ASB: + +![Service Provider scenarios](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/comit-network/xmr-btc-swap/363ce1cdf6fe6478736ff91e1458d650c2319248/docs/asb/diagrams/cli-asb-components-asb-self-hosted.puml) + +The diagram shows that the `asb` group (representing the `asb` binary) consists of three components: + +1. Monero Wallet +2. Bitcoin Wallet +3. ASB + +The `ASB` depicted in the diagram actually consists of multiple components (protocol impl, network communication, ...) that sums up the functionality to execute concurrent swaps in the role of Alice. + +#### Monero Wallet Setup + +The ASB uses the running Monero wallet RPC to create / open Monero wallets. +Currently you cannot connect to an existing Monero wallet, but the ASB will create the wallet `asb-wallet` upon intial startup. +In order to accept trades with a CLI you will have to send XMR to that wallet. +The wallet's address is printed upon startup of the ASB. +Currently the `asb-wallet` does not have a password. + +Upon startup of the ASB the `asb-wallet` is opened in the wallet RPC. +You can then interact with the wallet RPC for basic wallet management as well. + +#### Bitcoin Wallet Setup + +The ASB has an internally managed Bitcoin wallet. +The Bitcoin wallet is created upon initial startup and stored in the data folder of the ASB (configured through initial startup wizard). + +#### Market Making + +In order to be able to trade, the ASB must define a price to be able to agree on the amounts to be swapped with a CLI. +Currently we use a spot-price mode, i.e. the ASB dictates the price to the CLI. + +A CLI can connect to the ASB at any time and request a quote for buying XMR. +The ASB then returns the current price and the maximum amount tradeable. + +The maximum amount tradeable can be configured with the `--max-buy-btc` parameter. + +The `XMR<>BTC` price is currently determined by the price from the central exchange Kraken. +Upon startup the ASB connects to the Kraken price websocket and listens on the stream for price updates. + +Currently the spot price is equal to the market price on Kraken. + +#### Swap Execution + +Swap execution within the ASB is automated. +Incoming swaps request will be automatically processed and the swap will execute automatically. +Swaps where Bob does not act, so Alice cannot redeem, will be automatically refunded or punished. + +The refund scenario is a scenario where the CLI refunds the Bitcoin. +The ASB can then refund the Monero which will be automatically transferred to the `asb-wallet`. + +The punish scenario is a scenario where the CLI does not refund and hence the ASB cannot refund the Monero. +After a second timelock expires the ASB will automatically punish the CLI user by taking the Bitcoin. + +More information about the protocol in this [presentation](https://youtu.be/Jj8rd4WOEy0) and this [blog post](https://comit.network/blog/2020/10/06/monero-bitcoin). + +All claimed Bitcoin ends up in the internal Bitcoin wallet of the ASB. + +If the ASB has insufficient Monero funds to accept a swap the swap setup is rejected. +Note that currently there is no specific error sent back to the CLI for such kind of cases, so a user might not know why the swap execution was rejected. +Note that there is currently no notification service implemented for low funds. +The ASB provider has to monitor Monero funds to make sure the ASB still has liquidity. + +## Known Limitations + +Bitcoin wallet withdrawal and balance: + +- https://github.com/comit-network/xmr-btc-swap/issues/368 + +Configurable Spread: + +- https://github.com/comit-network/xmr-btc-swap/issues/381 + +Resuming unfinished Swaps: + +- https://github.com/comit-network/xmr-btc-swap/issues/374 +- https://github.com/comit-network/xmr-btc-swap/issues/378