NEM Blockchain onboarding combined with ReasonML crash course
This article explains basic usage of NEM2-SDK with ReasonML, together with NEM2-CLI.
Introduction
We will go trough setting up NEM Catapult services to catapult our blockchain workflow, then we will interact with the blockchain itself using NEM SDK for javascript, but to be extra-cool™ we will write our examples using ReasonML.
ReasonML is essentially a syntax for OCaml programming language, it comes with a bunch of useful tooling, that allows us to compile it to Javascript.
NEM is a relatively new blockchain technology, that handles multisignature transactions with ease, and has a wonderful dev-tooling.
Prerequisite
This article assumes you are familiar on an entry level with Docker, Javascript, Git and Blockchain (e.g. Ethereum, Tezos, …).
Getting started
First of all, let’s go trough the technologies that we will use:
- NEM Blockchain is a platform, that aims to ease the blockchain integration into existing / new apps, by providing a very very nice 💆♀️ developer experience out of the box. It enables private/public chains, smart asset trading and multi-signature transactions.
- ReasonML is a syntax and a toolbox, powered by OCaml, aimed at Javascript developers.
We will start by installing the NEM Catapult stack first. We are mainly interested in those two parts:
- Catapult server nodes (blockchain node); This layer handles the P2P blockchain magic 🧙♂️🔮
- Catapult Rest nodes (API layer); This layer provides an easy way for us (developers) to integrate with NEM 💻
1. Installing Catapult
Start off by cloning the catapult-service-bootstrap repository, and follow up by composing all the docker services using the commands below.
For those who are not familiar with docker or git, we’re copying a bunch of code from a remote repository, and then starting the provided services using docker ‘virtual machines’.
Once the NEM stack is running, your terminal output should look something like this.
Next step is to verify, that our Rest and Blockchain nodes are running. You can do that by querying the REST API provided by Catapult Rest, as shown below.
If everything went as expected, you’ll see a JSON reply similar to the one above.
You have successfully installed NEM Blockchain and REST nodes on your machine! 😎
2. Setting up ReasonML / NEM environment
To develop our blockchain integration with Catapult REST, we will use the NEM SDK, with ReasonML.
Start by creating the appropriate folder structure:
Commands below are executed outside of the ‘git cloned’ directory we created in step 1
We will need an environment to compile our reason scripts. Use a node based docker image, with bs-platform (ReasonML tooling) installed. Click here to learn what role does bs-platform a.k.a. bucklescript compiler play here.
Next step is to build our docker image, so we can use our reason environment.
We will use run-in-docker.sh to provide an interactive shell with ReasonML installed.
Result of the commands above. Dockerfile, run-in-docker.sh created with appropriate content, and reason-bread image available.
Congrats, you’re now ready to communicate with NEM Blockchain, trough scripts written in ReasonML — all that you need to compile and run ReasonML scripts, happens in the docker image we’ve just built.
3. Reason project setup
So far so good, we’ve established a solid base. NEM blockchain and REST nodes are running, and we have a docker-image with a tiny helper script to run ReasonML code.
Next step is to scaffold/generate a reason project.
Our interactive /bin/bash instance, with bucklescript available should look like this.
Yay, project generated successfully.
To confirm that our project has been generated as expected, let’s compile and execute our generated demo script.
Feel free to use a code editor of your choice, I usually opt-in for vscode. Our docker image, takes / mounts files from the same file system that we can access from our ‘real computer’. To learn more click here.
Our generated Demo script written in Reason, as shown in visual studio code editor.
Demo.re is a file, that has been generated for us using bsb -init, and Demo.bs.js is the same, but compiled into javascript.
Compile & run using node, as any other javascript file.
Let’s get this bread
Our setup works as expected, we can move on to the fun part (allegedly 🤔).
First exercise, will create a new account on NEM Blockchain, using the sdk, and the cli.
In our docker environment, install nem2-sdk.
Generating a new account — SDK
Our demo project contains a file named Demo.re, we can delete it. Instead, let’s create a new file in src/, called generateNewAccount.re. We’ll write a bunch of ReasonML code, that will use NEM2-SDK, to talk to the Catapult stack we’ve set up earlier. ReasonML enables us to write type-safe functional code, that interops smoothly with javascript (browser & node).
We want to create a NEM account / wallet, which is a basic identity block for the blockchain — enabling us to use all the cool NEM features such as smart asset trading, or multisignature transactions. We will end up with a private key, public key and an address.
Let’s verify that the file compiles and executes first, then we’ll walk trough it’s contents.
Output of yarn start, if everything went fine.
Now, a new file appeared, generateNewAccount.bs.js. This is in fact our compiled javascript output, thanks to bucklescript compiler. Let’s take a quick look:
Looks familiar huh? What does it do?
- Import the SDK,
- Extract the typescript enum’s value, for MIJIN_TEST
- If the test network is specified properly, use SDK’s Account class, to create a new account
You can now execute the output script, using node.
We have a public/private key pair, with NEM address as well.
Generating a new account — CLI
So far we’ve been able to create a new NEM Account, using the provided SDK, with custom ReasonML bindings. Now let’s try achieving the same result using the NEM CLI.
Our docker image already contains nem2-cli, so let’s use it.
In case your catapult services are not running, you can use the following commands to get them up again.
Now we will use the cli, to generate a new account, and save it to the CLI’s profile list. More or less the same, as our code did prieviously. Make sure to run the following commands, inside run-in-docker.sh — because you need access to nem2-cli that’s installed there.
Command below, will ask you for certain information, we’ll use the same network type as in our Reason examples, while NEM2 Node URL, will change (shown below) — this is due to the fact, that the REST Node, runs in a separate container, than our run-in-docker.sh, so essentially this comes down to docker networking, which you can learn more about here.
You can verify if your account was generated & saved successfully, by listing the existing profiles.
Using private keys generated with Reason
If you want to, you can populate the CLI’s profile list, with accounts generated programatically (using our Reason code).
It’s fairly straight forward:
New profile appears at the bottom
Congrats, you’ve successfully created two (or more?) NEM accounts, which you can now use to explore the rest of the NEM Blockchain. There’s a vast documentation available, you can find it at this link.
What’s next?
In the follow up article, we will explore the NEM2 Faucet, Mosaics and Multi-signature transactions.This will allow us to trade our custom Bread 🥖 (Mosaic / smart asset), for xem (virtual currency) with other accounts on the blockchain.
Part 2 of this series can be found here.
Special thanks to István Deák & Matus Rajsky from NEM Foundation and Matej Nemček ⚡ 孔子 from ProgressBar for organizing an amazing NEM workshop!