Nuklai CLI

In the nuklaivm ecosystem, interacting with the network, managing tokens, and participating in staking can be conducted through its robust API and a comprehensive command-line tool, nuklai-cli. Below, you will find detailed documentation on the API endpoints and their functionalities, along with a guide on using the nuklai-cli for various network operations.

nuklai-cli

The nuklai-cli tool offers a powerful interface for users to manage their interactions with the Nuklai network from the command line. It supports operations like checking balances, transferring tokens, staking, and more.

First, let's run our local nuklai subnet by doing:

./scripts/run.sh

Build nuklai-cli

To make it easy to interact with the nuklaivm, we have built nuklai-cli. Next, let's build this tool.

./scripts/build.sh

Configure nuklai-cli

Next, you'll need to add the chains you created and the default key to the nuklai-cli. You can use the following commands from this location to do so:

./build/nuklai-cli key import ed25519 demo.pk

If the key is added correctly, you'll see the following log:

database: .nuklai-cli
imported address: created address: nuklai1qrzvk4zlwj9zsacqgtufx7zvapd3quufqpxk5rsdd4633m4wz2fdjss0gwx

Next, you'll need to store the URLs of the nodes running on your Subnet:

./build/nuklai-cli chain import-anr

If nuklai-cli is able to connect to ANR, it will emit the following logs:

database: .nuklai-cli
stored chainID: 2JJEMRDZ3Bw2qf62PHxVGP2NV2QVDMJvz33CY62vgrr3kuiGXb uri: http://127.0.0.1:9656/ext/bc/2JJEMRDZ3Bw2qf62PHxVGP2NV2QVDMJvz33CY62vgrr3kuiGXb
stored chainID: 2JJEMRDZ3Bw2qf62PHxVGP2NV2QVDMJvz33CY62vgrr3kuiGXb uri: http://127.0.0.1:9658/ext/bc/2JJEMRDZ3Bw2qf62PHxVGP2NV2QVDMJvz33CY62vgrr3kuiGXb
stored chainID: 2JJEMRDZ3Bw2qf62PHxVGP2NV2QVDMJvz33CY62vgrr3kuiGXb uri: http://127.0.0.1:9650/ext/bc/2JJEMRDZ3Bw2qf62PHxVGP2NV2QVDMJvz33CY62vgrr3kuiGXb
stored chainID: 2JJEMRDZ3Bw2qf62PHxVGP2NV2QVDMJvz33CY62vgrr3kuiGXb uri: http://127.0.0.1:9652/ext/bc/2JJEMRDZ3Bw2qf62PHxVGP2NV2QVDMJvz33CY62vgrr3kuiGXb
stored chainID: 2JJEMRDZ3Bw2qf62PHxVGP2NV2QVDMJvz33CY62vgrr3kuiGXb uri: http://127.0.0.1:9654/ext/bc/2JJEMRDZ3Bw2qf62PHxVGP2NV2QVDMJvz33CY62vgrr3kuiGXb

./build/nuklai-cli chain import-anr connects to the Avalanche Network Runner server running in the background and pulls the URIs of all nodes tracking each chain you created.

Check Balance

To confirm you've done everything correctly up to this point, run the following command to get the current balance of the key you added:

./build/nuklai-cli key balance

If successful, the balance response should look like this:

database: .nuklai-cli
address: nuklai1qrzvk4zlwj9zsacqgtufx7zvapd3quufqpxk5rsdd4633m4wz2fdjss0gwx
chainID: 277DehNDB9szuxsiMgAfQBaJhW7JuE9CP6bdW5Up9D3qNeipZX
assetID (use NAI for native token): NAI
✔ assetID (use NAI for native token): NAI█
balance: 853000000.000000000 NAI

You can also check the balance of another address by passing in the address as the argument

./build/nuklai-cli key balance nuklai1de6kkmrpd9mx6anpde5hg72rv2u288wgh6rsrjmup0uzjamjskakqqjyt9u

Should give output

database: .nuklai-cli
address: nuklai1de6kkmrpd9mx6anpde5hg72rv2u288wgh6rsrjmup0uzjamjskakqqjyt9u
chainID: 277DehNDB9szuxsiMgAfQBaJhW7JuE9CP6bdW5Up9D3qNeipZX
assetID (use NAI for native token): NAI
balance: 0.000000000 NAI
please send funds to nuklai1de6kkmrpd9mx6anpde5hg72rv2u288wgh6rsrjmup0uzjamjskakqqjyt9u
exiting...

Generate another address

Now that we have a balance to send, we need to generate another address to send to. Because we use bech32 addresses, we can't just put a random string of characters as the recipient (won't pass checksum test that protects users from sending to off-by-one addresses).

./build/nuklai-cli key generate secp256r1

Note that we are now generating a key with curve secp256r1 instead of ed25519 like our first account. We can do this because the vm supports three types of keys(ed25519, secp256r1 and bls)

If successful, the nuklai-cli will emit the new address:

database: .nuklai-cli
created address: nuklai1qyfl0vx359gtn7vhj52xl9gp3pdphttqgtat9d8dad55c3rd4cnzgl3ma69

We can also generate a bls key doing

./build/nuklai-cli key generate bls

By default, the nuklai-cli sets newly generated addresses to be the default. We run the following command to set it back to demo.pk:

./build/nuklai-cli key set

You should see something like this:

database: .nuklai-cli
chainID: 2CvxouoGcBva3xxisHDmdQggad8bChYbMvu45oAXV7nXGK1Yob
stored keys: 2
0) address (ed25519): nuklai1qrzvk4zlwj9zsacqgtufx7zvapd3quufqpxk5rsdd4633m4wz2fdjss0gwx balance: 853000000.000000000 NAI
1) address (secp256r1): nuklai1qyfl0vx359gtn7vhj52xl9gp3pdphttqgtat9d8dad55c3rd4cnzgl3ma69 balance: 0.000000000 NAI
2) address (bls): nuklai1qgcty39f7z5q86yy7x8w0cnyuht34ut38wp2n5qp0zmyhglr5fjm5hqkejn balance: 0.000000000 NAI
✔ set default key: 0█

Generate vanity addresses with no private keys

There may be times when you just want to generate random nuklaivm addresses that have no associated private key. In theory, there could be a private key that corresponds to any given address, but the probability of such an occurrence is extremely low, especially when dealing with a sufficiently large random space. However, to be certain that an address does not correspond to any private key, we can construct it in such a way that it falls outside the normal range of addresses generated from private keys. One common approach is to use a clearly invalid or special pattern that cannot be derived from a private key under the normal address generation rules of our blockchain.

When you do

./build/nuklai-cli key generate-vanity-address

You should see something like:

database: .nuklai-cli
Address: nuklai1de6kkmrpd9mx6anpde5hg7gxgsjtdrhj6fe8yctv4npqchrey7sfspeyejq

We are creating an address that includes the word "nuklaivmvanity" followed by random 19 bytes of data. This kind of address is highly unlikely to be generated from a private key because it does not follow the typical structure of addresses derived from private keys.

Send Tokens

Lastly, we trigger the transfer:

./build/nuklai-cli action transfer

The nuklai-cli will emit the following logs when the transfer is successful:

database: .nuklai-cli
address: nuklai1qrzvk4zlwj9zsacqgtufx7zvapd3quufqpxk5rsdd4633m4wz2fdjss0gwx
chainID: 277DehNDB9szuxsiMgAfQBaJhW7JuE9CP6bdW5Up9D3qNeipZX
assetID (use NAI for native token): NAI
balance: 853000000.000000000 NAI
✔ recipient: nuklai1qyf889stx7rjrgh8tsa4acv4we94kf4w652gwq462tm4vau9ee20gq6k5l2
amount: 100
continue (y/n): y
✅ txID: pPmBtqtjpu4eTmLeBZtWLgSMvUf8Y85cZrdvsVn3vUtv24dzY

Bonus: Watch Activity in Real-Time

To provide a better sense of what is actually happening on-chain, the nuklai-cli comes bundled with a simple explorer that logs all blocks/txs that occur on-chain. You can run this utility by running the following command from this location:

./build/nuklai-cli chain watch

If you run it correctly, you'll see the following input (will run until the network shuts down or you exit):

database: .nuklai-cli
available chains: 2 excluded: []
0) chainID: QXRg1vtkJe4rPF2ShjHBj3ocyrRhW8A24aSM3qCsK35DKV5iD
1) chainID: 277DehNDB9szuxsiMgAfQBaJhW7JuE9CP6bdW5Up9D3qNeipZX
select chainID: 1
uri: http://127.0.0.1:44089/ext/bc/277DehNDB9szuxsiMgAfQBaJhW7JuE9CP6bdW5Up9D3qNeipZX
watching for new blocks on 277DehNDB9szuxsiMgAfQBaJhW7JuE9CP6bdW5Up9D3qNeipZX 👀
height:292 txs:1 root:RXYUPPSGL2zJiiR6r3ozakfyhEkPbiXkCHnm26H5UvMT23Sy5 size:0.31KB units consumed: [bandwidth=227 compute=7 storage(read)=12 storage(allocate)=25 storage(write)=26] unit prices: [bandwidth=100 compute=100 storage(read)=100 storage(allocate)=100 storage(write)=100] [TPS:4.30 latency:29273ms gap:0ms]
✅ pPmBtqtjpu4eTmLeBZtWLgSMvUf8Y85cZrdvsVn3vUtv24dzY actor: nuklai1qrzvk4zlwj9zsacqgtufx7zvapd3quufqpxk5rsdd4633m4wz2fdjss0gwx summary (*actions.Transfer): [100.000000000 NAI -> nuklai1qyf889stx7rjrgh8tsa4acv4we94kf4w652gwq462tm4vau9ee20gq6k5l2] fee (max 81.37%): 0.000029700 NAI consumed: [bandwidth=227 compute=7 storage(read)=12 storage(allocate)=25 storage(write)=26]

Emission Balancer Demo

Refer to Emission Balancer Demo to learn how to retrieve info such as totalsupply, rewardsperblock, staking info, etc from Emission Balancer.

Tokens Demo

Refer to Tokens Demo to learn how to mint an asset, transfer it within the same subnet or to another subnet with AWM, etc.

Nuklai Wallet

We have a native wallet for Nuklai network. This wallet integrates the following:

  • Local Wallet

  • Blockchain Explorer

  • Faucet that you can use to request some test NAI to your local wallet

  • Mint page where you can create and mint tokens to any address

  • Feed page which is like a mini blog that lets you post a message and the url to the blockchain within a transaction memo

To run the wallet, just do:

cd cmd/nuklai-wallet;
./scripts/dev.sh

Note that when you run dev.sh, it does the following:

  • Start Nuklai Feed from cmd/nuklai-feed

  • Start Nuklai Faucet from cmd/nuklai-faucet

  • Run Nuklai Wallet app

Then open http://localhost:34115/ in your browser to interact with the wallet.

Tests

Running Integration Tests

You can run the integration tests by doing

./scripts/tests.integration.sh

Running Unit Tests

You can run the unit tests by doing

./scripts/tests.unit.sh

Running End to End Tests

You can run the e2e tests by doing

MODE=test ./scripts/run.sh

Running Sync Tests

You can run the sync tests by doing

MODE=full-test./scripts/run.sh

Running a Load Test

Before running this demo, make sure to stop the network you started using ./scripts/stop.sh.

The nuklaivm load test will provision 5 nuklaivms and process 500k transfers on each between 10k different accounts.

./scripts/tests.load.sh

This test SOLELY tests the speed of the nuklaivm. It does not include any network delay or consensus overhead. It just tests the underlying performance of the hypersdk and the storage engine used (in this case MerkleDB on top of Pebble).

Last updated