Deploy your first Ardor Lightweight Contract

Lightweight contracts coming to Ardor

With the release of Ardor 2.1.2e and the available plugin for IntelliJ the time has come to try out this interesting piece of technology! This article explains the first steps to set you up for smart contract development on Ardor.

I tried to explain a few more details than the introduction in the nxtwiki, so I hope this tutorial works for beginners. It was originally aimed for Ubuntu / Linux, but the amount of OS specific configuration is small (steps 1,2,6) - so this tutorial might help you set up your environment on other platforms, too.

We will go through the installation of all required packages and the setup of the Ardor client, the contract runner and manager. Finally we’ll deploy the sample HelloWorld contract that is shipped with Ardor.

Step1, Installing Java JDK 8

To install Java JDK 8 using the Ubuntu package management open a terminal and execute the following commands:

sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java8-installer

A menu will open in the terminal and guide you through the installation.

To use Java, add the path to your system’s environment in /etc/environment:

cat >> /etc/environment <<EOL
JAVA_HOME=/usr/lib/jvm/java-8-oracle
JRE_HOME=/usr/lib/jvm/java-8-oracle/jre
EOL

or just use a text editor and add the two lines beginning with JAVA_HOME and JRE_HOME to the file.

Step 2, Install Ardor 2.1.1e

Download the latest Ardor experimental release 2.1.1e from www.jelurida.com. Choose the “UNIX installer” from the website (the platform independent zip doesn’t contain the developer tools).

Open a terminal. In your home directory type:

cd Downloads
chmod u+x ardor-client-2.1.1e.sh
./ardor-client-2.1.1e.sh

The shell script will open the installer. Follow the installation, for this tutorial we assume Ardor is installed in /home/you/Ardor. Leave the dev.tools checkbox checked. I’ve choosen console mode (but it shouldn’t make a difference)

Step 3, Set up the Contract Runner.

From now on we will work in the Ardor/ folder (/home/malnemark/Ardor by default).
Now create a file nxt.properties in the conf/ folder with the following three lines:

nxt.isTestnet=true
nxt.addOns=nxt.addons.ContractRunner
addon.contractRunner.configFile=./conf/contracts.json

The nxtwiki states that missing to provide a configuration file will make the Contract Runner abort loading. So starting the node to download the blockchain, it was actually a good sign getting this SEVERE error:

2018–10–06 16:22:08 INFO: Initializing nxt.addons.ContractRunner
2018–10–06 16:22:08 INFO: addon.contractRunner.configFile = “./conf/contracts.json”
2018–10–06 16:22:08 SEVERE: file not found /home/malnemark/ardor/./conf/contracts.json

Contract runner config settings

Next step, not specifically for Ubuntu, is to set up the contracts.json file. The configuration needs to be provided in JSON format which involves adding curly brackets, double colons and quotes as shown in this example:

{
“secretPhrase”:”very secret phrase”,
“accountRS”:”ARDOR-94UK-NE47-Z68Z-BAM67",
“feeRateNQTPerFXT.IGNIS”:300000000,
“params”:{},
“seed”:””,
}

The configuration parameters:

  • secretPhrase: The secret phrase belonging to the contract runner account. Note: Use a different one — just because this one is already taken ;-) and make sure you are on testnet (!)
  • accountRS: The contract runner account. Note: this account will need 10 ARDR minimum balance (and a few Ignis for fees) to be able to send any transactions.
  • feeRateNQTPerFXT is the rate of ARDOR per IGNIS provided in Integer (i.e. adding 8 zeros to the Ignis / Ardor balance as you see it in the wallet).
  • params: parameters are another nested JSON data object, which we keep empty for now. Here, the empty curly brackets are depicting an empty parameter configuration.

Start the Ardor node and observe the output. Your contract runner is loaded when you see the output below:

2018–10–06 21:01:45 INFO: Add-on nxt.addons.ContractRunner registered new API: triggerContractByVoucher
2018–10–06 21:01:45 INFO: Add-on nxt.addons.ContractRunner registered new API: getSupportedContracts
2018–10–06 21:01:45 INFO: Add-on nxt.addons.ContractRunner registered new API: triggerContractByRequest
2018–10–06 21:01:45 INFO: Add-on nxt.addons.ContractRunner registered new API: triggerContractByTransaction
2018–10–06 21:01:45 INFO: Add-on nxt.addons.ContractRunner registered new API: triggerContractByHeight

Now let’s check the output of the “getSupportedContracts” API. (Open http://localhost:26876/test pick “getSupportedContracts” and hit “submit”). Our current setup will result in this empty response, so there is still more to do:

{
“supportedContracts”: [],
“requestProcessingTime”: 180,
“contractAccount”: “ARDOR-94UK-NE47-Z68Z-BAM67”
}

Step 5, Contract Manager

The contract manager is setup automatically for the sample contracts shipped with Ardor. Just make sure you add the account’s secret phrase to your nxt.properties:

contract.manager.secretPhrase=very secret phrase

Note: Don’t use quotes, if there is anything not working correctly, check for additional spaces, line breaks, etc.

Step 6, Install IntelliJ IDEA Community edition

This is a one-liner with snap:

sudo snap install intellij-idea-community --classic

(https://blog.jetbrains.com/idea/2017/11/install-intellij-idea-with-snaps/)

Start IntelliJ with $intellij-idea-community.

and choose “open project”. Select the Ardor folder.

Give it a try and run both “Ardor Local” and “ContractRunnerSuite” scripts (upper right corner) and check the output. Let me know if you’re stuck with any error message you can’t solve. You might have missed something in the setup.

Step 7, the Contract Manager Plugin for IntelliJ

All tools are installed at this point and we now want to deploy the smart contract. There are two possible ways to use the Contract Manager for this — either via the command line utility or the intelliJ plugin provided by Jelurida.

Even though the usage of the command line tool might be slightly more Ubuntu related we will use the IntelliJ plugin for this tutorial. It is easy to use and I think perfect for the first steps in smart contract development on Ardor.

The nxtwiki provides screenshots of the different steps of the setup, so check it out if in doubt.

  • Open IntelliJ
  • Select “File” — Settings menu
  • Select “Plugins”
  • Select “Install plugin from disk…”
  • Select file /home/malnemark/Ardor/ContractManagerPlugin.zip
  • Ardor Contract Manager appears in the list of plugins (somewhere below “Android support”)
  • Restart IntelliJ.

To use the plugin you will need to set up a new runtime script by selecting “Edit configurations” in the upper right runtime script menu.

  • Select “Ardor Contract Manager” from the drop down list to create a script of this type.
  • Call the script “Upload HelloWorld”
  • Set contract name exactly to “HelloWorld” (this is the class name of the contract)
  • Leave all other fields unchanged.

Step 8, Deploying HelloWorld

Finally we’re at the point to actually deploy the Hello World smart contract to the Ardor testnet.

open a terminal
cd Ardor/
./run.sh

Let the node download the blockchain. Make sure you are on testnet.

Go back to Intellij and start the contract manager script “upload HelloWorld” and observe both, the intellij status window and the terminal where the node is running.

The first sign of a smart contract that I saw after installation was this log message:

2018–10–09 20:09:28 INFO: ContractRunner processBlock at height 417877 response: {“errorDescription”:”Contract com.jelurida.ardor.contracts.HelloWorld does not support processBlock operation”}

If you see such a message, your ContractRunner is monitoring the blockchain and lets you know that the HelloWorld class does not implement processBlock (which is true, we only listen to transactions).

Now go to http://localhost:26876/test and query the getSupportedContracts API again. You should now see an entry containing values such as “name”:”HelloWorld” and related setup information.

At this point your setup was successful and you’ve deployed your first contract!

Trial run HelloWorld

Let’s see what HelloWorld actually does. Choosing a different account (again, testnet!) and sending a “Hello” to the contract account returns the following log, but no “Hello” back!

2018–10–09 20:02:50 INFO: cannot parse attached message, probably not a trigger transaction Unexpected character (H) at position 0.
2018–10–09 20:02:50 INFO: ContractRunner response: {“errorDescription”:”cannot parse attached message, probably not a trigger transaction Unexpected character (H) at position 0.”,”errorCode”:1000}

Lightweight Contracts speak JSON and the node, based on the log message above, seems to wait for a trigger transaction, so I guessed we would have to use JSON to trigger the contract. Try to another message, this time with the following text:

{“contract”:”HelloWorld”}

This should work on you should see your node executing the contract which results in the following two messages and a subsequent wall of text as the node prints out all transaction API call responses.

2018-10-11 21:31:49 INFO: ContractRunner Process transaction 2:711d0adf4a60580dbe8acfc94b440cf45a8bab134da3cbfde6e5a1a24a0d7213
2018-10-11 21:31:49 INFO: Executing contract name HelloWorld class com.jelurida.ardor.contracts.HelloWorld
...
Lots of text
...

Check in your ‘other’ account if you’ve received the message!

That’s it. At this point you’ve set up an Ardor node, a Contract Runner on that node, the Contract Manager plugin for IntelliJ and you’ve deployed HelloWorld to the data cloud. You’re now ready to develop lightweight contracts with a fully working IDE.

This week the Ardor Lightweight Contracts hackathon was announced, so get ready, maybe you can start developing and turn your idea into a 4000$ prize:

I hope this was helpful for you, please let me know if not, or if you came across any blockers or anything didn’t work as described.