# Namada Mainnet Pre-genesis Instructions

### Reference:
- [Namada mainnet pre-genesis plan](https://docs.fileverse.io/0x5C63F785eF3F328b5130025322066671A677A674/0#key=tKVuI8ROuPFvUFD7P6ZJTNsHVf5LxkdsabtErTVwS83x2chChhT7dc6XBJnGWmfF)
- [Starting a decentralized network (Namada docs)](https://docs.namada.net/networks/starting-network/genesis-flow/participants.html)

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](https://github.com/anoma/namada/releases/tag/v0.43.0)). **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](https://raw.githubusercontent.com/anoma/namada-genesis/main/balances.toml). 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](https://github.com/anoma/namada-genesis/commits/main/balances.toml). 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](#init-bond).

---

#### 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](#init-validator). *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](#init-bond).

---

#### 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
<div id="add-keys"></div>

### 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

<div id="init-validator"></div>

### Initialize a pre-genesis validator

1. [Add the keys](#add-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"]

3. 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 = "[e-mail]"

[[bond]]
source = "tnam1qyjjdxmdgnr6r68d6zsacevv27cxy3np8qv8zm2z"
validator = "tnam1qyjjdxmdgnr6r68d6zsacevv27cxy3np8qv8zm2z"
amount = "1"

4. 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.

5. 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.

6. 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).

<div id="init-bond"></div>

### 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](https://github.com/anoma/namada-genesis/commits/main/balances.toml). 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](#add-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"

3. 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.

4. 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](https://github.com/anoma/namada-mainnet-genesis) and put your toml files in the `/transactions` directory.
6. Submit your toml's by making a PR to the [genesis repo](https://github.com/anoma/namada-mainnet-genesis). 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](https://github.com/anoma/namada-mainnet-genesis/blob/main/images/validators.png) 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:
- https://docs.namada.net/users/wallet/hardware-wallet
- https://docs.namada.net/networks/starting-network/genesis-flow/participants#using-a-ledger-hardware-wallet