This guide is a work in progress, and its organisation might evolve significantly. This page should however give an up to date overview of to use it.
Every page of this guide is editable by everyone in the web browser on Github thanks to the link “Edit this page” in the upper right corner. Clicking this link will lead you to Github, asking you to fork the repository to edit the page. After you save your changes in your own copy of the repository, you can send a pull request to have your changes included in the guide. Help us improve this guide!
Here are the tools we will use in this guide. They are all integrated in the Docker image accompanying this guide.
We will use httpie to interact with the NEM Infrastructure Server. It provides easy specification of query string parameters, URL shortcuts for localhost (which will shorten your typing if your NIS is listening on localhost, as it is the case if you use the guide’s docker image described below) and many other goodies. Check its documentation for more details.
httpie also outputs colored and readable information about the request and its response. Example in this guide will include httpie’s output when relevant. As an example, here is the output when querying google.com, where you can see the first line is the command executed, then comes the request, followed by the response headers and the response body:
$ http google.comGET / HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Connection: keep-alive Host: google.com User-Agent: HTTPie/0.9.2 HTTP/1.1 302 Found Cache-Control: private Content-Length: 256 Content-Type: text/html; charset=UTF-8 Date: Thu, 30 Mar 2017 19:14:26 GMT Location: http://www.google.be/?gfe_rd=cr&ei=ElndWMabDZPVXuW1j5AG <HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8"> <TITLE>302 Moved</TITLE></HEAD><BODY> <H1>302 Moved</H1> The document has moved <A HREF="http://www.google.be/?gfe_rd=cr&ei=ElndWMabDZPVXuW1j5AG">here</A>. </BODY></HTML>
You can pass POST data on the command line as key-value pairs. For string value, separate key and value with =, for non-string values like integer, use :=.
Insomnia is a great cross platform graphical REST client. Check it out, it might help you greatly in your development workflow.
nem-sdk is a javascript Nem library.
nem-library is an abstraction for NEM Blockchain using a Reactive approach for creating Blockchain applications. It is included in the tools container. Just open the Typescript repl with ./ndev ts-node.
An incompatibility between ts-node and typescript currently requires you to initialise an variable exports to and empty hash like so:
exports = {}
I have also discovered the need to have import instructions consist of only one line.
This will work
import {Account, MultisigTransaction, TimeWindow, Transaction, TransactionTypes} from "nem-library";
but this won’t (in ts-node):
import {Account, MultisigTransaction, TimeWindow,
Transaction, TransactionTypes} from "nem-library";
The tools container also mounts a host directory. This allows you to edit your code in you favourite editor on the
host while still easily compile in the container. By default, the directory in which to put your code in is ./code.
You can then compile your code from the host with
./ndev tsc code/myfile.tsc
and then run it with
./ndev node code/myfile.js
You can also use tsc inside the container to compile your typescript to javascript and then run it with nodejs,
but remember to always put your code under the diretory code or you’ll loose your files at the next shutdown!
ndev -c tools bash
cd code
tsc mycode.ts
node mycode.js
jq is a command line JSON processor. It comes very handy for scripting and quick validations.
mitmproxy is a intercept and inspect traffic flows. mitmweb provides a web interface providing easy access to information required in debugging sessions.
Two containers are accompanying this developer guide, one running only NIS on the testnet, the other proposing all other tools like mitm and nem-sdk. As both containers are meant to always run together, a docker-compose configuration file is available. Both images are based on Ubuntu.
In the NIS container, NIS is started by supervisord. The NIS data is stored under /var/lib/nem, and the logs are available at
/var/log/nis-stderr.log and /var/log/nis-stdout.log.
A helper script ndev is available. This section will give an overview on its usage.
Start by downloading the script in a working directory, for example nem-dev, and make it executable:
mkdir nem-dev
cd nem-dev
curl -q https://raw.githubusercontent.com/rb2nem/nem-dev-guide/master/docker/ndev > ndev
chmod +x ndev
Running the script with --help will give you an overview of all its options. We’ll take a look at the most used options.
Before running the script, create a directory where the container will store its persistent data. This is needed to avoid a full blockchain download at every update of the image. This directory will also hold the network traces automatically captured with tcpdump in the nis container.
The first time you run the script, it will:
./code) exists, and create it if needed.If you run the script without any argument, it will start the containers in background.
To check that the containers are running, you use ./ndev --status.
You can also run a command in the containers, by passing the command as argument to ndev. By default, commands are executed
in the tools container, where mitm is running.
Open a shell in the tools container: ndev bash.
You can select the container in which to run the command with the option -c or --container. To open a shell in the NIS container,
simply run ndev -c nis bash. The -c flag also applies to stopping containers. To stop the nis container only, issue the command
./ndev -c nis -s. The flag -s is actually toggling the running state of the container, so issuing the same command again will start
the container again.
Processes in the containers are managed with supervisord. You can manually control NIS. For example, to stop
nis, simply issue ndev -c nis supervisorctl start nis. To get an overview of the processes running in a container, user the command
supervisorctl status, for example:
$ ./ndev -c nis supervisorctl status
nis RUNNING pid 109, uptime 0:01:03
Only the tools container has ports mapped to the host. Port 7890 is mapped to the mitmweb process, which then sends the requests to the NIS process running in the other container. This makes it possible to inspect requests, as mitmweb exposes a web interface on port 8081 of the host, accessible at http://127.0.0.1:8081. If you get a blank page with Google Chrome, try with Firefox.
You stop and remove the containers with ndev --shutdown. Be sure to copy any data you want to keep out of the cointainers before running this command!
The ndev script mounts the ./code directory into the tools container under /home/nem/code.
If you put a typescript file in that directory, let’s say code/test.ts, you can compile and run it from the host without entering the container with
./ndev tsc code/test.ts
./ndev node code/test.js
This lets you use your favourite editor, while still enjoying the facilities offered by the container.