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

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 -g install @nilfoundation/smart-contracts

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

JSON-RPC API​

=nil; exposes a JSON-RPC API that supports several methods from regular Ethereum as well as some methods that are unique to the cluster.

Apart from the usual means of interacting with a JSON-RPC API (e.g., by sending CURL requests), the documentation portal provides an interactive API reference.

To use it, follow the link above, select a method, input the API endpoint in the form and fill the method parameters. Click on 'Send Request' to send the request.

info

The documentation portal will also generate a valid CURL script depending on the request params. This script can be used in CI pipelines or bash scripts.

=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.