How to use the NEM2 blockchain?

Hello fellow readers, follow us today on another journey in the field of distributed ledger technology. Today, we will integrate the NEM2 blockchain protocol into our software.

NEM is a blockchain that exists since March 2015 but since July of 2018, it is possible to experiment with the NEM2 blockchain, aka Catapult.

In this article, we will go through a few simple examples of usage for the NEM2 blockchain open source packages. Most of the packages we are going to use are still under active development and behaviour might change over time.

Additionally, we will be using the API node at: api.beta.catapult.mijin.io:3000, which may change the current deployed NEM2 version making some of the features listed here incompatible. This is to keep this article simple enough and to use the latest vetted NEM2 software.

Defining our Toolset

As defined in the getting started guide on the NEM website in the guide to setup your workstation, we will be installing the nem2-cli package.

In order to have a running NEM2 network we will be using the api.beta.catapult.mijin.io:3000 API node. This is all we need to get started and work with the NEM2 blockchain.

Let us now install the nem2-cli package which will let us interact with our peers.

Let us start with a few commands to create an account and end with monitoring transactions on the blockchain for the created account.

By default, nem2-cli will always use a default profile but you can also name those if you have multiple to manage. So following is the command to create your first NEM2 wallet address which you can use to interact with the latest NEM2 release currently deployed.

Note down your new private key, public key and address.

The command above will save the account to the default profile in nem2-cli. In case you wish to generate the account and import it into a different named profile, just add the –profile argument to nem2-cli commands.

We strongly recommend to use named profiles to keep a better overview of connected peers and available addresses per network.

Interacting with NEM2

As a next step, we can now read the block height of our blockchain. Following command is all the magic that is needed:

Using the nem2-cli you can do pretty much anything that you need with the NEM2 network. In the next section, we will see a few examples of this tool in practise.

Request funds on the current Catapult Beta

NEM2 gives us an amazing tool to feed our mosaic balances with Pull Transactions. Those let us request a certain amount of a given mosaic for our account. The request is sent from our account and the payer must co-sign the transaction.

As a first step, we will request funds from the public beta faucet on the Catapult website. Step over to the website of the Catapult Beta and request funds to your newly created address. Wait up to 15 seconds (next block) and your account should have been funded with 10’000 XEM. This amount is subject to change.

Let us now generate a second address, re-iterate the account generation command and note down the new private key and address. This address will be referred to as the second account.

The account generate command always asks you to set a profile name, we recommend to set human readable names to your profiles to make sure you keep them organised.

For instance, this time you would set as name second_account. This way, whenever you add –profile second_account to any nem2-cli commands, you would be using the second account for signing and properties.

You can check that the account was created by running nem2-cli profile list. You should now have two profiles in that list being our first (default) profile and the second_account profile, as shown below:

Following section will let you issue a similar request of funds, but manually, with your terminal using nem2-cli and the second account that we created.

Request funds manually with a Pull Transaction

Now what this action on the website actually does, is to issue a Pull Transaction as to request funds for our second account.

With the nem2-cli toolset, issuing such a pull transaction can be done with the following command:

If you execute this command, it will request 5 XEM from the account SDUFICQAIHN2VYORJILRQ5YXAERLJF5HDTPJNXVR. You should see something like this as the output:

Note down the second Hash you can see there. This is the transaction hash that must be co-signed before the pull transaction is effective. For this, we will use the co-signature module available in nem2-cli.

Following is an example with the values from the screenshot above:

This will issue a co-signature transaction with our defaultprofile to confirm the funds request. You can use the Block Explorer to watch your transactions when using api.beta.catapult.mijin.io.

The pull transaction is now being executed, and you can use the requested funds with your second account. Now isn’t this a delight? It is now possible to request any mosaic from any account and involved accounts are all required to co-sign the transaction.

The pullfunds transactions available in NEM2 will open the doors to innovative business use cases. We are very excited to be part of the NEM experience and very eager to research, use and analyse it. Funds requests are just one type of transactions that are possible with NEM2, read ahead to find out more!

Sending and receiving tokens

We have already seen a more complicated way of transfer in order to fund our accounts. We will now initiate simple transfers and get information about our account balances.

We will create a transfer transaction from our first account to our second account. This transfer transaction will send 1 XEM to our second account and attach a message to it with the content: Welcome to NEM2.

With nem2-cli, this will be just one command to execute. We need to set a recipient, an amount and a message for the transaction, as shows the following command. Please replace ADDRESS_SECOND_ACCOUNT with the address of your freshly created second account.

Mark the 1’000’000 amount, which represents the amount we want to send, expressed in the smallest unit of the XEM mosaic. XEM amounts have a divisibility of 6, which means we need to add six zeros if we want to send 1 XEM.

In our earlier example, we requested a fund transfer with an amount of 5’000’000, the same principle was applied there. Since we were requesting XEM, we added six zeros in order to request 5 XEM, and not just 0.000005 XEM.

We have now sent funds to our second account. It is time to monitor this second account, and get information about account balances.

Monitor NEM2 Accounts

Now that we have sent out our first transfer transaction to our second account, it is time to monitor the account and check for incoming transactions.

Yet again, nem2-cli is perfect for this task. Following command can be used to monitor transactions of a said account on the NEM2 network:

Once the transaction has been confirmed, the state of our account will be updated. This means that we will have an increased balance of XEM for our second account.

Let us verify this with the NEM2 API, execute the following command to view your account information:

You should get something like the following illustration:

There is more than the info command to discover in the nem2-cli account module. Following are valid commands which you can execute to see some information about your account state:

If you didn’t note down your public key, you can always jump back to the nem2-cli profile list command which will give you an overview of all your stored keys.

With these commands, you can monitor the state of an account very easily. Have a look at the nem2-cli and nem2-sdk source code packages to get more details about the NEM2 APIs.

What else should you know about NEM2?

NEM2 is an advanced blockchain system for which the architecture and source code have been started from scratch and come with the latest innovations of the blockchain field.

Advanced capabilities for the NEM2 blockchain include but are not limited to:

• Atomic swaps of tokens
• Multi-level multi-signature accounts
• Smart asset system
• Aggregate Transactions

Before it gets too complicated, let us research each of these innovations and define how they can be used or integrated in your business logic.

Atomic token swaps

Blockchains and cryptocurrencies have not only opened the doors to a faster transfer of value. With blockchain platforms like NEM2, it is now possible to execute contracts holding value, in a distributed fashion. And more over, those contracts can be atomic.

We are not talking about atoms, but about the atomicity of transactions. From a quick research on what atomic transactions should be we can find:

An atomic transaction is an indivisible and irreducible series of database operations such that either all occur, or nothing occurs

Replace database operations with account transactions in that quote. Atomic token swaps perform multiple transactions with the condition that either all execute or none.

This is very useful in many cases, for instance in the case of transfer of value between two different blockchain networks (token swap). So-called cross-chain token swaps are possible with the current NEM2 technology and we’ll let you know how to implement those in upcoming articles!

Another useful example – outside of the cryptocurrency domain – would be to use a blockchain to facilitate and manage the access to an automated office with many sister companies. A private blockchain would be used as to manage sensitive data privately but sister companies would all share one common distributed ledger as their access database.

It is probable that some of those use cases will require the issuance of multiple cryptocurrencies, in order to represent different components of their business logic. We can see today that digitalisation has to happen on many fronts.

In our automated office use case, atomic swaps will be the communication layer between inter-connected devices (IoT) to exchange value and execute digitalised contracts holding value on different platforms.

Multi-level Multi-signature

Multi-signature transactions in NEM2 combine simplicity and power. You can define a whole hierarchy of co-signer for your multi-signature accounts.

As an example of a multi-level multi-signature account we can define a Distributed Decision Tree in a software company for an upcoming release. Each of the involved accounts are NEM2 accounts as we created earlier. Let us take the following schema as an example:

In this case, the multi-signature configuration is straight-forward. The multi-signature account at the top of the hierarchy is a 3 of 3 multi-signature account which means that all three – the Marketing Team, the Finance Team and the Developer Team – must confirm the release with their respective minimum number of co-signatures.

For instance if two people of the Developer team define the release as being unsafe, they would not co-sign the release announcement transaction. This would block the announcement from happening. With such a structure, many digitalised companies may be managed remotely. Organisations, offices, companies, houses, facilities, etc. – as well.

Many things of our daily lives have yet to discover their digital counterparts.

Smart assets system

What exactly are smart assets? Is this just a marketing buzz created around the word smart? Well, as you will see, with NEM2, assets are indeed smart. They are configurable with properties like mutability of the supply, divisibility (or number of decimals) and dynamic fees (so-called levy fee).

NEM2 comes with an improved Namespace and Mosaics module. Mosaics on NEM are custom tokens created on the public network. On NEM2, it is possible to issue your own Mosaic as well. With many other features than just name registrations, Namespaces and Mosaics are very similar to working with your own blockchain.

NEM2 gives you all the API endpoints needed to manage your custom token without the hassle of re-defining your entire business logic.

As it was already the case with the previous version of NEM (NIS1), NEM2 comes with feature sets laid around powerful aggregate transactions which basically let you create any type of business flows – also with your custom tokens – and make them atomic or co-owned.

Aggregate Transactions

The simplest definition for aggregate transactions would be that they are transaction wrappers which can hold up to 1000 inner transactions also involving up to 15 different accounts.

This system is now also used to allow multi-signature pushes. In fact, using NEM2, you can create aggregate bonded transactions, which are [multiple or one] transaction(s) waiting for co-signatures.

In this way, in NEM2, Multi-signature has been improved to not only be account specific. As, for instance, an aggregate bonded transaction which contains two transfers from two different accounts. The transaction requires the two accounts to co-sign the aggregate bonded.

The inner transactions will all be executed at the same time only if all necessary co-signatures are pushed. Again, potential use cases for this are not defined, but you can have a quick overview of the possibilities on the nem.io website.

In this article we already used an aggregate transaction. When we requested funds manually, we actually created more than one transaction. In total, we created three transactions, two of which are wrapped in an aggregate transaction as listed below:

• We created a Hash Lock transaction with 10 XEM inside. This is required by the NEM2 network to prevent spamming.
• We created an Aggregate Bonded transaction with 5 XEM inside.
  • A first inner transaction holding a message to ask for funds
  • A second inner transaction holding the funds we requested

The advantage with aggregate transactions is that their inner transactions are executed all at once. Multiple actors are involved and operate the aggregate bonded transaction, each of them being notified for their needed actions.

A very powerful feature with aggregate transactions would be the example of a cross chain token swap as demonstrated on the nemtech github pages.

For the early NEMbers who created Mosaics before. Imagine creating your Mosaic and paying XEM fees for your shareholders so that they don’t need to buy XEM to work with your Mosaic. It is actually very simple with aggregate transactions on NEM2.

Conclusion

The NEM2 software may still be under development but it allows for any innovative ideas to be implemented around a standards complying blockchain protocol that is actively being improved.

Building with NEM2 is kept simple, and adapts very well to your business logic, without requiring business logic changes for the integration.

NEM2 comes with qualitative peer reviewed source code and a well-thought-of architecture layer making the work with NEM2 a delight.

Have a look at the available NEM2 repositories on Github:

• nemtech: The NEM2 Github Organisation
• catapult-server: The Peer-to-Peer reference implementation.
• catapult-rest: The RESTful API reference implementation.
• nem2-docs: The documentation package.
• community: How to work with the Open Source NEM2 community.

There is a lot more of course, but those are the repositories which are being worked on more actively at the time of writing this article.

A complete history of terminal commands for this article can be found on Github. We sincerely hope you enjoyed this article and would love to read your feedback! Feel free to contact us via our website or social media platforms.

NEM2 will revolutionise the way you interact with blockchain!

And don’t forget to #NEMJoy!