Nil.js: working with tokens

Specifying values

When specifying values for minting, sending or burning tokens, use exact numbers with no decimals.

For example, when sending 50 million tokens, specify their amount as 50_000_000n.

Basic example

To create a new token and withdraw it:

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

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

{
  const tx = await smartAccount.setTokenName("MY_TOKEN");
  await tx.wait();
}

{
  const tx = await smartAccount.mintToken(100_000_000n);
  await tx.wait();
}

To burn an existing token:

{
  const tx = await smartAccount.burnToken(50_000_000n);
  await tx.wait();
}

Working with multiple smart accounts

This example creates a smart account that stores three tokens: the default token, and two custom tokens.

Create two new smart accounts:

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

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

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

{
  const tx = await smartAccount.setTokenName("MY_TOKEN");
  await tx.wait();
}

{
  const tx = await smartAccountTwo.setTokenName("ANOTHER_TOKEN");
  await tx.wait();
}

Create a new token for Smart Account 1 and withdraw it:

{
  const tx = await smartAccount.mintToken(100_000_000n);
  await tx.wait();
}

{
  const tx = await smartAccountTwo.mintToken(50_000_000n);
  await tx.wait();
}

Create a new token for Smart Account 2 and send it to Smart Account 1:

const tx = await smartAccountTwo.sendTransaction({
  to: smartAccount.address,
  value: 1_000_000n,
  feeCredit: 5_000_000n,
  tokens: [
    {
      id: smartAccountTwo.address,
      amount: 50_000_000n,
    },
  ],
});
const tokens = await client.getTokens(smartAccount.address, "latest");

Working with the faucet service

tip

Refer to the Codebook for ready-made canonical examples on using the faucet service.

Nil.js offers several 'helper' wrappers designed to simplify work with the faucet service.

To create a new faucet client:

const faucetClient = new FaucetClient({
	transport: new HttpTransport({
		endpoint: FAUCET_ENDPOINT,
	}),
});

To request a list of all faucets:

const faucets = await faucetClient.getAllFaucets();

To request tokens from a faucet:

await faucetClient.topUpAndWaitUntilCompletion({
  smartAccountAddress: SMART_ACCOUNT_ADDRESS,
  faucetAddress: FAUCET_ADDRESS,
  amount: AMOUNT,
  },
  client
);