The peer-id is to be provided as part of the multiaddress.
This simplifies the interface for the user.
Note that the `resume` command was not adapted yet, and we are not yet saving the complete multiaddr in the database but only the peer-id.
The fact that we have the rendezvous behaviour composed into the ASB behaviour and handle all events in one eventloop is not optimal. It would be nice if we can handle rendezvous completely separate.
This command uses a rendezvous node to find sellers (i.e. ASBs) and query them for quotes.
Sellers, that can be dialed and queried for a quote will be listed.
@ -7,21 +7,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Fixed
- An issue where the connection between ASB and CLI would get closed prematurely.
The CLI expects to be connected to the ASB throughout the entire swap and hence reconnects as soon as the connection is closed.
This resulted in a loop of connections being established but instantly closed again because the ASB deemed the connection to not be necessary.
See issue https://github.com/comit-network/xmr-btc-swap/issues/648.
## [0.8.1] - 2021-08-16
### Fixed
- An occasional error where users couldn't start a swap because of `InsufficientFunds` that were off by exactly 1 satoshi.
## [0.8.0] - 2021-07-09
### Added
- Printing the deposit address to the terminal as a QR code.
@ -29,42 +14,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Configuration setting for the websocket URL that the ASB connects to in order to receive price ticker updates.
Can be configured manually by editing the config.toml file directly.
It is expected that the server behind the url follows the same protocol as the [Kraken websocket api](https://docs.kraken.com/websockets/).
- Registration and discovery of ASBs using the [libp2p rendezvous protocol](https://github.com/libp2p/specs/blob/master/rendezvous/README.md).
ASBs can register with a rendezvous node upon startup and, once registered, can be automatically discovered by the CLI using the `list-sellers` command.
The rendezvous node address (`rendezvous_point`), as well as the ASB's external addresses (`external_addresses`) to be registered, is configured in the `network` section of the ASB config file.
A rendezvous node is provided at `/dnsaddr/rendezvous.coblox.tech/p2p/12D3KooWQUt9DkNZxEn2R5ymJzWj15MpG6mTW84kyd8vDaRZi46o` for testing purposes.
Upon discovery using `list-sellers` CLI users are provided with quote and connection information for each ASB discovered through the rendezvous node.
- A mandatory `--change-address` parameter to the CLI's `buy-xmr` command.
The provided address is used to transfer Bitcoin in case of a refund and in case the user transfers more than the specified amount into the swap.
For more information see [#513](https://github.com/comit-network/xmr-btc-swap/issues/513).
### Fixed
- An issue where the ASB gives long price guarantees when setting up a swap.
Now, after sending a spot price the ASB will wait for one minute for the CLI's to trigger the execution setup, and three minutes to see the BTC lock transaction of the CLI in mempool after the swap started.
If the first timeout is triggered the execution setup will be aborted, if the second timeout is triggered the swap will be safely aborted.
- An issue where the default Monero node connection string would not work, because the public nodes were moved to a different domain.
The default monerod nodes were updated to use the [melo tool nodes](https://melo.tools/nodes.html).
### Changed
- The commandline interface of the CLI to combine `--seller-addr` and `--seller-peer-id`.
These two parameters have been merged into a parameter `--seller` that accepts a single [multiaddress](https://docs.libp2p.io/concepts/addressing/).
The multiaddress must end with a `/p2p` protocol defining the seller's peer ID.
- The `--data-dir` option to `--data-base-dir`.
Previously, this option determined the final data directory, regardless of the `--testnet` flag.
With `--data-base-dir`, a subdirectory (either `testnet` or `mainnet`) will be created under the given path.
This allows using the same command with or without `--testnet`.
### Removed
- The websocket transport from the CLI.
Websockets were only ever intended to be used for the ASB side to allow websites to retrieve quotes.
The CLI can use regular TCP connections and having both - TCP and websockets - causes problems and unnecessary overhead.
- The `--seller-addr` parameter from the CLI's `resume` command.
This information is now loaded from the database.
- The `--receive-address` parameter from the CLI's `resume` command.
This information is now loaded from the database.
## [0.7.0] - 2021-05-28
@ -188,9 +149,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Fixed an issue where Alice would not verify if Bob's Bitcoin lock transaction is semantically correct, i.e. pays the agreed upon amount to an output owned by both of them.
Fixing this required a **breaking change** on the network layer and hence old versions are not compatible with this version.
@ -5,39 +5,50 @@ 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).
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.
## Quick start - CLI
## 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.
This quickstart guide assumes that you are running the software on testnet (i.e. Bitcoin testnet3 and Monero stagenet):
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:
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:
For more detailed documentation on the CLI, see [this README](./docs/cli/README.md).
- the `swap` CLI
- the [`asb` service](/docs/asb/README.md)
## Becoming a Market Maker
### swap CLI
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.
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`.
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).
### asb service
## Safety
`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.
This software is using cryptography that has not been formally audited.
While we do our best to make it safe, it is up to the user to evaluate whether or not it is safe to use for their purposes.
Please also see section 15 and 16 of the [license](./LICENSE).
For details on how to run the ASB please refer to the [ASB docs](/docs/asb/README.md).
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`).
Each service provider running an ASB can decide how/where to share these connection details.
Eventually, more elaborate discovery mechanisms can be added.
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.
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.
### Setup Details
@ -92,37 +96,28 @@ 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:
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.
```toml
[maker]
min_buy_btc = 0.0001
max_buy_btc = 0.0001
ask_spread = 0.02
price_ticker_ws_url = "wss://ws.kraken.com"
```
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 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.
The maximum amount tradeable can be configured with the `--max-buy-btc` parameter.
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.
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, 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.
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.
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.
If the ASB is restarted unfinished swaps will be resumed automatically.
When 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 back to the `asb-wallet`.
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.
@ -133,6 +128,7 @@ 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.
--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
--tor-socks5-port <tor-socks5-port> Your local Tor socks5 proxy port [default: 9050]
```
Running `swap --testnet list-sellers --rendezvous-point /dnsaddr/rendezvous.coblox.tech/p2p/12D3KooWQUt9DkNZxEn2R5ymJzWj15MpG6mTW84kyd8vDaRZi46o` 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
# This is a utility script to showcase how the swap CLI can discover sellers and then trigger a swap using the discovered sellers
#
# 1st param: Path to the "swap" binary (aka the swap CLI)
# 2nd param: Multiaddress of the rendezvous node to be used for discovery
# 3rd param: Your Monero stagenet address where the XMR will be received
# 4th param: Your bech32 Bitcoin testnet address that will be used for any change output (e.g. refund scenario or when swapping an amount smaller than the transferred BTC)
_=>bail!("The given multiaddress does not end with the peer-id (i.e. /p2p/{peer-id}), make sure you provide the peer-id of the seller as part of the address.")
// Note: We are making very elaborate use of `select!` macro's feature here. Make sure to read the documentation thoroughly: https://docs.rs/tokio/1.4.0/tokio/macro.select.html