Git-Mirrors/xmr-btc-swap
1
0
Fork 0
mirror of https://github.com/comit-network/xmr-btc-swap.git synced 2025-10-31 15:09:08 -04:00
Code Issues Projects Releases Packages Wiki Activity

Update docs with latest changes to CLI and ASB

Browse source
This commit is contained in:
Daniel Karzel 2021-07-06 19:39:20 +10:00
parent 5c37fe6733
commit ffad47d515
No known key found for this signature in database
GPG key ID: 30C3FC2E438ADB6E
4 changed files with 200 additions and 63 deletions
Download patch file Download diff file Expand all files Collapse all files

53
README.md
View file

@ -5,50 +5,33 @@ It implements the protocol described in section 3 of [this](https://arxiv.org/ab
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).
## Quick start - CLI
Currently, swaps are only offered in one direction with the `swap` CLI on the buying side (send BTC, receive XMR).
We are working on implementing a protocol where XMR moves first, but are currently blocked by advances on Monero itself.
You can read [this blogpost](https://comit.network/blog/2021/07/02/transaction-presigning) for more information.
From version `0.6.0` onwards the software default to running on `mainnet`.
It is recommended to try the software on testnet first, which can be achieved by providing the `--testnet` flag.
This quickstart guide assumes that you are running the software on testnet (i.e. Bitcoin testnet3 and Monero stagenet):
## Quick Start
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 specifying the monero address where you wish to receive monero and the connection details of the seller:
`./swap --testnet buy-xmr --receive-address <YOUR MONERO ADDRESS> --seller-peer-id <SELLERS PEER ID> --seller-addr <SELLERS MULTIADDRESS>`
You can generate a receive address using your monero wallet.
The seller will provide you their peer id and multiaddress.
We are running an `asb` instance on testnet.
You can swap with to get familiar with the `swap` CLI.
Our peer id is `12D3KooWCdMKjesXMJz1SiZ7HgotrxuqhQJbP5sgBm2BwP1cqThi` and our multiaddress is `/dnsaddr/xmr-btc-asb.coblox.tech`
3. Follow the instructions printed to the terminal
1. Download the [latest `swap` binary release](https://github.com/comit-network/xmr-btc-swap/releases/latest) for your operating system.
2. Find a seller to swap with:
For running the software on mainnet you just omit the `--testnet` flag.
Running on mainnet will automatically apply sane defaults.
Be aware that this software is still early-stage.
Make sure to check `--help` and understand how the `cancel` and `refund` commands work before running on mainnet.
You are running this software at your own risk.
As always we recommend: Verify, don't trust.
All code is available in this repository.
```shell
./swap --testnet --list-sellers
```
## How it works
3. Swap with a seller:
This repository primarily hosts two components:
```shell
./swap --testnet buy-xmr --receive-address <YOUR MONERO ADDRESS> --change-address <YOUR BITCOIN CHANGE ADDRESS> --seller <SELLER MULTIADDRESS>
```
- the `swap` CLI
- the [`asb` service](/docs/asb/README.md)
For more detailed documentation on the CLI, see [this README](./docs/cli/README.md).
### swap CLI
## Becoming a Market Maker
The `swap` CLI acts in the role of Bob and swaps BTC for XMR.
See `./swap --help` for a description of all commands.
The main command is `buy-xmr` which automatically connects to an instance of `asb`.
Swapping of course needs two parties - and the CLI is only one of them: The taker that occasionally starts a swap with a market maker.
### asb service
`asb` is short for **a**utomated **s**wap **b**ackend (we are open to suggestions for better names!).
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).
If you are interested in becoming a market maker you will want to run the second binary provided in this repository: `asb` - the Automated Swap Backend.
Detailed documentation for the `asb` can be found [in this README](./docs/asb/README.md).
## Contact

6
docs/README.md Normal file
View file

@ -0,0 +1,6 @@
# Documentation
This directory hosts various pieces of documentation.
- [`swap` CLI](./cli/README.md)
- [`asb` service](./asb/README.md)

63
docs/asb/README.md
View file

@ -1,6 +1,6 @@
# XMR to BTC Atomic Swap - Automated Swap Backend (ASB)
# Automated Swap Backend (ASB)
## Quick Start ASB
## Quick Start
From version `0.6.0` onwards the software default to running on `mainnet`.
It is recommended to try the software on testnet first, which can be achieved by providing the `--testnet` flag.
@ -42,23 +42,22 @@ Since the ASB is a long running task we specify the person running an ASB as ser
### 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.
The ASB daemon supports the libp2p [rendezvous-protocol](https://github.com/libp2p/specs/tree/master/rendezvous).
Usage of the rendezvous functionality is entirely optional.
[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.
You can configure a rendezvous point in the `[network]` section of your config file.
For the registration to be successful, you also need to configure the externally reachable addresses within the `[network]` section.
For example:
When configuring a domain name for the ASB through a DNS entry, a service provider can configure it by using the [`dnsaddr` format](https://github.com/multiformats/multiaddr/blob/master/protocols/DNSADDR.md) for the TXT entry.
This will simplify the connection detail `--seller-addr` for CLI users connecting to the ASB and provides more flexibility with e.g. ports (i.e. `/dnsaddr/your.domain.tld` instead of `/dns4/your.domain.tld/tcp/port`).
```toml
[network]
rendezvous_point = "/dnsaddr/rendezvous.coblox.tech/p2p/12D3KooWQUt9DkNZxEn2R5ymJzWj15MpG6mTW84kyd8vDaRZi46o"
external_addresses = ["/dns4/example.com/tcp/9939"]
```
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-id`, see `./swap --help` for details.
For more information on the concept of multiaddresses, check out the libp2p documentation [here](https://docs.libp2p.io/concepts/addressing/).
In particular, you may be interested in setting up your ASB to be reachable via a [`/dnsaddr`](https://github.com/multiformats/multiaddr/blob/master/protocols/DNSADDR.md) multiaddress.
`/dnsaddr` addresses provide you with flexibility over the port and also allow you to register two addresses with transports (with and without websockets for example) under the same name.
### Setup Details
@ -96,28 +95,37 @@ The Bitcoin wallet is created upon initial startup and stored in the data folder
#### Market Making
For market making the ASB offers the following parameters in the config:
```toml
[maker]
min_buy_btc = 0.0001
max_buy_btc = 0.0001
ask_spread = 0.02
price_ticker_ws_url = "wss://ws.kraken.com"
```
The minimum and maximum amount as well as a spread, that is added on top of the price fetched from a central exchange, can be configured.
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.
You can plug in a different price ticker websocket using the the `price_ticker_ws_url` configuration option.
You will have to make sure that the format returned is the same as the format used by Kraken.
Currently the spot price is equal to the market price on Kraken.
Currently, we use a spot-price model, 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 minimum and maximum amount tradeable.
#### Swap Execution
Swap execution within the ASB is automated.
Incoming swaps request will be automatically processed and the swap will execute automatically.
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.
When the ASB is restarted unfinished swaps will be resumed automatically.
If the ASB is restarted unfinished swaps will be resumed automatically.
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 ASB can then refund the Monero which will be automatically transferred back 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.
@ -128,7 +136,6 @@ All claimed Bitcoin ends up in the internal Bitcoin wallet of the ASB.
The ASB offers a commands to withdraw Bitcoin and check the balance, run `./asb --help` for details.
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.

141
docs/cli/README.md Normal file
View file

@ -0,0 +1,141 @@
# Swap CLI
The CLI defaults to **mainnet** (from version 0.6.0 onwards).
For testing and to familiarise yourself with the tool, we recommend you to try it on testnet first.
To do that, pass the `--testnet` flag with the actual command:
```shell
swap --testnet <SUBCOMMAND>
```
The two main commands of the CLI are:
- `buy-xmr`: for swapping BTC to XMR with a particular seller
- `list-sellers`: for discovering available sellers through a rendezvous point
Running `swap --help` gives us roughly the following output:
```
swap 0.8.0
The COMIT guys <hello@comit.network>
CLI for swapping BTC for XMR
USAGE:
swap [FLAGS] [OPTIONS] <SUBCOMMAND>
FLAGS:
--debug Activate debug logging
-h, --help Prints help information
-j, --json Outputs all logs in JSON format instead of plain text
--testnet Swap on testnet and assume testnet defaults for data-dir and the blockchain related parameters
-V, --version Prints version information
OPTIONS:
--data-base-dir <data> The base data directory to be used for mainnet / testnet specific data like database, wallets etc
SUBCOMMANDS:
buy-xmr Start a BTC for XMR swap
list-sellers Discover and list sellers (i.e. ASB providers)
cancel Try to cancel an ongoing swap (expert users only)
help Prints this message or the help of the given subcommand(s)
history Show a list of past, ongoing and completed swaps
refund Try to cancel a swap and refund the BTC (expert users only)
resume Resume a swap
```
## Swapping BTC for XMR
Running `swap buy-xmr --help` gives us roughly the following output:
```
swap-buy-xmr 0.8.0
Start a BTC for XMR swap
USAGE:
swap buy-xmr [FLAGS] [OPTIONS] --change-address <bitcoin-change-address> --receive-address <monero-receive-address> --seller <seller>
FLAGS:
-h, --help Prints help information
--testnet Swap on testnet and assume testnet defaults for data-dir and the blockchain related parameters
-V, --version Prints version information
OPTIONS:
--change-address <bitcoin-change-address> The bitcoin address where any form of change or excess funds should be sent to
--receive-address <monero-receive-address> The monero address where you would like to receive monero
--seller <seller> The seller's address. Must include a peer ID part, i.e. `/p2p/`
--electrum-rpc <bitcoin-electrum-rpc-url> Provide the Bitcoin Electrum RPC URL
--bitcoin-target-block <bitcoin-target-block> Estimate Bitcoin fees such that transactions are confirmed within the specified number of blocks
--monero-daemon-address <monero-daemon-address> Specify to connect to a monero daemon of your choice: <host>:<port>
--tor-socks5-port <tor-socks5-port> Your local Tor socks5 proxy port [default: 9050]
```
This command has three core options:
- `--change-address`: A Bitcoin address you control. Will be used for refunds of any kind.
- `--receive-address`: A Monero address you control. This is where you will receive the Monero after the swap.
- `--seller`: The multiaddress of the seller you want to swap with.
## Discovering sellers
Running `swap list-sellers --help` gives us roughly the following output:
```
swap-list-sellers 0.8.0
Discover and list sellers (i.e. ASB providers)
USAGE:
swap list-sellers [FLAGS] [OPTIONS]
FLAGS:
-h, --help Prints help information
--testnet Swap on testnet and assume testnet defaults for data-dir and the blockchain related parameters
-V, --version Prints version information
OPTIONS:
--rendezvous-point <rendezvous-point> Address of the rendezvous point you want to use to discover ASBs [default: /dnsaddr/rendezvous.coblox.tech/p2p/12D3KooWQUt9DkNZxEn2R5ymJzWj15MpG6mTW84kyd8vDaRZi46o]
--tor-socks5-port <tor-socks5-port> Your local Tor socks5 proxy port [default: 9050]
```
This command only takes optional parameters and can be run as-is:
Running `swap --testnet list-sellers` will give you something like:
```
Connected to rendezvous point, discovering nodes in 'xmr-btc-swap-testnet' namespace ...
Discovered peer 12D3KooWPZ69DRp4wbGB3wJsxxsg1XW1EVZ2evtVwcARCF3a1nrx at /dns4/ac4hgzmsmekwekjbdl77brufqqbylddugzze4tel6qsnlympgmr46iid.onion/tcp/8765
+----------------+----------------+----------------+--------+----------------------------------------------------------------------------------------------------------------------------------------+
| PRICE | MIN_QUANTITY | MAX_QUANTITY | STATUS | ADDRESS |
+====================================================================================================================================================================================================+
| 0.00665754 BTC | 0.00010000 BTC | 0.00100000 BTC | Online | /dns4/ac4hgzmsmekwekjbdl77brufqqbylddugzze4tel6qsnlympgmr46iid.onion/tcp/8765/p2p/12D3KooWPZ69DRp4wbGB3wJsxxsg1XW1EVZ2evtVwcARCF3a1nrx |
+----------------+----------------+----------------+--------+----------------------------------------------------------------------------------------------------------------------------------------+
```
or this if a node is not reachable:
```
Connected to rendezvous point, discovering nodes in 'xmr-btc-swap-testnet' namespace ...
Discovered peer 12D3KooWPZ69DRp4wbGB3wJsxxsg1XW1EVZ2evtVwcARCF3a1nrx at /dns4/ac4hgzmsmekwekjbdl77brufqqbylddugzze4tel6qsnlympgmr46iid.onion/tcp/8765
+-------+--------------+--------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------+
| PRICE | MIN_QUANTITY | MAX_QUANTITY | STATUS | ADDRESS |
+============================================================================================================================================================================================+
| ??? | ??? | ??? | Unreachable | /dns4/ac4hgzmsmekwekjbdl77brufqqbylddugzze4tel6qsnlympgmr46iid.onion/tcp/8765/p2p/12D3KooWPZ69DRp4wbGB3wJsxxsg1XW1EVZ2evtVwcARCF3a1nrx |
+-------+--------------+--------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------+
```
## Automating discover and swapping
The `buy-xmr` and `list-sellers` command have been designed to be composed.
[This script](./discover_and_take.sh) is example of what can be done.
Deciding on the seller to use is non-trivial to automate which is why it is not implemented as part of the tool.
## Tor
By default, the CLI will look for Tor at the default socks port `9050` and automatically route all traffic with a seller through Tor.
This allows swapping with sellers that are only reachable with an onion address.
Disclaimer:
Communication with public blockchain explorers (Electrum, public XMR nodes) currently goes through clearnet.
For complete anonymity it is recommended to run your own blockchain nodes.
Use `swap buy-xmr --help` to see configuration options.