Nil.js

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

Table of contents

• Installation
• Getting started
• Usage
• License

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: "{NIL_ENDPOINT}",
  }),
  shardId: 1,
});

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

WalletV1 is a class representing a wallet (in =nil; a wallet is just a smart contract) that allows for signing messages and performing requests that require authentication.

To deploy a wallet:

const pubkey = signer.getPublicKey();

const wallet = new WalletV1({
  pubkey: pubkey,
  salt: 100n,
  shardId: 1,
  client,
  signer,
});
const walletAddress = wallet.address;

The Faucet contract is for 'topping up' an address on the =nil; devnet. The faucet contract is always deployed at a pre-defined static address. To initialize a faucet instance:

await faucet.withdrawTo(walletAddress, 100000n);
const faucet = new Faucet(client);

In =nil;, the address for a wallet must be 'topped up' first before deploying the wallet. To 'top up' an existing address:

const deploymentMessage = externalDeploymentMessage(
  {
    salt: 100n,
    shard: 1,
    bytecode: WalletV1.code,
    abi: WalletV1.abi,
    args: [bytesToHex(pubkey)],
  },
  chainId
);
const addr = bytesToHex(deploymentMessage.to);
console.log("walletAddress", addr);

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 = WalletV1.calculateWalletAddress({
  pubKey: pubkey,
  shardId: 1,
  salt: 200n,
});

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

To perform a sync call:

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

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

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

Multi-currency and bouncing

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

There is no need to create currency, it exists for each account by default. But it has no name and zero value. To set the name of the currency for a wallet:

const hashMessage = await wallet.sendMessage({
  to: walletAddress,
  gas: 1_000_000n,
  value: 100_000_000n,
  data: encodeFunctionData({
    abi: MINTER_ABI,
    functionName: "setCurrenctName",
    args: ["MY_TOKEN"],
  }),
});

await waitTillCompleted(client, hashMessage);

To mint 1000 tokens of the currency:

const hashMessage = await wallet.sendMessage({
  to: walletAddress,
  gas: 1_000_000n,
  value: 100_000_000n,
  data: encodeFunctionData({
    abi: MINTER_ABI,
    functionName: "mintCurrency",
    args: [1000n],
  }),
});

await waitTillCompleted(client, hashMessage);

To send a currency to another contract:

const sendHash = await wallet.sendMessage({
  to: anotherAddress,
  value: 10_000_000n,
  gas: 100_000n,
  tokens: [
    {
      id: n,
      amount: 100_00n,
    },
  ],
});

await waitTillCompleted(client, sendHash);

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

Licence

MIT