Skip to main content

Prerequisites

This page details the steps that need to be completed before working with =nil;.

Dependencies​

Prior to working with =nil;, it is recommended to install the following:

  • Node.js > 18.0.0
  • NPM
  • Git
  • Hardhat

This will allow for using the entire set of the developer tools provided with =nil; such as the =nil; client library or the =nil; Hardhat plugin.

To install Node.js and NPM via NVM:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
npm install -g npm

To install Git:

apt-get install git

To install Hardhat:

npm install hardhat

Solidity library​

=nil; provides the Nil.sol Solidity library that contains several 'helper' functions and function modifiers for working with the cluster.

Access the Solidity library.

To use the library, simply import it at the top of any smart contract:

import "path/to/Nil.sol";

With the library imported, use the asyncCall() function in the smart contract code to send a message to another contract deployed either on the same shard or on a different shard. The message will be processed asynchronously: it will spawn a message, and whatever function was called via the message will be executed when the message itself is processed.

To read more about what is included in the Solidity library, read this guide.

Follow this explanation to learn more about the theory behind async execution, or complete this tutorial on handling async calls.

=nil; CLI​

The =nil; CLI is an easy-to-use tool for interacting with the cluster from any shell: it supports all major operations and can be integrated into a CI/CD pipeline.

The CLI is distributed as a standalone binary. To install it:

curl -fsSL https://github.com/NilFoundation/nil_cli/raw/master/install.sh | bash

Initial setup is required for the =nil; CLI to be able to interact with the cluster. Learn more about configuring the =nil; CLI.

The 'Reference' section contains a full list of commands that can be used via the =nil; CLI.

info

When using the =nil; CLI, it is possible to switch between verbose and quiet outputs using the --quiet | -q and --verbose | -v flags. This documentation uses verbose outputs throughout.

Client library​

The =nil; client library is a JavaScript module that allows for interating with the cluster using JS classes and functions.

The library can be installed similarly to any other module.

npm install @nilfoundation/niljs

Afterward, import the necessary functions and classes from the library:

import { ... } from "@nilfoundation/niljs";
Addresses

When working with Nil.js, make sure that all hardcoded addresses are in lowercase. If an address is generated by Nil.js, there is no need to perform additional modifications on it.

The 'Reference' section contains descriptions of all essential classes and functions.

Hardhat plugin​

=nil; has several features distinguishing it from Ethereum, which means that Hardhat is not natively compatible with the cluster.

However, it is still possible to use Hardhat with =nil; by installing nil-hardhat-plugin. This plugin ensures compatibility between the convenience and familiarity of Hardhat and the unique architecture of =nil;.

The plugin uses ignition and ethers to handle contract deployment and interactions with the cluster. It is also possible to use other combinations of packages (such as ignition and viem) to extend nil-hardhat-plugin. Note that the use of these additional packages may cause instability in how the plugin operates.

To install the plugin:

npm install @nilfoundation/hardhat-plugin

Learn more about using the =nil; Hardhat plugin.

tip

Using the =nil; Hardhat plugin requires creating a wallet.

info

The =nil; Hardhat plugin only supports sending internal messages from a wallet. It is impossible to send external messages when using this tool.

Block explorer​

The =nil; block explorer is a web app that tracks statistics about blocks, accounts, and messages.

info

Information in the block explorer may update with a slight delay compared to the current state of the cluster.

Access the =nil; block explorer and learn about its usage.

Smart contracts package​

The @nilfoundation/smart-contracts NPM package contains the source code of all extension libraries and various Solidity contracts used inside =nil; (such as the basic wallet contract).

npm install @nilfoundation/smart-contracts