Create Localnet

This document describes 3 ways to setup a network of aiozd nodes, each serving a different usecase:

1. Single-node, local, manual testnet
2. Multi-node, local, automated testnet
3. Multi-node, remote, automated testnet

Supporting code can be found in the networks directory (opens in a new tab) and additionally the local or remote sub-directories.

NOTE: The remote network bootstrapping may be out of sync with the latest releases and is not to be relied upon.

Single-node, Local, Manual Testnet

This guide helps you create a single validator node that runs a network locally for testing and other development-related uses.

Requirements

• Install aioz
• Install jq (opens in a new tab) (optional)

Create Genesis File and Start the Network

# You can run all of these commands from your home directory
cd $HOME
 
# Initialize the genesis.json file that will help you to bootstrap the network
aiozd init my-node --chain-id my-chain
 
# Create a key to hold your validator account
aiozd keys add my-account
 
# Add that key into the genesis.app_state.accounts array in the genesis file
# NOTE: this command lets you set the number of coins. Make sure this account has some coins
# with the genesis.app_state.staking.params.bond_denom denom, the default is staking
aiozd add-genesis-account $(aiozd keys show my-account -a) 1000000000stake,1000000000validatortoken
 
# Generate the transaction that creates your validator
aiozd gentx my-account 1000000000stake --chain-id my-chain
 
# Add the generated bonding transaction to the genesis file
aiozd collect-gentxs
 
# Now its safe to start `aiozd`
aiozd start

This setup puts all the data for aiozd in ~/.aioz. You can examine the genesis file you created at ~/.aioz/config/genesis.json. With this configuration, aiozd is also ready to use and has an account with tokens (both staking and custom).

Multi-node, Local, Automated Testnet

From the networks/local directory (opens in a new tab):

Requirements

• Install aioz
• Install docker (opens in a new tab)
• Install docker-compose (opens in a new tab)

Build

Build the aiozd binary (linux) and the aioz/aiozdnode docker image required for running the localnet commands. This binary will be mounted into the container and can be updated without rebuilding the image, so you only need to build the image once.

# Clone the go-aioz repo
git clone https://github.com/AIOZNetwork/go-aioz.git
 
# Work from the repo
cd go-aioz
 
# Build the linux binary in ./build
make build-linux
 
# Build aioz/aiozdnode image
make build-docker-aiozdnode

Run Your Testnet

To start a 4 node testnet run:

make localnet-start

This command creates a 4-node network using the aiozdnode image. The ports for each node are found in this table:

To update the binary, just rebuild it and restart the nodes:

make build-linux localnet-start

Configuration

The make localnet-start creates files for a 4-node testnet in ./build by calling the aiozd testnet command. This outputs a handful of files in the ./build directory:

$ tree -L 2 build/
build/
├── aiozd
├── gentxs
│   ├── node0.json
│   ├── node1.json
│   ├── node2.json
│   └── node3.json
├── node0
│   └── aiozd
│       ├── key_seed.json
│       ├── keys
│       ├── ${LOG:-aiozd.log}
│       ├── config
│       └── data
├── node1
│       ├── key_seed.json
│       ├── ${LOG:-aiozd.log}
│       ├── config
│       └── data
├── node2
│       ├── key_seed.json
│       ├── ${LOG:-aiozd.log}
│       ├── config
│       └── data
└── node3
         ├── key_seed.json
         ├── ${LOG:-aiozd.log}
         ├── config
         └── data

Each ./build/nodeN directory is mounted to the /aiozd directory in each container.

Logging

Logs are saved under each ./build/nodeN/aiozd/aioz.log. You can also watch logs directly via Docker, for example:

docker logs -f aiozdnode0

Keys & Accounts

To interact with aiozd and start querying state or creating txs, you use the aiozd directory of any given node as your home, for example:

aiozd keys list --home ./build/node0/aiozd

Now that accounts exist, you may create new accounts and send those accounts funds!

Special Binaries

You can specify which one to run with the BINARY environment variable if you have multiple binaries with different names. The path of the binary is relative to the attached volume. For example:

# Run with custom binary
BINARY=aiozfoo make localnet-start