From 65b0e54a5fc787c761893acaf98388a16d44bb88 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Thu, 8 Oct 2020 09:12:17 +1100 Subject: [PATCH 1/5] 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 --- README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..20683206 --- /dev/null +++ b/README.md @@ -0,0 +1,56 @@ +XMR to BTC Atomic Swap +====================== + +This repository is a proof of concept for atomically swapping XMR for BTC. + +We define: + +- Alice to be the actor that initially holds XMR. +- Bob to be the actor that initially holds BTC. + +The repository is structured as a library and a single test function that executes the swap. +The library has the following modules: + +- `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). + +Currently we have a single test function that proves the following: + +- 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. + + +Currently we do not do: + +- Actual network communication. +- Watch the blockchain for transactions (we just assume they have been mined as soon as we broadcast and move onto the next state). +- Verification that the UI is acceptable. +Since we do everything in a single test function their is no user interaction, this is unrealistic for a real product. + + +## 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. + From 861dcc4a56e827ee49125be15a9a3b60f4db3d74 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Fri, 9 Oct 2020 09:34:24 +1100 Subject: [PATCH 2/5] 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 --- README.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 20683206..f5a58518 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,21 @@ XMR to BTC Atomic Swap This repository is a proof of concept for atomically swapping XMR for BTC. +In the best-case scenario the protocol looks like this: + +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. + +BTC/XMR Atomic Swap Protocol + We define: - Alice to be the actor that initially holds XMR. @@ -24,14 +39,14 @@ Currently we have a single test function that proves the following: - 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 blockcahin using `monero-wallet-rpc` +- It is possible to watch a bitcoind instance using `bitcoin-harness` (we already knew this :) Currently we do not do: - Actual network communication. -- Watch the blockchain for transactions (we just assume they have been mined as soon as we broadcast and move onto the next state). - Verification that the UI is acceptable. -Since we do everything in a single test function their is no user interaction, this is unrealistic for a real product. +Since we do everything in a single test function there is no user interaction, this is unrealistic for a real product. ## Testing From 1f89ea122ecd849cf84048e542adbde63d53fa6e Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Fri, 9 Oct 2020 09:40:26 +1100 Subject: [PATCH 3/5] Fix embedded image --- BTC_XMR_atomic_swap_protocol.svg | 1 + README.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 BTC_XMR_atomic_swap_protocol.svg diff --git a/BTC_XMR_atomic_swap_protocol.svg b/BTC_XMR_atomic_swap_protocol.svg new file mode 100644 index 00000000..63d794c0 --- /dev/null +++ b/BTC_XMR_atomic_swap_protocol.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/README.md b/README.md index f5a58518..61a609b7 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ This means that neither of them can actually spend this output unless they learn 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. -BTC/XMR Atomic Swap Protocol +![BTC/XMR atomic swap protocol](https://github.com/comit-network/xmr-btc-swap/blob/readme/BTC_XMR_atomic_swap_protocol.svg) We define: From 30767ec7552fc4d40ae33a6526bb71e23f5c095e Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Fri, 9 Oct 2020 09:46:44 +1100 Subject: [PATCH 4/5] Move alice/bob definition comment --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 61a609b7..ca9343ce 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,11 @@ XMR to BTC Atomic Swap This repository is a proof of concept for atomically swapping XMR for BTC. +We define: + +- Alice to be the actor that initially holds XMR. +- Bob to be the actor that initially holds BTC. + In the best-case scenario the protocol looks like this: 1. Alice and Bob exchange a set of addresses, keys, zero-knowledge proofs and signatures. @@ -18,11 +23,6 @@ When doing so she leaks her Monero secret key `s_a` to Bob through the magic of ![BTC/XMR atomic swap protocol](https://github.com/comit-network/xmr-btc-swap/blob/readme/BTC_XMR_atomic_swap_protocol.svg) -We define: - -- Alice to be the actor that initially holds XMR. -- Bob to be the actor that initially holds BTC. - The repository is structured as a library and a single test function that executes the swap. The library has the following modules: From bfeb4600730a143704f4609440b68b96c2478787 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Fri, 9 Oct 2020 09:49:39 +1100 Subject: [PATCH 5/5] Fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ca9343ce..e9a2a1dc 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ Currently we have a single test function that proves the following: - 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 blockcahin using `monero-wallet-rpc` +- 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 :) Currently we do not do: