feat(atomic-swap): add atomic swap guide

[pedroferreira1]

Rendered

[msbrogli]

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

[pedroferreira1]

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

[msbrogli]

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.

[pedroferreira1]

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

[msbrogli]

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

[pedroferreira1]

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]

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

[pedroferreira1]

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]

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

1. Wallet 1 and Wallet 2 agrees to exchange 3 X and 1 Y.
2. Wallet 2 sends its inputs and change outputs to wallet 2.
3. Wallet 1 generate an unsigned tx with all inputs and outputs.
4. Wallet 1 signs its inputs (in my example, TxA.inputs[0] only).
5. Note that the tx is not ready to be pushed yet.
6. Wallet 1 sends bytes(tx) to Wallet 2.
7. Wallet 2 receives bytes(tx) , decodes it, and check whether the inputs and ouputs are correct.
8. Wallet 2 signs its inputs.
9. Now tx is ready to be pushed.
10. Wallet 2 pushes the transaction.
11. Wallet 1 receives the transactions and confirms the swap.

Maybe it should in a sequence diagram.

[msbrogli]

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.

[pedroferreira1]

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?

[andreabadesso]

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

---

Reference-level explanation

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

> node

2. 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()

3. Verify that wallets are ready

wallet1.isReady()
wallet2.isReady()

4. Get available utxos for each wallet and each token

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

5. 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);

6. 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]

@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?