mirror of
https://github.com/comit-network/xmr-btc-swap.git
synced 2024-10-01 01:45:40 -04:00
Replace protocol definition in README with setup instructions
Fixes #262.
This commit is contained in:
Thomas Eizinger
parent
2041f367c6
commit
0b17b1177a
77
README.md
77
README.md
@ -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.
|
||||
|
||||
|
||||
## 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).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user