From 0b17b1177ac28440677f2c57ebeaabc6432bb69f Mon Sep 17 00:00:00 2001 From: Thomas Eizinger Date: Fri, 5 Mar 2021 15:47:16 +1100 Subject: [PATCH] Replace protocol definition in README with setup instructions Fixes #262. --- README.md | 77 ++++++++++++++++--------------------------------------- 1 file changed, 22 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index e9a2a1dc..c27b3d63 100644 --- a/README.md +++ b/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 ` +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).