xmr-btc-swap/README.md

# XMR to BTC Atomic Swap

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.

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

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. 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

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.

## How it works

This repository primarily hosts two components:

- the `swap` CLI
- the [`asb` service](/docs/asb/README.md)

### swap CLI

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`.

### 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).

## Contact

Feel free to reach out to us in the [COMIT-Monero Matrix channel](https://matrix.to/#/#comit-monero:matrix.org).
Enforce consistent formatting of Markdown files 2021-03-23 19:40:02 -04:00			`# XMR to BTC Atomic Swap`
Add a README.md file Add a readme that describes the project. Specifically - module structure - what we prove and do not prove - how we test 2020-10-07 18:12:17 -04:00
Replace protocol definition in README with setup instructions Fixes #262. 2021-03-04 23:47:16 -05:00			`This repository hosts an MVP for atomically swapping BTC to XMR.`
Minor fixes in README.md 2021-03-15 19:28:51 -04:00			`It implements the protocol described in section 3 of [this](https://arxiv.org/abs/2101.12332) paper.`
Add a README.md file Add a readme that describes the project. Specifically - module structure - what we prove and do not prove - how we test 2020-10-07 18:12:17 -04:00
Document the setup of the ASB - How to run the ASB - ASB component interaction - ASB wallet management 2021-03-23 04:42:25 -04:00			`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).`
Move alice/bob definition comment 2020-10-08 18:46:44 -04:00
Document the setup of the ASB - How to run the ASB - ASB component interaction - ASB wallet management 2021-03-23 04:42:25 -04:00			`## Quick start - CLI`

Update the README for mainnet 2021-05-21 06:09:10 -04:00			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):`

Document the setup of the ASB - How to run the ASB - ASB component interaction - ASB wallet management 2021-03-23 04:42:25 -04:00			1. Download the [latest `swap` binary release](https://github.com/comit-network/xmr-btc-swap/releases/latest) for your operating system
Remove default connection details from CLI Connecting buyers to us by default is not consistent with our vision of a decentralised network of sellers. Closes #395 2021-04-01 00:13:29 -04:00			`2. Run the binary specifying the monero address where you wish to receive monero and the connection details of the seller:`
Update the README for mainnet 2021-05-21 06:09:10 -04:00			`./swap --testnet buy-xmr --receive-address <YOUR MONERO ADDRESS> --seller-peer-id <SELLERS PEER ID> --seller-addr <SELLERS MULTIADDRESS>`
Remove default connection details from CLI Connecting buyers to us by default is not consistent with our vision of a decentralised network of sellers. Closes #395 2021-04-01 00:13:29 -04:00			`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.
`dnsaddr` instead of `dns4` 2021-04-19 08:48:08 -04:00			Our peer id is `12D3KooWCdMKjesXMJz1SiZ7HgotrxuqhQJbP5sgBm2BwP1cqThi` and our multiaddress is `/dnsaddr/xmr-btc-asb.coblox.tech`
Replace protocol definition in README with setup instructions Fixes #262. 2021-03-04 23:47:16 -05:00			`3. Follow the instructions printed to the terminal`
Move alice/bob definition comment 2020-10-08 18:46:44 -04:00
Update the README for mainnet 2021-05-21 06:09:10 -04:00			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.`
Update README Update the readme inline with review suggestions by doing: - Copy 'long story short' text from blog post - Correct the erroneous description of watching blockchains - Fix gramar 2020-10-08 18:34:24 -04:00
Replace protocol definition in README with setup instructions Fixes #262. 2021-03-04 23:47:16 -05:00			`## How it works`
Update README Update the readme inline with review suggestions by doing: - Copy 'long story short' text from blog post - Correct the erroneous description of watching blockchains - Fix gramar 2020-10-08 18:34:24 -04:00
Replace protocol definition in README with setup instructions Fixes #262. 2021-03-04 23:47:16 -05:00			`This repository primarily hosts two components:`
Add a README.md file Add a readme that describes the project. Specifically - module structure - what we prove and do not prove - how we test 2020-10-07 18:12:17 -04:00
Replace protocol definition in README with setup instructions Fixes #262. 2021-03-04 23:47:16 -05:00			- the `swap` CLI
Document the setup of the ASB - How to run the ASB - ASB component interaction - ASB wallet management 2021-03-23 04:42:25 -04:00			- the [`asb` service](/docs/asb/README.md)
Add a README.md file Add a readme that describes the project. Specifically - module structure - what we prove and do not prove - how we test 2020-10-07 18:12:17 -04:00
Replace protocol definition in README with setup instructions Fixes #262. 2021-03-04 23:47:16 -05:00			`### swap CLI`
Add a README.md file Add a readme that describes the project. Specifically - module structure - what we prove and do not prove - how we test 2020-10-07 18:12:17 -04:00
Replace protocol definition in README with setup instructions Fixes #262. 2021-03-04 23:47:16 -05:00			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`.
Add a README.md file Add a readme that describes the project. Specifically - module structure - what we prove and do not prove - how we test 2020-10-07 18:12:17 -04:00
Replace protocol definition in README with setup instructions Fixes #262. 2021-03-04 23:47:16 -05:00			`### asb service`
Add a README.md file Add a readme that describes the project. Specifically - module structure - what we prove and do not prove - how we test 2020-10-07 18:12:17 -04:00
Replace protocol definition in README with setup instructions Fixes #262. 2021-03-04 23:47:16 -05:00			`asb` is short for automated swap backend (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.`
Add a README.md file Add a readme that describes the project. Specifically - module structure - what we prove and do not prove - how we test 2020-10-07 18:12:17 -04:00
Document the setup of the ASB - How to run the ASB - ASB component interaction - ASB wallet management 2021-03-23 04:42:25 -04:00			`For details on how to run the ASB please refer to the [ASB docs](/docs/asb/README.md).`

Replace protocol definition in README with setup instructions Fixes #262. 2021-03-04 23:47:16 -05:00			`## Contact`
Add a README.md file Add a readme that describes the project. Specifically - module structure - what we prove and do not prove - how we test 2020-10-07 18:12:17 -04:00
Minor fixes in README.md 2021-03-15 19:28:51 -04:00			`Feel free to reach out to us in the [COMIT-Monero Matrix channel](https://matrix.to/#/#comit-monero:matrix.org).`