mirror of
https://github.com/comit-network/xmr-btc-swap.git
synced 2024-10-01 01:45:40 -04:00
Merge #366
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]
GitHub
commit
7cf7e08132
10
README.md
10
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 <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
129
docs/asb/README.md
Normal 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.
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
Contrary, here is a diagram that showcases a service provider running it's own blockchain infrastructure for the ASB:
|
||||
|
||||
|
||||
|
||||
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
|
||||
57
docs/asb/diagrams/cli-asb-components-asb-pub-nodes.puml
Normal file
57
docs/asb/diagrams/cli-asb-components-asb-pub-nodes.puml
Normal 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
|
||||
67
docs/asb/diagrams/cli-asb-components-asb-self-hosted.puml
Normal file
67
docs/asb/diagrams/cli-asb-components-asb-self-hosted.puml
Normal 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
|
||||
34
docs/asb/diagrams/cli-asb-overview.puml
Normal file
34
docs/asb/diagrams/cli-asb-overview.puml
Normal 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
|
||||
Loading…
Reference in New Issue
Block a user