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:
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:
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
During internal and private testnets, checkout the latest testnet branch using git checkout $NAMADA_TESTNET_BRANCH
.
Install From Binaries
Prebuilt binaries might not be available for a specific release or architecture, in this case you have to build from source.
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 Namadanamadan
: The ledger nodenamadac
: The clientnamadaw
: 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.
Adding binaries to path
The binaries should be added to $PATH
from the make install
command. However, if this for some reason did not work, a solution may be to copy the binaries from namada/target/release
to home/$USER/.local/bin/
for example:
sudo cp namada/target/release/namada* /home/alice/.local/bin/
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
In a linux based terminal, one can use the following command in order to copy the tendermint
binaries to $PATH
sudo cp ./build/tendermint $HOME/go/bin/
`
Namada Testnets
For more context read:
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
- Environment setup
- Pre-genesis instructions 1. Pre-genesis validator setup 2. Pre-genesis validator apply
- Running your genesis validator
- Running a full node
- 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
on2023-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
- Namada protocol version:
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
If you don't want to build Namada from source you can install Namada from binaries
Export the following variables:
export NAMADA_TAG=v0.15.3
export TM_HASH=v0.1.4-abciplus
Installing Namada
-
Install all pre-requisites
-
Clone namada repository and checkout the correct versions
git clone https://github.com/anoma/namada && cd namada && git checkout $NAMADA_TAG
- 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
- 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
2. Copy both the namada and tendermint binaries to somewhere on $PATH (or use the relative paths). This step may or may not be necessary.- namada binaries can be found in
/target/release
- tendermint is in
build/tendermint
Check ports
- Open ports on your machine:
- 26656
- 26657
- 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 output0.1.4-abciplus
- Make sure you are using the correct Namada version
namada --version
should outputNamada 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)
With the release of v0.15.3
we have introduced a new base directory. This means that you will need to reset your validator node to use the new base directory. This is a one time operation.
The base directory has been moved from .namada
to .local/share/namada
on Linux and Library/Application Support/Namada
on MacOS.
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.
Technically, the correct directory will be the one assigned to $XDG_DATA_HOME
, but if you haven't set that variable, it will default to the above.
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
- Begin by stopping all instances of the namada node
killall namadan
- Build the new tag (or download the binaries here)
cd namada
export NAMADA_TAG=v0.13.4
make build-release
- Copy the new binaries to path. More in depth instructions can be found at here
- Once this has been completed, the node must tesync from genesis (see below)
How to resync from genesis:
- As a precautionary measure, make a backup of your pregenesis keys
mkdir backup-pregenesis && cp -r .namada/pre-genesis backup-pregenesis/
- 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
- 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
-
Download the binaries or install them from source
-
Ensure the versions are correct, such that
<PATH_TO_BINARY>/namada --version
isv0.13.1-hardfork
-
Interrupt the
namada ledger
by the interrupt command^C
-
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. -
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.
Note that this current fix will be not be included in Mainnet as it is circumstantial to testnet
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
- Wait for the genesis file to be ready, you will receive a
$CHAIN_ID
. - Join the network with the
CHAIN_ID
export CHAIN_ID="public-testnet-8.0.b92ef72b820"
namada client utils join-network --chain-id $CHAIN_ID
- 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:
If you have set the variable $XDG_DATA_HOME this is where the pre-genesis TOML will be written to. Otherwise see below for the default locations.
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
Node Type | RAM | SSD |
---|---|---|
Validator | 32 GB | 500GB-2TB* |
Full Node | 8GB DDR4 | 2TB |
Light Node | TBD | TBD |
*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:
If you have set the variable $XDG_DATA_HOME this is where the pre-genesis TOML will be written to. Otherwise see below for the default locations.
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
The derived implicit address shares the same my-key
alias. The previous command has the same effect as namada wallet address 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
Note that this will also generate and save a key from which the address was derived and save it under the same my-account
alias. Thus, this command has the same effect as namada wallet key 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
For any client command that submits a transaction (init-account
, transfer
, tx
, update
and PoS transactions), you can use the --dry-run
flag to simulate the transaction being applied in the block and see what would be the result.
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:
- How to become a public goods steward
- How to submit a public goods funding proposal
- 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.
In the motivation and abstract field, it is important to make clear what type of public goods funding the steward will be focusing on. The areas of public goods funding can be found in the public goods funding specs.
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 ofmy-new-acc
.voting_start_epoch
with a future epoch (must be a multiple of 3) for which you want the voting to beginvoting_end_epoch
with an epoch greater thanvoting_start_epoch
, a multiple of 3, and by which no further votes will be acceptedgrace_epoch
with an epoch greater thanvoting_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>"
The data field for default proposals is optional. This is in line with the nature of default proposals. If the proposals have code attached to them in order to change governance parameters, then this code will be represented as a wasm file and the path to this file will be given in the data field.
ETH Bridge Proposal
"data" : "<hex-encoded-bytes-of-what-will-be-signed-by-validators>"
Steward Proposal
"data" : [
{
"action" : "add",
"address" : "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn"
}
]
The data field for steward proposals is a list of actions to be taken. The actions can be either add
or remove
and the address is the address of the steward to be added or removed. In this way you can add or remove multiple stewards in a single proposal.
PGF Proposal
"data" :
{
"continuous" : [
{
"target": {
"amount": 420,
"address": "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn"
},
"action" : "add",
},
],
"retro" : [
{
"target": {
"amount": 1337,
"address": "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn"
}
}
]
},
The data field for PGF proposals contains both continuous and retroactive PGF funding actions. Within each action, the user can include multiple payments in the form of a vector. Within each payment, the target field contains the address of the recipient as well as the amount of NAM that they will receive. For continuous PGF funding, the amount specified will be sent at the end of each epoch. There is also the option to remove a recipient from the continuous PGF funding, by specifying an already existing continuous funding payment, and then also including the "remove" action. For retroactive PGF funding, the amount specified will be sent immediately.
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
The community may decide to post data of their off-chain voting to another censorship resistant blockchain to preserve the decision reached by social consensus.
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:
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)
The testnet tokens which the faucet can provide you have the aliases NAM
,
BTC
, ETH
, DOT
, Schnitzel
, Apfel
, and Kartoffel
. The faucet
will transfer these in increments of 1000 maximum at a time.
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
- Follow the instructions in the testnets to connect to a testnet or you can set up a local node using docker.
- 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 runningcat $BASE_DIR/global-config.toml
. Save this chain-id to the variableexport CHAIN_ID=<CHAIN_ID>
. - 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 thecors_allowed_origins
field to["*"]
. You can do this by runningsed -i 's/cors_allowed_origins = \[\]/cors_allowed_origins = ["*"]/' $BASE_DIR/$CHAIN_ID/tendermint/config/config.toml
.
Setting up the extension
- Clone the namada-interface repository
- Follow the installation instructions in the intro.md (which should be visible on the repository page).
cd
into thenamada-interface/apps/extension
directory and runyarn start:chrome
. This will build the extension and place it in thenamada-interface/apps/extension/build
directory. It also starts the dev server which will watch for changes.cd
into thenamada-interface/apps/namada-interface
directory and runyarn dev:local
in order to launch a local instance of the web wallet.- Add the extension to the browser. For example, in Chrome, you can go to
chrome://extensions/
and clickLoad unpacked
and select thenamada-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
- Open the Namada web extension
- Under settings, click on the
Connect Ledger
button. - Set an alias for the account that ledger will control the keys for.
- You can choose to connect to the ledger via
USB
(recommended) orHID
(Human Interface Devices). - The ledger will ask you to confirm the connection. Confirm this connection on your ledger device.
- Once completed, the extension will show the address of the account that the ledger is controlling the keys for.
- 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:
trash
must be installed.- python3 must be installed.
- 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:
config_toml
: the path to the (validator-free) genesis configuration file.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"
.namada_dir
: the path to the namada BINARIES directory. If the binaries were build usingmake build-release
this would imply thenamada/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
Note that the common debug statement Error reconnecting to peers
does not mean that your node is not working properly. Instead, it means there exists at least one validator on the network not working properly. To check whether this is a problem on your end, note the block height and see if it corresponds to the blockheight at https://namada.world
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