feat(atomic-swap): add atomic swap guide by pedroferreira1 · Pull Request #41 · HathorNetwork/rfcs

pedroferreira1 · 2021-12-13T16:57:42Z

guides/0000-atomic-swap.md

msbrogli · 2021-12-15T18:42:54Z

guides/0000-atomic-swap.md

@@ -0,0 +1,97 @@
+### What is atomic swap


I prefer the template format. It seems more intuitive and easier to follow.

I've change the format. What do you think?

msbrogli · 2021-12-15T18:44:19Z

guides/0000-atomic-swap.md

@@ -0,0 +1,97 @@
+### What is atomic swap
+
+Atomic swap is a feature where two different users can exchange different tokens in the same transaction without any third party and any trust.


I'd add that an atomic swap consists of a single transaction that is either executed or not. Hence, the parties do not have to trust each other. If Alice receives Bob's token, then Bob will certainly receives Alice's token.

I've added this to the summary. What do you think?

guides/0000-atomic-swap.md

msbrogli · 2021-12-15T18:47:11Z

guides/0000-atomic-swap.md

+
+![atomic swap wallets drawio](https://user-images.githubusercontent.com/3298774/145630746-ca4c0011-2e01-4574-8143-f3c64c214f4e.png)
+
+The first thing to do is to define how many tokens will be exchanged, i.e. user1 will send X token1 to user2 and user2 will send Y token2 to user1. The atomic swap will happen in some steps that will be done in both wallets, where the users will need to exchange some information after each step. Below there is an image with each step and the explanation of them.


I'd emphasize that the steps are supposed to be executed one after the other.

Not all of them, right? There are steps that can be done concurrently.

That's why I added this in the diagram and it's clear with the number which steps can be done concurrently and the ones that have dependencies.

msbrogli · 2021-12-15T18:47:45Z

guides/0000-atomic-swap.md

+
+![atomic swap wallets drawio](https://user-images.githubusercontent.com/3298774/145630746-ca4c0011-2e01-4574-8143-f3c64c214f4e.png)
+
+The first thing to do is to define how many tokens will be exchanged, i.e. user1 will send X token1 to user2 and user2 will send Y token2 to user1. The atomic swap will happen in some steps that will be done in both wallets, where the users will need to exchange some information after each step. Below there is an image with each step and the explanation of them.


I feel we can add a sequence diagram to illustrate each step and the communication between independent wallets.

In the end of the guide level explanation there is a diagram. Do you prefer to have each step separated? I think I like more the explanation text, then the full diagram.

msbrogli · 2021-12-15T18:49:53Z

guides/0000-atomic-swap.md

+
+The first thing to do is to define how many tokens will be exchanged, i.e. user1 will send X token1 to user2 and user2 will send Y token2 to user1. The atomic swap will happen in some steps that will be done in both wallets, where the users will need to exchange some information after each step. Below there is an image with each step and the explanation of them.
+
+#### Step 1


Before explaining each step in details, I'd add a summary like this:

Wallet 1 and Wallet 2 agrees to exchange 3 X and 1 Y.

Wallet 2 sends its inputs and change outputs to wallet 2.

Wallet 1 generate an unsigned tx with all inputs and outputs.

Wallet 1 signs its inputs (in my example, TxA.inputs[0] only).

Note that the tx is not ready to be pushed yet.

Wallet 1 sends bytes(tx) to Wallet 2.

Wallet 2 receives bytes(tx) , decodes it, and check whether the inputs and ouputs are correct.

Wallet 2 signs its inputs.

Now tx is ready to be pushed.

Wallet 2 pushes the transaction.

Wallet 1 receives the transactions and confirms the swap.

Maybe it should in a sequence diagram.

Maybe add an example as well.

For example, let TxA be a transaction. Let X and Y be two different tokens. Then,

TxA.inputs[0] = 10 X (wallet 1)
TxA.inputs[1] = 5 Y (wallet 2)
TxA.outputs[0] = 3 X (wallet 2)
TxA.outputs[1] = 7 X (wallet 1, change)
TxA.outputs[2] = 1 Y (wallet 1)
TxA.outputs[2] = 4Y (wallet 2, change)

In this case, TxA is an atomic swap of 3 X and 1 Y from wallet 1 and wallet 2.

I've added the summary but I've changed a bit. The example I decided to use is with a central coordinator because it's the request we had from a use case.

About the example, I guess it's confusing this way, we already have the code example in the reference level, I guess it's enough. What do you think?

guides/0000-atomic-swap.md

andreabadesso · 2021-12-23T13:48:57Z

The guide level looks good to me, I would just suggest a refactor on the reference level:

Reference-level explanation

Call node in a folder that you have wallet-lib installed in node_modules

> node

Import the hathor wallet-lib and start both wallets that will take part on the atomic swap

const hathorLib = require('@hathor/wallet-lib')
const conn1 = new hathorLib.Connection({network: 'mainnet', servers: ['https://node1.mainnet.hathor.network/v1a/']});
const conn2 = new hathorLib.Connection({network: 'mainnet', servers: ['https://node1.mainnet.hathor.network/v1a/']});
const pin = '123';
const password = '123';
const wallet1 = new hathorLib.HathorWallet({connection: conn1, password, pinCode: pin, seed: seed1});
const wallet2 = new hathorLib.HathorWallet({connection: conn2, password, pinCode: pin, seed: seed2});

// Start wallets
wallet1.start()
wallet2.start()

Verify that wallets are ready

wallet1.isReady()
wallet2.isReady()

Get available utxos for each wallet and each token

wallet1.getUtxos({ token: token1 })
wallet2.getUtxos({ token: token2 })

Create the tokens, inputs and outputs arrays with change outputs already

const tokens = [token1, token2]

// With the data from the get utxos method you will fill the inputs objects
// in the example below we will swap token1 from wallet1 with token2 from wallet2. token1 will be sent from a single utxo and token2 will be sent from 2 utxos.
const inputs = [{
  tx_id: txId1,
  index: index1,
  token: token1,
  address: address1,
}, {
  tx_id: txId2,
  index: index2,
  token: token2,
  address: address2,
}, {
  tx_id: txId3,
  index: index3,
  token: token2,
  address: address3,
}];

const outputs = [{
  address: address4,
  value: value1,
  token: token1,
  tokenData: 1,
}, {
  address: address5,
  value: value2,
  token: token2,
  tokenData: 2
}];

const data = {
  tokens,
  inputs,
  outputs,
};

hathorLib.transaction.completeTx(data);

Sign the inputs with each wallet by loading their storage on the hathorLib

const dataToSign = hathorLib.transaction.dataToSign(data);
hathorLib.storage.setStore(wallet1.store);
hathorLib.transaction.signTx(data, dataToSign, pin);

hathorLib.storage.setStore(wallet2.store);
hathorLib.transaction.signTx(data, dataToSign, pin);

const transaction = hathorLib.helpersUtils.createTxFromData(data, new hathorLib.Network('mainnet'));
transaction.prepareToSend()

const sendTxObj = new hathorLib.SendTransaction({ transaction })
await sendTxObj.runFromMining();

pedroferreira1 · 2021-12-29T20:08:24Z

@andreabadesso

The guide level looks good to me, I would just suggest a refactor on the reference level:

Refactor done. It's much better. Can you take a look again please?

Pedro Ferreira and others added 2 commits December 13, 2021 13:56

wip(atomic-swap) feat: add atomic swap guide

948b6c5

feat: update guide with latest image flow

1bdd39a

pedroferreira1 changed the title ~~wip(atomic-swap) feat: add atomic swap guide~~ feat(atomic-swap): add atomic swap guide Dec 13, 2021

luislhl reviewed Dec 13, 2021

View reviewed changes

guides/0000-atomic-swap.md Outdated Show resolved Hide resolved

fix: type from W2 to W1*

de8fe69

pedroferreira1 self-assigned this Dec 13, 2021

pedroferreira1 requested review from andreabadesso, luislhl and msbrogli December 13, 2021 17:37

luislhl approved these changes Dec 13, 2021

View reviewed changes

msbrogli requested changes Dec 15, 2021

View reviewed changes

feat: template structure change and some review changes

376e69d

pedroferreira1 requested a review from msbrogli December 20, 2021 17:03

chore: refactor reference level to improve reading the code

4ec5dce

andreabadesso approved these changes Dec 29, 2021

View reviewed changes

luislhl approved these changes Jan 5, 2022

View reviewed changes

jansegre force-pushed the master branch from ebb5226 to 32b9677 Compare January 22, 2024 17:57

		@@ -0,0 +1,97 @@
		### What is atomic swap

		Atomic swap is a feature where two different users can exchange different tokens in the same transaction without any third party and any trust.


		![atomic swap wallets drawio](https://user-images.githubusercontent.com/3298774/145630746-ca4c0011-2e01-4574-8143-f3c64c214f4e.png)

		The first thing to do is to define how many tokens will be exchanged, i.e. user1 will send X token1 to user2 and user2 will send Y token2 to user1. The atomic swap will happen in some steps that will be done in both wallets, where the users will need to exchange some information after each step. Below there is an image with each step and the explanation of them.


		The first thing to do is to define how many tokens will be exchanged, i.e. user1 will send X token1 to user2 and user2 will send Y token2 to user1. The atomic swap will happen in some steps that will be done in both wallets, where the users will need to exchange some information after each step. Below there is an image with each step and the explanation of them.

		#### Step 1

Conversation

pedroferreira1 commented Dec 13, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

andreabadesso commented Dec 23, 2021

Reference-level explanation

Uh oh!

pedroferreira1 commented Dec 29, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pedroferreira1 commented Dec 13, 2021 •

edited

Loading