Skip to main content

Release 03.09.2024: migration guide

The latest release of =nil; introduces several changes to multi-currency support and the minting mechanism.

Summary of key changes​

  • The Minter contract no longer exists and cannot be called from other smart contracts
  • The Nil.sol extension library now exposes the awaitCall() function that allows for making an async call to a smart contract and then awaiting the result
  • The JSON-RPC API now includes the eth_estimateFee method which can be used for gas estimations. Client tools (Nil.js and the =nil; CLI) will support this feature at a later date

Migration of smart contracts​

  • Mint currencies directly from wallets

All 'out of the box' wallets provided by =nil; can now mint currencies without having to refer to the Minter contract. As a result, the Minter contract has been discontinued. Any calls or messages sent to this contract should be removed.

A more detailed overview of how to create currencies via wallets is provided in this tutorial.

  • Use NilCurrencyBase to create custom currencies

Instead of using the now non-existant Minter contract, create new custom currencies by deriving contracts from NilCurrencyBase:

import "path/to/NilCurrencyBase.sol";

contract Example is NilCurrencyBase {}

NilCurrencyBase base is a template contract that has all the necessary methods for mimicking the behavior of tokens including minting, currency creation, and attaining the total currency supply.

info

Derived contracts can override virtual functions inside NilCurrencyBase to change the default minting, transferring, or currency creation behaviors.

  • Adjust the logic of smart contracts to account for awaitCall()

The awaitCall() function makes it possible to perform async calls between smart contracts while retrieving the returned value.

If necessary, change the logic of existing smart contracts to use awaitCall().

Migration of =nil; CLI​

No specific changes have to be made to existing =nil; CLI commands.

Note that the nil wallet call-readonly command has been added. It allows for performing 'dry runs' of calling contracts via wallet. Provide the --with-details flag to see exactly how much fee credit could be spent on performing the operation tested during the 'dry run'.

Migration of Nil.js scripts​

  • Remove any messages sent to the Minter contract

With the latest release, Nil.js changes the logic for creating and minting currencies.

To set the currency name:

{
    const hashMessage = await wallet.setCurrencyName("MY_TOKEN");
    await waitTillCompleted(client, 1, hashMessage);
}

To mint the currency and withdraw it to its owner:

{
    const hashMessage = await wallet.mintCurrency(100_000_000n);
    await waitTillCompleted(client, 1, hashMessage);
}

To transfer the currency to another contract:

await wallet.sendMessage({
    ...
    tokens: [
        {
            id: hexToBigInt(walletAddress),
            amount: AMOUNT
        }
    ]
    ...
});

  • Adjust function signatures

  • The PublicClient.call() function no longer expects a from argument in its CallArgs and accepts feeCredit:

await client.call({
        to: address,
        feeCredit: 500000n,
        abi,
        functionName: "FUNC_NAME",
    }, "latest")
  • The waitTillCompleted() function accepts additional options allowing for waiting until the message with the given hash is included in a block in the main shard:
await waitTillCompleted(CLIENT, SHARD_ID, HASH, {
    waitTilMainShard: true,
    interval: INTERVAL
}
);

Migration of Hardhat scripts​

No specific changes have to be made to existing Hardhat scripts.