Keep an eye on the listed Iota Wiki link (the OFFICIAL source) as this is a fast changing area. If you find that this guide needs updating or correcting then please contact @dumdave on the Iota or Assembly Discords.

Guide to the Iota Wasp CLI Tool, GoShimmer and Smart Contracts (for SWARM users) - Part 1

last change to this doc - 23rd Dec 2021

The author of these notes is @dumdave (contact as above)

This document assumes that you have already created a working version of the WASP 'Smart Contracts' node on a VPS running Ubuntu 20.04. See the guide linked here for more on that (and links to installing Bee, Hornet and GoShimmer nodes).

Notes on installing an Iota Wasp Node with SWARM

If you are not using SWARM then you may still find the later parts of this guide useful.

If you want to view the source code for Wasp go to: Wasp Github

As the Smart Contracts area is perhaps the fastest growing area of the whole Iota Ecosystem it is essential to regularly read the Iota Wiki at this point: Running a WASP node in Iota Wiki

Note though that if you read the Wiki, most of the text assumes a different installation method, so you have to pick out the bits that are relevant.

[A]. Using SWARM to configure your WASP Node

Back to this guide, with the assumption that you have SWARM installed. Go to the Main Menu where you will see Option 5 is Wasp. Select that.

SWARM Main Menu

The next page has as option 1 'WASP info', select that to check that you have a working WASP installation.

SWARM Main Menu

This should look a little bit like the following, though probably with a later version of Wasp (this guide version was prepared with Wasp v. 0.2.3).

SWARM Main Menu

Return to the WASP menu and next select Configuration.

SWARM Main Menu

The next screen has WASP-CLI as the first option. This refers to the WASP Command Line tool which is separate software to the Wasp node - SWARM will generally have installed it at the same time as it installed the main Wasp node. Note that you will mostly use the Wasp-CLI tool in the (Terminal) Command Line not SWARM but you can see some information within SWARM.

SWARM Main Menu

The next screen allows you to see your WASP node Peering ID. You won't need this again in this guide as you will working with a single WASP Smart Contract node, but to complete the logic, select the first option to see your ID.

WASP node peering ID

It should look like this.

WASP node peering ID

Back to the settings for the Wasp Node itself. Select 6 on the Wasp Configuration menu in Swarm. You will need to add a setting - for the NODECONN address.

NB Wasp manages the Smart Contract aspects but needs a connection to a GoShimmer node to register information on the network. That is called the NODECONN connection and is 'exposed' by the TXStream plugin which has to be enabled.

Nodeconn connection setting

Now enter an appropriate setting for the GoShimmer node that will be used as your Nodeconn address. Important. Read below for where to find this and why this is probably not your own GoShimmer node if you also set one up using SWARM.

At the time of writing the value being used in creating this version of the guids was: for reasons explained below.

Nodeconn connection setting

How WASP and GoShimmer work together

WASP is responsible for setting up Smart Contract chains. One WASP node can communicate with other WASP nodes to form a committee - a group who together decide on the validity of things that happen in a Smart Contract.

GoShimmer is a node on Iota 2.0, the next generation of the Iota Network. It is essentially the same as the Hornet and Bee nodes except for some advanced functionality. It gossips messages to other GoShimmer nodes and arranges for them to be confirmed on the network.

Each WASP node has a configuration file where the GoShimmer node it uses is set. The WASP node does not itself have any way of storing anything on the Iota network.

There are two separate GoShimmer address settings between WASP and GoShimmer, and it should be the same GoShimmer node in each case. One setting is made for the WASP Node and other one is made for the WASP-CLI tool.

GoShimmer versions and third party Endpoints

After GoShimmer version 0.7.7 it was decided that there needed to be a break while the GoShimmer development progressed without needing to check the WASP interaction all of the time. GoShimmer is now (Dec 2021) on version 0.8.3 or thereabouts. The situation is also subject to sudden change as development progresses.

At this moment in time, Smart Contract development is done using GoShimmer version 0.7.7. As SWARM will normally update your GoShimmer node to the latest version (0.8.3 or later) it will not be the version you need for your Smart Contract development.

For that reason it can be easier to use a community GoShimmer v0.7.7 node rather than your own.

The following is the offical place giving the community nodes.

Official GoShimmer publically available nodes.

At the time of writing the page gives this information: " The TXStream TCP port to use for the nodeconn address with Wasp nodes."

This is also a good place to check to see the WASP and GoShimmer versions currently being recommended. [It was GoShimmer Version v0.7.7 at 22nd Dec 2021]

Latest 22nd Dec 2021: Using the official node details above was giving a timeout for unknown reasons when Deploying a Chain (explained below), however this GoShimmer node allowed Chains to be created. We would expect the official community node to be the one usually used however.

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
In wasp-cli.json:  "api": ""

In the Wasp config.json: "nodeconn": {
    "address": ""
NB The latter changed via the SWARM interface.
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 

[B]. Configuring the WASP-CLI tool

Exit from SWARM and return to the Command Line.

Note. Note that there are 2 separate JSON files, one for Wasp and one for Wasp-CLI.

If you want to see where the WASP CONFIG.json file is then change directory to: /var/lib/wasp

If you want to see where the WASP-CLI file is along with its WASP-CLI.json file, change directory to: /usr/bin

Assuming that WASP-CLI is installed, then simply entering 'wasp-cli' (or ./wasp-cli ) at the command line (without the quote marks) should bring up the following screen.

wasp-cli information screen

[Step 1]. Initialise Wasp-CLI

Enter: wasp-cli init
You should see a message similar to that below.

wasp-cli init screen

[Step 2]. Add connection setting for Wasp-CLI to contact GoShimmer

The following setting comes from the publically available nodes page above, and should be the same GoShimmer instance as that used when configuring the WASP Nodeconn setting earlier.
For example, [The GoShimmer api to allow the WASP-CLI to interact with the Tangle directly].

Enter: wasp-cli set goshimmer.api

This just writes the information to the Wasp-CLI JSON file, so there is no response.

At this point it is useful to inspect the wasp-cli.json file (location as noted above) and look at it using 'nano' or equivalent. It should look something like this.

wasp-cli json file

Note that there is an index of [0] for your own Wasp node, but in real life use there would probably be many Wasp nodes working together.

If you do not have the 'wasp' fields already there, they can be added at the Command Line as follows:

wasp-cli set wasp.0.api
wasp-cli set wasp.0.nanomsg
wasp-cli set wasp.0.peering

[Step 3]. Request funds

Enter: wasp-cli request-funds
You should see a message like this one.

wasp-cli funds screen

To view funds received Enter: wasp-cli balance

wasp-cli balance screen

Hint. If you have a failure to deploy a chain at a later stage, you may find that on a second attempt you get an error message suggesting that you do not have funds. If you then request funds, you may find that does not work as the faucet recognises your seed and thinks you have had your fair share!

The solution is simple. Go back and rerun the 'wasp-cli init' stage again, generating a new seed and allowing you to once again get funds.

[Step 4]. Deploy a Chain

Enter: wasp-cli chain deploy --committee=0 --quorum=1 --chain=mychain2 --description="My second chain"


[a]. There is a single Wasp node in this trial setup, so the quorum to give approval is just 1 (if there were five Wasp nodes involved, it might be 3).

[b]. The entry '--chain=mychain2' puts an entry into the wasp-cli.json file telling it that when the word 'chain' is used in a future command, it refers to the particular chain called 'mychain2'.

If everything goes smoothly then in Terminal there will be a sequence similar to the following:

wasp-cli chain deploy code

The WASP-CLI.JSON file will look something like this:

wasp-cli json updated

[Step 5]. Inspect Chain on Wasp Node

Open the dashboard on your Wasp Node, then go to the tab called CHAINS. The chain that you have just created should be there.

wasp node CHAINS tab

If you then click on the chain, it should give you a second page containing all of the Chain details as follows:

wasp node CHAINS detail 1

wasp node CHAINS detail 2

wasp node CHAINS detail 3

[Step 6]. Note the standard Chain Contracts

There are six of them, but they are discussed in the second part of this guide. Well done for getting your first Chain up and running.

Interesting further material from the Iota Foundation:

Video 8 covers the same ground as this guide, and Video 1 shows how to install Wasp if you do not use SWARM.

[1] YouTube Video - IOTA Smart Contracts Tutorial - WASP node Setup (updated) by Kumar Anirudha 16th Dec 2021

[2] YouTube Video - IOTA Smart Contracts Tutorial - Creating Smart Contracts using AssemblyScript by Kumar Anirudha 16th Nov 2021

[3] YouTube Video - IOTA Smart Contracts Tutorial - Deploying with Schema Tool by Kumar Anirudha 9th Nov 2021

[4] YouTube Video - IOTA Smart Contracts Tutorial - Deploy Solidity Contracts with Hardhat by Kumar Anirudha 8th Nov 2021

[5] YouTube Video - IOTA Smart Contracts Tutorial - Deploy Solidity Contract via Remix + Metamask by Kumar Anirudha 3rd Nov 2021

[6] YouTube Video - IOTA Smart Contracts Tutorial - EVM Chain Setup by Kumar Anirudha 1st Nov 2021

[7] YouTube Video - IOTA Smart Contracts Tutorial - Deploy a Wasm Contract by Kumar Anirudha 1st Nov 2021

[8]YouTube Video - IOTA Smart Contracts Tutorial - WASP Chain Setup by Kumar Anirudha 28th Oct 2021

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ end _ _ _ _ _ _ _ _ _ _ _ _ _ _

While you are here, why not also visit the main area of the website. We are always keen to hear about more International projects to list.

Iota Smart Cities
Iota Identity and Trust
Iota Climate and eHealth
Iota Transport and Mobility