Merge #234

234: add comments to the separate apps example r=D4nte a=da-kami

cleaned up PR, there should not be additional changes @D4nte 

Co-authored-by: Daniel Karzel <daniel.karzel@coblox.tech>
Co-authored-by: Franck Royer <franck@coblox.tech>

Author: 3 people

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Fixed
 - Upgrade `separate_apps` example to comit-sdk 0.7.0 to fix maker auto-accept.
+- Add code comments in `separate_apps` to describe the behaviour and help app developers understand how to use COMIT SDK.
 
 ## [0.5.0] - 2019-11-28
 

README.md

@@ -16,10 +16,12 @@ If you have any question please [reach out to the team in our Gitter chat](https
 
 1. `yarn create comit-app new <your-app-name>`,
 2. `yarn create comit-app start-env` to start blockchain and COMIT nodes,
-3. Run the [btc-eth](https://github.com/comit-network/create-comit-app/tree/master/new_project/examples/btc_eth) example (in separate terminal):
-    1. Navigate to the btc-eth example app directory `cd <path-to-your-app>/examples/btc_eth`,
+3. Run the [separate-apps](https://github.com/comit-network/create-comit-app/tree/master/new_project/examples/separate_apps) example (in separate terminals for the taker and maker):
+    1. Navigate to the separate-apps example app directory `cd <path-to-your-app>/examples/separate-apps`,
     2. `yarn install` to install dependencies,
-    3. `yarn start` to run the application.
+    3. `yarn run maker` to run the maker app.
+    4. `yarn run taker` to run the taker app.
+    5. Follow the steps be hitting `Return` to complete the swap.
 
 You can find additional examples in the [examples](https://github.com/comit-network/create-comit-app/tree/master/new_project/examples) directory that is created as part of step 1.
 

new_project/examples/separate_apps/README.md

@@ -2,6 +2,19 @@
 
 An example project that shows how to swap Bitcoin for Ether with COMIT.
 
+In this example the taker and maker are split up in separate executable files.
+Upon executing the maker and taker apps the execution will bounce between the maker and taker, making the example closer to a production app.
+
+The example includes the simple negotiation protocol provided by the COMIT SDK.
+
+It sets off at the point where the maker has already published an order for the taker.
+It then consists of 5 steps:
+1. The taker takes the order and starts the swap execution.
+2. The taker funds the Ethereum HTLC.
+3. The maker funds the Bitcoin HTLC.
+4. The taker redeems the Bitcoin HTLC.
+5. The maker redeems the Ethereum HTLC.
+
 ## How to run this example
 
 1. Make sure you have an environment setup through `create-comit-app`, 

new_project/examples/separate_apps/src/lib.ts

@@ -2,6 +2,8 @@ import { BitcoinWallet, Cnd, ComitClient, EthereumWallet } from "comit-sdk";
 import fs from "fs";
 
 export async function startClient(index: number): Promise<Actor> {
+    checkEnvFile(process.env.DOTENV_CONFIG_PATH!);
+
     const bitcoinWallet = await BitcoinWallet.newInstance(
         "regtest",
         process.env.BITCOIN_P2P_URI!,

new_project/examples/separate_apps/src/maker.ts

@@ -8,31 +8,25 @@ import { formatEther } from "ethers/utils";
 import moment from "moment";
 import readLineSync from "readline-sync";
 import { toBitcoin } from "satoshi-bitcoin-ts";
-import { checkEnvFile, startClient } from "./lib";
-
-function createOrder(): Order {
-    return {
-        id: "123",
-        tradingPair: "ETH-BTC",
-        validUntil: moment().unix() + 300,
-        ask: {
-            nominalAmount: "9",
-            asset: "ether",
-            ledger: "ethereum",
-        },
-        bid: {
-            nominalAmount: "1",
-            asset: "bitcoin",
-            ledger: "bitcoin",
-        },
-    };
-}
-
+import { startClient } from "./lib";
+
+/**
+ * This executable function represents the maker side during a trade.
+ * A trade consists of two phases: negotiation and execution.
+ *
+ * During the negotiation phase the maker publishes an order that the taker can take.
+ * Once the negotiation is over (i.e. the taker has accepted the order) the execution of the swap commences.
+ *
+ * -- Execution details: --
+ * Most of the logic of the swap execution is done by COMIT SDK. The example tells the ComitClient that
+ * it wants to execute fund and redeem for a specific swap. The ComitClient checks for the availability of the
+ * fund and redeem action in the comit node daemon.
+ */
 (async function main() {
-    checkEnvFile(process.env.DOTENV_CONFIG_PATH!);
-
+    // Initialize the maker Actor
     const maker = await startClient(0);
 
+    // print balances before swapping
     console.log(
         "[Maker] Bitcoin balance: %f. Ether balance: %f",
         parseFloat(await maker.bitcoinWallet.getBalance()).toFixed(2),
@@ -41,46 +35,70 @@ function createOrder(): Order {
         ).toFixed(2)
     );
 
-    const peerId = await maker.comitClient.getPeerId();
-    const addressHint = await maker.comitClient
-        .getPeerListenAddresses()
-        .then(addresses => addresses[0]);
-
-    console.log("[Maker] peer id:", peerId);
-    console.log("[Maker] address hint:", addressHint);
-
-    // start negotiation protocol handler so that a taker can take the order and receives the latest rate
-
+    // Initialize the maker negotiator that defines the negotiation phase of the trade.
+    // The maker negotiator manages the maker's orders, makes them available to potential takers
+    // and defines when an order was taken by a taker.
+    // Once an order was taken by a taker the negotiator hands over the order and execution parameters to the
+    // execution phase.
     const makerNegotiator = new MakerNegotiator(
         maker.comitClient,
         {
+            // Connection information for the comit network daemon.
+            // The maker has to provide this to the taker for the execution phase,
+            // so that the taker's comit network daemon can message the maker's comit network daemon.
             peer: {
-                peer_id: peerId,
-                address_hint: addressHint,
+                peer_id: maker.peerId,
+                address_hint: maker.addressHint,
             },
+            // The expiry time for the taker.
             alpha_expiry: moment().unix() + 7200,
+            // The expiry time for the maker
             beta_expiry: moment().unix() + 3600,
+            // The network the swap will be executed on.
             ledgers: {
                 bitcoin: { network: "regtest" },
-                // TODO: It should be possible to use the chain_id
                 ethereum: { network: "regtest" },
             },
         },
         { maxTimeoutSecs: 1000, tryIntervalSecs: 0.1 }
     );
 
+    // Start the HTTP service used to publish orders.
     const makerHttpApi = new MakerHttpApi(makerNegotiator);
-
+    // The maker's HTTP service will be served at port 2318.
     makerHttpApi.listen(2318);
-    const order = createOrder();
+    // Create an order to be published.
+    const order: Order = {
+        id: "123",
+        tradingPair: "ETH-BTC",
+        validUntil: moment().unix() + 300,
+        ask: {
+            nominalAmount: "9",
+            asset: "ether",
+            ledger: "ethereum",
+        },
+        bid: {
+            nominalAmount: "1",
+            asset: "bitcoin",
+            ledger: "bitcoin",
+        },
+    };
+
+    // Publish the order so the taker can take it.
     makerNegotiator.addOrder(order);
 
+    // Let the world know that there is an order available.
+    // In a real-world application this information could be shared publicly, e.g. on social medias.
     const invitationDetails = `http://localhost:2318/orders/ETH-BTC`;
     console.log(`Waiting for someone taking my order at: ${invitationDetails}`);
 
+    // Wait for a taker to accept the order and send a swap request through the comit network daemon (cnd).
     let swapHandle;
+    // This loop runs until a swap request was sent from the taker to the maker
+    // and a swap is waiting to be processed on the maker's side.
     while (!swapHandle) {
         await new Promise(r => setTimeout(r, 1000));
+        // Check for incoming swaps in the comit node daemon (cnd) of the maker.
         swapHandle = await maker.comitClient.getOngoingSwaps().then(swaps => {
             if (swaps) {
                 return swaps[0];
@@ -90,6 +108,7 @@ function createOrder(): Order {
         });
     }
 
+    // Retrieve the details (properties) of the swap
     const swap = await swapHandle.fetchDetails();
     const swapParams = swap.properties!.parameters;
 
@@ -100,26 +119,64 @@ function createOrder(): Order {
         swapParams.beta_asset.name
     );
 
-    readLineSync.question("2. Continue?");
+    // Wait for commandline input for demo purposes
+    readLineSync.question("3. Continue funding the Bitcoin HTLC?");
 
     const tryParams: TryParams = { maxTimeoutSecs: 100, tryIntervalSecs: 1 };
 
     console.log(
         "Bitcoin HTLC funded! TXID: ",
+
+        // -- FUND --
+        // Wait for the successful execution of the funding transaction of the maker.
+        //
+        // -- Execution Details: --
+        // The maker's fund transaction will only be executed after the maker's comit network daemon (cnd)
+        // has detected the funding transaction of the taker. (The taker funds first.)
+        //
+        // This promise will thus resolve once:
+        // - The taker has sent the fund transaction,
+        // - The maker's comit network daemon has retrieved the taker's fund transaction from an incoming block,
+        // - The maker has sent the fund transaction.
+        //
+        // The transaction ID will be returned by the wallet after sending the transaction.
         await swapHandle.fund(tryParams)
     );
 
-    readLineSync.question("4. Continue?");
+    // Wait for commandline input for demo purposes
+    readLineSync.question("5. Continue redeeming the Ethereum HTLC?");
 
-    console.log("Ether redeemed! TXID: ", await swapHandle.redeem(tryParams));
+    console.log(
+        "Ether redeemed! TXID: ",
+
+        // -- REDEEM --
+        // Wait for the successful execution of the redeem transaction of the maker.
+        //
+        // -- Execution Details: --
+        // The maker's redeem transaction will only be executed after the maker's comit network daemon (cnd)
+        // has detected the redeem transaction of the taker. (The taker redeems first.)
+        //
+        // This promise will thus resolve once:
+        // - The taker has sent the fund transaction,
+        // - The maker's comit network daemon has retrieved the taker's fund transaction from an incoming block,
+        // - The maker has sent the fund transaction,
+        // - The taker's comit network daemon has retrieved the maker's fund transaction from an incoming block,
+        // - The taker has sent the redeem transaction.
+        //
+        // The transaction ID will be returned by the wallet after sending the transaction.
+        await swapHandle.redeem(tryParams)
+    );
 
     console.log("Swapped!");
+
+    // print balances after swapping
     console.log(
         "[Maker] Bitcoin balance: %f. Ether balance: %f",
         parseFloat(await maker.bitcoinWallet.getBalance()).toFixed(2),
         parseFloat(
             formatEther(await maker.ethereumWallet.getBalance())
         ).toFixed(2)
     );
+
     process.exit();
 })();