=nil; 101
This tutorial acts as a 'primer' for working with =nil;. It explains how to perform essential actions with the cluster: creating a new wallet, deploying a contract, and calling a method inside this contract.
Set up the =nil; CLI
The =nil; CLI is an easy-to-use tool for interacting with the cluster.
To install the CLI:
curl -fsSL https://github.com/NilFoundation/nil_cli/raw/master/install.sh | bash
To generate a new private key and set inside the CLI config:
nil keygen new
To point the CLI toward the RPC endpoint:
nil config set rpc_endpoint RPC_ENDPOINT
Create a new wallet
In =nil; a wallet is just a smart contract that can handle payments. There are no other structural differences between a wallet and a smart contract, which means that wallets can support any logic that can be expressed inside a smart contract.
Flow
To create a new wallet:
nil wallet new
Expected response:
Contract WALLET_ADDRESS balance is topped up by 100000000
Contract address: WALLET_ADDRESS
To check the wallet bytecode:
nil contract code WALLET_ADDRESS
To request a 'top up':
nil wallet top-up 1000000
To see the wallet address and its public key:
nil wallet info
Advanced tutorials
Deploy a smart contract
In =nil; contracts can be deployed on different execution shards that act as separate blockchains. Contracts can communicate with contracts on other shards, avoiding state fragmentation.
Any smart contract deployed in Ethereum-compatible networks and written in Solidity can be redeployed to =nil;
Flow
Create a new contract containing this code:
pragma solidity ^0.8.0;
contract Counter {
uint256 private value;
event ValueChanged(uint256 newValue);
function increment() public {
value += 1;
emit ValueChanged(value);
}
function getValue() public view returns (uint256) {
return value;
}
}
Compile the contract:
solc -o path/to/Counter --bin --abi path/to/Counter.sol --overwrite
Deploy a contract with the =nil; CLI:
nil wallet deploy path/to/Counter.bin --salt SALT
Expected output:
Contract address: COUNTER_ADDRESS
Transaction hash: TRANSACTION_HASH (shard 1)
Call the increment()
function:
nil wallet send-message COUNTER_ADDRESS increment --abi path/to/Counter.abi
Retrieve the result:
nil contract call-readonly COUNTER_ADDRESS getValue --abi path/to/Counter.abi
Advanced tutorials
Make a cross-shard call
When a smart contract makes a call to another smart contract deployed on a separate shard, the destination shard retrieves the resulting message and processes it. To make thing simpler, the Nil.sol
library provides the async_call()
function: it calls a special precompiled contract that allows for easily passing messages between shards.
Flow
Create a new contract with the following code:
pragma solidity ^0.8.9;
import "@nilfoundation/smart-contracts/contracts/Nil.sol";
contract Caller {
using Nil for address;
receive() external payable {}
function call(address dst) public {
Nil.asyncCall(
dst,
msg.sender,
msg.sender,
100000,
2,
0,
abi.encodeWithSignature("increment()")
);
}
function verifyExternal(
uint256,
bytes calldata
) external pure returns (bool) {
return true;
}
}
Compile it and deploy it to Shard 2:
solc -o path/to/Caller --bin --abi path/to/Caller.sol --overwrite
nil wallet deploy path/to/Caller.bin --shard-id 2 --salt SALT
Expected output:
Contract address: CALLER_ADDRESS
Transaction hash: TRANSACTION_HASH (shard 1)
Note that CALLER_ADDRESS
starts with 0x0002
, which indicates that Caller
is indeed deployed on Shard 2.
Send tokens to Caller
and call the call()
function:
nil wallet send-tokens CALLER_ADDRESS 300000
nil wallet send-message CALLER_ADDRESS call COUNTER_ADDRESS --abi path/to/Caller.abi
Retrieve the result:
nil contract call-readonly COUNTER_ADDRESS getValue --abi path/to/Counter.abi
Advanced tutorials
Tokens and multi-currency
=nil; has base tokens that are used to pay for essential functionalities such as deploying contracts.
However, each contract can also create a custom currency. A contract can only be the owner of one custom currency. While custom currencies can be transferred between contracts, they cannot be used to pay for operations inside =nil;.
Non-owners cannot perform any operations with a custom currency.
Flow
Create a new wallet:
nil wallet new --salt SALT
Create a new currency and withdraw it:
nil minter create-currency NEW_WALLET_ADDRESS 5000 new-currency
Check the currencies of the wallet:
nil contract currencies NEW_WALLET_ADDRESS
Expected output:
Contract currencies:
Balance: 50000 CurrencyId=CURRENCY_ID