Reading and writing to =nil;

This tutorial details the different ways that allow for reading and writing information to =nil;. It covers these actions:

1. Reading information from a block
2. Calling an existing smart contract
3. Retrieving data about the resulting message
4. Reading the message receipt

Via the =nil; CLI

The =nil; CLI provides several commands that produce data about key cluster entities including blocks, messages, and logs.

To view the latest block recorded by shard with shardId = 1:

nil block latest --shard-id 1 

To call an existing smart contract via the wallet:

nil wallet send-message CONTRACT_ADDRESS METHOD_NAME [ARGS] --abi path/to/contract.abi

To read information about the resulting message:

nil message HASH 

To read the message receipt:

nil receipt HASH 

Via the client library

The Nil.js client library provides several 'helper' methods for reading and writing to =nil;

To retrieve the block with the given hash:

import { PublicClient } from '@nilfoundation/niljs';

const client = new PublicClient({
    transport: new HttpTransport({
        endpoint: "{NIL_ENDPOINT}",
    }),
    shardId: 1,
});
const block = await client.getBlockByHash(BLOCK_HASH);

To call an existing smart contract after initializing a wallet:

import {
  encodeFunctionData,
  type Abi,
} from "viem";

const data = encodeFunctionData({
    abi: CONTRACT_ABI as Abi,
    functionName: "{funcName}",
    args: [],
    }
);

const messageHash = await wallet.sendMessage({
    to: '{CONTRACT_ADDRESS}',
    data: data,
    value: 100_000n,
    feeCredit: 1_000_000n
});

await waitTillCompleted(client, 1, messageHash);

tip

The waitTillCompleted() function enforces waiting for the results of the execution of the message whose hash is passed as an argument. It is crucial for avoiding null-type errors.

To read information about the resulting message:

const message = await client.getMessageByHash(messageHash);

To read the message receipt:

const receipt = await client.getMessageReceiptByHash(messageHash);