Spinning up a local network

Prerequisites

Namada must be installed from source in order to run a local network.

There is a script that has been written specifically for this purpose, which can be found under scripts in the Namada repository (opens in a new tab).

Installing script dependencies

The script has some dependencies that must be installed in order to run it successfully:

python3 must be installed.
toml Python pip library https://pypi.org/project/toml/ (opens in a new tab) must be installed.

The script will require a genesis configuration file, which is a TOML file that specifies the parameters of the network. Examples of such files can be found in the anoma-network-config repo (opens in a new tab) in the templates directory.

Modifying the genesis configuration file

In order to run the script successfully, all sections of validators must be removed from the toml file. This is because the script will generate a new set of validators for the network.

The below code block shows an example of a genesis configuration file that has been modified to remove the validators section.

# Editing genesis config steps
# Developer network
genesis_time = "2021-12-20T15:00:00.00Z"
native_token = "NAM"
faucet_pow_difficulty = 0
faucet_withdrawal_limit = "100000"
 
- # 3 genesis validators.
- [validator.validator-1]
- # Validator's token balance at genesis.
- tokens = 100000
- # Amount of the validator's genesis token balance which is not staked.
- non_staked_balance = 100000
- # VP for the validator account
- validator_vp = "vp_validator"
- # Commission rate for rewards
- commission_rate = 0.05
- # Maximum change per epoch in the commission rate
- max_commission_rate_change = 0.01
- # Public IP:port address
- net_address = "52.210.23.30:26656"
-
- [validator.validator-2]
- # Validator's token balance at genesis.
- tokens = 100000
- # Amount of the validator's genesis token balance which is not staked.
- non_staked_balance = 100000
- # VP for the validator account
- validator_vp = "vp_validator"
- # Commission rate for rewards
- commission_rate = 0.05
- # Maximum change per epoch in the commission rate
- max_commission_rate_change = 0.01
- # VP for the staking reward account
- staking_reward_vp = "vp_user"
- # Public IP:port address
- net_address = "63.32.203.239:26656"
-
- [validator.validator-3]
- # Validator's token balance at genesis.
- tokens = 100000
- # Amount of the validator's genesis token balance which is not staked.
- non_staked_balance = 100000
- # VP for the validator account
- validator_vp = "vp_validator"
- # Commission rate for rewards
- commission_rate = 0.05
- # Maximum change per epoch in the commission rate
- max_commission_rate_change = 0.01
- # VP for the staking reward account
- staking_reward_vp = "vp_user"
- # Public IP:port address
- net_address = "54.195.72.213:26656"
 
# Some tokens present at genesis.
 
[token.NAM]
address = "atest1v4ehgw36x3prswzxggunzv6pxqmnvdj9xvcyzvpsggeyvs3cg9qnywf589qnwvfsg5erg3fkl09rg5"
vp = "vp_token"
[token.NAM.balances]
atest1v4ehgw36gc6yxvpjxccyzvphxycrxw2xxsuyydesxgcnjs3cg9znwv3cxgmnj32yxy6rssf5tcqjm3 = 9223372036854
 
[token.BTC]
address = "atest1v4ehgw36xdzryve5gsc52veeg5cnsv2yx5eygvp38qcrvd29xy6rys6p8yc5xvp4xfpy2v694wgwcp"
vp = "vp_token"
[token.BTC.balances]
atest1v4ehgw36gc6yxvpjxccyzvphxycrxw2xxsuyydesxgcnjs3cg9znwv3cxgmnj32yxy6rssf5tcqjm3 = 9223372036854
 
[token.ETH]
address = "atest1v4ehgw36xqmr2d3nx3ryvd2xxgmrq33j8qcns33sxezrgv6zxdzrydjrxveygd2yxumrsdpsf9jc2p"
vp = "vp_token"
[token.ETH.balances]
atest1v4ehgw36gc6yxvpjxccyzvphxycrxw2xxsuyydesxgcnjs3cg9znwv3cxgmnj32yxy6rssf5tcqjm3 = 9223372036854
 
[token.DOT]
address = "atest1v4ehgw36gg6nvs2zgfpyxsfjgc65yv6pxy6nwwfsxgungdzrggeyzv35gveyxsjyxymyz335hur2jn"
vp = "vp_token"
[token.DOT.balances]
atest1v4ehgw36gc6yxvpjxccyzvphxycrxw2xxsuyydesxgcnjs3cg9znwv3cxgmnj32yxy6rssf5tcqjm3 = 9223372036854
 
[token.Schnitzel]
address = "atest1v4ehgw36xue5xvf5xvuyzvpjx5un2v3k8qeyvd3cxdqns32p89rrxd6xx9zngvpegccnzs699rdnnt"
vp = "vp_token"
[token.Schnitzel.balances]
atest1v4ehgw36gc6yxvpjxccyzvphxycrxw2xxsuyydesxgcnjs3cg9znwv3cxgmnj32yxy6rssf5tcqjm3 = 9223372036854
 
[token.Apfel]
address = "atest1v4ehgw36gfryydj9g3p5zv3kg9znyd358ycnzsfcggc5gvecgc6ygs2rxv6ry3zpg4zrwdfeumqcz9"
vp = "vp_token"
[token.Apfel.balances]
atest1v4ehgw36gc6yxvpjxccyzvphxycrxw2xxsuyydesxgcnjs3cg9znwv3cxgmnj32yxy6rssf5tcqjm3 = 9223372036854
 
[token.Kartoffel]
address = "atest1v4ehgw36gep5ysecxq6nyv3jg3zygv3e89qn2vp48pryxsf4xpznvve5gvmy23fs89pryvf5a6ht90"
public_key = ""
vp = "vp_token"
[token.Kartoffel.balances]
atest1v4ehgw36gc6yxvpjxccyzvphxycrxw2xxsuyydesxgcnjs3cg9znwv3cxgmnj32yxy6rssf5tcqjm3 = 9223372036854
 
# Some established accounts present at genesis.
 
[established.faucet]
address = "atest1v4ehgw36gc6yxvpjxccyzvphxycrxw2xxsuyydesxgcnjs3cg9znwv3cxgmnj32yxy6rssf5tcqjm3"
vp = "vp_testnet_faucet"
 
[established.masp]
address = "atest1v4ehgw36xaryysfsx5unvve4g5my2vjz89p52sjxxgenzd348yuyyv3hg3pnjs35g5unvde4ca36y5"
vp = "vp_masp"
 
# Wasm VP definitions
 
# Implicit VP
 
[wasm.vp_implicit]
filename = "vp_implicit.wasm"
 
# Default user VP in established accounts
 
[wasm.vp_user]
 
# filename (relative to wasm path used by the node)
 
filename = "vp_user.wasm"
 
# Validator VP
 
[wasm.vp_validator]
filename = "vp_validator.wasm"
 
# Token VP
 
[wasm.vp_token]
filename = "vp_token.wasm"
 
# Faucet VP
 
[wasm.vp_testnet_faucet]
filename = "vp_testnet_faucet.wasm"
 
# MASP VP
 
[wasm.vp_masp]
filename = "vp_masp.wasm"
 
# General protocol parameters.
 
[parameters]
 
# Minimum number of blocks in an epoch.
 
min_num_of_blocks = 5
 
# Maximum expected time per block (in seconds).
 
max_expected_time_per_block = 11
 
# Implicit VP WASM name
 
implicit_vp = "vp_implicit"
 
# Expected number of epochs per year (also sets the min duration of an epoch in seconds)
 
epochs_per_year = 262800 # ~120 sec epoch duration (60*60*24\*365 / 120)
 
# The P gain factor in the Proof of Stake rewards controller
 
pos_gain_p = 0.1
 
# The D gain factor in the Proof of Stake rewards controller
 
pos_gain_d = 0.1
 
# The wrapper tx fixed fees
 
wrapper_tx_fees = "5"
 
# The max size of blocks in bytes
 
max_proposal_bytes = 5242880
vp_whitelist = []
tx_whitelist = []
max_public_key_per_account = 15
#Maximum number of signatures required per transaction
max_signature_per_tx = 15
 
# Proof of stake parameters.
 
[pos_params]
 
# Maximum number of active validators.
 
max_validator_slots = 128
 
# Pipeline length (in epochs). Any change in the validator set made in
 
# epoch 'n' will become active in epoch 'n + pipeline_len'.
 
pipeline_len = 2
 
# Unbonding length (in epochs). Validators may have their stake slashed
 
# for a fault in epoch 'n' up through epoch 'n + unbonding_len'.
 
unbonding_len = 4
 
# Votes per fundamental staking token (namnam)
 
tm_votes_per_token = 1.0
 
# Reward for proposing a block.
 
block_proposer_reward = 0.125
 
# Reward for voting on a block.
 
block_vote_reward = 0.1
 
# Maximum inflation rate per annum (10%)
 
max_inflation_rate = 0.1
 
# Targeted ratio of staked tokens to total tokens in the supply
 
target_staked_ratio = 0.6667
 
# Portion of a validator's stake that should be slashed on a duplicate
 
# vote.
 
duplicate_vote_min_slash_rate = 0.001
 
# Portion of a validator's stake that should be slashed on a light
 
# client attack.
 
light_client_attack_min_slash_rate = 0.001
cubic_slashing_window_length = 1
 
# Governance parameters.
 
[gov_params]
 
# minimum amount of xan token to lock
 
min_proposal_fund = 100
 
# proposal code size in kibibytes (KiB)
 
max_proposal_code_size = 300000
 
# min proposal period length in epochs
 
min_proposal_period = 3
 
# max proposal period length in epochs
 
max_proposal_period = 6
 
# maximum number of characters in the proposal content
 
max_proposal_content_size = 10000
 
# minimum epochs between end and grace epoch
 
min_proposal_grace_epochs = 0

Building wasm

The script will also require all wasm files for transactions to be built. This can be done by running the following command (whilst in the namada directory):

make build-wasm-scripts

Running the script

The script is called build_network.sh and can be run with the following command:

# Ensure you are in the root of the namada repository directory
./scripts/build_network.sh <config_toml> <namada_dir> <OPTIONAL: base_dir>

More specifically, the script takes three arguments:

config_toml: the path to the (validator-free) genesis configuration file.
namada_dir: the path to the Namada binaries directory. If the binaries were build using make build-release this would imply the namada/target/release directory. Otherwise, if they were built using make build it would be the namada/target/debug directory.
base_dir: (optional argument) the path to the BASE_DIR directory, where all chain-data is stored. This is only necessary if the BASE_DIR is not the default given by namadac utils default-base-dir command.

For example, a MacOS user would run something along the lines of:

./scripts/build_network.sh \
~/anoma-network-config/templates/edited_genesis_config.toml \
./target/release # Assuming the binaries were built using `make build-release`

Running the ledger

After the script has been run, a python process will have started in the background. The ledger can be run through the familiar command:

target/release/namada ledger # Assuming the binaries were built using `make build-release`

Cleaning up

After the local network has fulfilled its purpose, it can be cleaned up by running the following commands found in the cleanup function of the script:

    pkill -f ".hack/chains"
    rm -r .hack/chains
    rm local.*.tar.gz

Proof of Stake IBC on Namada