Namada Mainnet Pre-genesis Instructions

Reference:

There will be a decentralized pre-genesis process in preparation for mainnet. The purpose of this process will be to generate a genesis state for the chain, including the initial validator set and initial stake distribution. At the end of the process, a set of genesis files will be proposed. Should genesis validators comprising > 2/3 of voting power go ahead with launching the chain from the proposed genesis files, it will signal social consensus of approval of the initial state.

Overview:

  1. proposed balances.toml containing genesis account balances published by the Anoma Foundation
  2. potential genesis validators submit pre-genesis transactions initializing their validators to the pre-genesis repo. Token holders (optionally) submit pre-genesis transactions bonding to one or more potential genesis validators.
  3. after the submission deadline, submitted pre-genesis transactions are checked for validity. Valid transactions are then collated into a single transactions.toml file. (This defines the initial validator set/stake distribution).
  4. a proposed genesis state and chain-id are published to the repo.
  5. pending acceptance by 2/3 of voting power – network launch 🚀

Prerequisites

  1. Namada v0.43.0 binaries (link). Important: when running your node, make sure you have upgraded your CometBFT version to v0.37.9 instead of the v0.37.2 which was used with earlier Namada versions.
  2. Proposed balances.toml file from here. You will need this to see your genesis token allocation, so that you know how much you have available to bond. Note: the final version of the balances.toml file was published Sept 9, 2024. To make merging your PR as smooth as possible, please check that you're using the latest version.
  3. Your genesis account mnemonic or private key, to load into your wallet.

Pre-genesis process

Collecting pre-genesis transactions happens in two stages: Stage 1 (initialize-validator) and Stage 2 (bond).

Find the scenario below that describes your situation:

Scenario 1:

My address is in balances.toml. I don't intend to create a pre-genesis validator or a pre-genesis bond

No further action required. Once the chain has launched, you can import your key into your wallet from the mnemonic or private key and access your funds.

Scenario 2:

My address is in balances.toml. I don't intend to create a pre-genesis validator, but do want to make a pre-genesis bond

Summary:

  • Stage 1: do nothing.
  • Stage 2: Generate and submit a pre-genesis bond transaction as described here.

Scenario 3:

My address is in balances.toml and I will use it to initialize a validator

Summary:

  • Stage 1: Generate and submit a pre-genesis-init-validator transaction as described here. Note: do not self-bond, instead create a separate bond transaction in the next step.
  • Stage 2: Generate and submit a pre-genesis bond transaction as described here.

Scenario 4:

I want to initialize a validator from a new address

This is the same as Scenario 3, except you will be creating a new keypair to initialize your validator from instead of using an existing one.

Detailed Instructions

Add existing or new keys to your wallet

Before generating your pre-genesis transaction(s), you'll need to have your keys loaded into your wallet. You can either import existing keys (e.g. your shielded-expedition keys) or create a new pair.

Your pre-genesis wallet is located in ~/.local/share/namada/pre-genesis/wallet.toml by default.

To import an existing keypair:

# load from mnemonic
namadaw --pre-genesis derive --alias $ALIAS

# load from private key
namadaw --pre-genesis add --alias $ALIAS --value $RAW_PRIVATE_KEY

Or, to create a new keypair:
(Remember to save the mnemonic!)

namadaw --pre-genesis gen --alias $ALIAS

You can use this command to display your public key/address:

namadaw --pre-genesis find --alias $ALIAS

Initialize a pre-genesis validator

  1. Add the keys you will use to initialize your validator to your wallet as described above. You can either import existing keys (e.g. your shielded-expedition keys) or create a new pair.

  2. Next, generate an established account toml file, providing the alias of your keys:

namadac utils init-genesis-established-account \
  --path ~/.local/share/namada/pre-genesis/transactions.toml \
  --aliases $ALIAS

You will see a message similar to:

Derived established account address: tnam1qyjjdxmdgnr6r68d6zsacevv27cxy3np8qv8zm2z

You will have generated a file ~/.local/share/namada/pre-genesis/transactions.toml. Its contents should look similar to this:

# ~/.local/share/namada/pre-genesis/transactions.toml

[[established_account]]
vp = "vp_user"
threshold = 1
public_keys = ["tpknam1qp87s56pfekaukvs0ernayr7plt4a673sj9pfc7wuj26nsrw567jjfwcx2c"]
  1. Convert the established account to a validator account with the following command. The --path should point to the transactions.toml created in the previous step. The --address should be the established account address generated in the previous step (starts with tnam). The --self-bond-amount should be 1 (the value given here doesn't matter since we'll be removing it in the next step).
# discord-handle, avatar, website, description and name are all optional

namadac utils init-genesis-validator \
  --address $ESTABLISHED_ACCOUNT_ADDRESS \
  --alias $VALIDATOR_ALIAS \
  --net-address "$IP_ADDRESS:26656" \
  --commission-rate 0.05 \
  --max-commission-rate-change 0.01 \
  --self-bond-amount 0.1 \
  --email $EMAIL \
  --discord-handle $DISCORD_HANDLE \
  --avatar $AVATAR_URL \
  --website $WEBSITE \
  --description $DESCRIPTION \
  --name $ONCHAIN_MONIKER \
  --path $TX_FILE_PATH

A couple notes on the above:

  • email is mandatory but discord-handle, avatar, website, description and name are optional
  • alias refers to the alias in your local wallet, not your validator's name on-chain (that's set by name)
  • net-address is a mandatory argument for the command, but if you don't know your IP address yet you can use a placeholder like 1.2.3.4:26656
  • the two commission parameters and self-bond-amount are mandatory

Afterwards, you will see a message similar to:

The validator's keys were stored in the wallet at ~/.local/share/namada/pre-genesis/$ALIAS/validator-wallet.toml
Validator account address: tnam1qyjjdxmdgnr6r68d6zsacevv27cxy3np8qv8zm2z
Wrote genesis tx to: ~/.local/share/namada/pre-genesis/validator-transactions.toml

This will append the validator data to your transaction file ~/.local/share/namada/pre-genesis/transactions.toml. Its contents should now look similar to the following:

# ~/.local/share/namada/pre-genesis/transactions.toml

[[established_account]]
vp = "vp_user"
threshold = 1
public_keys = ["tpknam1qp87s56pfekaukvs0ernayr7plt4a673sj9pfc7wuj26nsrw567jjfwcx2c"]

[[validator_account]]
address = "tnam1qyjjdxmdgnr6r68d6zsacevv27cxy3np8qv8zm2z"
vp = "vp_user"
commission_rate = "0.05"
max_commission_rate_change = "0.01"
net_address = "192.168.0.1:26656"
consensus_key = "tpknam1qrfm0ref54e605l8zjt8dqe6nqzczzc4hnkjf5ujvxkar7f6ff7lvhc7y9y"
protocol_key = "tpknam1qz0dput2lcy8gwdggz5plfkyfyhhpp59vzac289myqnxqu26h4r6xwxz9vu"
tendermint_node_key = "tpknam1qzuyfa3t6nw2f0df7evj9kjpmng4a2uvzu8lqmr8vefl9g28j5zyz8ktw4k"
eth_hot_key = "tpknam1qyp3mc4f9nf75j66fg6e02a093salvj6e85n8wcatepf7rqsm6zdv0c9f026z"
eth_cold_key = "tpknam1qypcfn4tnm8qxpewg3cckv8r6xl6smacj92lm775tnsaf06yle7qjdct8ccys"

[validator_account.metadata]
email = "test@gmail.com"

[[bond]]
source = "tnam1qyjjdxmdgnr6r68d6zsacevv27cxy3np8qv8zm2z"
validator = "tnam1qyjjdxmdgnr6r68d6zsacevv27cxy3np8qv8zm2z"
amount = "1"
  1. We'll be creating the bond transacion separately, instead of using the self-bond option. (We had to supply a value for self-bond as a workaround, since the command will not accept a 0 value.) Open the transactions.toml file and remove this section:
[[bond]]
source = "tnam1qyjjdxmdgnr6r68d6zsacevv27cxy3np8qv8zm2z"
validator = "tnam1qyjjdxmdgnr6r68d6zsacevv27cxy3np8qv8zm2z"
amount = "1"

and then save the file.

  1. Before submitting our transaction toml file, we need to sign it. Use this command:
namadac utils sign-genesis-txs \
  --path ~/.local/share/namada/pre-genesis/transactions.toml \
  --output ~/.local/share/namada/pre-genesis/transactions-signed.toml \
  --alias $VALIDATOR_ALIAS

This will generate a (final) signed toml file named transactions-signed.toml. This is the file we will be submitting.

  1. Rename your file to {your github username}-validator.toml and follow the steps in the section Submit a PR with your toml files below when submitting your toml file(s).

Create a pre-genesis bond

Notes:

  • You can generate your bond tx locally at any time, but please wait until Stage 2 before submitting it.
  • Be careful not to overwrite the transactions-signed.toml you generated for your validator, if using the same filenames. Make a backup copy before proceeding.
  • Note: the final version of the balances.toml file was published Sept 9, 2024. To make merging your PR as smooth as possible, please check that you're using the latest version.

To create a bond, your address must have a genesis balance allocated to it in the balances.toml file.

  1. Load your existing keys with genesis balance into your pre-genesis wallet from the mnemonic or private key.

  2. Generate a bond transaction. The --amount must be less than your allocation in balances.toml (and save at least a few NAM unbonded for gas costs).

namadac utils genesis-bond \
  --validator $TARGET_VALIDATOR \
  --amount $AMOUNT \
  --source $YOUR_PUB_KEY \
  --path ~/.local/share/namada/pre-genesis/transactions.toml

This will generate a transactions.toml file with contents similar to the following:

[[bond]]
source = "tpknam1qp87s56pfekaukvs0ernayr7plt4a673sj9pfc7wuj26nsrw567jjfwcx2c"
validator = "tnam1qyjjdxmdgnr6r68d6zsacevv27cxy3np8qv8zm2z"
amount = "1000"
  1. Before submitting our transaction toml file, we need to sign it. Use this command:
namadac utils sign-genesis-txs \
  --path ~/.local/share/namada/pre-genesis/transactions.toml \
  --output ~/.local/share/namada/pre-genesis/transactions-signed.toml

This will generate a (final) signed toml file named transactions-signed.toml. This is the file we will be submitting.

  1. Follow the steps in the section Submit a PR with your toml files below when submitting your toml file(s).

Submit a PR with your toml files

Please adhere to the following conventions when submitting your toml file(s). The CI scripts which check the validity of submissions expects them to be in a specific format; otherwise your PR may be rejected.

  1. Rename your init-validator transaction toml to {your github username}-validator.toml.
  2. Rename your bond transaction toml to {your github username}-bond.toml.
  3. Note: the github username in the filenames must match exactly the github account you submit the PR from.
  4. Note: if you're initializing a pre-genesis validator, you should have two toml files – one 'validator' toml and one 'bond' toml. You can submit both in a single PR. Edit: Please submit only the 'validator' toml in stage 1, and wait until stage 2 to submit the 'bond' toml.
  5. When you're ready, fork the genesis repo and put your toml files in the /transactions directory.
  6. Submit your toml's by making a PR to the genesis repo. You should name your PR Add {your github username} pre-genesis transactions.
  7. If you're submitting a validator transaction: at the top of the PR description, include your Discord handle. This way, we can assign you the mainnet-validator role in the Namada server (if your PR is accepted).
  8. If your toml's are valid and your PR passes all CI checks, it will be merged. If there's an issue with your PR, you may be requested to make some changes – so keep an eye on its status in case any action is needed from you.

Pre-genesis stake distribution chart

As PRs for pre-genesis init-validator and bond txs are merged, the CI scripts will update the chart in the genesis repo with the current stake distribution. This can be helpful when deciding who to stake your tokens with.

Using a Ledger Hardware Wallet

You can sign your init-validator and bond transactions using a Ledger.

Important
The app on the official Ledger app store is not current and will not work. You must sideload the in-development version 0.0.27 or newer. You need a Ledger Nano or Nano S device.

For instructions on how to sideload the app, and how to use it to sign your pre-genesis transactions, see:

Select a repo