diff --git a/packages/docs/pages/networks.mdx b/packages/docs/pages/networks.mdx index 9c2210ce..195639e5 100644 --- a/packages/docs/pages/networks.mdx +++ b/packages/docs/pages/networks.mdx @@ -1,10 +1,8 @@ # Namada Networks -This page is for Namada networks. - -There are two network types: +This section contains information about the current public Namada networks (mainnet and testnet) as well as instructions for creating a new decentralized network or local devnet. * [Mainnets](./networks/mainnets.mdx) - the main networks * [Testnets](./networks/testnets.mdx) - the test networks - -The mainnet chain-ids are prefixed with `main` and the testnet chain-ids are prefixed with `test`. +* [Setting up a local network](./networks/starting-network/local-network.mdx) - how to set up a local network (useful for development and testing) +* [Setting up a decentralized network](./networks/starting-network/genesis-flow.mdx) - how to launch a decentralized network involving multiple participants diff --git a/packages/docs/pages/networks/_meta.json b/packages/docs/pages/networks/_meta.json new file mode 100644 index 00000000..9f12969a --- /dev/null +++ b/packages/docs/pages/networks/_meta.json @@ -0,0 +1,5 @@ +{ + "mainnets": "Mainnets", + "testnets": "Testnets", + "starting-network": "Starting a network" +} \ No newline at end of file diff --git a/packages/docs/pages/operators/networks.mdx b/packages/docs/pages/networks/starting-network.mdx similarity index 100% rename from packages/docs/pages/operators/networks.mdx rename to packages/docs/pages/networks/starting-network.mdx diff --git a/packages/docs/pages/operators/networks/_meta.json b/packages/docs/pages/networks/starting-network/_meta.json similarity index 100% rename from packages/docs/pages/operators/networks/_meta.json rename to packages/docs/pages/networks/starting-network/_meta.json diff --git a/packages/docs/pages/networks/starting-network/genesis-flow.mdx b/packages/docs/pages/networks/starting-network/genesis-flow.mdx new file mode 100644 index 00000000..33dc3a3e --- /dev/null +++ b/packages/docs/pages/networks/starting-network/genesis-flow.mdx @@ -0,0 +1,12 @@ +# Setting up a decentralized Namada network + +Setting up a decentralized Namada network requires coordination between two distinct parties: + +1. [The network coordinator](./genesis-flow/coordinator.mdx#the-network-coordinator) +2. [The pre-genesis participants](./genesis-flow/participants.mdx#pre-genesis-network-participants) + +This process is also called the **genesis ceremony** or the **pre-genesis process**. + +The purpose of this process is to establish the initial (genesis) state of the network -- including initial account balances, an initial validator set and an initial stake distribution -- through social consensus. +This is done by generating *pre-genesis transactions* that define established accounts, validator accounts, and bonds. See the [pre-genesis participants](./genesis-flow/participants.mdx#pre-genesis-network-participants) +section for more details on generating pre-genesis transactions. diff --git a/packages/docs/pages/operators/networks/genesis-flow/_meta.json b/packages/docs/pages/networks/starting-network/genesis-flow/_meta.json similarity index 100% rename from packages/docs/pages/operators/networks/genesis-flow/_meta.json rename to packages/docs/pages/networks/starting-network/genesis-flow/_meta.json diff --git a/packages/docs/pages/operators/networks/genesis-flow/coordinator.mdx b/packages/docs/pages/networks/starting-network/genesis-flow/coordinator.mdx similarity index 54% rename from packages/docs/pages/operators/networks/genesis-flow/coordinator.mdx rename to packages/docs/pages/networks/starting-network/genesis-flow/coordinator.mdx index d66ff767..2b7ae942 100644 --- a/packages/docs/pages/operators/networks/genesis-flow/coordinator.mdx +++ b/packages/docs/pages/networks/starting-network/genesis-flow/coordinator.mdx @@ -4,11 +4,11 @@ import { Steps } from 'nextra-theme-docs' The network coordinator is responsible for: - 0. [Setup](#setup) - 1. [Collecting pre-genesis public keys](#collecting-pre-genesis-public-keys) - 2. [Allocating pre-genesis NAM balances](#allocating-pre-genesis-nam-balances) - 3. [Collecting pre-genesis transactions](#collecting-pre-genesis-transactions) - 4. [Generating the genesis block](#generating-the-genesis-block) + 1. [Setup](#setup) + 2. [Collecting pre-genesis public keys](#collecting-pre-genesis-public-keys) + 3. [Allocating pre-genesis NAM balances](#allocating-pre-genesis-nam-balances) + 4. [Collecting pre-genesis transactions](#collecting-pre-genesis-transactions) + 5. [Generating the genesis block](#generating-the-genesis-block) ### Setup @@ -26,14 +26,14 @@ Conventionally, the network coordinator hosts a git repository that allows the p ### Allocating pre-genesis NAM balances -Once the participants have [submitted their keys and addresses](./participants.mdx#submitting-keys-and-addresses) the network coordinator must allocate balances to these addresses/public keys. The coordinator will often have prior identity information associated with desired balances, which they will then associate with the public keys and addresses in order to set the correct balances in `balances.toml`. The coordinator must also ensure that the total pre-genesis NAM balances allocated to the pre-genesis network participants is equal to the total NAM supply. +Once the participants have [submitted their keys and addresses](./participants.mdx#submitting-keys-and-addresses), the network coordinator must allocate balances to these addresses/public keys. The coordinator will often have prior identity information associated with desired balances, which they will then associate with the public keys and addresses in order to set the correct balances in `balances.toml`. The coordinator must also ensure that the total pre-genesis NAM balances allocated to the pre-genesis network participants is equal to the total NAM supply. -After this is completed, the network coordinator will publish the `balances.toml` file that contains the pre-genesis NAM balances allocated to the pre-genesis network participants. The `balances.toml` file should be published in the same location as the pre-genesis public keys were submitted. +After this is completed, the network coordinator will publish the `balances.toml` file that contains the pre-genesis NAM balances allocated to the pre-genesis network participants. The `balances.toml` file should be published at the same location to which the pre-genesis public keys were submitted. ### Collecting pre-genesis transactions -Once the participants have [submitted their keys and addresses](./participants.mdx#submitting-keys-and-addresses) the network coordinator must collect the signed pre-genesis transactions from the pre-genesis network participants. The network coordinator must ensure that the total number of pre-genesis transaction files collected is equal to the total number of pre-genesis network participants. +Once the participants have [submitted their keys and addresses](./participants.mdx#submitting-keys-and-addresses), the network coordinator must collect the signed pre-genesis transactions from the pre-genesis network participants. The network coordinator then aggregates these transaction files into one file and saves it as the `transactions.toml` file to be used in the generation of the genesis block. @@ -41,7 +41,25 @@ The `transactions.toml` file is validated by the network coordinator to ensure t ### Generating the genesis block -Once the network coordinator has collected the pre-genesis public keys, allocated pre-genesis NAM balances, and collected pre-genesis transactions, the network coordinator is ready to generate the genesis block. +Once the network coordinator has collected the pre-genesis public keys, allocated pre-genesis NAM balances, and collected pre-genesis transactions, the network coordinator is ready to generate the genesis block. + +The following command can be used to generate a `.tar.gz` archive that packages all genesis files needed to bootstrap any new node which wishes to join the chain. + +``` +namadac utils init-network \ + --genesis-time $GENESIS_TIME \ + --wasm-checksums-path $CHECKSUMS_PATH \ + --chain-prefix $CHAIN_PREFIX \ + --templates-path $TEMPLATES_PATH +``` +where: +- `GENESIS_TIME` is a string containing the desired network start time in the format `YYYY-MM-DDTHH:MM:SS.000000000+00:00`. Nodes will not attempt to make blocks before this time. +- `CHECKSUMS_PATH` is the path to the chain's `checksums.json` file +- `CHAIN_PREFIX` is a string of alphanumeric characters that will be used as the first part of the chain-id, chosen by the network coordinator +- `TEMPLATES_PATH` is the path to a directory containing the five `toml` files required to create the genesis block -- `balances.toml`, `transactions.toml`, `tokens.toml`, `paramaters.toml` and `validity-predicates.toml` + +After successfully running the command, a file will be generated with the name `$CHAIN_ID.tar.gz` containing the genesis contents. The network coordinator must host this file so that +other nodes can download and apply it to their nodes ahead of the genesis time. \ No newline at end of file diff --git a/packages/docs/pages/networks/starting-network/genesis-flow/participants.mdx b/packages/docs/pages/networks/starting-network/genesis-flow/participants.mdx new file mode 100644 index 00000000..3e01136b --- /dev/null +++ b/packages/docs/pages/networks/starting-network/genesis-flow/participants.mdx @@ -0,0 +1,282 @@ +import { Callout } from 'nextra-theme-docs' +import { Steps } from 'nextra-theme-docs' + +# Pre-genesis participants +This section contains details on the pre-genesis process and instructions on how participants can generate, sign, and submit each available type of pre-genesis +transaction. + +## Genesis state + +A chain always starts from an initial state (the 'genesis state'), which is defined in its genesis files. Among other things, these +files define an initial allocation of tokens to various accounts, along with an initial validator set and stake distribution. + +Initial token allocations are given in the chain's `balances.toml` file, and the initial validator set and stake distribution are +derived as a result of applying the pre-genesis transactions given in the chain's `transactions.toml` file. + +To produce an initial validator set in a decentralized manner, network participants (i.e. users and operators) are given the opportunity to generate and submit a +pre-genesis transaction in which they can initialize their validators and/or bond stake to a genesis validator. + +Prospective pre-genesis transactions are then collected in a single location (typically a GitHub repo) where they can be reviewed by the +[network coordinator](./coordinator.mdx) and selected for inclusion in the genesis block. The finalized set of pre-genesis transactions are +published in the chain configuration `.tar.gz` file used to bootstrap all nodes. Should validators with a sufficient amount of stake +choose to proceed to launch the chain with the proposed configuration, it will signal social consensus of the legitimacy of the genesis state. + +## Pre-genesis network participants + +The pre-genesis network participants are the entities that are participating in the genesis ceremony. The pre-genesis network participants are responsible for: +1. [Generating their public and private keys](#generating-keys) +2. [Submitting their public keys and addresses to the network coordinator](#submitting-keys-and-addresses) +3. [Generating their pre-genesis transactions](#generating-transactions) +4. [Signing their pre-genesis transactions](#signing-transactions) +5. [Submitting their pre-genesis transactions to the network coordinator](#submitting-transactions) + +### Notes: + +Before getting to the pre-genesis transaction procedure in the next section, it's helpful to keep the following in mind: + +#### Pre-genesis wallet +Whenever you perform a pre-genesis action that requires a public or private key (such as generating or signing pre-genesis transactions), +the Namada client will attempt to find them in the pre-genesis wallet, which is located at `$BASE_DIR/pre-genesis/wallet.toml`. + +To perform wallet actions such as adding or removing keys with the pre-genesis wallet, use the `--pre-genesis` flag with `namadaw`. +For example, to generate a new key in the pre-genesis wallet: +```bash copy +namadaw --pre-genesis gen --alias $ALIAS +``` + +#### Implicit accounts +Unlike established and validator accounts (which exist on-chain), [implicit accounts](../../../users/transparent-accounts/implicit-accounts.mdx) have no pre-genesis logic attached -- they simply exist by +virtue of being part of Namada's address space. Possessing the private key that corresponds to an implicit account permits one to spend +any tokens that may or may not be present at that address. Therefore, an implicit account can be given a genesis allocation in the chain's `balances.toml` file, +by specifying its public key and an amount, but does not require any accompanying pre-genesis transaction. + +## Pre-genesis process +This section gives instructions on the order of operations and commands used by pre-genesis participants when creating their pre-genesis transaction(s). It only applies before network launch. + + + +### Generating keys + +Before the genesis ceremony begins, the pre-genesis network participants must generate their public and private keys. The pre-genesis network participants must ensure that their private keys are kept secret and that their public keys are submitted to the network coordinator in due time. + +This can be done through the namada cli: + +```bash +ALIAS="" +namadaw --pre-genesis gen --alias $ALIAS +``` + +After the user has entered their passwords and written down their mnemonic phrase, the Namada cli will save the keys to the `pre-genesis` folder inside the [base directory](../../ledger/base-directory.mdx). + +In order to print the keys, the user can run the following command: + +```bash +namadaw --pre-genesis find --alias $ALIAS +``` + +The network coordinator should specify the schema in which the pre-genesis network participants should submit their public keys and addresses. A toml file with the following schema is recommended: + +```toml +[] +"public-key" = "ED25519_PK_PREFIXtpknam1qpjs6jrjuu5cj508ys7ezee4r40v8as6vz4j3ddc9qm68nfhf5n7clp4xse" +"address" = "tnam1qq5skuga54tfs7422hzz8sqvk3s6lhe2dg32jjhd" +``` + +Remember, a public key begins with `tpknam`, whereas an address begins with `tnam`. + + +### Submitting keys and addresses + +After the network coordinator has published the location (conventionally a GitHub repository) for the pre-genesis network participants to submit their public keys, the participants are expected to submit their generated public keys (and their corresponding addresses) to the network coordinator in due time. The deadline will be set by the network coordinator. + +### Generating transactions + +Participants are also responsible for generating the genesis-block transactions that set the initial state of the blockchain, including initializing +genesis validator accounts and bonding to them. However, it is only possible to make transactions that require value once the balances of the keys +become agreed upon (i.e. once the `balances.toml` file has been published). + +The available pre-genesis transactions are: +- initialize an established account +- initialize a validator from an established account +- bond stake to a genesis validator + +More details on generating each type of pre-genesis transaction follow below. + +#### Initialize an established account + +You can initialize an established account pre-genesis using the `init-genesis-established-account` command. + +First, you must add the public key(s) you wish to associate with the established account to your pre-genesis wallet, if not already present. + + +You can add a public key to your wallet, separate from its corresponding private key, with the following command: +``` +namadaw --pre-genesis add --value $PUBLIC_KEY --alias $ALIAS +``` + + +You can then generate the pre-genesis transaction that will initialize the account and write it to a `toml` file with the following +command: +```bash copy +namadac utils init-genesis-established-account \ + --path $OUTPUT_FILE \ + --aliases $ALIAS +``` +The `aliases` argument specifies the public key(s) to be associated with the account, and the `path` argument +specifies the output file. + +**Note:** After initializing a pre-genesis established account you may proceed to "promoting" it to a pre-genesis validator account (see below), however +you are not required to do so. + +If the `init-genesis-established-account` command is successful, you will see output similar to the following: +```bash +Derived established account address: {your tnam address} + +IMPORTANT: keep a note of this address, especially if you plan to use it for a validator account in the future! + +Wrote genesis tx to: {output file location} +``` + +This will generate a `transactions.toml` file that contains the pre-genesis transaction that will establish the account. The `transactions.toml` file should look similar to: + +```toml +[[established_account]] +vp = "vp_user" +threshold = 1 +public_keys = ["tpknam1qr872zwdvw4u4nkpl0ykmvhyvxw7j0u6g7ymz03d7he0jr3szkuwczddjp2"] +``` + + +You can also initialize the account as a [multi-sig](../../../users/transparent-accounts/multisignature.mdx) by providing multiple aliases as a comma-separated list and providing the `threshold` parameter: +```bash copy +namadac utils init-genesis-established-account \ + --path $OUTPUT_FILE \ + --aliases $ALIAS1,$ALIAS2,$ALIAS3 \ + --threshold $THRESHOLD +``` + + +#### Initialize a pre-genesis validator account + + +This step will require the `balances.toml` file to have been published by the network coordinator. + + +**Note:** To initialize a pre-genesis validator, you must first have followed the steps above to initialize a pre-genesis established account +and generate a transaction `toml` file. + +The following command will generate a pre-genesis transaction which initializes a validator account: + +```bash +# Ensure $BASE_DIR is set to the base directory +# Ensure $ESTABLISHED_ACCOUNT_ADDRESS is set +# Ensure $TX_FILE_PATH is set + +EMAIL="" +DISCORD_HANDLE="" # This is optional +AVATAR_URL="" # This is optional, and expects a URL to an image the size of 128x128 pixels +WEBSITE="" # This is optional +DESCRIPTION="" # This is optional +VALIDATOR_NAME="" # This is optional +SELF_BOND_AMOUNT=1000000 # Set this to the amount of NAM you want to self-bond. This must be less than or equal to the amount of NAM allocated to the pre-genesis keys in the `balances.toml` that was published by the network coordinator. +VALIDATOR_ALIAS="" +IP_ADDRESS="" +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 $SELF_BOND_AMOUNT \ + --email $EMAIL \ + --name $VALIDATOR_NAME \ + --discord-handle $DISCORD_HANDLE \ + --avatar $AVATAR_URL \ + --website $WEBSITE \ + --description $DESCRIPTION \ + --path $TX_FILE_PATH +``` + + + +The `SELF_BOND_AMOUNT` must be less than or equal to the amount of NAM allocated to the pre-genesis keys in the `balances.toml` that was published by the network coordinator. It will correspond to the self-bonded stake of the validator account at genesis. + +The `--net-address` specifies the network address of the validator node given by "IP:PORT". It is also possible to use DNS names instead of IP:PORT addresses. This is used to bootstrap peer discovery between validators on network launch. + +The `--alias` flag is the moniker name of the validator account in your wallet. + +The `--commission-rate` and `--max-commision-rate` flags are the commission rate and the maximum permitted commission rate change of the validator account per epoch. See the [validator docs](../../../operators/validators/validator-setup.mdx#initialize-a-new-validator-account) for more info. + +The `--email` flag is the email address of the validator account. This is used for the validator account to receive notifications from the network coordinator and other participants. + +The optional flags `--name`, `--discord-handle`, `--avatar`, `--website` and `--description` configure additional optional on-chain metadata that identify your validator. + +The `--address` flag is the `tnam...` address of the established account that was generated in the previous section. + +The `--path` flag is the path to the `transactions.toml` file that was generated in the previous section. + + + +The above command will append the necessary transactions to the file given by `$TX_FILE_PATH` and your newly generated validator keys will be written to `$BASE_DIR/pre-genesis/$VALIDATOR_ALIAS/validator-wallet.toml`. + +Successful execution will output the new validator address: + +```text +Validator account address: tnam1q8lsztqqhpjxdwzw88mqqc2mun7dvpxvas3v2dxk +``` + + +**IMPORTANT:** Make a secure backup of the validator keys created in this step. They are located in the folder `$BASE_DIR/pre-genesis/$VALIDATOR_ALIAS` + + +#### Bond to a pre-genesis validator account + + +This step will require the `balances.toml` file to have been published by the network coordinator. + + +You can generate a pre-genesis transaction to bond tokens to a genesis validator (assuming you have tokens allocated to your account at genesis). + +You can generate a pre-genesis transaction to bond tokens to a genesis validator (assuming you have tokens allocated to your account at genesis). +To do so, first add your genesis account to your pre-genesis wallet using its mnemonic or private key. + +Then, generate the pre-genesis bond transaction and write it to a `toml` file with: + +```bash copy +namadac utils genesis-bond \ + --validator $TARGET_VALIDATOR \ + --amount $AMOUNT \ + --source $YOUR_PUBLIC_KEY \ + --path $OUTPUT_FILE +``` + +### Signing transactions + +For validator initialization and bonding transactions, after generating your pre-genesis transaction (but before submitting it for inclusion in the genesis block), you must +sign it with the relevant private key. You can do this using the `sign-genesis-txs` command. + +The command will check for the necessary private key in the [pre-genesis wallet](#pre-genesis-wallet). If you are signing an init-validator +transaction, it will also check for the validator keys at `$BASE_DIR/pre-genesis/$VALIDATOR_ALIAS/validator-wallet.toml`. + +To sign an init-validator transaction, use: +```bash copy +namadac utils sign-genesis-txs --path $INPUT_FILE --output $OUTPUT_FILE --alias $VALIDATOR_ALIAS +``` + +When signing a bond transaction, the `alias` can be omitted: +```bash copy +namadac utils sign-genesis-txs --path $INPUT_FILE --output $OUTPUT_FILE +``` + + +Transactions that only initialize an established account do not need to be signed (attempting to sign one will simply output the original file). + + +### Submitting transactions + +At this point, participants will submit their signed transaction `toml` file(s) for review and possible inclusion in the genesis block. +The network coordinator will provide specific instructions on when and how to do this, along with a submission deadline. Most often, a dedicated GitHub +repo will be created where the files can be submitted via pull request. By convention, a directory for each pre-genesis network participant is created in +the git repository. The signed transactions `toml` file is then submitted to its respective directory. + + diff --git a/packages/docs/pages/operators/networks/local-network.mdx b/packages/docs/pages/networks/starting-network/local-network.mdx similarity index 100% rename from packages/docs/pages/operators/networks/local-network.mdx rename to packages/docs/pages/networks/starting-network/local-network.mdx diff --git a/packages/docs/pages/networks/testnets/testnet-history.mdx b/packages/docs/pages/networks/testnets/testnet-history.mdx index bdb13055..da493ddf 100644 --- a/packages/docs/pages/networks/testnets/testnet-history.mdx +++ b/packages/docs/pages/networks/testnets/testnet-history.mdx @@ -193,16 +193,16 @@ make build-release 4. Once this has been completed, **the node must tesync from genesis** (see below) **How to resync from genesis:** -1. As a precautionary measure, make a backup of your pregenesis keys +1. As a precautionary measure, make a backup of your pre-genesis keys ```bash copy -mkdir backup-pregenesis && cp -r .namada/pre-genesis backup-pregenesis/ +mkdir backup-pre-genesis && cp -r .namada/pre-genesis backup-pre-genesis/ ``` 2. Delete the relevant folder in .namada ```bash copy 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. +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-pre-genesis file. 3. Rejoin the network ```bash copy diff --git a/packages/docs/pages/operators/_meta.json b/packages/docs/pages/operators/_meta.json index e1533fdc..c4acbf2f 100644 --- a/packages/docs/pages/operators/_meta.json +++ b/packages/docs/pages/operators/_meta.json @@ -3,7 +3,6 @@ "ledger": "Running a full node", "remote-signing": "Remote signing", "validators": "Validators", - "networks": "Starting a network", "ibc": "IBC Relayers", "troubleshooting": "Troubleshooting" } \ No newline at end of file diff --git a/packages/docs/pages/operators/networks/genesis-flow.mdx b/packages/docs/pages/operators/networks/genesis-flow.mdx deleted file mode 100644 index 9b2a9fc2..00000000 --- a/packages/docs/pages/operators/networks/genesis-flow.mdx +++ /dev/null @@ -1,15 +0,0 @@ -# Setting up a decentarlised Namada network - -Setting up a decentralized Namada network requires coordination between two distinct parties: - -1. [The network coordinator](./genesis-flow/coordinator.mdx#the-network-coordinator) -2. [The pre-genesis network participants](./genesis-flow/participants.mdx#pre-genesis-network-participants) - -This process is also called the **genesis ceremony**. - - - - - - - diff --git a/packages/docs/pages/operators/networks/genesis-flow/participants.mdx b/packages/docs/pages/operators/networks/genesis-flow/participants.mdx deleted file mode 100644 index 2530a751..00000000 --- a/packages/docs/pages/operators/networks/genesis-flow/participants.mdx +++ /dev/null @@ -1,236 +0,0 @@ -import { Callout } from 'nextra-theme-docs' -import { Steps } from 'nextra-theme-docs' - - -## Pre-genesis network participants - -The pre-genesis network participants are the entities that are participating in the genesis ceremony. The pre-genesis network participants are responsible for: -1. [Generating their public and private keys](#generating-keys) -2. [Submitting their public keys and addresses to the network coordinator](#submitting-keys-and-addresses) -3. [Generating their pre-genesis transactions](#generating-transactions) -4. [Signing their pre-genesis transactions](#signing-transactions) -5. [Submitting their pre-genesis transactions to the network coordinator](#submitting-transactions) - - - -### Generating keys - -Before the genesis ceremony begins, the pre-genesis network participants must generate their public and private keys. The pre-genesis network participants must ensure that their private keys are kept secret and that their public keys are submitted to the network coordinator in due time. - -This can be done through the namada cli: - -```bash -ALIAS="" -namadaw --pre-genesis gen --alias $ALIAS -``` - -After the user has entered their passwords and written down their mnemonic phrase, the namada cli will save the keys to the `pre-genesis` folder inside the [base directory](../../ledger/base-directory.mdx). - -In order to print the keys, the user can run the following command: - -```bash -# Not recommended in production since it will print the private key to the terminal (which can be recovered) -cat $BASE_DIR/pre-genesis/wallet.toml -``` - -It is the public keys that the pre-genesis network participants must submit to the network coordinator. - -```toml -# Example wallet.toml -[public_keys] -alice = "ED25519_PK_PREFIXtpknam1qq2vscpcvhdwht9tldj9ntxnknandhnerhzd6d42xqzukw2kpcfpudh3dl2" - -... - -[addresses] -alice = "tnam1qq97eqvv4lam8ds00j9em2s2f0r8e7r60qw9fdfq" -``` - -It is then the right hand side of each of these fields that is submitted to the network coordinator, i.e `ED25519_PK_PREFIXtpknam1qq2vscpcvhdwht9tldj9ntxnknandhnerhzd6d42xqzukw2kpcfpudh3dl2` and `tnam1qq97eqvv4lam8ds00j9em2s2f0r8e7r60qw9fdfq` in the example above. - -The network coordinator should specify the schema in which the pre-genesis network participants should submit their public keys and addresses. A toml file with the following schema is recommended: - -```toml -[] -"public-key" = "ED25519_PK_PREFIXtpknam1qpjs6jrjuu5cj508ys7ezee4r40v8as6vz4j3ddc9qm68nfhf5n7clp4xse" -"address" = "tnam1qq5skuga54tfs7422hzz8sqvk3s6lhe2dg32jjhd" -``` - -### Submitting keys and addresses - -After the network coordinator has published the location (conventionally a git repository) for the pre-genesis network participants to submit their public keys, the participants are expected to submit their generated public keys (and their corresponding addresses) to the network coordinator in due time. The deadline will be set by the network coordinator. - -### Generating transactions - -Participants are also responsible for generating the genesis-block transactions that set the initial state of the blockchain, including initialising genesis validator accounts and bonding to them. However, it is only possible to make transactions that require value once the balances of the keys become agreed upon (once the `balances.toml` file has been published). - -#### Generate an established account - -In order to generate a pre-genesis validator account, the pre-genesis network participants must first generate an established account. This can be done through the namada cli: - - -The `$ALIAS` variable is the alias of the pre-genesis keys that were generated in the [Generating keys](#generating-keys) step. - - -```bash -#Ensure $BASE_DIR is set to the base directory -TX_FILE_PATH="$BASE_DIR/pre-genesis/transactions.toml" -namadac utils init-genesis-established-account --path $TX_FILE_PATH --aliases $ALIAS - -# You can change the `--path` argument to any file path, but the recommended is `$BASE_DIR/pre-genesis/transactions.toml` -``` - -The command will output the generated address of the established account. - -```text -Derived established account address: tnam1q8lsztqqhpjxdwzw88mqqc2mun7dvpxvas3v2dxk -``` - -It is useful to save this address for later use. - -```bash -ESTABLISHED_ACCOUNT_ADDRESS=tnam1q8lsztqqhpjxdwzw88mqqc2mun7dvpxvas3v2dxk -``` - -This will generate a `transactions.toml` file that contains the pre-genesis transaction that will establish the account. The `transactions.toml` file should look something like this: - -```toml -[[established_account]] -vp = "vp_user" -threshold = 1 -public_keys = ["tpknam1qr872zwdvw4u4nkpl0ykmvhyvxw7j0u6g7ymz03d7he0jr3szkuwczddjp2"] -``` - -#### Generate a pre-genesis multisignature account - -In order to generate a pre-genesis multisignature account, just add --aliases. With the list of key aliases to use, separated by commas. - - -```bash -# Ensure $BASE_DIR is set to the base directory -# Assuming that the values of $ALIAS1, $ALIAS2, and $ALIAS3 are the aliases of the pre-genesis keys that were generated in the [Generating keys](#generating-keys) step. -TX_FILE_PATH="$BASE_DIR/pre-genesis/transactions.toml" - -namadac utils init-genesis-established-account --path $TX_FILE_PATH --aliases $ALIAS1,$ALIAS2,$ALIAS3 -``` - -The command will output the generated address of the multisignature account. - - -```text -Derived established account address: tnam1q8qvns6ndpff03wmszkhgepk2r8f9ws68ugktfml -``` - -The corresponding `transactions.toml` file should look something like this: - -```toml -[[established_account]] -vp = "vp_user" -threshold = 1 -public_keys = ["tpknam1qr872zwdvw4u4nkpl0ykmvhyvxw7j0u6g7ymz03d7he0jr3szkuwczddjp2", "tpknam1qpz5n0u49s6s5jx4nyycyw0w288yfq96p3lvwxkedxyw77y0vd53sqmryce"] -``` - -#### Generate a pre-genesis validator account - - -This step will require the `balances.toml` file to have been published by the network coordinator. - - -Once the pre-genesis network participants have generated respective pre-genesis established accounts, they can generate their pre-genesis validator accounts. This can be done through the namada cli: - -```bash -# Ensure $BASE_DIR is set to the base directory -# Ensure $ESTABLISHED_ACCOUNT_ADDRESS is set -# Ensure $TX_FILE_PATH is set - -EMAIL="" -DISCORD_HANDLE="" # This is optional -AVATAR_URL="" # This is optional, and expects a URL to an image the size of 128x128 pixels -WEBSITE="" # This is optional -DESCRIPTION="" # This is optional -SELF_BOND_AMOUNT=1000000 # Set this to the amount of NAM you want to self-bond. This must be less than or equal to the amount of NAM allocated to the pre-genesis keys in the `balances.toml` that was published by the network coordinator. -VALIDATOR_ALIAS="" -IP_ADDRESS="" -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 $SELF_BOND_AMOUNT \ - --email $EMAIL \ - --discord-handle $DISCORD_HANDLE \ - --avatar $AVATAR_URL \ - --website $WEBSITE \ - --description $DESCRIPTION \ - --path $TX_FILE_PATH -``` - - - -The `SELF_BOND_AMOUNT` must be less than or equal to the amount of NAM allocated to the pre-genesis keys in the `balances.toml` that was published by the network coordinator. It will correspond to the self-bonded stake of the validator account at genesis. - -The `--net-address` specifies the network address of the validator node given by "IP:PORT". It is also possible to use DNS names instead of IP:PORT addresses. - -The `--alias` flag is the moniker name of the validator account. - -The `--commission-rate` and `--max-commision-rate` flags are the commission rate and the maximum permitted commission rate change of the validator account per epoch. See the validator docsfor more info. - -The `--email` flag is the email address of the validator account. This is used for the validator account to receive notifications from the network coordinator and other participants. - -The optional `--discord-handle` flag is the discord handle of the validator account. This is used for the validator account to receive notifications from the network coordinator and other participants. - -The `--address` flag is the Namada address of the account. - -The `--path` flag is the path to the `transactions.toml` file that will be appended to, and requires the established account to already be initialized under. - - - -The above command will append the necessary transactions to the `transactions.toml` file. The `transactions.toml` file should look something like this: - -Successful execution will output the new validator address: - -```text -Validator account address: tnam1q8lsztqqhpjxdwzw88mqqc2mun7dvpxvas3v2dxk -``` - -#### Bond to a pre-genesis validator account -If your public key has been allocated `NAM` (`NAAN` for the shielded expedition), you can bond to a genesis validator as a pre-genesis transaction. - -This step is intended for pre-genesis participants who have been allocated `NAM` (`NAAN` for the shielded expedition) and want to bond to a genesis validator that is not their own. If you want to bond to your own genesis validator, please follow the steps in [Generate a pre-genesis validator account](#generate-a-pre-genesis-validator-account) and use the `--self-bond` arguments. - - -The bond can be achieved by running: - -```bash copy -namadac utils genesis-bond \ - --validator "" \ - --amount "" \ - --source "" \ - --path "" -``` - -After this step is completed, it is required to sign the transaction. - - -### Signing transactions - -Once the `transactions.toml` file has been generated, the pre-genesis network participants must sign the transactions. This can be done through the namada cli: - -```bash -namadac utils sign-genesis-txs \ - --path $TX_FILE_PATH \ - --output $BASE_DIR/pre-genesis/signed-transactions.toml \ - --alias $VALIDATOR_ALIAS # This is only necessary if a validator account was generated, otherwise leave out the flag entirely -``` - -The above command will output a `signed-transactions.toml` file that contains the signed transactions. - - -### Submitting transactions - -Once all pre-genesis transactions have been generated and signed, the pre-genesis network participants must submit their transactions to the network coordinator in due time. The deadline will be set by the network coordinator. This will involve simply submitting the `signed-transactions.toml` file to the network coordinator at the agreed upon location. - -By convention, a directory for each pre-genesis network participant is created in the git repository. The `signed-transactions.toml` file is then submitted to the respective directory. - - diff --git a/packages/docs/pages/operators/validators/validator-setup.mdx b/packages/docs/pages/operators/validators/validator-setup.mdx index 32cd9b84..89089546 100644 --- a/packages/docs/pages/operators/validators/validator-setup.mdx +++ b/packages/docs/pages/operators/validators/validator-setup.mdx @@ -21,7 +21,7 @@ consensus assuming they possess the expected consensus keys. ### Method -The method for setting up a genesis validator is described under the [pre-genesis participants](../networks/genesis-flow/participants.mdx#generate-a-pre-genesis-validator-account) section. +The method for setting up a (pre-)genesis validator is described under the [pre-genesis process](../../networks/starting-network/genesis-flow.mdx) section. ## Post-genesis validators diff --git a/packages/docs/pages/users/wallet/file-system-wallet.mdx b/packages/docs/pages/users/wallet/file-system-wallet.mdx index 555432f0..189c330d 100644 --- a/packages/docs/pages/users/wallet/file-system-wallet.mdx +++ b/packages/docs/pages/users/wallet/file-system-wallet.mdx @@ -72,7 +72,7 @@ You can remove all keys/addresses associated with an alias from your wallet with namadaw remove --alias --do-it ``` -#### Using the Pregenesis flag +#### Using the pre-genesis flag Normally, you will be expected to join a network before using the wallet; and `namadaw` will throw an error when an existing chain context is not found. However, there may be times when you want to use `namadaw` prior to joining a chain -- for example, when generating a keypair to recieve a token allotment in the genesis block of a future chain. In these cases, you can use the flag `--pre-genesis` with your `namadaw` commands.