Replace protocol definition in README with setup instructions

Fixes #262.
This commit is contained in:
Thomas Eizinger 2021-03-05 15:47:16 +11:00
parent 2041f367c6
commit 0b17b1177a
No known key found for this signature in database
GPG Key ID: 651AC83A6C6C8B96

View File

@ -1,71 +1,38 @@
XMR to BTC Atomic Swap
======================
This repository is a proof of concept for atomically swapping XMR for BTC.
This repository hosts an MVP for atomically swapping BTC to XMR.
It implements the protocol described in [this](https://arxiv.org/abs/2101.12332) paper.
We define:
## Quick start
- Alice to be the actor that initially holds XMR.
- Bob to be the actor that initially holds BTC.
1. Download the [latest release](https://github.com/comit-network/xmr-btc-swap/releases/latest) for your operation system
2. Run the binary: `./swap buy-xmr --receive-address <YOUR MONERO ADDRESS>`
3. Follow the instructions printed to the terminal
In the best-case scenario the protocol looks like this:
## Limitations
1. Alice and Bob exchange a set of addresses, keys, zero-knowledge proofs and signatures.
2. Bob publishes `Tx_lock`, locking up his bitcoin in a 2-of-2 multisig output owned by Alice and Bob.
Given the information exchanged in step 1, Bob can refund his bitcoin if he waits until time `t_1` by using `Tx_cancel` and `Tx_refund`.
If Bob doesn't refund after time `t_1`, Alice can punish Bob for being inactive by first publishing `Tx_cancel` and, after `t_2`, spending the output using `Tx_punish`.
3. Alice sees that Bob has locked up the bitcoin, so she publishes `Tx_lock` on the Monero blockchain, locking up her monero in an output which can only be spent with a secret key owned by Alice (`s_a`) *and* a secret key owned by Bob (`s_b`).
This means that neither of them can actually spend this output unless they learn the secret key of the other party.
4. Bob sees that Alice has locked up the monero, so he now sends Alice a missing key bit of information which will allow Alice to redeem the bitcoin using `Tx_redeem`.
5. Alice uses this information to spend the bitcoin to an address owned by her.
When doing so she leaks her Monero secret key `s_a` to Bob through the magic of adaptor signatures.
6. Bob sees Alice's `Tx_redeem` on Bitcoin, extracts Alice's secret key from it and combines it with his own to spend the monero to an address of his own.
For now, the MVP is `limited` to testnet3 on Bitcoin and `stagenet` on Monero.
![BTC/XMR atomic swap protocol](https://github.com/comit-network/xmr-btc-swap/blob/readme/BTC_XMR_atomic_swap_protocol.svg)
## How it works
The repository is structured as a library and a single test function that executes the swap.
The library has the following modules:
This repository primarily hosts two components:
- `alice`: Defines the state machine that describes the swap for Alice.
This includes the messages sent to/from Alice.
- `bob`: Defines the state machine that describes the swap for Bob.
This includes the messages sent to/from Bob.
- `bitcoin`: Keys, signing functions, transactions etc. for Bitcoin.
Also includes a test wallet (see below).
- `monero`: Keys, signing functions, transactions etc. for Monero.
Also includes a test wallet (see below).
- the `swap` CLI
- the `asb` service
Currently we have a single test function that proves the following:
### swap CLI
- Interaction with both block chains and their respective wallets works.
- The messages required are correct and can manually drive the state transitions to execute a swap.
- It is possible to interact with, and watch, the monero blockchain using `monero-wallet-rpc`.
- It is possible to watch a bitcoind instance using `bitcoin-harness` (we already knew this :)
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`.
Currently we do not do:
### asb service
- Actual network communication.
- Verification that the UI is acceptable.
Since we do everything in a single test function there is no user interaction, this is unrealistic for a real product.
`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.
## Testing
We wrote a few additional libraries to facilitate testing:
### Wallets
- `bitcoin` module contains a test wallet by way of `bitcoind`.
- `monero`: module contains a test wallet by way of `monero-wallet-rpc`.
### Blockchain harnesses
We have written two harnesses for interacting with bitcoin and monero.
- [bitcoin-harness](https://github.com/coblox/bitcoin-harness-rs)
- [monero-harness](https://github.com/comit-network/xmr-btc-swap/tree/master/monero-harness)
These harnesses wrap interaction with `bitcoind` and `monerod`/`monero-wallet-rpc`.
We use [testcontainers-rs](https://github.com/testcontainers/testcontainers-rs) to spin up `bitcoind`, `monerod`, and `monero-wallet-rpc` in docker containers during unit/integration testing.
## Contact
Feel free to reach to out us in the [COMIT-Monero Matrix channel](https://matrix.to/#/#comit-monero:matrix.org).