366: Asb docs r=da-kami a=da-kami

Note: 
There is currently quite a lot ongoing to make the ASB better, so the documentation will naturally get outdated. 
Knowing that, I opted for linking to ongoing issues that will improve ASB setup / execution so that users can refer to them to see the progress. 

We need documentation to make ASB setup / exec understandable. Let's see to get this in so we have something to iterate on :)

Co-authored-by: Daniel Karzel <daniel@comit.network>
This commit is contained in:
bors[bot] 2021-03-29 00:06:02 +00:00 committed by GitHub
commit 7cf7e08132
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 294 additions and 3 deletions

View File

@ -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 <YOUR MONERO 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).

129
docs/asb/README.md Normal file
View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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