Merge #606
606: Script to list sellers and auto trigger swap + docs r=da-kami a=da-kami Uses best price to determine the seller to swap with. TODO: - [x] Codebase to be tested on test-/stagenet. - [x] Update readme - [x] Update docs This includes a couple of changes that I found while toying with the output and writing docs. Can drop the individual commits if necessary (but would need to adapt the docs then). Co-authored-by: Daniel Karzel <daniel@comit.network> Co-authored-by: Thomas Eizinger <thomas@eizinger.io>pull/610/head
bors[bot]
3 years ago
committed by
GitHub
commit
93a69563a9
@ -0,0 +1,6 @@
|
||||
# Documentation
|
||||
|
||||
This directory hosts various pieces of documentation.
|
||||
|
||||
- [`swap` CLI](./cli/README.md)
|
||||
- [`asb` service](./asb/README.md)
|
||||
@ -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.
|
||||
@ -0,0 +1,28 @@
|
||||
#!/bin/bash
|
||||
|
||||
CLI_PATH=$1
|
||||
YOUR_MONERO_ADDR=$2
|
||||
YOUR_BITCOIN_ADDR=$3
|
||||
|
||||
CLI_LIST_SELLERS="$CLI_PATH --testnet --json --debug list-sellers"
|
||||
echo "Requesting sellers with command: $CLI_LIST_SELLERS"
|
||||
echo
|
||||
|
||||
BEST_SELLER=$($CLI_LIST_SELLERS | jq -s -c 'min_by(.status .Online .price)' | jq -r '.multiaddr, (.status .Online .price), (.status .Online .min_quantity), (.status .Online .max_quantity)')
|
||||
read ADDR PRICE MIN MAX < <(echo $BEST_SELLER)
|
||||
|
||||
echo
|
||||
|
||||
echo "Seller with best price:"
|
||||
echo " multiaddr : $ADDR"
|
||||
echo " price : $PRICE sat"
|
||||
echo " min_quantity: $MIN sat"
|
||||
echo " max_quantity: $MAX sat"
|
||||
|
||||
echo
|
||||
|
||||
CLI_SWAP="$CLI_PATH --testnet --debug buy-xmr --receive-address $YOUR_MONERO_ADDR --change-address $YOUR_BITCOIN_ADDR --seller $ADDR"
|
||||
|
||||
echo "Starting swap with best seller using command $CLI_SWAP"
|
||||
echo
|
||||
$CLI_SWAP
|
||||
Loading…
Reference in new issue