Skip to main content

Nil.js: getting started

Overview

Nil.js is a JS/TS library providing all essential tools for interacting with =nil;.

Installation and usage

The library can be installed similarly to any other NPM 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.

Key members

Here is a non-exhaustive list of 'helper' classes and functions provided by Nil.js:

NameWhat id does
PublicClientAllows for interacting with =nil; in ways that do not require authorization.
SmartAccountV1Provides an instance of a new 'default' smart account.
generateSmartAccount()Deploys a new 'default' smart account on the cluster and tops it up.
SmartAccountV1.deployContract()Deploys a smart contract via a previously deployed smart account.
SmartAccountV1.sendMessage()Sends a message to a smart contract via previously deployed smart account.
FaucetClientProvides an instance of a client interacting with the faucet service.
FaucetClient.topUpAndWaitUntilCompletion()Tops up a smart contract from the specified faucet.
CometaServiceAllows for interacting with the Cometa service.
CometaService.registerContractData()Registers a smart contract inside the Cometa service.

To see all members exposed by Nil.js, proceed to the 'References' section.

info

The testnet RPC endpoint provides access to the cluster and all related services including the faucet service and the Cometa service.

When running the cluster, the faucet service and the Cometa service locally, their endpoints will be different. This will require providing different endpoints when creating instances of PublicClient, FaucetClient and CometaService.

Sample Node.js project

Nil.js can be easily used with Node.js to interact with =nil; on the server.

Project set-up

First, create a new file titled server.js in an environment where Node.js is installed.

Then, import the following components and initialize the following variables:

const { createServer } = require("node:http");
const { generateSmartAccount } = require("@nilfoundation/niljs");

const hostname = "127.0.0.1";
const port = 3000;

Server code

The server will initialize a new smart account and, once smart account creation ends, show its address in the browser window:

const server = createServer((req, res) => {
(async () => {
try {
res.statusCode = 200;
res.setHeader("Content-Type", "text/plain");

const smartAccount = await generateSmartAccount({
shardId: 1,
rpcEndpoint: RPC_ENDPOINT,
faucetEndpoint: FAUCET_ENDPOINT,
});

const smartAccountAddress = smartAccount.address;

res.write(`New smart account address: ${smartAccountAddress}\n`);
res.on("finish", () => {
console.log(`New smart account address: ${smartAccountAddress}`);
});
res.end();
} catch (error) {
console.error(error);
res.statusCode = 500;
res.write("An error occurred while creating the smart account.");
res.end();
}
})();
});

server.listen(port, hostname, () => {
console.log(`Server running at http://${hostname}:${port}/`);
});

Interacting with the server

To launch the server:

node path/to/server.js

After the server is launched, open http://127.0.0.1:3000/ in the browser and wait a couple of seconds while the project creates a new smart account.

Alternatively, run the following snippet to fetch the smart account address once the server calculates it:

const response = await fetch("http://127.0.0.1:3000/");
const text = await response.text();
console.log(test);