@nilfoundation/niljs

Nil.js

The TypeScript client library for interacting with the =nil; cluster.

Table of contents

• Installation
• Getting started
• Usage
• Tokens and bouncing
• Accessing the dev environment
• Licence

Installation

npm install @nilfoundation/niljs

Getting started

PublicClient is used for performing read-only requests to =nil; that do not require authentication (e.g., attaining information about a block).

To initialize a PublicClient:

const client = new PublicClient({
  transport: new HttpTransport({
    endpoint: RPC_ENDPOINT,
  }),
  shardId: 1,
});

shardId is a concept unique to =nil; in that it designates the execution shard where the smart account should be deployed. Execution shards manage portions of the global state and are coordinated by the main shard.

SmartAccountV1 is a class representing a smart account that allows for signing transactions and performing requests that require authentication.

To deploy a new smart account:

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

Usage

In =nil;, it is possible to call functions asynchronously. When a contract makes an async call, a new transaction is spawned. When this transaction is processed, the function call itself is executed.

It is possible to make async calls within the confines of the same shard or between contracts deployed on different shards.

To perform an async call:

const anotherAddress = SmartAccountV1.calculateSmartAccountAddress({
  pubKey: pubkey,
  shardId: 1,
  salt: 200n,
});

await smartAccount.sendTransaction({
  to: anotherAddress,
  value: 10n,
  gas: 100000n,
});

To perform a sync call:

const anotherAddress = SmartAccountV1.calculateSmartAccountAddress({
  pubKey: pubkey,
  shardId: 1,
  salt: 200n,
});

await smartAccount.syncSendTransaction({
  to: anotherAddress,
  value: 10n,
  gas: 100000n,
});

It is only possible to perform sync calls within the confines of one shard.

Tokens and bouncing

=nil; provides a multi-token mechanism. A contract can be the owner of one custom token, and owners can freely send custom tokens to other contracts. As a result, the balance of a given contract may contain standard tokens, and several custom tokens created by other contracts.

Custom tokens do not have to be created, and each contract is assigned one by default. However, at contract deployment, a token has no name and its total supply equals zero.

To set the name of the token for an existing smart account:

const transaction = await smartAccount.sendTransaction({
  to: smartAccountAddress,
  feeCredit: 1_000_000n * gasPrice,
  value: 0n,
  data: encodeFunctionData({
    abi: SmartAccountV1.abi,
    functionName: "setTokenName",
    args: ["MY_TOKEN"],
  }),
});

await transaction.wait();

To mint 1000 tokens:

const transaction2 = await smartAccount.sendTransaction({
  to: smartAccountAddress,
  feeCredit: 1_000_000n * gasPrice,
  value: 0n,
  data: encodeFunctionData({
    abi: SmartAccountV1.abi,
    functionName: "mintToken",
    args: [100_000_000n],
  }),
});

await transaction2.wait();

To send a token to another contract:

const anotherAddress = generateRandomAddress();

const tx = await smartAccount.sendTransaction({
  to: anotherAddress,
  value: 10_000_000n,
  feeCredit: 100_000n * gasPrice,
  tokens: [
    {
      id: smartAccountAddress,
      amount: 100_00n,
    },
  ],
});

await tx.wait();

=nil; also supports token bouncing. If a transaction carries custom tokens, and it is unsuccesful, the funds will be returned to the address specified in the bounceTo parameter when sending the transaction.

Accessing the dev environment

To enter the Nix dev environment for Nil.js:

nix develop .#niljs

After that, it should be possible to run npm run test and other scripts specified in ./niljs/package.json.

Licence

MIT