Version: 0.15.2

Development Setup

This documentation section shows an overview of how to setup a COMIT-app for development. The tools around the COMIT protocol are listed and the interaction between them is shown.

Introduction

The COMIT project consists of several projects on GitHub. The reference implementation of the protocol is shipped as binary and is called Comit Network Daemon (cnd).

A swap is executed between two parties. We call them a maker and a taker. While the former one creates orders and makes them available, the latter one can take these orders and initiate the swap execution.

Each party runs its own cnd. Typically those two instances would run separately on different machines. For the development environment they are typically started on the same machine. The two cnd nodes communicate via the COMIT communication protocols for exchanging swap parameters prior to executing the swap. Cnd offers a REST API for executing the cryptographic protocols.

For your local dev setup you will need the following components:

  • Two cnd nodes; one for each party of the trade.
  • The respective blockchain nodes for the swap. If you are swapping bitcoin for ether you need a Bitcoin and Ethereum node.
  • Wallets, corresponding to the ledgers, to send transactions. If you are swapping bitcoin for ether you need a Bitcoin and Ethereum wallet.

You can use comit-scripts to start up a development environment based on docker containers.

The COMIT-app holds all the components together and offers an interface for swap negotiation and execution to the user. A COMIT-app typically includes some mechanism to find trading partners and manage orders because cnd does not support negotiation protocols yet.

This slide shows an overview of the components and their interaction.

Javascript Developers

In order to make COMIT more accessible for Javascript developers we offer the comit-sdk and create-comit-app. Create-comit-app includes the comit-scripts module which includes scripts that setup your development environment.

create-comit-app

create-comit-app is a project to help COMIT App developers setup an environment.

The create-comit-app allows you to create a template COMIT App which includes working examples. To create your template app in the my-app directory, just do:

yarn create comit-app my-app
yarn create v1.21.1
[1/4] πŸ” Resolving packages...
[2/4] 🚚 Fetching packages...
[3/4] πŸ”— Linking dependencies...
[4/4] πŸ”¨ Building fresh packages...
success Installed "create-comit-app@0.8.3" with binaries:
- create-comit-app
First time execution, downloading create-comit-app 0.8.3...βœ“
Your project `my-app` has been created!
✨ Done in 7.09s.

Let's have a look at what we have here:

cd my-app
tree # You can alternatively use `ls -R`
.
β”œβ”€β”€ README.md
β”œβ”€β”€ demos
β”‚Β Β  β”œβ”€β”€ btc_eth
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ README.md
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ package.json
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ src
β”‚Β Β  β”‚Β Β  β”‚Β Β  └── index.ts
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ tsconfig.json
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ tslint.json
β”‚Β Β  β”‚Β Β  └── yarn.lock
β”‚Β Β  └── erc20_btc
β”‚Β Β  β”œβ”€β”€ README.md
β”‚Β Β  β”œβ”€β”€ package.json
β”‚Β Β  β”œβ”€β”€ src
β”‚Β Β  β”‚Β Β  └── index.ts
β”‚Β Β  β”œβ”€β”€ tsconfig.json
β”‚Β Β  β”œβ”€β”€ tslint.json
β”‚Β Β  └── yarn.lock
β”œβ”€β”€ examples
β”‚Β Β  β”œβ”€β”€ README.md
β”‚Β Β  └── btc_eth
β”‚Β Β  β”œβ”€β”€ README.md
β”‚Β Β  β”œβ”€β”€ package.json
β”‚Β Β  β”œβ”€β”€ src
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ lib.ts
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ maker.ts
β”‚Β Β  β”‚Β Β  └── taker.ts
β”‚Β Β  β”œβ”€β”€ tsconfig.json
β”‚Β Β  β”œβ”€β”€ tslint.json
β”‚Β Β  └── yarn.lock
β”œβ”€β”€ package.json
└── src
└── index.js
9 directories, 24 files
  • . is where you can start writing your app, see write your app tuto
  • ./package.json contains some useful dependencies for your app
  • ./examples contains projects that are made to inspire developers such as yourself to build their app
  • ./demos contains projects which are catered for workshops demonstration. They do not have a conventional structure but have verbose output.

comit-scripts

The comit-scripts package helps you run a development environment to build a COMIT App.

When creating an application with create-comit-app (yarn create comit-app my-app) it is part of the setup.

Let's install it from the template folder to play with it.

The example package.json of create-comit-app template includes the start-env command of comit-scripts:

{
"name": "my-app",
"version": "0.1.0",
"private": true,
"main": "index.js",
"scripts": {
"start": "node ./src/index.js",
"start-env": "comit-scripts start-env",
"force-clean-env": "comit-scripts force-clean-env"
},
"dependencies": {
"comit-sdk": "^0.10.0"
},
"devDependencies": {
"comit-scripts": "^0.8.3"
}
}

When running start-env the development environemnt is started:

yarn run start-env
yarn run v1.21.1
$ comit-scripts start-env
Creating Docker network (create-comit-app)...βœ“
Starting Ethereum node...βœ“
Starting Bitcoin node...βœ“
Starting two cnds...βœ“
Writing configuration in env file...βœ“
πŸŽ‰ Environment is ready, time to create a COMIT app!
βœ“

The second command force-clean-env can be used if the environment unexpectedly crashed and some containers were not removed. Usually you will not need this command, as Shutdown will properly clean up the containers.

Creating Docker network (create-comit-app)...βœ“

Creates a docker network to allow several docker containers to communicate with each others. The network is named create-comit-app.

Starting Ethereum node...βœ“

  • Starts a parity node in a docker container,
  • Deploys an ERC20 token contract
  • Creates two accounts,
  • Funds each account with 1000 Ethers and 100 ERC20 tokens.

Starting Bitcoin node...βœ“

  • Starts a bitcoind node in a docker container,
  • Creates two HD wallet,
  • Funds each wallet with 10 Bitcoin,
  • Mines a new block every second.

Starting two cnds...βœ“

Starts 2 cnd (COMIT Network Daemon) in docker containers.


Let's take a break and check out what containers are now running:

docker ps
CONTAINER ID IMAGE ... NAMES
207bdd00d103 comitnetwork/cnd:0.4.0 ... cnd_1
e72b5910e530 comitnetwork/cnd:0.4.0 ... cnd_0
7c9855e6f3c0 coblox/bitcoin-core:0.17.0 ... bitcoin
66a52568666d coblox/parity-poa:v2.5.9-stable ... ethereum

Indeed we have bitcoind, parity and 2 cnds running.

Writing configuration in env file...βœ“

Writes useful information to ~/.create-comit-app/env.

Let's have a look at this env file in more details:

cat ~/.create-comit-app/env
BITCOIN_HD_KEY_0=tprv8ZgxMBicQKsPf8tkuTQ3eftSjgnE17mEaoNbDz8r7N9TQd...
BITCOIN_HD_KEY_1=tprv8ZgxMBicQKsPfCW2nYxkfxMnb49PyTYFCF7sdkHdNWBgm8...
BITCOIN_P2P_URI=127.0.0.1:58233
ERC20_CONTRACT_ADDRESS=0x62d69f6867a0a084c6d313943dc22023bc263691
ETHEREUM_KEY_0=77914ef506f41277bd62c9296143c68bbb8006d7c66619af42a626aced947654
ETHEREUM_KEY_1=f8ce18c1bf5c586ef2f89ed04d0296c49bf915483d2866decddd487dc83488c9
ETHEREUM_NODE_HTTP_URL=http://127.0.0.1:58176
HTTP_URL_CND_0=http://127.0.0.1:58248
HTTP_URL_CND_1=http://127.0.0.1:58249

We have here the private keys of the funded accounts on Ethereum and Bitcoin and the endpoint to the various services. This can be used to be imported in my-app so that you can test it with funded accounts.

Two cnds?

You may have noticed that you are getting 2 Bitcoin wallet, 2 Ethereum accounts and 2 cnd instances out of start-env. This is simply due to the fact that one cannot do an atomic swap by themselves!

Atomic swap are inherently peer-to-peer. One can only sell Bitcoin for Ether if someone else buys Bitcoin For Ether. As you need two parties to do a swap, start-env gives you an environment for both parties.

Shutdown

To stop the environment, just hit CTRL+C and wait few seconds:

yarn run start-env
yarn run v1.21.1
$ comit-scripts start-env
Creating Docker network (create-comit-app)...βœ“
Starting Ethereum node...βœ“
Starting Bitcoin node...βœ“
Starting two cnds...βœ“
Writing configuration in env file...βœ“
πŸŽ‰ Environment is ready, time to create a COMIT app!
βœ“
^C🧹 Cleaning up...
βœ“

comit-sdk

caution

This section of the documentation is still under construction. Stay tuned for more content!

The comit JavaScript software development kit (comit-sdk) helps integrating swaps into JavaScript applications. It wraps the communication with cnd to simplify creating and executing swaps. It includes a simple negotiation module that can be used to create and take orders.