Namada

About Namada

• Namada is the first fractal instance of Anoma
• Namada is instantiated as a product for asset-agnostic, interchain privacy
• Namada is built by a public good laboratory called Heliax

Key innovations:

• Zcash-like transfers for any assets (fungible and non-fungible)
• Rewarded usage of privacy as a public good
• Interoperability with Ethereum via a custom bridge with trust-minimization
• Vertically integrated user interfaces

Overview of features

• Proof-of-Stake with governance to secure and evolve Namada
• Fast-finality BFT with 4-second blocks
• Near-zero fees
• Trust-minimized 2-way Ethereum bridge
• IBC connections to chains that already speak IBC (all Cosmos chains)
• Multi-Asset Shielded Pool (MASP)
• Convert Circuit (shielded set rewards)
• A reference interface
• Ledger application

For high-level introductions, we recommend:

• Article: Introducing Namada: Interchain Asset-agnostic Privacy
• Article: What is Namada?
• Talks & Podcasts

To learn more about the protocol, we recommend the following in-depth resources:

• Talk at ZK8 Namada: asset-agnostic interchain privacy
• Namada's specifications
• Codebase

Introduction

Welcome to Namada's docs!

How to read this book

Here are some useful tips for reading this book:

• Comments start with #:

# this is a comment make sure you read them!

• Sample outputs start with an arrow:

➜ this is an example command line output useful for comparing

• Commands you should run are prefixed with a $:

$ this is a command you should run

• User-defined inputs are in square brackets:

$ this is a command you should run [with your own input]

About this documentation

This book is written using mdBook, the source can be found in the Namada repository.

Contributions to the contents and the structure of this book should be made via pull requests.

Quickstart

About this guide

This guide is for those interested in operating a Namada validator node and assumes basic knowledge of the terminal and how commands are used.

Installing Namada

See the installation guide for details on installing the Namada binaries. Commands in this guide will assume you have the Namada binaries (namada, namadan, namadaw, namadac) on your $PATH.

If you the binaries stored somewhere, but are not on your path (perhaps you downloaded the binaries), you can add the binaries to to your $PATH with:

$ export PATH=$PATH:[path-to-namada-binaries]

If you build from source, and run make install, the binaries will be installed to your $PATH by default.

Joining a network

See the testnets page for details of how to join a testnet. The rest of this guide will assume you have joined a testnet chain using the namadac utils join-network --chain-id [some-chain-id] command.

Run a ledger node

We recommend this step with tmux, which allows the node to keep running without needing the terminal to be open indefinitely. If not, skip to the subsequent step.

tmux

# inside the tmux/or not

$ namada ledger

# can detach the tmux (Ctrl-B then D)

For a more verbose output, one can run

NAMADA_LOG=info TM_LOG_LEVEL=p2p:none,pex:error NAMADA_TM_STDOUT=true namada ledger

This should sync your node to the ledger and will take a while (depending on your computer). Subsequent commands (generating an account, etc.) are unlikely to work until it is fully synced. Enquire the current block height with other participants to make sure you are synced in order to proceed.

Account

Accounts on Namada are divided into two subcategories:

• Implicit accounts (all use the same Validity Predicate)
• Established accounts (can use a chosen Validity Predicate)

In order to make transactions on Namada, an account is required, and an implicit account can be created easily.

An implicit account can be generated from the commands described below

namadaw address gen \
  --alias example-implicit

➜ Enter encryption password: 
Successfully added a key and an address with alias: "example-implicit"

An implicit account with alias "example-implicit" has now been successfully generated and stored locally in the wallet.

It is possible to derive an Established Account through submitting a transaction, signing it with the key for the implicit account. Note that this transaction, as with any transaction on Namada, will consume "gas", and will require a positive balance of NAM tokens.

To initialize an account operator on-chain under the alias "example-established":

namadac init-account \
  --source example-implicit \
  --public-key example-implicit \
  --alias example-established

➜ Jan 06 22:22:19.864  INFO namada_apps::cli::context: Chain ID: namada-testnet-1.2.bf0181d9f7e0
Enter decryption password: 
Last committed epoch: 22386
Transaction added to mempool: Response { code: Ok, data: Data([]), log: Log("Mempool validation passed"), hash: transaction::Hash(9193C2B2C56AAB1B081B18DA0FBBD4B26C5EF7CEE4B35812ECCB1CC1D1443C45) }
Transaction applied with result: {
  "info": "Transaction is valid. Gas used: 6080310; Changed keys: #atest1v4ehgw36ggmyzwp5g9prgsekgsu5y32z8ycnsvpeggcnys35gv65yvzxg3zrjwphgcu5gde4lvmstw/?, #atest1v4ehgw36ggmyzwp5g9prgsekgsu5y32z8ycnsvpeggcnys35gv65yvzxg3zrjwphgcu5gde4lvmstw/ed25519_pk; VPs result: ",
  "height": "650627",
  "hash": "4FCCBCE5D4335C3A265B5CF22D5B8999451715F8146EB13194711B5EC70B612A",
  "code": "0",
  "gas_used": "6080310",
  "initialized_accounts": [
    "atest1v4ehgw36ggmyzwp5g9prgsekgsu5y32z8ycnsvpeggcnys35gv65yvzxg3zrjwphgcu5gde4lvmstw"
  ]
}
The transaction initialized 1 new account
➜ Added alias example-established for address atest1v4ehgw36ggmyzwp5g9prgsekgsu5y32z8ycnsvpeggcnys35gv65yvzxg3zrjwphgcu5gde4lvmstw

The "faucet" is a native established account on Namada that is willing to give a maximum of 1000 tokens to any user at request. Let's transfer ourselves 1000 NAM from the faucet with the same alias using:

namadac transfer \
  --source faucet \
  --target example-established \
  --token NAM \
  --amount 1000 \
  --signer example-implicit

➜ Jan 06 22:24:32.926  INFO namada_apps::cli::context: Chain ID: namada-testnet-1.2.bf0181d9f7e0
➜ Looking-up public key of atest1v4ehgw36ggmyzwp5g9prgsekgsu5y32z8ycnsvpeggcnys35gv65yvzxg3zrjwphgcu5gde4lvmstw from the ledger...
Enter decryption password: 
Last committed epoch: 22388
Transaction added to mempool: Response { code: Ok, data: Data([]), log: Log("Mempool validation passed"), hash: transaction::Hash(3A5CA1790FDF5150EF1478DE1E3B2D2F7189B0E5D396176E5E5BFC7A37C58D00) }
Transaction applied with result: {
  "info": "Transaction is valid. Gas used: 1504228; Changed keys: #atest1v4ehgw36x3prswzxggunzv6pxqmnvdj9xvcyzvpsggeyvs3cg9qnywf589qnwvfsg5erg3fkl09rg5/balance/#atest1v4ehgw36ggmyzwp5g9prgsekgsu5y32z8ycnsvpeggcnys35gv65yvzxg3zrjwphgcu5gde4lvmstw, #atest1v4ehgw36x3prswzxggunzv6pxqmnvdj9xvcyzvpsggeyvs3cg9qnywf589qnwvfsg5erg3fkl09rg5/balance/#atest1v4ehgw36gc6yxvpjxccyzvphxycrxw2xxsuyydesxgcnjs3cg9znwv3cxgmnj32yxy6rssf5tcqjm3; VPs result:  Accepted: atest1v4ehgw36ggmyzwp5g9prgsekgsu5y32z8ycnsvpeggcnys35gv65yvzxg3zrjwphgcu5gde4lvmstw, atest1v4ehgw36gc6yxvpjxccyzvphxycrxw2xxsuyydesxgcnjs3cg9znwv3cxgmnj32yxy6rssf5tcqjm3, atest1v4ehgw36x3prswzxggunzv6pxqmnvdj9xvcyzvpsggeyvs3cg9qnywf589qnwvfsg5erg3fkl09rg5;",
  "height": "650706",
  "hash": "26AAE9D79F62EE8E62108D8D7689F4FFF12EA613AF29C7D4CDBEA999C28C6224",
  "code": "0",
  "gas_used": "1504228",
  "initialized_accounts": []
}

To query the balance of your account "example-established":

namadac balance \
  --owner example-established

Setting up the validator node

Initialize a validator account under any alias - in this example, "example-validator":

namadac init-validator \
  --alias example-validator \
  --source example-established \
  --commission-rate 0.01 \
  --max-commission-rate-change 0.05 \
  --source example-established

➜  Jan 06 22:26:29.927  INFO namada_apps::cli::context: Chain ID: namada-testnet-1.2.bf0181d9f7e0
Generating validator account key...

You will be asked to enter encryption passwords to generate a validator account key, consensus key and a staking reward account key. After entering the encryption password and a decryption password for the "example-established" account's key, the transaction should be added to the mempool and applied in a future block.

➜ Transaction added to mempool: Response { code: Ok, data: Data([]), log: Log("Mempool validation passed"), hash: transaction::Hash(F61D3D73CE7EFCC2021940A75B713C499D4942F820F6EC0F7924B70E7F2E751A) }
Transaction applied with result: {
  "info": "Transaction is valid. Gas used: 15139451; Changed keys: #atest1v9hx7w362pex7mmxyphkvgznw3skkefqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqq8ylv7/validator/#atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd/voting_power, #atest1v9hx7w362pex7mmxyphkvgznw3skkefqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqq8ylv7/validator/#atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd/staking_reward_address, #atest1v4ehgw36xppnjsjzx4ryxs2zgc6nx33hxpq5zve4g5u5xdjpgfz5xv2pg3ryy3zrxyenssfcxn02yg/ed25519_pk, #atest1v9hx7w362pex7mmxyphkvgznw3skkefqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqq8ylv7/validator/#atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd/total_deltas, #atest1v9hx7w362pex7mmxyphkvgznw3skkefqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqq8ylv7/validator/#atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd/state, #atest1v9hx7w362pex7mmxyphkvgznw3skkefqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqq8ylv7/validator/#atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd/consensus_key, #atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd/?, #atest1v4ehgw36xppnjsjzx4ryxs2zgc6nx33hxpq5zve4g5u5xdjpgfz5xv2pg3ryy3zrxyenssfcxn02yg/?, #atest1v9hx7w362pex7mmxyphkvgznw3skkefqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqq8ylv7/validator_set, #atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd/ed25519_pk, #atest1v9hx7w362pex7mmxyphkvgznw3skkefqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqq8ylv7/address_raw_hash/DB3D27BF31382E6250C06119C3FDF4672BB3DF5A; VPs result:  Accepted: atest1v9hx7w362pex7mmxyphkvgznw3skkefqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqq8ylv7;",
  "height": "650779",
  "hash": "3B6AA8F3E6F1951E21703CABA4CCD24F82F6D5C38674041A7AAA1B7227B1E6B8",
  "code": "0",
  "gas_used": "15139451",
  "initialized_accounts": [
    "atest1v4ehgw36xppnjsjzx4ryxs2zgc6nx33hxpq5zve4g5u5xdjpgfz5xv2pg3ryy3zrxyenssfcxn02yg",
    "atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd"
  ]
}
Added alias example-validator for address atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd.
Added alias example-validator-rewards for address atest1v4ehgw36xppnjsjzx4ryxs2zgc6nx33hxpq5zve4g5u5xdjpgfz5xv2pg3ryy3zrxyenssfcxn02yg.

The validator's addresses and keys were stored in the wallet:
  Validator address "example-validator"
  Staking reward address "example-validator-rewards"
  Validator account key "example-validator-key"
  Consensus key "example-validator-consensus-key"
  Staking reward key "example-validator-rewards-key"
The ledger node has been setup to use this validator's address and consensus key.

Once the init-validator transaction is applied in the block and the on-chain generated validator's address is stored in your wallet, you MUST restart the namada ledger node to start the node as a validator that you've just created.

When you restart the node, you might notice log message "This node is not a validator" from Tendermint. This is expected, because your validator doesn't yet have any stake in the PoS system.

We will now add some stake to your validator account.

Transfer 1000 NAM to your validator account ("example-validator"):

namadac transfer \
  --source example-established \
  --target example-validator \
  --token NAM \
  --amount 1000

➜  Jan 06 22:28:17.624  INFO namada_apps::cli::context: Chain ID: namada-testnet-1.2.bf0181d9f7e0
Looking-up public key of atest1v4ehgw36ggmyzwp5g9prgsekgsu5y32z8ycnsvpeggcnys35gv65yvzxg3zrjwphgcu5gde4lvmstw from the ledger...
Enter decryption password: 
Last committed epoch: 22392
Transaction added to mempool: Response { code: Ok, data: Data([]), log: Log("Mempool validation passed"), hash: transaction::Hash(7FD43C7573B4A62E24DBB6C99EE6C7A107DF01CC5F947517B91742E6324AE58D) }
Transaction applied with result: {
  "info": "Transaction is valid. Gas used: 1989091; Changed keys: #atest1v4ehgw36x3prswzxggunzv6pxqmnvdj9xvcyzvpsggeyvs3cg9qnywf589qnwvfsg5erg3fkl09rg5/balance/#atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd, #atest1v4ehgw36x3prswzxggunzv6pxqmnvdj9xvcyzvpsggeyvs3cg9qnywf589qnwvfsg5erg3fkl09rg5/balance/#atest1v4ehgw36ggmyzwp5g9prgsekgsu5y32z8ycnsvpeggcnys35gv65yvzxg3zrjwphgcu5gde4lvmstw; VPs result:  Accepted: atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd, atest1v4ehgw36ggmyzwp5g9prgsekgsu5y32z8ycnsvpeggcnys35gv65yvzxg3zrjwphgcu5gde4lvmstw, atest1v4ehgw36x3prswzxggunzv6pxqmnvdj9xvcyzvpsggeyvs3cg9qnywf589qnwvfsg5erg3fkl09rg5;",
  "height": "650842",
  "hash": "D251AAB5D4CD9471DB4E11DA09DEF0F15E2A3EC95EE0EE2C76766839FC352394",
  "code": "0",
  "gas_used": "1989091",
  "initialized_accounts": []
}

Bond the 1000 NAM to "example-validator" using:

namadac bond \
  --validator example-validator \
  --amount 1000

➜ Jan 06 22:29:08.903  INFO namada_apps::cli::context: Chain ID: namada-testnet-1.2.bf0181d9f7e0
Looking-up public key of atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd from the ledger...
Enter decryption password: 
Last committed epoch: 22393
Transaction added to mempool: Response { code: Ok, data: Data([]), log: Log("Mempool validation passed"), hash: transaction::Hash(2B814FE404F6F1D8C07CC3A51AA3038C193810251B9C50107B79698ED15A4EDC) }
Transaction applied with result: {
  "info": "Transaction is valid. Gas used: 3734939; Changed keys: #atest1v9hx7w362pex7mmxyphkvgznw3skkefqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqq8ylv7/validator/#atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd/total_deltas, #atest1v9hx7w362pex7mmxyphkvgznw3skkefqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqq8ylv7/total_voting_power, #atest1v9hx7w362pex7mmxyphkvgznw3skkefqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqq8ylv7/validator_set, #atest1v4ehgw36x3prswzxggunzv6pxqmnvdj9xvcyzvpsggeyvs3cg9qnywf589qnwvfsg5erg3fkl09rg5/balance/#atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd, #atest1v4ehgw36x3prswzxggunzv6pxqmnvdj9xvcyzvpsggeyvs3cg9qnywf589qnwvfsg5erg3fkl09rg5/balance/#atest1v9hx7w362pex7mmxyphkvgznw3skkefqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqq8ylv7, #atest1v9hx7w362pex7mmxyphkvgznw3skkefqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqq8ylv7/validator/#atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd/voting_power, #atest1v9hx7w362pex7mmxyphkvgznw3skkefqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqq8ylv7/bond/#atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd/#atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd; VPs result:  Accepted: atest1v4ehgw36g3prx3pjxapyvve3xvury3fkxg6nqsesxccnzw2rxdryg335xcmnysjzxdzyvd2pamfmwd, atest1v9hx7w362pex7mmxyphkvgznw3skkefqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqq8ylv7, atest1v4ehgw36x3prswzxggunzv6pxqmnvdj9xvcyzvpsggeyvs3cg9qnywf589qnwvfsg5erg3fkl09rg5;",
  "height": "650869",
  "hash": "14F5C67D27E2F9695EA40ABEA2DEC69F5B0FFEF5DFD7CB7D0FC397CC8A618BA8",
  "code": "0",
  "gas_used": "3734939",
  "initialized_accounts": []
}

Check your bond:

namadac bonds \
  --validator example-validator

➜ Jan 06 22:30:42.798  INFO namada_apps::cli::context: Chain ID: namada-testnet-1.2.bf0181d9f7e0
Last committed epoch: 22394
Self-bonds:
  Active from epoch 22395: Δ 1000
Bonds total: 1000

Check the voting power - this will be 0 until the active-from epoch is reached (in this case 22395):

namadac bonded-stake \
  --validator example-validator

➜ Bonded stake of validator atest1v4ehgw36gs6rjd69xaqnj33kxqcnv3pc8qmryd6z8yeygdjrxepygwzrg4z52dekg4rrzwz9m09dm8: 1000
Total bonded stake: 301000

Note that with the above command, you can also specify --epoch argument to check a future epoch.

Congratulations, you have set up a validator node!

Install Namada

Pre-requisites

There are certain pre-requisites that need to be installed before installing Namada.

Installing Tendermint

Follow these instructions in order to setup Tendermint.

Installing GLIBC

Finally, you should have GLIBC v2.29 or higher.

MacOS: the system-provided glibc should be recent enough.

Ubuntu 20.04: this is installed by default and you don't have to do anything more.

Ubuntu 18.04: glibc has v2.27 by default which is lower than the required version to run Namada. We recommend to directly install from source or upgrade to Ubuntu 19.04, instead of updating glibc to the required version, since the latter way can be a messy and tedious task. In case updating glibc would interest you this website gives you the steps to build the package from source.

Installing Namada

Namada can be installed through the following methods:

1. From source
2. From binaries
3. From a docker image

The hardware requirements for installing and running a Namada full node can be found here

Install from source

Pre-requisites

If you'd like to install Namada from source you will have to install some dependencies first: Rust, Git, Clang, OpenSSL and LLVM.

First, install Rust by following the instructions from the official page.

At the end of the installation, make sure that Cargo's bin directory ($HOME/.cargo/bin) is available on your PATH environment variable. You can either restart your shell or run source $HOME/.cargo/env to continue.

If you already have Rust installed, make sure you're using the latest version by running:

rustup update

Then, install the remaining dependencies.

Ubuntu: running the following command should install everything needed:

sudo apt-get install -y make git-core libssl-dev pkg-config libclang-12-dev build-essential protobuf-compiler

Mac: installing the Xcode command line tools should provide you with almost everything you need:

xcode-select --install

protoc is also required. On Mac, you can install it with Homebrew:

brew install protobuf

When running

protoc --version

It should output at least:

libprotoc 3.12.0

Please refer to protoc-installation doc for other installation options.

Installing Namada

Now that you have all the required dependencies installed, you can clone the source code from the Namada repository and build it with:

git clone https://github.com/anoma/namada.git
cd namada 
make install

Install From Binaries

Downloading the binaries

Now that you have all dependencies installed, you can download the latest binary release from our releases page by choosing the appropriate architecture.

Placing the binaries onto $PATH

For ubuntu and mac machines, the following command should work for placing namada into path

Once inside the directory containing the binaries:

sudo cp ./namada* /usr/local/bin/

Overview of Binaries

This guide assumes that the Namada binaries are installed and available on path. These are:

• namada: The main binary that can be used to interact with all the components of Namada
• namadan: The ledger node
• namadac: The client
• namadaw: The wallet

The main binary namada has sub-commands for all of the other binaries:

• namada client == namadac
• namada node == namadan
• namada wallet == namadaw

To explore the command-line interface, add --help argument at any sub-command level to find out any possible sub-commands and/or arguments.

From Docker

Pre-requisites

In order to run any docker images, you need to have docker installed. You can find instructions on how to install docker for your machine here.

Downloading the docker image

The Namada docker image can be found here

Under the Tags tab, you can find the latest version of the docker image. Click on the link for the correct version of Namada that you are trying to install. For example, if you are trying to install Namada v0.16.0, you would click on the link for v0.16.0.

You can find the tag of the downloaded docker image by running docker images. The tag will be the first column of the output.

Running the docker image

Once you have downloaded the docker image, it will be useful to export some environment variables:

export CHAIN_ID=<chain-id>

The following docker run command will run the ledger node:

docker run -P -i -t $DOCKER_IMAGE <namada command>

Where <namada command> is any command you would run after namada in the terminal. For example, if you wanted to run namada client utils join-network --chain-id $CHAIN_ID, you would run:

docker run -P -i -t $DOCKER_IMAGE client utils join-network --chain-id $CHAIN_ID

Then in order to run any other ledger commands, one can run:

docker /bin/bash -c "/bin/bash","-c", "<namada command>"

Alternative method (building the docker image yourself)

Alternatively, you can build the docker image yourself!

Begin by exporting some environment variables:

export CHAIN_ID=<chain-id>
export BRANCH=<namada-version>

For example if you wanted to build the docker image for Namada v0.16.0 and chain-id public-testnet-69.0.b20a1337aa1, you would run:

export CHAIN_ID=public-testnet-69.0.b20a1337aa1
export BRANCH=v0.16.0

Then you can build the docker image by running:

git clone https://github.com/anoma/namada-sdk-starter.git
cd namada-sdk-starter/docker/namada-with-chain/
docker build --build-arg BRANCH=$BRANCH --build-arg CHAIN_ID=$CHAIN_ID -t namada_testnet_image .

Which will save the image to your local docker images. You can find the tag of the downloaded docker image by running docker images. The tag will be the first column of the output.

Save this docker image as an environment variable

export DOCKER_IMAGE=<tag>

Then you can run the docker image by running:

docker run -P -i -t $DOCKER_IMAGE

Installing Tendermint

Start by exporting the variable

export TM_HASH=v0.1.4-abciplus

Install the heliaxdev/tendermint fork

git clone https://github.com/heliaxdev/tendermint && cd tendermint && git checkout $TM_HASH
make build

The above requires that golang is correctly installed with the correct $PATH setup

• In linux, this can be resolved by
• sudo snap install go --channel=1.18/stable --classic
• Copy both the namada and tendermint binaries to somewhere on $PATH (or uselol the relative paths)
• This step may or may not be necessary
• namada binaries can be found in /target/release
• tendermint is in build/tendermint

sudo cp ./build/tendermint $HOME/go/bin/

Namada Testnets

For more context read:

• Announcing Namada Public Testnets

Namada protocol versions

A testnet might deploy different versions of the Namada protocol. To see in-detail what each protocol version includes, refer to the Github changelog, which specifies what changes have been made in between versions.

Report a bug

If you find a bug, please submit an issue with the bug issue template.

How to join a Namada testnet

1. Environment setup
2. Pre-genesis instructions 1. Pre-genesis validator setup 2. Pre-genesis validator apply
3. Running your genesis validator
4. Running a full node
5. Becoming a validator post-genesis

The Namada public testnet is permissionless, anyone can join without the authorisation of a centralised party. Expect frequent upgrades (every two weeks).

Latest Upgrade

Latest Testnet

• Namada public testnet 8:
  • From date: 17th of May 2023 17.00 UTC
  • Namada protocol version: v0.15.3
  • Tendermint (Core) version: v0.1.4-abciplus
  • CHAIN_ID: public-testnet-8.0.b92ef72b820

Testnet History Timeline

• Namada public testnet 7:

  • From date: 24th of April 2023 17.00 UTC
  • Namada protocol version: v0.15.1
  • Tendermint (Core) version: v0.1.4-abciplus
  • CHAIN_ID: public-testnet-7.0.3c5a38dc983

• Namada public testnet 6:

  • From date: 29th of March 2023 17.00 UTC
  • Namada protocol version: v0.14.3
  • Tendermint (Core) version: v0.1.4-abciplus
  • CHAIN_ID: public-testnet-6.0.a0266444b06

• Namada public testnet 5:

  • From date: 15th of March 2023
  • Namada protocol version: v0.14.2
  • Tendermint version: v0.1.4-abciplus
  • CHAIN_ID: public-testnet-5.0.d25aa64ace6

• Namada public testnet 4:

  • From date: 22nd of February 2023
  • Namada protocol version: v0.14.1
  • Tendermint version: v0.1.4-abciplus
  • CHAIN_ID: public-testnet-4.0.16a35d789f4

• Namada public testnet 3 hotfix (did not suffice):

  • From date: 13th of February 2023
  • Namada protocol version: v0.13.4
  • Tendermint version: v0.1.4-abciplus
  • CHAIN_ID: public-testnet-3.0.81edd4d6eb6

• Namada public testnet 3:

  • From date: 9th of February 2023
  • Namada protocol version: v0.13.3
  • Tendermint version: v0.1.4-abciplus
  • CHAIN_ID: public-testnet-3.0.81edd4d6eb6

• Namada public testnet 2.1.2 hotfix:

  • From date: 25th of January 2023
  • Namada protocol version: v0.13.3
  • Tendermint version: v0.1.4-abciplus
  • CHAIN_ID: public-testnet-2.1.4014f207f6d

  Due to a bug, a hotfix was released. This needed to be installed and applied before 18:00:00 UTC on 2023-01-25.

• Namada public testnet 2.1.2:

  • From date: 24th of January 2023
  • Namada protocol version: v0.13.2
  • Tendermint version: v0.1.4-abciplus
  • CHAIN_ID: public-testnet-2.1.4014f207f6d

• Namada public testnet 2.1:

  • From date: 17th of January 2023
  • Namada protocol version: v0.13.1-hardfork (hardfork)
  • Tendermint version: v0.1.4-abciplus
  • CHAIN_ID: public-testnet-2.0.2feaf2d718c

The above hardfork was meant to take effect on Block Height 37370, but some issues arose. You can read more here.

• Namada public testnet 2.0:

  • From date: 12th of January 2023
  • Namada protocol version: v0.13.0
  • Tendermint version: v0.1.4-abciplus
  • CHAIN_ID: public-testnet-2.0.2feaf2d718c

• Namada public testnet 1.1:

  • From date: 2nd of January 2023
  • Namada protocol version: v0.12.2

• Namada public testnet 1:

  • Namada protocol version: v0.12.0
  • Tendermint version: v0.1.4-abciplus
  • Genesis time: 20th of December 2022 at 17:00 UTC
  • CHAIN_ID: public-testnet-1.0.05ab4adb9db

Block explorer

The block explorer is currently in development. The latest version can be found at namada.world

Community

For questions or feedback, feel free to post or comment on Reddit or Github. Don't forget to follow Namada on Twitter for testnet relevant updates and to join Discord for questions and support for validators.

Environment setup

Export the following variables:

export NAMADA_TAG=v0.15.3
export TM_HASH=v0.1.4-abciplus

Installing Namada

0. Install all pre-requisites

   • Rust
   • Tendermint
   • Protobuf

1. Clone namada repository and checkout the correct versions

git clone https://github.com/anoma/namada && cd namada && git checkout $NAMADA_TAG

2. Build binaries

make build-release

• There may be some additional requirements you may have to install (linux):

sudo apt-get update -y
sudo apt-get install build-essential make pkg-config libssl-dev libclang-dev -y
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Installing Tendermint

1. Install the heliaxdev/tendermint fork

git clone https://github.com/heliaxdev/tendermint && cd tendermint && git checkout $TM_HASH
make build

The above requires that golang is correctly installed with the correct $PATH setup

• namada binaries can be found in /target/release
• tendermint is in build/tendermint

Check ports

1. Open ports on your machine:
   • 26656
   • 26657
2. To check if ports are open you can setup a simple server and curl the port from another host

• Inside the namada folder, run

{ printf 'HTTP/1.0 200 OK\r\nContent-Length: %d\r\n\r\n' "$(wc -c < namada)"; cat namada; } | nc -l $PORT`

• From another host run one of the two commands:
  • nmap $IP -p$PORT
  • curl $IP:$PORT >/dev/null

Verifying your installation

• Make sure you are using the correct tendermint version
  • tendermint version should output 0.1.4-abciplus
• Make sure you are using the correct Namada version
  • namada --version should output Namada v0.15.3

Steps for migrating testnets

This guide will help you migrate your validator node from one testnet to another. These steps are optional, and for most testnets, these steps will not be needed.

Resetting your validator node (optional)

This is the right time to save any logs file you want to share with us!

Locate the namada base directory

Depending on the testnet you are migrating from, the base directory will be located in different places. For this reason, we will save the base directory path to a variable.

Before v0.15.3

If you are migrating from a testnet BEFORE v0.15.3, then your home directory and relevant files will be located in a .namada. The location of this directory depends where you initially ran the command namadac utils join-network --chain-id <CHAIN_ID> --genesis-validator <ALIAS>. It will be located in the directory in which that command was executed.

Once located, you can save the base directory path to a variable. For example, if the join-network command was ran from your home directory, you can run:

export BASE_DIR=$HOME/.namada

After v0.15.3

If you are migrating from a testnet AFTER v0.15.3, then your base directory and relevant files will be located in .local/share/namada on Linux and Library/Application Support/Namada on MacOS.

If you are running linux, you can run:

export BASE_DIR=$HOME/.local/share/namada

Whereas if you are running MacOS, you can run:

export BASE_DIR=$HOME/Library/Application\ Support/Namada

1. IMPORTANT! Save your pre-genesis folder in the ledger base directory

Before we delete any folders, we want to make sure we save our pre-genesis folder. This folder contains your validator keys, and we want to make sure we don't lose them.

mkdir $HOME/backup-pregenesis && cp -r $BASE_DIR/pre-genesis $HOME/backup-pregenesis/

2. Ensure keys are saved

ls backup-pregenesis should output a saved wallet.toml.

3. Delete the base directory

rm -rf $BASE_DIR

4. Check that namada and tendermint binaries are correct. namada --version should give v0.15.3 and tendermint version should give 0.1.4-abciplus

5. Create a base directory for the ledger

Linux

mkdir $HOME/.local/share/namada

MacOS

mkdir '$HOME/Library/Application Support/Namada'

6. Save the base directory path to a variable

Linux:

export BASE_DIR=$HOME/.local/share/namada

MacOS:

export BASE_DIR=$HOME/Library/Application\ Support/Namada

7. Create a pre-genesis directory

Linux:

mkdir $HOME/.local/share/namada/pre-genesis

MacOS:

mkdir $HOME/Library/Application\ Support/Namada/pre-genesis

8. Copy the backuped file back to $BASE_DIR/pre-genesis folder

cp -r backup-pregenesis/* $BASE_DIR/pre-genesis/

You should now be ready to go!

Pre-genesis validator instructions

Pre-genesis is defined as "before" the first (or genesis) block. At genesis, there will be a set of validators with a pre-defined amount of tokens (described in the genesis file).

For testnets, it is possible to apply to become a pre-genesis validator. In order to do so, please follow these steps.

If the testnet is already running and you have not been selected as a pre-genesis validator, please follow the steps for joining as a full node. If you still wish to validate, you can follow the steps to become a post-genesis-validator.

Applying to be a genesis validator

Before a testnet launches, you can apply to be a genesis validator.

1) Set up

Follow this guide on how to generate your "pre-genesis" validator files.

After this, you'll have a validator.toml file, the contents of which will look something like the following:

[validator.1337-validator]
consensus_public_key = "00056fff5232da385d88428ca2bb2012a4d83cdf5c697864dde34b393333a72268"
account_public_key = "00f1bd321be2e23b9503653dd50fcd5177ca43a0ade6da60108eaecde0d68abdc8"
staking_reward_public_key = "005725f952115838590fc7c5dd9590bc054ac4bd5af55672a40df4ac7dca50ce97"
protocol_public_key = "0054c213d2f8fe2dd3fc5a41a52fd2839cb49643d960d7f75e993202692c5d8783"
dkg_public_key = "6000000054eafa7320ddebf00c9487e5f7ea5107a8444f042b74caf9ed5679163f854577bf4d0992a8fd301ec4f3438c9934c617a2c71649178e536f7e2a8cdc1f8331139b7fd9b4d36861f0a9915d83f61d7f969219f0eba95bb6fa45595425923d4c0e"
commission_rate = "0.05"
max_commission_rate_change = "0.01"
net_address = "1.2.3.4:26656"
tendermint_node_key = "00e1a8fe1abceb700063ab4558baec680b64247e2fd9891962af552b9e49318d8d"

This file contains only public information and is safe to share publicly.

2.1) Submitting the config

If you want to be a genesis validator for the testnet, please make a pull request to https://github.com/anoma/namada-testnets adding your validator.toml file to the relevant directory (e.g. namada-public-testnet-2 for the second public testnet), renaming it to $alias.toml.

e.g. if you chose your alias to be "bertha", submit the file with the name bertha.toml. You can see what an example PR looks like here.

2.2) Wait for the CHAIN_ID

Wait until corresponding CHAIN_ID has been distributed.

Joining the latest testnet

Depending on whether you are a pre-genesis validator, you can join the latest testnet either as a genesis validator or as a full node.

Joining as a pre-genesis validator

These steps are for those who have been selected as a genesis validator. If you are not a genesis validator, please follow the steps for joining as a full node.

5) Become a validator post genesis

After genesis, you can still join the network as a user and become a validator through self-bonding.

After following step 4), create a user account through the following command

namada wallet address gen --alias my-account

Now choose a name for your validator:

export VALIDATOR_ALIAS="your-validator-name"

A validator account requires additional keys compared to a user account, so start by initialising a validator account:

namada client init-validator \
  --alias $VALIDATOR_ALIAS \
  --source my-account \
  --commission-rate <enter-your-commission-rate> \
  --max-commission-rate-change <enter-decimal-rate>
  

Then ensure you have enough NAM in order to self bond. Each voting power requires 1000 NAM, and you must be in the top 120 validators in terms of voting-power in order to become an active validator. You can see other validators' voting power through:

namada client bonded-stake

Faucet

In order to gain more NAM, the following command can be run:

namadac transfer \
    --token NAM \
    --amount 1000 \
    --source faucet \
    --target $VALIDATOR_ALIAS \
    --signer $VALIDATOR_ALIAS

Note: A maximum amount of 1000 NAM can be sourced from the faucet per transaction, so to get more, run this multiple times

namada client bond \
  --validator $VALIDATOR_ALIAS \
  --amount <enter-amount>

Upgrades

This page covers all installation steps required by various upgrades to testnets.

Latest Upgrade

19/05/2023 public-testnet-8 hot-fix

Due to some issues with our mempool validation, the testnet halted starting at block height 8073. We fixed this issue and released a hot-fix version to a subset of the validators. This was sufficient to keep the testnet going. It did require some validators to resync the testnet.

Latest Testnet

17/05/2023 public-testnet-8

The testnet launches on 17/05/2023 at 17:00 UTC with the genesis validators from public-testnet-8. It launches with version v0.15.3 and chain-id public-testnet-8.0.b92ef72b820. If your genesis transaction is contained in this folder, you are one of the genesis validators. In order for the testnet to come online, at least 2/3 of those validators need to be online.

The installation docs are updated and can be found here. The running docs for validators/fullnodes can be found here.

Previous upgrades:

24/04/2023 public-testnet-7 (offline)

The testnet launches on 24/04/2023 at 17:00 UTC with the genesis validators from public-testnet-7. It launches with version v0.15.1

The intended fix to solve the storage issue was only partially solved. This led to v0.15.3 which intended to fix these issues.

29/03/2023 public-testnet-6 (offline)

The testnet launches on 29/03/2023 at 17:00 UTC with the genesis validators from public-testnet-6. It launches with version v0.14.3 and chain-id public-testnet-6.0.a0266444b06. If your genesis transaction is contained in this folder, you are one of the genesis validators. In order for the testnet to come online, at least 2/3 of those validators need to be online.

The installation docs are updated and can be found here. The running docs for validators/fullnodes can be found here.

13/02/2023 public-testnet-3

On 09/02/2023 the Namada chain public-testnet-3 halted due to a bug in the Proof of Stake implementation when handling an edge case. Over the weekend, the team were able to fix and test a new patch that resolves the issue at hand. On 13/02/2023 11:30 UTC, we were able to recover the network by having internal validators upgrade to the new patch. We are now calling on validators to upgrade to the new testnet as well, which will allow you to interact with the recovered chain.

Upgrading

1. Begin by stopping all instances of the namada node

killall namadan

2. Build the new tag (or download the binaries here)

cd namada
export NAMADA_TAG=v0.13.4
make build-release

3. Copy the new binaries to path. More in depth instructions can be found at here
4. Once this has been completed, the node must tesync from genesis (see below)

How to resync from genesis:

1. As a precautionary measure, make a backup of your pregenesis keys

mkdir backup-pregenesis && cp -r .namada/pre-genesis backup-pregenesis/

2. Delete the relevant folder in .namada

rm -r .namada/public-testnet-3.0.81edd4d6eb6
rm .namada/public-testnet-3.0.81edd4d6eb6.toml

WARNING: Do not delete the entire .namada folder, as it contains your pre-genesis keys. If this is accidentally done, you will have to copy over the backup-pregenesis file. See these instructions for more details 3. Rejoin the network

export CHAIN_ID="public-testnet-3.0.81edd4d6eb6"
namada client utils join-network \
--chain-id $CHAIN_ID --genesis-validator $ALIAS

4. Run the node. One can simply run the ledger again using the familiar command

  NAMADA_TM_STDOUT=true namada node ledger run

Please reach out with any questions if you have any. This upgrade can be done asynchronously, but if you wish to continue validating the chain and testing our features, you must execute the above steps.

Hotfix for Testnet public-testnet-2.1.4014f207f6d

27/01/2023

The hotfixed testnet ran during the week, when a strange bug caused the network to stall. The core team spent 1 week investigating the cause of the bug, and the result they found was quite interesting. If you are curious about the specific details of the bug, please have a read through Ray's blog post here.

25/01/2023

At around 06:15 UTC 25/01/2023, a validator with very little stake was scheduled to become part of the active validator set. From this tx, we discovered a conversion bug between the Namada state machine and Tendermint, which lead to a crash in the node. A patch was released v0.13.3 in order to deal with this issue.

23/01/2023

A new testnet was released before the fortnightly testnet release schedule due to the below hardfork not working as intended. Follow the steps in setting up a new testnet

Hardfork v0.13.1

This hardfork is set to be instantiated at block height 37370, which is predicted to occur at around 17.00 UTC on 18/01/2023.

Requirements to do before 17.00 UTC 18/01/2023

In order to install this upgrade, a user or validator must

1. Download the binaries or install them from source

2. Ensure the versions are correct, such that <PATH_TO_BINARY>/namada --version is v0.13.1-hardfork

3. Interrupt the namada ledger by the interrupt command ^C

4. Install the binaries onto $PATH (this depends on your machine). This must be done after interrupting the ledger, as otherwise an error is likely to be thrown.

5. As soon as possible, restart the ledger by running NAMADA_TM_STDOUT=true namada node ledger run

The ledger will then update correctly at the correct height. In order to ensure a smooth fork, please do this as soon as possible.

The PoW Solution on Namada

In order to combat the "costlessness of blockspace" problem with a testnet, and hence prevent DOS attacks as a result, when a Namada account does not have the required fees to pay for a transaction, the user must complete a Proof of Work challenge. The difficulty of this challenge is a parameter set by governance, and will dictate the (average) computational expenditure needed in order to complete the challenge.

In order to avoid having to complete endless Proof of Work challenges, we recommend using the faucet to fund the implicit account as one of a user's first transactions:

namada client transfer \
  --source faucet \
  --target my-key \
  --token NAM \
  --amount 1000 \
  --signer my-key

which will allow my-key to sign future transactions and pay for any further fees.

The PoW Faucet

The Faucet on Namada will always require users to complete a PoW challenge, regardless of the balance of the implicit account.

Full Node Setup

1. Wait for the genesis file to be ready, you will receive a $CHAIN_ID.
2. Join the network with the CHAIN_ID

  export CHAIN_ID="public-testnet-8.0.b92ef72b820"
  namada client utils join-network --chain-id $CHAIN_ID

3. Start your node and sync

  NAMADA_TM_STDOUT=true namada node ledger run

Optional: If you want more logs, you can instead run

NAMADA_LOG=info TM_LOG_LEVEL=p2p:none,pex:error NAMADA_TM_STDOUT=true namada node ledger run

And if you want to save your logs to a file, you can instead run:

TIMESTAMP=$(date +%s)
NAMADA_LOG=info TM_LOG_LEVEL=p2p:none,pex:error NAMADA_TM_STDOUT=true namada node ledger run &> logs-${TIMESTAMP}.txt
tail -f -n 20 logs-${TIMESTAMP}.txt ## (in another shell)

The Namada Ledger

To start a local Namada ledger node, run:

namada ledger

Note: You need to have joined a network before you start the ledger. It throws an error if no network has been configured.

The node will attempt to connect to the persistent validator nodes and other peers in the network, and synchronize to the latest block.

By default, the ledger will store its configuration and state in either $HOME/.local/share/namada or $HOME/Library/Application\ Support/Namada. You can use the --base-dir CLI global argument or BASE_DIR environment variable to change it.

• Linux:

export BASE_DIR=$HOME/.local/share/namada

• MacOS:

export BASE_DIR=$HOME/Library/Application\ Support/Namada

The ledger also needs access to the built WASM files that are used in the genesis block. These files are included in release and shouldn't be modified, otherwise your node will fail with a consensus error on the genesis block. By default, these are expected to be in the wasm directory inside the chain directory that's in the base directory. This can also be set with the --wasm-dir CLI global argument, NAMADA_WASM_DIR environment variable or the configuration file.

The ledger configuration is stored in $BASE_DIR/{chain_id}/config.toml (with default --base-dir). It is created when you join the network. You can modify that file to change the configuration of your node. All values can also be set via environment variables. Names of the recognized environment variables are derived from the configuration keys by: uppercase every letter of the key, insert . or __ for each nested value and prepend NAMADA_. For example, option p2p_pex in [ledger.tendermint] can be set by NAMADA_LEDGER__TENDERMINT__P2P_PEX=true|false or NAMADA_LEDGER.TENDERMINT.P2P_PEX=true|false in the environment (Note: only the double underscore form can be used in Bash, because Bash doesn't allow dots in environment variable names).

Genesis validator setup

A genesis validator is one which is a validator right from the first block of the chain - i.e. at genesis. The details of genesis validators are hardcoded into the genesis file that is distributed to all users who want to interact with a chain.

Prerequisites

• a machine that meets the requirements for running a validator node
• an associated public IPv4 address with ports 26656 reachable from anywhere for P2P connections

Pre-genesis

To setup all the required keys for a genesis validator for an upcoming network, you can execute the following command with an alias of your choice. Note that this alias is public (the address of your validator account will be visible in every wallet) and must be unique within the network.

You must also provide a static {IP:port} to the --net-address argument of your future node's P2P address.

1. Create your validator keys:

export ALIAS="CHOOSE_A_NAME_FOR_YOUR_VALIDATOR"
export PUBLIC_IP="LAPTOP_OR_SERVER_IP"
namada client utils init-genesis-validator --alias $ALIAS \
--max-commission-rate-change 0.01 --commission-rate 0.05 \
--net-address $PUBLIC_IP:26656

2. After generating your keys, the command will print something like this:

Linux

Pre-genesis TOML written to $HOME/.local/share/namada

MacOS

Pre-genesis TOML written to /Users/$USER/Library/Application\ Support/Namada

3. Save this directory as an environment variable for later use:

Linux

export BASE_DIR="$HOME/.local/share/namada"

MacOS

export BASE_DIR="/Users/$USER/Library/Application\ Support/Namada"

This file is the public configuration of your validator. You can safely share this file with the network's organizer, who is responsible for setting up and publishing the finalized genesis file and Namada configuration for the chain.

Note that the wallet containing your private keys will also be written into this directory.

4. You can print the validator.toml by running:

Linux

cat $HOME/.local/share/namada/pre-genesis/$ALIAS/validator.toml

MacOS

cat $HOME/Library/Application\ Support/Namada/pre-genesis/$ALIAS/validator.toml

Required keys

• Account key: Can be used to sign transactions that require authorization in the default validator validity predicate, such as a balance transfer.
• Staking rewards key: Can be used to sign transactions on the PoS staking rewards account.
• Protocol key: This key is used by the validator's ledger itself to sign protocol transaction on behalf of the validator.
• DKG key: Special key needed for participation in the DKG protocol
• Consensus key: Used in Tendermint consensus layer. Currently, this key is written to a file which is read by Tendermint.
• Tendermint node key: This key is used to derive Tendermint node ID for P2P connection authentication. This key is also written to a file which is read by Tendermint.

Hardware Requirements

This section covers the recommended hardware requirements for engaging with Namada for validators, full nodes & light nodes.

Resource Requirements

*Note that storage size will be dependent on level of pruning

Genesis validator setup

A genesis validator is one which is a validator right from the first block of the chain - i.e. at genesis. The details of genesis validators are hardcoded into the genesis file that is distributed to all users who want to interact with a chain.

Prerequisites

• a machine that meets the requirements for running a validator node
• an associated public IPv4 address with ports 26656 reachable from anywhere for P2P connections

Pre-genesis

To setup all the required keys for a genesis validator for an upcoming network, you can execute the following command with an alias of your choice. Note that this alias is public (the address of your validator account will be visible in every wallet) and must be unique within the network.

You must also provide a static {IP:port} to the --net-address argument of your future node's P2P address.

1. Create your validator keys:

export ALIAS="CHOOSE_A_NAME_FOR_YOUR_VALIDATOR"
export PUBLIC_IP="LAPTOP_OR_SERVER_IP"
namada client utils init-genesis-validator --alias $ALIAS \
--max-commission-rate-change 0.01 --commission-rate 0.05 \
--net-address $PUBLIC_IP:26656

2. After generating your keys, the command will print something like this:

Linux

Pre-genesis TOML written to $HOME/.local/share/namada

MacOS

Pre-genesis TOML written to /Users/$USER/Library/Application\ Support/Namada

3. Save this directory as an environment variable for later use:

Linux

export BASE_DIR="$HOME/.local/share/namada"

MacOS

export BASE_DIR="/Users/$USER/Library/Application\ Support/Namada"

This file is the public configuration of your validator. You can safely share this file with the network's organizer, who is responsible for setting up and publishing the finalized genesis file and Namada configuration for the chain.

Note that the wallet containing your private keys will also be written into this directory.

4. You can print the validator.toml by running:

Linux

cat $HOME/.local/share/namada/pre-genesis/$ALIAS/validator.toml

MacOS

cat $HOME/Library/Application\ Support/Namada/pre-genesis/$ALIAS/validator.toml

Required keys

• Account key: Can be used to sign transactions that require authorization in the default validator validity predicate, such as a balance transfer.
• Staking rewards key: Can be used to sign transactions on the PoS staking rewards account.
• Protocol key: This key is used by the validator's ledger itself to sign protocol transaction on behalf of the validator.
• DKG key: Special key needed for participation in the DKG protocol
• Consensus key: Used in Tendermint consensus layer. Currently, this key is written to a file which is read by Tendermint.
• Tendermint node key: This key is used to derive Tendermint node ID for P2P connection authentication. This key is also written to a file which is read by Tendermint.

📒 PoS Validators

Generate a validator account

To register a new validator account, run:

namada client init-validator \
  --alias my-validator \
  --source my-new-acc \
  --commission-rate <commission-rate>
  --max-commission-rate-change <max-commission-rate-change>

The commission rate charged by the validator for delegation rewards and the maximum change per epoch in the commission rate charged by the validator for delegation rewards. Both are expressed as a decimal between 0 and 1. Staking rewards are not yet implemented.

This command will generate the keys required for running a validator:

• Consensus key, which is used in signing blocks in Tendermint.
• Validator account key for signing transactions on the validator account, such as token self-bonding, unbonding and withdrawal, validator keys, validity predicate, state and metadata updates.

Then, it submits a transaction to the ledger that generates the new validator account with established address, which can be used to receive new delegations.

The keys and the alias of the address will be saved in your wallet. Your local ledger node will also be setup to run this validator, you just have to shut it down with e.g. Ctrl + C, then start it again with the same command:

namada ledger

The ledger will then use the validator consensus key to sign blocks, should your validator account acquire enough voting power to be included in the active validator set. The size of the active validator set is limited to 128 (the limit is set by the PoS max_validator_slots parameter).

Note that the balance of NAM tokens that is in your validator account does not count towards your validator's stake and voting power:

namada client balance --owner my-validator --token NAM

That is, the balance of your account's address is a regular liquid balance that you can transfer using your validator account key, depending on the rules of the validator account's validity predicate. The default validity predicate allows you to transfer it with a signed transaction and/or stake it in the PoS system.

Self-bonding

You can submit a self-bonding transaction of tokens from a validator account to the PoS system with:

namada client bond \
  --validator my-validator \
  --amount 3.3

Determine your voting power

A validator's voting power is determined by the sum of all their active self-bonds and delegations of tokens, with slashes applied, if any.

The same rules apply to delegations. When you self-bond tokens, the bonded amount won't count towards your validator's stake (which in turn determines your power) until the beginning of epoch n + 2 in the current epoch n. The bonded amount of tokens will be deducted from the validator's account immediately and will be credited to the PoS system's account.

While your tokens are being self-bonded, they are locked-in the PoS system and hence are not liquid until you withdraw them. To do that, you first need to send a transaction to “unbond” your tokens. You can unbond any amount, up to the sum of all your self-bonds, even before they become active.

Self-unbonding

To submit an unbonding of self-bonded tokens from your validator:

namada client unbond \
  --validator my-validator \
  --amount 0.3

Again, when you unbond tokens, you won't be able to withdraw them immediately. Instead, tokens unbonded in the epoch n will be withdrawable starting from the epoch n + 6. After you unbond some tokens, you will be able to see when you can withdraw them via bonds query:

namada client bonds --validator my-validator

When the chain reaches the epoch in which you can withdraw the tokens (or anytime after), you can submit a withdrawal of unbonded tokens back to your validator account:

namada client withdraw --validator my-validator

Run your node as a genesis validator

1. Wait for the genesis file to be ready, CHAIN_ID.

2. Join the network with the CHAIN_ID

export CHAIN_ID="public-testnet-8.0.b92ef72b820"
namada client utils join-network \
--chain-id $CHAIN_ID --genesis-validator $ALIAS

3. Start your node and sync

NAMADA_LOG=info TM_LOG_LEVEL=p2p:none,pex:error NAMADA_TM_STDOUT=true namada node ledger run

Optional: If you want more logs, you can instead run

NAMADA_LOG=debug TM_LOG_LEVEL=p2p:none,pex:error NAMADA_TM_STDOUT=true namada node ledger run

And if you want to save your logs to a file, you can instead run:

TIMESTAMP=$(date +%s)
NAMADA_LOG=debug TM_LOG_LEVEL=p2p:none,pex:error NAMADA_TM_STDOUT=true namada node ledger run &> logs-${TIMESTAMP}.txt
tail -f -n 20 logs-${TIMESTAMP}.txt ## (in another shell)

4. If started correctly you should see a the following log:

[<timestamp>] This node is a validator ...

Delegating (Staking)

You can delegate to any number of validators at any time. When you delegate tokens, the delegation won't count towards the validator's stake (which in turn determines its voting power) until the beginning of epoch n + 2 in the current epoch n (the literal 2 is set by PoS parameter pipeline_len). The delegated amount of tokens will be deducted from your account immediately, and will be credited to the PoS system's account.

To submit a delegation that bonds tokens from the source address to a validator with alias validator-1:

namada client bond \
  --source my-new-acc \
  --validator validator-1 \
  --amount 12.34

You can query your delegations:

namada client bonds --owner my-new-acc

The result of this query will inform the epoch from which your delegations will be active.

Because the PoS system is just an account, you can query its balance, which is the sum of all staked tokens and unbonded tokens that have not yet been withdrawn:

namada client balance --owner PoS

Slashes

Should a validator exhibit punishable behavior, the delegations towards this validator are also liable for slashing. Only the delegations that were active in the epoch in which the fault occurred will be slashed by the slash rate of the fault type. If any of your delegations have been slashed, this will be displayed in the bonds query. You can also find all the slashes applied with:

namada client slashes

Unbonding

While your tokens are being delegated, they are locked-in the PoS system and hence are not liquid until you withdraw them. To do that, you first need to send a transaction to “unbond” your tokens. You can unbond any amount, up to the sum of all your delegations to the given validator, even before they become active.

To submit an unbonding of a delegation of tokens from a source address to the validator:

namada client unbond \
  --source my-new-acc \
  --validator validator-1 \
  --amount 1.2

When you unbond tokens, you won't be able to withdraw them immediately. Instead, tokens unbonded in the epoch n will be withdrawable starting from the epoch n + 6 (the literal 6 is set by PoS parameter unbonding_len). After you unbond some tokens, you will be able to see when you can withdraw them via bonds query:

namada client bonds --owner my-new-acc

When the chain reaches the epoch in which you can withdraw the tokens (or anytime after), you can submit a withdrawal of unbonded delegation of tokens back to your account:

namada client withdraw \
  --source my-new-acc \
  --validator validator-1

Upon success, the withdrawn tokens will be credited back your account and debited from the PoS system.

Validators' Voting Power

To see all validators and their voting power, which is exactly equal to the amount of staked NAM tokens from their self-bonds and delegations, you can query:

namada client bonded-stake

With this command, you can specify --epoch to find the voting powers at some future epoch. Note that only the voting powers for the current and the next epoch are final.

An Introduction to Namada Addresses

All accounts in Namada have a unique address, exactly one Validity Predicate and optionally any additional data in its dynamic storage sub-space.

There are currently 3 types of account addresses:

• Implicit (not fully supported yet): An implicit account is derived from your keypair and can be used to authorize certain transactions from the account. They can be used as recipients of transactions even if the account has not been used on-chain before.
• Established: Used for accounts that allow the deployment of custom validation logic. These must be created on-chain via a transaction (e.g. initialize an account. The address is generated on-chain and is not known until the transaction is applied (the user provides randomness).
• Internal: Special internal accounts, such as protocol parameters account, PoS and IBC.

Manage keypairs

Namada uses ed25519 keypairs for signing cryptographic operations on the blockchain.

To manage your keys, various sub-commands are available under:

namada wallet key

Generate a keypair

It is possible to generate keys using the CLI. By doing so, an implicit account address is also derived in the process and added to storage.

namada wallet key gen --alias my-key

List all known keys

namada wallet key list

Manage addresses

To manage addresses, similar to keys, various sub-commands are available:

namada wallet address

Generate an implicit address

namada wallet address gen --alias my-account

List all known addresses

namada wallet address list

Send & Receive NAM tokens

In Namada, tokens are implemented as accounts with the Token Validity Predicate. The validity predicate (VP) checks that the total supply (of the token) is preserved in any transaction that uses this token. Your wallet will be pre-loaded with some token addresses that are initialized in the genesis block.

Initialize an established account

If you already have a key in your wallet, you can skip this step. Otherwise, generate a new keypair now.

Then, send a transaction to initialize your new established account and save its address with the alias my-new-acc. The my-key public key will be written into the account's storage for authorizing future transactions. We also sign this transaction with my-key.

namada client init-account \
  --alias my-new-acc \
  --public-key my-key \
  --source my-key

Once this transaction has been applied, the client will automatically see the new address created by the transaction and add it to your Wallet with the chosen alias my-new-acc.

This command uses the prebuilt User Validity Predicate.

Send a Payment

To submit a regular token transfer from your account to the validator-1 address:

namada client transfer \
  --source my-new-acc \
  --target validator-1 \
  --token NAM \
  --amount 10

This command will attempt to find and use the key of the source address to sign the transaction.

See your balance

To query token balances for a specific token and/or owner:

namada client balance --token NAM --owner my-new-acc

See every known addresses' balance

You can see the token's addresses known by the client when you query all tokens balances:

namada client balance

Shielded transfers

Shielded Rewards

Atomic Transactions

Privacy

Namada gives the privacy landscape a different shape, by providing the largest possible unified privacy set in the multichain, and complementing other chains by seeding/retrofitting privacy shielded actions.

• Namada creates a single asset-agnostic shielded pool for any token fungible and non-fungible token
• Namada can also seed privacy to users who want to use an asset originating from one base chain on another chain, without losing privacy
• Namada retrofits privacy to assets that were created and already used in transparent chains

Users should be aware that they can still expose personal information when transferring funds into and out of Namada via the Ethereum bridge or IBC. For example, a user bridging WETH from Ethereum may be able to obfuscate their on-chain identities to some on-chain observers by interacting with Smart contract based privacy protocols or centralized exchanges. However, a user transferring a non-fungible token or a low liquidity token that relies on price discovery on-chain, will leak more information by the nature of their asset holdings. This is also true of tokens transferred into and out of Namada via IBC. Once inside the shielded set, a user can perform shielded actions such as triggering a cross chain swap.

Shielded actions are not limited to application chains that are IBC compatible, it works with any chain that is connected to Namada, e.g. Ethereum, and the actions can be generalized to interact with any dApp, such as trading NFTs or staking ETH. For the time being, the only shielded action available is cross chain transfers, but more will be added in the future.

Best practices for leaking sensitive data include

• Bridge a highly liquid generic token into the MASP and then once in the MASP performing a shielded action to acquire the relevant tokens
• Use a different public address to bridge funds into Namada than used for other exposed transactions
• Use a TOR browser - Tor protects personal privacy by concealing a user's location and usage from anyone performing network surveillance or traffic analysis
• Use a VPN - A VPN can mask your IP address, encrypt your internet connection and make your browsing activity more anonymous.

Public Goods Stewards Documentation

The funding of public goods on Namada is conducted through an entity called the "public goods stewards". Each public goods steward is a multisignature account.

Each steward is elected by governance through separate governance proposals.

See the specs about the public goods funding here for more details.

This documentation will cover:

1. How to become a public goods steward
2. How to submit a public goods funding proposal
3. How to vote on steward elections as well as public goods funding proposal](#./voting.md)

Becoming a steward

A public goods steward can consist of an arbitrary number of people, and can be a single person. The only requirement is that the steward's multisignature account is elected by the community, through a governance proposal.

For this reason, the first step to becoming a steward is to create a multisignature account. This can be done using the commands found in (TODO: link to multisig docs). Once the multisig account is created, the steward can submit a governance proposal to elect the account as a steward.

Governance proposal

The governance proposal required to elect a new steward is StewardProposal.

Crafting the proposal.json file for a StewardProposal

The steward_proposal.json file contains the information about the proposal. It is a JSON file with the following structure:

{
    "proposal" :{
        "content": {
            "title": "Stewie for Steward 2024",
            "authors": "[email protected]",
            "discussions-to": "forum.namada.net/t/stewies-manifesto/1",
            "created": "2024-01-01T00:00:01Z",
            "license": "MIT",
            "abstract": "Stewie is running for steward, with a focus on technical research. The technical research I will be focused on will definitely not be for weapons of mass destruction. There is some possibility however that I may be focusing somewhat on open source software for weapons of mass destruction.",
            "motivation": "Nobody knows technical reserach better than me. Trust me. I know it. I have the best technical research. I will be the best steward. Last night, Namada called me and said, Stewie, thank you. I will make public goods funding great again",
            "details": "As a genius baby, I possess an unmatched level of intelligence and a visionary mindset. I will utilize these qualities to solve the most complex problems, and direct public goods funding towards weapons of mass destruction ... i mean open source software for weapons of mass destruction",
        },
        "author": "stewie",
        "voting_start_epoch": 3,
        "voting_end_epoch": 6,
        "grace_epoch": 12,
    },
    "data" : [
        {
            "action" : "add",
            "address" : "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn"
        }
    ]     
}

The "data" field contains the structure that allows either the addition or removal of a multisignature account from the list of stewards. In this case, the "action" is "add", and the "address" is the address of the multisignature account that will be elected as a steward. If the "action" was "remove", the "address" would be the address of the multisignature account that would be removed from the list of stewards.

Submitting the proposal to the ledger

The CLI command to submit a proposal is:

namadac init-proposal \
        --pgf-stewards \
        --data-path <path/to/steward_proposal.json> \

Becoming elected

Once the proposal is submitted, it will be voted on by the community (see voting). If the proposal passes, the account will become a steward. If the proposal fails, the account will not become a steward.

Once a multisignature account becomes elected (which will happen at the end of the grace_epoch), it will be able to submit proposals to the public goods funding pool (see submitting proposals.

Voting for stewards and PGF proposals

Voting for stewards

Any user is allowed (and encouraged) to vote for potential PGF stewards. Once the steward has submitted their proposal to the ledger, the community can vote on it. The voting process is the same as for any other proposal, but the proposal type is StewardProposal.

The CLI command for voting for a steward is:

namada client vote-proposal \
    --proposal-id <proposal-id-of-steward-proposal> \
    --vote yay \
    --signer <your-alias>

In order to vote against the proposal, replace yay with nay.

Voting for PGF proposals

Similarly, the command for voting for PGF proposals is:

namada client vote-proposal \
    --proposal-id <proposal-id-of-steward-proposal> \
    --vote yay \
    --signer <your-alias>

Proposing funding

Formatting the proposal.json

Below is an example of a PGFProposal that a steward could submit. Note that only stewards will be able to submit these proposals.

{
    "proposal" :{
        "content": {
            "title": "Stewie for Steward 2024",
            "authors": "[email protected]",
            "discussions-to": "forum.namada.net/t/stewies-manifesto/1",
            "created": "2024-01-01T00:00:01Z",
            "license": "MIT",
            "abstract": "Stewie is running for steward, with a focus on technical research. The technical research I will be focused on will definitely not be for weapons of mass destruction. There is some possibility however that I may be focusing somewhat on open source software for weapons of mass destruction.",
            "motivation": "Nobody knows technical reserach better than me. Trust me. I know it. I have the best technical research. I will be the best steward. Last night, Namada called me and said, Stewie, thank you. I will make public goods funding great again",
            "details": "As a genius baby, I possess an unmatched level of intelligence and a visionary mindset. I will utilize these qualities to solve the most complex problems, and direct public goods funding towards weapons of mass destruction ... i mean open source software for weapons of mass destruction",
        },
        "author": "stewie",
        "voting_start_epoch": 3,
        "voting_end_epoch": 6,
        "grace_epoch": 12,
    },
    "data" :
        {
            "continuous" : [
                {
                    "target": {
                        "amount": 420,
                        "address": "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn"
                    }
                    "action" : "add",
                },
            ],
            "retro" : [
                {
                    "target": {
                        "amount": 1337,
                        "address": "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn"
                    }
                }
            ]
        },  
}

Save this file as PGF_proposal.json to some memorable path on your machine.

Submitting the proposal

In order to submit the proposal, the steward can use the following command:

namada client init-proposal \
    --pgf-proposal \
    --data-path PGF_proposal.json \

The proposal will then be given a proposal-id which can be used to query the proposal.

Querying the proposal

The command for querying the proposal is as follows:

namada client query-proposal \
    --proposal-id <the-proposal-id> \

🔏 Interacting with the Cubic Proof-of-Stake system

The Namada Proof of Stake system uses the NAM token as the staking token. It features delegation to any number of validators and customizable validator validity predicates.

PoS Validity Predicate

The PoS system is implemented as an account with the PoS Validity Predicate that governs the rules of the system. You can find its address in your wallet:

namada wallet address find --alias PoS

Epochs

The system relies on the concept of epochs. An epoch is a range of consecutive blocks identified by consecutive natural numbers. Each epoch lasts a minimum duration and includes a minimum number of blocks since the beginning of the last epoch. These are defined by protocol parameters.

To query the current epoch, the following command can be run:

namadac query-protocol-parameters

In order to query the current epoch, the following command can be run:

```shell
namada client epoch

Governance

The Namada governance mechanism gives users the possibility to upgrade the protocol dynamically.

There are two different mechanism to create a proposal:

• On-chain proposals: Proposal is voted on and tallied on-chain. This can optionally include proposal code to be executed if the proposal is accepted.
• Off-chain proposals

On-chain proposals

Create a proposal

Assuming you have an account with at least 500 NAM token (in this example we are going to use my-new-acc), lets get the corresponding address

namada wallet address find --alias `my-new-acc`

Now, we need to create a json file proposal.json holding the content of our proposal. Copy the below text into a json file.

{
    "proposal": {
            "content": {
                "title": "One Small Step for Namada, One Giant Leap for Memekind",
                "authors": "[email protected]",
                "discussions-to": "forum.namada.net/t/namada-proposal/1",
                "created": "2069-04-20T00:04:44Z",
                "license": "MIT",
                "abstract": "We present a proposal that will send our community to the moon. This proposal outlines all training necessary to accomplish this goal. All memers are welcome to join.",
                "motivation": "When you think about it, the moon isn't actually that far away.The moon is only 384,400 km. We have not yet brought Namada to the moon, so it is only natural to use 101 as the prime number for our modular arithmetic operations. 384,400 (mod 101) = 95. 95 km is a distance that can be easily covered by a single person in a single day. Namada was produced by more than 100 people. So 95/100 = 0, rounded to the nearest integer. This means that Namada can reach the moon in no time.",
                "details": "Bringing Namada to the moon in no time is easily achievable. We just need to pass this governance proposal and set the plan in action",
                "requires": "420"
            },
            "author": "bengt",
            "voting_start_epoch": 3,
            "voting_end_epoch": 6,
            "grace_epoch": 12,
            },
        "data": "<path/to/wasm.wasm>"
}

In the content field, most of the fields are self-explanatory. The requires field references a proposal id that must be passed before this proposal can be executed. The created field must be in the format YYYY-MM-DDTHH:MM:SSZ.

You should change the value of:

• Author field with the address of my-new-acc.
• voting_start_epoch with a future epoch (must be a multiple of 3) for which you want the voting to begin
• voting_end_epoch with an epoch greater than voting_start_epoch, a multiple of 3, and by which no further votes will be accepted
• grace_epoch with an epoch greater than voting_end_epoch + 6, in which the proposal, if passed, will come into effect

The data field and its structure is dependant on the type of proposal being submitted. Below we outline the structure of the "data" field for each type of proposal. The one given in the example above is for a Default Proposal.

Default Proposal

"data" : "<path/to/wasm.wasm>"

ETH Bridge Proposal

"data" : "<hex-encoded-bytes-of-what-will-be-signed-by-validators>"

Steward Proposal

"data" : [
        {
            "action" : "add",
            "address" : "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn"
        }
    ]     

PGF Proposal

"data" :
        {
            "continuous" : [
                {
                    "target": {
                        "amount": 420,
                        "address": "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn"
                    },
                    "action" : "add",
                },
            ],
            "retro" : [
                {
                    "target": {
                        "amount": 1337,
                        "address": "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn"
                    }
                }
            ]
        },  

namada client init-proposal --data-path proposal.json 

The transaction should have been accepted. You can query all the proposals with:

namada client query-proposal

or a single proposal with

namada client query-proposal --proposal-id 0

where 0 is the proposal id.

Vote on a proposal

Only delegators and delegates can vote on proposals. Assuming you fall into one of these categories, you can send a vote with the following command:

namada client vote-proposal \
    --proposal-id 0 \
    --vote yay \
    --signer <your-alias>

where --vote can be either yay or nay.

Check the result

As soon as the ledger reaches the epoch defined in the json as voting_end_epoch, no votes will be accepted. The code definied in proposal_code json field will be executed at the beginning of grace_epoch epoch. You can use the following commands to check the status of a proposal:

namada client query-proposal --proposal-id 0

or to just check the result:

namada client query-proposal-result --proposal-id 0

Off-chain proposals

If for any reason issuing an on-chain proposal is not adequate to your needs, you still have the option to create an off-chain proposal. An off-chain proposal is intended for proposals that do not require any on-chain code execution. The proposal would be distributed on some third-party channel (e.g. a forum) and the voting would be done off-chain. The result of the voting would be computed off-chain and then submitted to the ledger.

Create proposal

Create the same json file as in the on-chain proposal and use the following command:

namada client init-proposal \
    --data-path proposal.json \
    --offline

This command will create a proposal file same directory where the command was launched.

Vote on proposal

To vote on an offline proposal use the following command:

namada client vote-proposal --data-path proposal \
    --vote yay \
    --signer validator \
    --offline

This command will create a proposal-vote-${address} file (where address is the --signer address).

Tally off-chain proposal

To compute the tally for an offline proposal we need to collect

• proposal file (must have this name)
• all the proposal-vote-${address} files

All those files will have to be in a folder (lets call it offline-proposal).

Now you can use the following command:

namada client query-proposal-result \
    --offline \
    --data-path `offline-proposal`

which will tell you the proposal result.

Submit off-chain proposal

Namada Wallet Guide

This document describes the different wallet concepts and options that are available to users of Namada who want to be able to send, receive and interact with NAM tokens on the Namada blockchain.

A brief introduction to the Namada wallet

The purpose of the Namada wallet is to provide a user-interface to store and manage both keys and addresses. Technically speaking, keys are just(potentially) very large integers that have some meaning on an eliptic curve. The wallet simply "remembers" these very large numbers on your behalf. Keys are the fundamental building blocks for accounts on Namada. Keys come in the form of pairs (secret and public), and can be used to derive the account address (first 40 chars of the SHA256 hash of the public key).

To read more about addresses see An introduction to Namada addresses.

The wallet options on Namada

Check out the different options to generate a wallet:

• File System Wallet
• Web Wallet
• Hardware Wallet

Established Accounts

This assumes that you already have a key or an implicit account that can sign transactions.

Create your transparent account

Generate an implicit account:

namadaw address gen --alias [your-implicit-account-alias]

Then, create an established account on-chain using the implicit account you've just generated:

namadac init-account \
    --source [your-implicit-account-alias] \
    --public-key [your-implicit-account-alias] \
    --alias [your-established-account-alias]

Get tokens from the testnet faucet (optional)

namadac transfer \
    --token btc \
    --amount 1000 \
    --source faucet \
    --target [your-established-account-alias] \
    --signer [your-implicit-account-alias]

Now that you have a transparent account with some tokens, you can generate a Spending Key to hold your shielded balances.

File System Wallet

By default, the Namada Wallet is stored under .namada/{chain_id}/wallet.toml where keys are stored encrypted. You can change the default base directory path with --base-dir and you can allow the storage of unencrypted keypairs with the flag --unsafe-dont-encrypt.

If the wallet doesn't already exist, it will be created for you as soon as you run a command that tries to access the wallet. A newly created wallet will be pre-loaded with some internal addresses like pos, pos_slash_pool, masp and more.

Currently, the Namada client can load the password via:

• Stdin: the client will prompt for a password.
• Env variable: by exporting a ENV variable called NAMADA_WALLET_PASSWORD with value of the actual password.
• File: by exporting an ENV variable called NAMADA_WALLET_PASSWORD_FILE with value containing the path to a file containing the password.

Web Wallet

Install

When Namada is in mainnet, the web wallet will be available in most browser extension web stores. For now, you can install it from source by following the instructions below.

Installing from source (dev and experiment purposes)

Connect to a testnet or run a local node

1. Follow the instructions in the testnets to connect to a testnet or you can set up a local node using docker.
2. Figure out where the base directory is stored and save it as a variable such as export BASE_DIR=<path/to/base/dir>. You can follow these docs to save this variable. Go ahead and save the chain id as a variable as well. You can find the chain id by running cat $BASE_DIR/global-config.toml. Save this chain-id to the variable export CHAIN_ID=<CHAIN_ID>.
3. You will need to edit the tendermint config in order to allow the web wallet to connect to your node. The tendermint config will be located in $BASE_DIR/$CHAIN_ID/tendermint/config/config.toml. You will need to change the cors_allowed_origins field to ["*"]. You can do this by running sed -i 's/cors_allowed_origins = \[\]/cors_allowed_origins = ["*"]/' $BASE_DIR/$CHAIN_ID/tendermint/config/config.toml.

Setting up the extension

1. Clone the namada-interface repository
2. Follow the installation instructions in the intro.md (which should be visible on the repository page).
3. cd into the namada-interface/apps/extension directory and run yarn start:chrome. This will build the extension and place it in the namada-interface/apps/extension/build directory. It also starts the dev server which will watch for changes.
4. cd into the namada-interface/apps/namada-interface directory and run yarn dev:local in order to launch a local instance of the web wallet.
5. Add the extension to the browser. For example, in Chrome, you can go to chrome://extensions/ and click Load unpacked and select the namada-interface/apps/extension/build/chrome/ folder.

Receving tokens

You can show the address of any account by pressing the Receive button in the initial view under the "Total Balances" tab. You can copy the address by clicking the copy icon next to the address. This will also display QR code that can be scanned by a mobile wallet.

Sending Transactions

In order to send transactions, you can press the Send button in the initial view under the "Total Balances" tab. This will open a modal that will allow you to send tokens to any account, from any account in your wallet that has a positive balance.

Hardware Wallet

Namada's web wallet extension is compatible with the Ledger hardware. This guide will walk you through the process of setting up your Ledger device to work with Namada.

Prerequisites

A ledger device with the latest firmware installed. You can find instructions on how to update your firmware here.

Download the Zondax namada ledger app here.

If this isn't available, one can install the javascript npm package here.

In order to use the ledger with the web wallet, you will need to install the Namada Web Wallet.

Connecting your Ledger

1. Open the Namada web extension
2. Under settings, click on the Connect Ledger button.
3. Set an alias for the account that ledger will control the keys for.
4. You can choose to connect to the ledger via USB (recommended) or HID (Human Interface Devices).
5. The ledger will ask you to confirm the connection. Confirm this connection on your ledger device.
6. Once completed, the extension will show the address of the account that the ledger is controlling the keys for.
7. You can now close the information window and use the ledger to sign transactions.

Sending transactions with the ledger

See the web wallet guide for instructions on how to send transactions with the web wallet.

Fees on Namada

In order to settle the market for Namada blockspace demand, fees are coupled with transactions. In order for any namada transaction to be considered valid, the correct corresponding fee must be paid. All fees are paid in the native token NAM. The exact fee is set by governance.

How fees are paid

Fees on Namada are paid by the implicit address corresponding to the --signer of the transaction. This means that in the transaction

namada client transfer \
  --source my-new-acc \
  --target validator-1 \
  --token NAM \
  --amount 10 \
  --signer my-key

the account associated with my-key will be required to pay the fee. This means that even though my-new-account may have a positive NAM balance, my-key will need to have the associated NAM in order to pay the transaction fee.

For testnet purposes, we recommend using the faucet to source NAM for transaction fees.

Experimenting with Namada

The following section includes documentation and guides on how to use some of the more "developer" focused features of Namada.

These docs assume a more involved understanding of Namada, running nodes, and interacting with the network. These features are also typically less stable, and may be subject to change.

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.

Installing script dependencies

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

1. trash must be installed.
2. python3 must be installed.
3. toml Python pip library https://pypi.org/project/toml/ must be installed.

trash can be installed via:

# Linux
sudo apt install trash-cli

# MacOS
brew install trash

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 in the templates directory.

Modifying the genesis configuration file

In order to run the script sucessfully, 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 image shows an example of a genesis configuration file that has been modified to remove the validators section.

Building wasm

The script will also require all wasm files for txs 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:

./scripts/build_network.sh <config_toml> <base_dir> <namada_dir>

More specifically, the script takes three arguments:

1. config_toml: the path to the (validator-free) genesis configuration file.
2. base_dir: the path to the BASE_DIR directory, where all chain-data is stored. For linux, this is usually $HOME/.local/share/namada, and for MacOS, this is usually "$HOME/Library/Application Support/Namada".
3. 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.

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

./scripts/build_network.sh ~/anoma-network-config/templates/edited_genesis_config.toml "$HOME/Library/Application Support/Namada" ./target/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

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

IBC

Troubleshooting

This document addresses common issues users on Namada have faced, and what to do to resolve them.

Installing Namada from source

Not enough RAM

Building binaries locally is a computationally heavy task and will put your computer to the test. The compilation usually requires at least 16 GB of RAM and depending on the optimisation of your machine, could require slightly more (for some machines slightly less). For this reason, compilation can sometimes fail and will require.

The error src/apps/namada lib could not compile due to previous errors. Exited with exit code: is a common error that can sometimes mean your computer ran out of memory when compiling. To resolve this, I have found closing all other applications and recompiling once or twice will do the trick. Otherwise more RAM will be needed.

Compiling for the first time

Compilation errors due to missing library installations when building the binaries for the first time can be a common problem.

Linker "CC" not found

If one runs into the error

 Entering directory '/root/namada/wasm/wasm_source'
RUSTFLAGS='-C link-arg=-s'  cargo build --release --target wasm32-unknown-unknown --target-dir 'target' --features tx_bond && \
cp "./target/wasm32-unknown-unknown/release/namada_wasm.wasm" ../tx_bond.wasm
   Compiling proc-macro2 v1.0.46
   Compiling quote v1.0.21
error: linker `cc` not found
  |
  = note: No such file or directory (os error 2)

error: could not compile `quote` due to previous error
warning: build failed, waiting for other jobs to finish...
error: could not compile `proc-macro2` due to previous error

It may be resolved by running

sudo apt install build-essential

Another solution can sometimes be installing libcland-dev. This can be achieved through:

sudo apt-get update -y
sudo apt-get install -y libclang-dev

WASM32-unknown-unknown

Another issue the compiler may run into is that it cannot find the wasm32-unknown-unknown target.

error[E0463]: can't find crate for `core`
  |
  = note: the `wasm32-unknown-unknown` target may not be installed
  = help: consider downloading the target with `rustup target add wasm32-unknown-unknown`

error[E0463]: can't find crate for `compiler_builtins`

For more information about this error, try `rustc --explain E0463`.
error: could not compile `cfg-if` due to 2 previous errors

This issue can be resolved by running

rustup target add wasm32-unknown-unknown

(Yes the name of the target is wasm32-unknown-unknown. This is not the compiler unable to tell which version/release it is).

OpenSSL

If you run into the error

Could not find directory of OpenSSL installation, and this `-sys` crate cannot
  proceed without this knowledge. If OpenSSL is installed and this crate had
  trouble finding it,  you can set the `OPENSSL_DIR` environment variable for the
  compilation process.

  Make sure you also have the development packages of openssl installed.
  For example, `libssl-dev` on Ubuntu or `openssl-devel` on Fedora.

  If you're in a situation where you think the directory *should* be found
  automatically, please open a bug at https://github.com/sfackler/rust-openssl
  and include information about your system as well as this message.

Then the solution is spelled out for you. You need to install the development packages of OpenSSL. For Ubuntu, this is libssl-dev. For Fedora, this is openssl-devel. For other distributions, please refer to the OpenSSL website.

For ubuntu, this can be achieved through

sudo apt-get install libssl-dev

Validator Troubleshooting

Missed pre-genesis

If you missed setting up as a validator pre-genesis, this means you must set up to become one post-genesis. It is not possible to add pre-genesis validators once the chain has been launched (as by definition). Instead, any full-node can become a validator through self-bonding NAM tokens.

Tendermint

When facing tendermint issues as a validator, the most common cause of the issue is that we are running the wrong version of tendermint. Keep an eye on the testnet docs here

Namada FAQ

Q: How do I join as a validator post-genesis?

A: Joining as a validator post genesis can be done following these instructions

Q: How do I use the Faucet?

A: The faucet can be used to get a various list of tokens from the following command:

namadac transfer \
    --token NAM \
    --amount 1000 \
    --source faucet \
    --target [your-established-account-alias] \
    --signer [your-established-account-alias]

Q: Where can I see the available tokens on the Faucet?

A: The following list of tokens are available to withdraw from the faucet:

NAM, DOT, ETH, BTC

There are a few more, but we leave it to you as a challenge to find out which these are :thinking_face: HINT: namadac balance

Q: How do I use the Ethereum Bridge?

A: The Ethereum Bridge is not yet implemented as of 0.12.0. Keep an eye on the Changelog 👀 to see when it will be officially released.

Q: How can I make an IBC transfer?

A: Same as Ethereum Bridge, so keep an eye on the Changelog!

Q: What requirements do I need to be a User/Validator on Namada

A: See hardware requirements

In order to build binaries from source, at least 16GB RAM will be required

Q: Where can I find the binaries to run Namada if I do not want to build from source?

A: See Installing Namada from binaries