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 hashTransaction = await smartAccount.setTokenName("MY_TOKEN");
  await waitTillCompleted(client, hashTransaction);
}

{
  const hashTransaction = await smartAccount.mintToken(100_000_000n);
  await waitTillCompleted(client, hashTransaction);
}

To burn an existing token:

{
  const hashTransaction = await smartAccount.burnToken(50_000_000n);
  await waitTillCompleted(client, hashTransaction);
}

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 hashTransaction = await smartAccount.setTokenName("MY_TOKEN");
  await waitTillCompleted(client, hashTransaction);
}

{
  const hashTransaction = await smartAccountTwo.setTokenName("ANOTHER_TOKEN");
  await waitTillCompleted(client, hashTransaction);
}

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

{
  const hashTransaction = await smartAccount.mintToken(100_000_000n);
  await waitTillCompleted(client, hashTransaction);
}

{
  const hashTransaction = await smartAccountTwo.mintToken(50_000_000n);
  await waitTillCompleted(client, hashTransaction);
}

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

const transferTransaction = 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
);