Git-Mirrors/xmr-btc-swap
1
0
Fork 0
mirror of https://github.com/comit-network/xmr-btc-swap.git synced 2025-08-17 10:41:22 -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

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.