From 9a538e30ae7d9f50fcd874fa4d3bf755a2a5d695 Mon Sep 17 00:00:00 2001 From: Luther Blissett Date: Fri, 23 Sep 2022 18:36:49 +0200 Subject: [PATCH] darkotc: Document localnet usage. --- bin/darkotc/README.md | 138 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) diff --git a/bin/darkotc/README.md b/bin/darkotc/README.md index fd3fc82ac..3fec91fbd 100644 --- a/bin/darkotc/README.md +++ b/bin/darkotc/README.md @@ -2,3 +2,141 @@ darkotc ======= Commandline tool for atomic swaps. + + +## Usage (localnet) + +Prerequisite: Compile all the tools: + +``` +% make BINS="darkfid drk faucetd darkotc" +``` + +First start the localnet simulation from `contrib/localnet/darkfid` +called `tmux_sessions.sh` and allow them all to run and sync up. + +We will communicate with two darkfid nodes which represent two peers +in the atomic swap, and with the faucet, so we can get some coins in +our wallets. + +* The first endpoint (Alice) JSON-RPC URI is: `tls://127.0.0.1:8440`. +* The second endpoint (Bob) JSON-RPC URI is: `tls://127.0.0.1:8540`. +* The faucet JSON-RPC URI is: `tls://127.0.0.1:8640`. + + +### Airdropping shitcoins + +Once the daemons are running, we can interact with them. First we +will airdrop some coins to both Alice and Bob, so they can swap them +between each other. We'll also export some variables for easier usage. + +``` +% export ALICE_RPC="tls://127.0.0.1:8440" +% export BOB_RPC="tls://127.0.0.1:8540" +% export FAUCET_RPC="tls://127.0.0.1:8640" +% export ALICE_TOKEN="A7f1RKsCUUHrSXA7a9ogmwg8p3bs6F47ggsW826HD4yd" +% export BOB_TOKEN="BNBZ9YprWvEGMYHW4dFvbLuLfHnN9Bs64zuTFQAbw9Dy" +% ./drk -e "${ALICE_RPC}" airdrop --faucet-endpoint "${FAUCET_RPC}" \ + --token-id "${ALICE_TOKEN}" 113 +% ./drk -e "${BOB_RPC}" airdrop --faucet-endpoint "${FAUCET_RPC}" \ + --token-id "${BOB_TOKEN}" 14 +``` + +This will airdrop 113 `ALICE_TOKEN` into Alice's wallet, and 14 +`BOB_TOKEN` into Bob's wallet. + +Wait a bit until the transactions settle on the blockchain and they +appear in your wallet. You can check this with the `drk` utility: + +``` +% ./drk -e "${ALICE_RPC}" wallet --balance +% ./drk -e "${BOB_RPC}" wallet --balance +``` + +Once the coins are settled, you should see them in a table after +running one of the above commands. + +### Doing everyone's part + +After we have the coins in the wallets, Alice and Bob decide they +want to swap 113 `ALICE_TOKEN` for 14 `BOB_TOKEN`. Now both of them +will do a partial transaction which they are going to join if they +both agree on the parameters, and finally publish it on the network. + +So first, let's have Alice do her part: + +``` +% ./darkotc -e "${ALICE_RPC}" init -t "${ALICE_TOKEN}:${BOB_TOKEN}" \ + -v 113:14 > alice_partial_swap +``` + +This command will make the `darkotc` tool communicate with +her `darkfid` instance and gather necessary information to +create her half of the atomic swap. This includes the ZK mint +and burn proofs, and all the necessary transaction data (see +`darkotc/src/main.rs::PartialSwapData`). + +The way this works is that Alice _mints_ the tokens she wants to +receive (in this case, 14 `BOB_TOKEN`, and _burns_ the token she +wants to send to Bob (in this case 117 `ALICE_TOKEN`). In turn, +Bob does the same with his tokens. + +Once Alice builds her half of the atomic swap, she can send the newly +created file that we redirected from running the `darkotc` tool to +Bob over an encrypted channel. When Bob has it, he can inspect if +everything is in order, beacuse Alice will send all the blinding +values necessary to convince Bob that the transaction they will make +is true. Note however that this cannot be exploited in a way of +stealing Alice's coins, because Alice does not create a signature +for the data she is sending, so if Bob published something else, +it would not be considered valid on the network. + +To inspect the `alice_partial_swap` file, Bob runs: + +``` +% ./darkotc -e "${BOB_RPC}" inspect-partial < alice_partial_swap +``` + +The tool will then verify all pieces of the partial transaction +and report what is or isn't valid. If Bob is satisfied, then he can +proceed by creating his half of the atomic swap: + +``` +% ./darkotc -e "${BOB_RPC}" init -t "${BOB_TOKEN}:${ALICE_TOKEN}" \ + -v 14:113 > bob_partial_swap +``` + +(Note how the values separated by `:` are swapped in contrast to what +Alice has done). + +Now Bob can send this back to Alice for verification. We'll leave that +as an excercise to the reader. + +Once both parties are satisfied with the contents, they can join the +two halves into a full transaction, and sign it. First, Bob will join +both parts and create a signature: + +``` +% ./darkotc -e "${BOB_RPC}" join alice_partial_swap bob_partial_swap \ + | ./darkotc -e "${BOB_RPC}" sign-tx > bob_signed_swap +``` + +Now the `bob_signed_swap` file contains a full atomic swap signed +by Bob. However we're still missing Alice's signature. So Bob sends +back the signed data to Alice, and she can now sign and broadcast it +to the network. + +``` +% ./darkotc -e "${ALICE_RPC}" sign-tx < bob_signed_swap > signed_swap \ + | ./drk -e "${ALICE_RPC}" broadcast +``` + +On success, Alice should see a transaction ID. Now wait until the +swap settles on the network, and check the balances: + +``` +% ./drk -e "${ALICE_RPC}" wallet --balance +% ./drk -e "${BOB_RPC}" wallet --balance +``` + +Alice and Bob successfully executed an atomic swap!