diff --git a/packages/docs/pages/networks/testnets.en-US.mdx b/packages/docs/pages/networks/testnets.en-US.mdx index 04d5af6e..7bc3d9e4 100644 --- a/packages/docs/pages/networks/testnets.en-US.mdx +++ b/packages/docs/pages/networks/testnets.en-US.mdx @@ -5,11 +5,11 @@ For more context read: [Announcing Namada Public Testnets](https://blog.namada.net/announcing-namada-public-testnets/) ## Latest Testnet -- Namada public testnet 14: - - From date: 5th of October 2023 17:00 UTC - - Namada protocol version: `v0.23.0` +- Namada public testnet 15: + - From date: 14th of December 2023 17:00 UTC + - Namada protocol version: `v0.28.0` - Cometbft version: `0.37.2` - - CHAIN_ID: `public-testnet-14.5d79b6958580` + - CHAIN_ID: `tbd` The history of all testnets can be found [here](./testnets/testnet-history.mdx). @@ -25,9 +25,9 @@ If you find a bug, please submit an issue with the `bug` [issue template](https: 1. [Environment setup](./testnets/environment-setup.mdx) 2. [Pre-genesis instructions](./testnets/pre-genesis.mdx) -3. [Pre-genesis validator setup](../operators/validators/genesis-validator-setup.mdx) +3. [Pre-genesis validator setup](../operators/validators/validator-setup.mdx) 4. [Pre-genesis validator apply](./testnets/genesis-validator-apply.mdx) -5. [Running your genesis validator](../operators/validators/run-your-genesis-validator.mdx) +5. [Running your genesis validator](../operators/validators/validator-setup.mdx#start-validating) 6. [Running a full node](../operators/ledger/running-a-full-node.mdx) 7. [Becoming a validator post-genesis](./testnets/post-genesis-validator.mdx) diff --git a/packages/docs/pages/networks/testnets/campfire.en-US.mdx b/packages/docs/pages/networks/testnets/campfire.en-US.mdx index a1f861b7..dc7c12b6 100644 --- a/packages/docs/pages/networks/testnets/campfire.en-US.mdx +++ b/packages/docs/pages/networks/testnets/campfire.en-US.mdx @@ -18,7 +18,7 @@ The most up-to-date docs on joining Campfire β›ΊπŸ”₯ can be found [here](https:/ Currently, Campfire β›ΊπŸ”₯ docs only detail support for Ubuntu machines. -The user will need to have installed the [Stack-Orchestrator](https://github.com/vknowable/stack-orchestrator), which is a general tool for quickly and flexibly launching and managing a software stack in a containerized environment. The docs are found in the [README](https://github.com/vknowable/stack-orchestrator/README.md) of the repo, and the tool can be installed by running the following command: +The user will need to have installed the [Stack-Orchestrator](https://github.com/vknowable/stack-orchestrator), which is a general tool for quickly and flexibly launching and managing a software stack in a containerized environment. The docs are found in the [README](https://github.com/vknowable/stack-orchestrator/#readme) of the repo, and the tool can be installed by running the following command: ```bash copy git clone https://github.com/vknowable/stack-orchestrator.git diff --git a/packages/docs/pages/networks/testnets/faq.en-US.mdx b/packages/docs/pages/networks/testnets/faq.en-US.mdx index 75b6e175..a67f3313 100644 --- a/packages/docs/pages/networks/testnets/faq.en-US.mdx +++ b/packages/docs/pages/networks/testnets/faq.en-US.mdx @@ -2,7 +2,7 @@ ### **Q: How do I join as a validator post-genesis?** -**A:** Joining as a validator post genesis can be done following [these instructions](../../operators/validators/post-genesis-validator-setup.mdx). +**A:** Joining as a validator post genesis can be done following [these instructions](../../operators/validators/validator-setup.mdx). ### **Q: How do I use the Faucet?** diff --git a/packages/docs/pages/networks/testnets/genesis-validator-apply.en-US.mdx b/packages/docs/pages/networks/testnets/genesis-validator-apply.en-US.mdx index aadd597e..f437ce7c 100644 --- a/packages/docs/pages/networks/testnets/genesis-validator-apply.en-US.mdx +++ b/packages/docs/pages/networks/testnets/genesis-validator-apply.en-US.mdx @@ -6,33 +6,68 @@ Before a testnet launches, you can apply to be a genesis validator. ### Set up -Follow [this guide](../../operators/validators/genesis-validator-setup.mdx#pre-genesis) on how to generate your "pre-genesis" validator files. +Follow [this guide](../../operators/validators/validator-setup.mdx#pre-genesis) 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: + +All pre-genesis validators are expected to bond `1000000` NAM tokens. At least that many tokens will be allocated to the pre-genesis validator key + + +After this, you'll have a signed `transactions.toml` file, the contents of which will look something like the following: ```toml -[validator.1337-validator] -consensus_public_key = "00056fff5232da385d88428ca2bb2012a4d83cdf5c697864dde34b393333a72268" -eth_cold_key = "0103d985a8345ef505cf139c3dfbd5f5a1da73d2864c62ce9d0a98da73898a59f6f9" -eth_hot_key = "010241bb691e44dd3c4263522474e45751e97307e92326250f96c1bcd0a06880875d" -account_public_key = "00f1bd321be2e23b9503653dd50fcd5177ca43a0ade6da60108eaecde0d68abdc8" -protocol_public_key = "0054c213d2f8fe2dd3fc5a41a52fd2839cb49643d960d7f75e993202692c5d8783" -dkg_public_key = "6000000054eafa7320ddebf00c9487e5f7ea5107a8444f042b74caf9ed5679163f854577bf4d0992a8fd301ec4f3438c9934c617a2c71649178e536f7e2a8cdc1f8331139b7fd9b4d36861f0a9915d83f61d7f969219f0eba95bb6fa45595425923d4c0e" +[[established_account]] +vp = "vp_user" +threshold = 1 +public_keys = ["tpknam1qrf7k5r2kvuppxnp0ruapkkd5szmyxzjxg7t64salgz5wrf6d327wmdh8xj"] + +[[validator_account]] +address = "tnam1q9yprrkkhy0kfngwg59rxx9q2f8kj5ufhctn4n6u" +vp = "vp_user" commission_rate = "0.01" -max_commission_rate_change = "0.05" -net_address = "1.2.3.4:26656" -tendermint_node_key = "00e1a8fe1abceb700063ab4558baec680b64247e2fd9891962af552b9e49318d8d" +max_commission_rate_change = "0.01" +net_address = "1.2.3.4:1000" + +[validator_account.consensus_key] +pk = "tpknam1qz2t8q4xt0vtm4x8kclr4lxhp0sea3956jzltdc2kqx4428a3queja2jx7p" +authorization = "signam1qp2a25j2x2u5ggawvd6fa4z8h7m0tw3ndtulzfwzxtfe6487arazthq2s28v5lmekn6dlp9qukehxwvanzyhfcgqpu7y6cut5l928qsxr3pp7k" + +[validator_account.protocol_key] +pk = "tpknam1qzwl3qsqtthmdwa2xn8pgymlsl3r8mdx53qgpm7xwwxgmn4hg0hjccnd27q" +authorization = "signam1qzp03svcajhr7f68ayy3kq8xq4l78j7qdnxfc2v0g3s0qt69gkxhm0kx866hg77wty9hj004jfn94pavkmfqxqhyypjs0padv99vrjsqeqgg9q" + +[validator_account.tendermint_node_key] +pk = "tpknam1qqwxpdvqyqlke25cfg46knx3slmzl84ap6v3kunu5r4efu3va3n7zf7nduz" +authorization = "signam1qpwzap7pczw3dlxjjxauhls9rya4fpxu4mmtrplkx9yfur5t3cf4wmwkvexnd4jyaeme3l9tfuxt7aapzzmjjsejsz8zz5upccykafgyu3dzqm" + +[validator_account.eth_hot_key] +pk = "tpknam1qypdeegcgv32w6ynrqsaml546rn9jr8ua9pv54t0dpdyuf2069eyflghxz99u" +authorization = "signam1qx5ve2mcu2s8pajr4w6tat9z3v3p4g75zy9vug0w7epwdzapg7k8u3jxrsg5kax4xk7p3maxv49va98hsz6ntdfs2fx3whk70raepyg3qyn0nufq" + +[validator_account.eth_cold_key] +pk = "tpknam1qyp0659xh8e8la0gx39f40epmamgug5l2ddgpplfe2zgpm8xlk7yzhcpnfx2e" +authorization = "signam1q806c02930rdnac5jtxtnmdr6jwhfwteu4eqchu0xe5jgaqsv0znztam6u3tyatme6fh72les7d502wpajqa0v8l5kc8cpef4nv8py5lqyv80ct3" + +[validator_account.metadata] +email = "test@test.com" + +[validator_account.signatures] +tpknam1qrf7k5r2kvuppxnp0ruapkkd5szmyxzjxg7t64salgz5wrf6d327wmdh8xj = "signam1qptu8kxn9apr7e7h438d60gsaqyupvgcur9rcxva4ft3vzh67y4qv2v2rm7ugg469kpe6qx7cr206n8tk0daqw9h03k72m6ffqwf56swvg0cjs" + +[[bond]] +source = "tnam1q9yprrkkhy0kfngwg59rxx9q2f8kj5ufhctn4n6u" +validator = "tnam1q9yprrkkhy0kfngwg59rxx9q2f8kj5ufhctn4n6u" +amount = "100" + +[bond.signatures] +tpknam1qrf7k5r2kvuppxnp0ruapkkd5szmyxzjxg7t64salgz5wrf6d327wmdh8xj = "signam1qqgn525t548eg7nrwhrlke0n6r8d3zqw79tdkeyva79r6snc26ew6fq2fkvunljw7l6hq5ed6e8dqyaq9afexwd88gnprlusjds77qgq57ej0a" ``` This file contains only public information and is safe to share publicly. - -The field `tendermint_node_key` is named this for legacy reasons. It is actually the CometBFT consensus public key. - ### 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](https://github.com/anoma/namada-testnets/pull/29). +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 signed `transactions.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](https://github.com/anoma/namada-testnets/pull/2616). ### Wait for the `CHAIN_ID` Wait until the corresponding `CHAIN_ID` has been distributed. \ No newline at end of file diff --git a/packages/docs/pages/networks/testnets/joining-the-testnet.en-US.mdx b/packages/docs/pages/networks/testnets/joining-the-testnet.en-US.mdx index 39a6e707..2e38dd00 100644 --- a/packages/docs/pages/networks/testnets/joining-the-testnet.en-US.mdx +++ b/packages/docs/pages/networks/testnets/joining-the-testnet.en-US.mdx @@ -5,7 +5,7 @@ Depending on whether you are a genesis validator, you can join the latest testne ## Joining as a genesis validator Joining the testnet validator is identical to that of a mainnet validator. -For this reason, please refer to [these docs](../../operators/validators/run-your-genesis-validator.mdx). +For this reason, please refer to [these docs](../../operators/validators/validator-setup.mdx#start-validating). ## Joining as a full node If you are not a genesis validator, please follow the steps for [joining as a full node](../../operators/ledger/running-a-full-node.mdx). diff --git a/packages/docs/pages/networks/testnets/migrating-testnets.en-US.mdx b/packages/docs/pages/networks/testnets/migrating-testnets.en-US.mdx index 04528184..9231ca8e 100644 --- a/packages/docs/pages/networks/testnets/migrating-testnets.en-US.mdx +++ b/packages/docs/pages/networks/testnets/migrating-testnets.en-US.mdx @@ -2,74 +2,6 @@ import { Callout, Steps } from 'nextra-theme-docs' # 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.19.0` we have introduced mandatory keys for validators. These keys are `eth_hot_key` and `eth_cold_key` that are used for Ethereum bridge purposes. - - -### 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 --genesis-validator `. 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: -```bash copy -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. You can verify the default directory on your machine by running: -```bash copy -export BASE_DIR=$(namadac utils default-base-dir) -``` - - - -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 one given above. - - - -### 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. - -```bash copy -mkdir $HOME/backup-pregenesis && cp -r $BASE_DIR/pre-genesis $HOME/backup-pregenesis/ -``` - -### **Ensure keys are saved** - -`ls backup-pregenesis` should output a saved `wallet.toml`. - -### Delete the base directory - -```bash copy -rm -rf $BASE_DIR/* -``` - -### Check that namada and cometbft binaries are correct. - -`namada --version` should yield `v0.22.0` and `cometbft version` should output `0.37.2` - - - -### Create a pre-genesis directory - -```bash copy -mkdir $BASE_DIR/pre-genesis -``` - -### Copy the backuped file back to `$BASE_DIR/pre-genesis` folder -```bash copy -cp -r backup-pregenesis/* $BASE_DIR/pre-genesis/ -``` - - -**You should now be ready to go!** \ No newline at end of file + +With the introduction of `v0.28.0` there is no way to migrate keys over. Please follow the instructions from scratch. + \ No newline at end of file diff --git a/packages/docs/pages/networks/testnets/post-genesis-validator.en-US.mdx b/packages/docs/pages/networks/testnets/post-genesis-validator.en-US.mdx index a396be69..ec8c9184 100644 --- a/packages/docs/pages/networks/testnets/post-genesis-validator.en-US.mdx +++ b/packages/docs/pages/networks/testnets/post-genesis-validator.en-US.mdx @@ -2,7 +2,7 @@ After genesis, you can still join the network as a user and become a validator through self-bonding. -After [joining the network as a full node](../../operators/ledger/running-a-full-node.mdx), you must [create a validator account](../../operators/validators/post-genesis-validator-setup.mdx). +After [joining the network as a full node](../../operators/ledger/running-a-full-node.mdx), you must [create a validator account](../../operators/validators/validator-setup.mdx). After this has been completed, you will need to increase your validator's `bonded-stake`, which can be done by self-bonding tokens sourced from the faucet. diff --git a/packages/docs/pages/networks/testnets/testnet-history.en-US.mdx b/packages/docs/pages/networks/testnets/testnet-history.en-US.mdx index af897804..e49c3f9b 100644 --- a/packages/docs/pages/networks/testnets/testnet-history.en-US.mdx +++ b/packages/docs/pages/networks/testnets/testnet-history.en-US.mdx @@ -6,41 +6,25 @@ This page covers all installation steps required by various upgrades to testnets ## Latest Upgrade -- Namada public testnet 14 (soft-upgrade hot-fix): - - From date: 19th of October 2023 9:00 UTC - - Namada protocol version: `v0.23.1` - - Cometbft version: `0.37.2` - - CHAIN_ID: `public-testnet-14.5d79b6958580` +No upgrades are currently scheduled. -How to upgrade to the latest testnet: -The upgrade is a soft upgrade, meaning that there is no consensus breaking change to the new binaries, and they are backwards compatible. Validators are encouraged to upgrade to the latest version of the binaries, which can be found [here](https://github.com/anoma/namada/releases/tag/v0.23.1) - -Then, simply stop the current ledger and restart it with the new binaries. This can be done by running the following commands: +## Latest Testnet -```bash copy -OS="Linux" # Or OS="Darwin" for Mac -wget https://github.com/anoma/namada/releases/download/v0.23.1/namada-v0.23.1-${OS}-x86_64.tar.gz -tar -xvf namada-v0.23.1-${OS}-x86_64.tar.gz --strip-components 1 -C /usr/local/bin/ #sudo may be required -killall namadan -namada --version #should output v0.23.1 -NAMADA_CMT_STDOUT=true namada node ledger run -``` +- Namada public testnet 15: + - From date: 14th of December 2023 17:00 UTC + - Namada protocol version: `v0.28.0` + - Cometbft version: `0.37.2` + - CHAIN_ID: `tbd` - -Note that the `v0.23.1` Linux binaries require Ubuntu LTS, which means that some older versions of Ubuntu will not be compatible (only Ubuntu `22.04` or later). In this case, it is recommended to build from source in order to upgrade. - -## Latest Testnet +## Testnet History Timeline -- Namada public testnet 14: +- Namada public testnet 14 (offline): - From date: 5th of October 2023 17:00 UTC - Namada protocol version: `v0.23.0` - Cometbft version: `0.37.2` - CHAIN_ID: `public-testnet-14.5d79b6958580` - -## Testnet History Timeline - - Namada public testnet 13 (offline): - From date: 12th of September 2023 17:00 UTC - Namada protocol version: `v0.22.0` @@ -202,7 +186,8 @@ mkdir backup-pregenesis && cp -r .namada/pre-genesis backup-pregenesis/ 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](../../operators/validators/run-your-genesis-validator.mdx) for more details +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. + 3. Rejoin the network ```bash copy export CHAIN_ID="public-testnet-3.0.81edd4d6eb6" diff --git a/packages/docs/pages/operators.en-US.mdx b/packages/docs/pages/operators.en-US.mdx index a8377825..1c376b1c 100644 --- a/packages/docs/pages/operators.en-US.mdx +++ b/packages/docs/pages/operators.en-US.mdx @@ -7,4 +7,4 @@ The guide assumes that you have already installed the node and are familiar with - [Running a full node](./operators/ledger.mdx) - [Running a validator node](./operators/validators.mdx) -- [Setting up a local network](./operators/local-network.mdx) \ No newline at end of file +- [Setting up a local network](./operators/networks/local-network.mdx) \ No newline at end of file diff --git a/packages/docs/pages/operators/_meta.json b/packages/docs/pages/operators/_meta.json index 0c4a2ebb..74c5233a 100644 --- a/packages/docs/pages/operators/_meta.json +++ b/packages/docs/pages/operators/_meta.json @@ -2,7 +2,7 @@ "hardware": "Hardware requirements", "ledger": "Running a full node", "validators": "Validators", - "local-network": "Setting up a local network", + "networks": "Starting a network", "ibc": "IBC Relayers", "troubleshooting": "Troubleshooting", "eth-bridge": "Eth bridge", diff --git a/packages/docs/pages/operators/ibc.en-US.mdx b/packages/docs/pages/operators/ibc.en-US.mdx index 2978fb13..4282ff05 100644 --- a/packages/docs/pages/operators/ibc.en-US.mdx +++ b/packages/docs/pages/operators/ibc.en-US.mdx @@ -3,30 +3,25 @@ import Expandable from '../../components/Expandable' # Relaying on Namada -This document describes how to operate a relayer for the Inter-Blockchain Communication (IBC) protocol with Namada. This documentation covers being able to create connections through IBC as well as setting up local instances of Namada for testing purposes. +This document describes how to operate a relayer for the Inter-Blockchain Communication (IBC) protocol with Namada. This documentation covers being able to create connections through IBC as well as setting up local chains of Namada for testing purposes. This document covers essential steps for using IBC with Namada: -1. [Setup Hermes](#setup-hermes) +1. [Configure Hermes](#configure-hermes) 2. [Install Hermes](#install-hermes) 3. [Setting up the relayer](#setting-up-the-relayer) 4. [Start the relayer](#start-the-relayer) -5. [Set up local Namada instances](#set-up-local-namada-instances-using-the-hermes-script) +5. [Set up local Namada chains](#set-up-local-namada-chains-using-the-hermes-script) The below is intended for those that wish to relay IBC message transfers between two Namada chains. There is of course the capability to do this between any two IBC compatible chains (such as a Cosmos chain). In this case, it is necessary to have a node running on both the destination and the source chain in order to make any package transfers. -Below, we discuss first how to enable this connection between two pre-existing chains by Hermes, and second, setting up two Namada local instances or joining two pre-existing Namada instances for this purpose. +Below, we discuss first how to enable this connection between two pre-existing chains by Hermes, and second, setting up two Namada local chains for this purpose. -## Setup Hermes -Hermes is an IBC relayer to relay IBC packets between chains (instances). -Namada uses a [fork of Hermes supporting Namada instances](https://github.com/heliaxdev/hermes/tree/1.6.0-namada). -Before packet relay, the user needs the following steps to configure and start Hermes. - -1. Make Hermes config file -2. Create IBC client/connection/channel between instances -3. Run Hermes +## Configure Hermes +Hermes is an IBC relayer to relay IBC packets between chains. +Namada uses a [fork of Hermes supporting Namada chains](https://github.com/heliaxdev/hermes/tree/v1.7.1-namada-beta4). ### Make Hermes config file One essential piece of the puzzle is to create a `config.toml` file that describes what connections will be set up that the relayer will be responsible for. @@ -38,7 +33,7 @@ touch $HERMES_CONFIG If you don't specify the file path, `~/.hermes/config.toml` is read as default. -You can find an example of the config file below. Essentially, you change only the chain IDs, the RPC addresses, and the key names in the config file for Namada. If you don't have nodes, please set up nodes manually or through our [scripts](#set-up-local-namada-instances-using-the-hermes-script). +You can find an example of the config file below. Essentially, you change only the chain IDs, the RPC addresses, and the key names in the config file for Namada. If you don't have nodes, please set up nodes manually or through our [scripts](#set-up-local-namada-chains-using-the-hermes-script).
Example: config.toml @@ -72,25 +67,25 @@ port = 3001 [[chains]] id = 'namada-test.0a4c6786dbda39f786' # set your chain ID -type = 'namada' +type = 'Namada' rpc_addr = 'http://127.0.0.1:27657' # set the IP and the port of the chain grpc_addr = 'http://127.0.0.1:9090' # not used for now event_source = { mode = 'push', url = 'ws://127.0.0.1:27657/websocket', batch_delay = '500ms' } # set the IP and the port of the chain account_prefix = '' # not used key_name = 'relayer' # The key is an account name you made store_prefix = 'ibc' -gas_price = { price = 0.001, denom = 'nam' } # not used for now +gas_price = { price = 0.001, denom = 'atest1v4ehgw36x9ry2dphx5mrvdjxgez5gdengeq5gs2pg3znx32yg9p5yv2zg3pnjvf4g9q5x329epndn0' } # the price isn't used for now, the denom should be a raw token address [[chains]] id = 'namada-test.647287156defa8728c' -type = 'namada' +type = 'Namada' rpc_addr = 'http://127.0.0.1:28657' grpc_addr = 'http://127.0.0.1:9090' event_source = { mode = 'push', url = 'ws://127.0.0.1:28657/websocket', batch_delay = '500ms' } account_prefix = '' key_name = 'relayer' store_prefix = 'ibc' -gas_price = { price = 0.001, denom = 'nam' } +gas_price = { price = 0.001, denom = 'atest1v4ehgw36xazry3pn89q5xv3ngyungs3hxc65vwp3xez5zdp3xppy2v6yxc65zsfegyc5yd2ptuf9d8' } ```
@@ -106,11 +101,11 @@ These are the pieces of this puzzle you want to keep your πŸ‘€ on: - `chains.rpc_address` specifies the port that the channel is communicating through, and will be the argument for the `ledger_address` of Namada when interacting with the ledger (will become clearer later) - Make sure to change the IP address to the IP address of your local machine that is running this node! - `chains.key_name` specifies the key of the signer who signs a transaction from the relayer. The key should be generated before starting the relayer. - - `event_source` specifies the URL of the chain's websocket. This must be the same as the `rpc_address` for Hermes to work properly. - + - `chains.event_source` specifies the URL of the chain's websocket. This must be the same as the `rpc_address` for Hermes to work properly. + - `chains.gas_price.denom` specifies the token that the relayer pays for IBC transactions. `chains.gas_price.price` isn't used for now. -### Create IBC client/connection/channel between instances -Hermes CLI has commands to create them. Before the creation, a node of each instance should be running at the specified rpc addresses. If you don't have nodes, please set up nodes manually or through our [scripts](#set-up-local-namada-instances-using-the-hermes-script). +You can see more details of configuration in [the official document](https://hermes.informal.systems/documentation/configuration). + ### Export environment variables The relaying user will need to save certain environment variables. These are: @@ -128,7 +123,7 @@ One can download the latest binary release from our [releases page](https://gith E.g. ```bash copy -export TAG="v1.6.0-namada-beta3" +export TAG="v1.7.1-namada-beta4" export ARCH="x86_64-unknown-linux-gnu" # or "aarch64-apple-darwin" curl -Lo /tmp/hermes.tar.gz https://github.com/heliaxdev/hermes/releases/download/${TAG}/hermes-${TAG}-${ARCH}.tar.gz tar -xvzf /tmp/hermes.tar.gz -C /usr/local/bin @@ -145,7 +140,7 @@ This is also true for the command `cp ./target/release/hermes /usr/local/bin/` b ### From source ```bash copy -export TAG="v1.6.0-namada-beta3" +export TAG="v1.7.1-namada-beta4" git clone https://github.com/heliaxdev/hermes.git git checkout $TAG @@ -168,37 +163,28 @@ cp ./target/release/hermes /usr/local/bin/ ## Setting up the relayer -### Create the `namada_wallet` directory and chain directories to hold each relayer wallet.toml - -For the relayer to work, it needs to have a wallet directory to store the keys of the relayer. This can be done by running -```bash copy -# in the Hermes folder -mkdir namada_wallet -mkdir -p ~/.hermes/namada_wallet/$CHAIN_A_ID -mkdir -p ~/.hermes/namada_wallet/$CHAIN_B_ID -``` - - -This step is only needed for namada chains. For cosmos based chains, it is advised to add the key directly to hermes. -```bash copy -./hermes --config $HERMES_CONFIG keys add --chain "" --key-file "" --overwrite -``` - - ### Create the relayer account -On each chain, there must be a `relayer` account. On a namada chain, this can be done by running +On each chain, there must be a `relayer` account. The alias should be the same as `chains.key_name` in the config. On a namada chain, this can be done by running ```bash copy namadaw key gen --alias relayer ``` This will generate a key for the relayer account. The key will be stored in the `wallet.toml` that is found in the [base directory](./ledger/base-directory.mdx) of the node, inside the `chain-id` folder. For example, if the `chain-id` is `namada-test.0a4c6786dbda39f786`, the `wallet.toml` will be found in `$HOME/.local/share/namada/namada-test.0a4c6786dbda39f786/wallet.toml` (on a ubuntu machine where `base-dir` has not been set up properly). -It is now important to copy this wallet file into the `namada_wallet` directory that was created above, for each chain. Continuing this example, the first wallet can be copied by running: +The relayer account should have some balance to pay the fee of transactions. Before creating an IBC channel or relaying an IBC packet, you need to transfer the fee token to the relayer account. + +### Add the relayer key to Hermes +To sign each transaction, the relayer's key should be added to Hermes with `keys add` command in advance. It requires the `wallet.toml` which should have the key of `chains.key_name`. Once the key has been added, Hermes doesn't need the wallet anymore. ```bash copy -cp $HOME/.local/share/namada/$CHAIN_A_ID/wallet.toml ~/.hermes/namada_wallet/$CHAIN_A_ID/wallet.toml -# Make sure this is done for both wallets on each chain! +hermes --config $HERMES_CONFIG keys add --chain $CHAIN_ID --key-file $WALLET_PATH ``` +Hermes will store the key in `~/.hermes/keys/${CHAIN_ID}` as default. You can specify the directory by setting `chains.key_store_folder` in the config file. + + +If you want to use an encrypted key with a password, you have to set an environment variable `NAMADA_WALLET_PASSWORD_FILE` for the password file or `NAMADA_WALLET_PASSWORD` to avoid entering the password for each transaction submission. + + It is now possible to set up the client. ### Create IBC channel @@ -278,7 +264,7 @@ SUCCESS Channel { ## Start the relayer -Once you run Hermes, it monitors instances via the nodes and relays packets according to monitored events. +Once you run Hermes, it monitors chains via the nodes and relays packets according to monitored events. ```bash copy hermes --config $HERMES_CONFIG start ``` @@ -300,24 +286,24 @@ hermes --config $HERMES_CONFIG \ ### Transferring assets over IBC It is now possible to [transfer assets between the two chains.](../users/ibc.mdx) -## Set up local Namada instances using the hermes script -The script `setup-namada` will set up two instances with one validator node, copy necessary files for Hermes, and make an account for Hermes on each ledger. Also, it will make a Hermes' config file `config_for_namada.toml` in the `hermes` directory. +## Set up local Namada chains using the Hermes script +The script `setup-namada` will set up two chains with one validator node, copy necessary files for Hermes, and make an account for Hermes on each ledger. Also, it will make a Hermes' config file `config_for_namada.toml` in the `hermes` directory. First, you will need to export some environment variables: ```bash copy export NAMADA_DIR="" -export TAG="v1.6.0-namada-beta3" +export TAG="v1.7.1-namada-beta4" ``` ```bash copy git clone https://github.com/heliaxdev/hermes.git git checkout $TAG # The branch is the same as our Hermes cd hermes -./scripts/setup-namada $NAMADA_DIR $CHAIN_ID_A $CHAIN_ID_B +./scripts/setup-namada $NAMADA_DIR ``` -In this case, the user doesn't have to wait for sync. If the relayer account on each instance has enough balance, the user can create a channel and start Hermes immediately as explained [above](#create-ibc-channel). The user finds these chain IDs of the instances in the config file `config_for_namada.toml`. One can run `grep "id" ${HERMES_CONFIG}`. +In this case, the user doesn't have to wait for sync. If the relayer account on each instance has enough balance, the user can create a channel and start Hermes immediately as explained [above](#create-ibc-channel). The user finds these chain IDs of the chains in the config file `config_for_namada.toml`. One can run `grep "id" ${HERMES_CONFIG}`. ```bash copy # create a channel hermes --config $HERMES_CONFIG \ diff --git a/packages/docs/pages/operators/networks.mdx b/packages/docs/pages/operators/networks.mdx new file mode 100644 index 00000000..2b5710ef --- /dev/null +++ b/packages/docs/pages/operators/networks.mdx @@ -0,0 +1,8 @@ +# Starting Namada networks + +This guide will explore setting up Namada networks. + +It is broken into the following sections: + +* [Decentralised network setup](./networks/genesis-flow.mdx) +* [Local network setup](./networks/local-network.mdx) \ No newline at end of file diff --git a/packages/docs/pages/operators/networks/_meta.json b/packages/docs/pages/operators/networks/_meta.json new file mode 100644 index 00000000..fb0eb0e9 --- /dev/null +++ b/packages/docs/pages/operators/networks/_meta.json @@ -0,0 +1,4 @@ +{ + "genesis-flow": "Setting up a decentralised network", + "local-network": "Setting up a local network" +} \ 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 new file mode 100644 index 00000000..23901d6b --- /dev/null +++ b/packages/docs/pages/operators/networks/genesis-flow.mdx @@ -0,0 +1,15 @@ +# Setting up a decentarlised Namada network + +Setting up a decentralised 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/_meta.json b/packages/docs/pages/operators/networks/genesis-flow/_meta.json new file mode 100644 index 00000000..0573abb0 --- /dev/null +++ b/packages/docs/pages/operators/networks/genesis-flow/_meta.json @@ -0,0 +1,4 @@ +{ + "coordinator": "The network coordinator", + "participants": "Pre-genesis participants" +} \ No newline at end of file diff --git a/packages/docs/pages/operators/networks/genesis-flow/coordinator.mdx b/packages/docs/pages/operators/networks/genesis-flow/coordinator.mdx new file mode 100644 index 00000000..41de6a9e --- /dev/null +++ b/packages/docs/pages/operators/networks/genesis-flow/coordinator.mdx @@ -0,0 +1,47 @@ +import { Steps } from 'nextra-theme-docs' + +## The network coordinator + +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) + +### Setup + +The genesis ceremony preperation includes creating a coordinated location for the pre-genesis network participants to submit their public keys. The network coordinator is responsible for setting up this location. Conventionally, the network coordinator will host a git repository that allows the pre-genesis network participants to submit their public keys. The network coordinator must ensure that the git repository is publicly accessible and that the pre-genesis network participants are able to submit their public keys in a secure manner. + +Further, the network coordinator is responsible for making clear timelines for the various steps in the genesis ceremony. The network coordinator must ensure that the pre-genesis network participants are aware of the timelines and that they are able to submit their public keys, transactions, and be online in due time. + + + +### Collecting pre-genesis public keys + +The ceremony begins by the network coordinator collecting the public keys of the pre-genesis network participants. The network coordinator must ensure that the total number of pre-genesis public keys collected is equal to the total number of pre-genesis network participants. + +Conventionally, the network coordinator hosts a git repository that allows the pre-genesis network participants to submit their public keys. The network coordinator must ensure that the git repository is publicly accessible and that the pre-genesis network participants are able to submit their public keys in a secure manner. + +### 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 coordinaotor 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. + + +### 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. + +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. + +The `transactions.toml` file is validated by the network coordinator to ensure that each transaction has been correctly signed by each pre-genesis network participant. The network coordinator must ensure that the `transactions.toml` file is valid before proceeding to the next step. + +### 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. + + + \ No newline at end of file diff --git a/packages/docs/pages/operators/networks/genesis-flow/participants.mdx b/packages/docs/pages/operators/networks/genesis-flow/participants.mdx new file mode 100644 index 00000000..1780c203 --- /dev/null +++ b/packages/docs/pages/operators/networks/genesis-flow/participants.mdx @@ -0,0 +1,204 @@ +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 key 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] +bengt = "ED25519_PK_PREFIXtpknam1qq2vscpcvhdwht9tldj9ntxnknandhnerhzd6d42xqzukw2kpcfpudh3dl2" + +... + +[addresses] +bengt = "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 ouptut 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=tnam1q8lsztqqhpjxdwzw88mqqc2mun7dvpx +``` + +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, simply add multiple `--aliases` flags to the command: + +```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 --aliases $ALIAS2 --aliases $ALIAS3 +``` + +The command will ouptut 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="" +SELF_BOND_AMOUNT=1000000 # Set this to the amount of NAM you want to self-bond +VALIDATOR_ALIAS="" +namadac utils init-genesis-validator \ + --address $ESTABLISHED_ACCOUNT_ADDRESS \ + --alias $VALIDATOR_ALIAS \ + --net-address "127.0.0.1:26656" \ + --commission-rate 0.05 \ + --max-commission-rate-change 0.01 \ + --self-bond-amount $SELF_BOND_AMOUNT \ + --email $EMAIL \ + --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 `--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 initialised 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 +``` + +### 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/local-network.en-US.mdx b/packages/docs/pages/operators/networks/local-network.mdx similarity index 95% rename from packages/docs/pages/operators/local-network.en-US.mdx rename to packages/docs/pages/operators/networks/local-network.mdx index ee88443e..5c2a809d 100644 --- a/packages/docs/pages/operators/local-network.en-US.mdx +++ b/packages/docs/pages/operators/networks/local-network.mdx @@ -1,10 +1,10 @@ -import Expandable from "../../components/Expandable"; +import Expandable from "../../../components/Expandable"; # Spinning up a local network ## Prerequisites -Namada must be installed [from source](../introduction/install/source.mdx) in order to run a local network. +Namada must be installed [from source](../../introduction/install/source.mdx) in order to run a local network. There is a script that has been written specifically for this purpose, which can be found under `MakeFile` in the root directory. diff --git a/packages/docs/pages/operators/validators.en-US.mdx b/packages/docs/pages/operators/validators.en-US.mdx index ed611d97..82547a08 100644 --- a/packages/docs/pages/operators/validators.en-US.mdx +++ b/packages/docs/pages/operators/validators.en-US.mdx @@ -17,6 +17,6 @@ In addition, the validator node must meet the [minimum hardware requirements](./ #### Steps -See these steps for [setting up a genesis validator](./validators/genesis-validator-setup.mdx). +See these steps for [setting up a genesis validator](./validators/validator-setup.mdx). -See these steps for [setting up a post-genesis validator](./validators/post-genesis-validator-setup.mdx). \ No newline at end of file +See these steps for [setting up a post-genesis validator](./validators/validator-setup.mdx). \ No newline at end of file diff --git a/packages/docs/pages/operators/validators/_meta.json b/packages/docs/pages/operators/validators/_meta.json index 6efd10f5..c41995de 100644 --- a/packages/docs/pages/operators/validators/_meta.json +++ b/packages/docs/pages/operators/validators/_meta.json @@ -1,7 +1,5 @@ { - "genesis-validator-setup": "Genesis validator setup", - "run-your-genesis-validator": "Running a genesis validator", - "post-genesis-validator-setup": "Initialising a validator account", + "validator-setup": "Validator setup", "staking": "Staking", "proof-of-stake": "Proof of stake" } diff --git a/packages/docs/pages/operators/validators/genesis-validator-setup.en-US.mdx b/packages/docs/pages/operators/validators/genesis-validator-setup.en-US.mdx deleted file mode 100644 index 63dbaac8..00000000 --- a/packages/docs/pages/operators/validators/genesis-validator-setup.en-US.mdx +++ /dev/null @@ -1,128 +0,0 @@ -import { Callout } from 'nextra-theme-docs' - -# 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](../hardware.mdx) 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](#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: - -#### Before `v0.25.0` - -``` bash -export VALIDATOR_ALIAS="CHOOSE_A_NAME_FOR_YOUR_VALIDATOR" -export PUBLIC_IP="LAPTOP_OR_SERVER_IP" -namada client utils init-genesis-validator \ - --alias $VALIDATOR_ALIAS \ - --max-commission-rate-change 0.01 \ - --commission-rate 0.05 \ - --net-address $PUBLIC_IP:26656 -``` - -#### After `v0.25.0` - -##### 1.1 Generate your keys - -``` bash -export KEY_ALIAS="CHOOSE_A_NAME_FOR_YOUR_VALIDATOR-KEY" -namadaw key gen --pre-genesis --alias $ALIAS -``` -##### 1.2 Generate your validator - - -Before pre-genesis validator tomls are collected, the public keys must first be collected, and balances given to each key. This is done by the network organizer. - - -``` bash -export VALIDATOR_ALIAS="CHOOSE_A_NAME_FOR_YOUR_VALIDATOR" -export PUBLIC_IP="LAPTOP_OR_SERVER_IP/DNS" -export BALANCE_ON_KEY="The amount of tokens allocated at genesis to the key" # For testnets, usually 1000000000 -export EMAIL="The email address for validator communications" # Required field, but can be a dummy email (although not recommended) -namada client utils init-genesis-validator \ - --source $KEY_ALIAS \ - --alias $VALIDATOR_ALIAS \ - --net-address "${PUBLIC_IP}:26656" \ - --commission-rate 0.05 \ - --max-commission-rate-change 0.01 \ - --transfer-from-source-amount $BALANCE_ON_KEY \ - --self-bond-amount 1000000 \ - --email $EMAIL -``` - -### 2. After generating your keys, the command will print something like this: - -#### Before `v0.25.0` - - -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 -```text copy -Pre-genesis TOML written to $HOME/.local/share/namada -``` - -##### MacOS -```text copy -Pre-genesis TOML written to /Users/$USER/Library/Application\ Support/Namada -``` - -#### After `v0.25.0` - -##### Linux -```text copy -Pre-genesis transactions TOML written to $HOME/.local/share/namada/pre-genesis/$VALIDATOR_ALIAS/transactions.toml -``` - -##### MacOS -```text copy -Pre-genesis transactions TOML written to /Users/$USER/Library/Application Support/Namada/pre-genesis/$VALIDATOR_ALIAS/transactions.toml -``` - -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. - -### 3. You can print the validator.toml by running: - -#### Before `v0.25.0` -### Linux -```shell copy -cat $HOME/.local/share/namada/pre-genesis/$VALIDATOR_ALIAS/validator.toml -``` - -### MacOS -```shell copy -cat $HOME/Library/Application\ Support/Namada/pre-genesis/$VALIDATOR_ALIAS/validator.toml -``` - -#### After `v0.25.0` -### Linux -```shell copy -cat $HOME/.local/share/namada/pre-genesis/$VALIDATOR_ALIAS/validator-wallet.toml -``` - -### MacOS -```shell copy -cat $HOME/Library/Application\ Support/Namada/pre-genesis/$VALIDATOR_ALIAS/validator-wallet.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. -- Tendermint node key: Can be used to sign transactions on the PoS staking rewards account. -- Protocol key pair: 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. (No longer needed after `v0.26.0`) -- Consensus key: Used in CometBFT consensus layer. Currently, this key is written to a file which is read by CometBFT. -- Eth hot key: Used for validating eth-bridge transactions. (No longer after `v0.26.0`) -- Eth cold key: Used for emergency eth-bridge operations. \ No newline at end of file diff --git a/packages/docs/pages/operators/validators/proof-of-stake.en-US.mdx b/packages/docs/pages/operators/validators/proof-of-stake.en-US.mdx index 59f0c816..99fd8c78 100644 --- a/packages/docs/pages/operators/validators/proof-of-stake.en-US.mdx +++ b/packages/docs/pages/operators/validators/proof-of-stake.en-US.mdx @@ -24,4 +24,22 @@ In order to query the current epoch, the following command can be run: ```shell copy namada client epoch -``` \ No newline at end of file +``` + +## Slashing + +Validators on Namada are slashed for misbehavior. Automatic slashing conditions are defined by the CometBFT, but validators can also report misbehavior by other validators. If a validator is deemed to have misbehaved, they are slashed by a certain amount of their stake. The amount of stake slashed, as well as the time required for the slash to take effect (pipeline) is defined by protocol parameters. + +## Jailing + +Validators on Namada are jailed for either misbehaviour or for being offline for too long. If a number of blocks pass (also defined in the protocol parameters under `liveness_window_check`) in which none have been signed by the validator in question, the validator is jailed. + +When a validator is jailed, they are unable to participate in the consensus protocol. A validator is jailed for at least the pipeline amount of epochs, but must be unjailed manually by the validator. This is done by submitting an `unjail-validator` command. + +```bash +VALIDATOR_ALIAS="" +SIGNING_KEYS="" +namada client unjail-validator --validator $VALIDATOR_ALIAS --signing-keys $SIGNING_KEYS +``` + +If successful, the validator will be unjailed after the pipeline amount of epochs, and is able to participate in the consensus protocol again. diff --git a/packages/docs/pages/operators/validators/run-your-genesis-validator.en-US.mdx b/packages/docs/pages/operators/validators/run-your-genesis-validator.en-US.mdx deleted file mode 100644 index 45fd53ff..00000000 --- a/packages/docs/pages/operators/validators/run-your-genesis-validator.en-US.mdx +++ /dev/null @@ -1,32 +0,0 @@ -# Run your node as a genesis validator - -Once the `CHAIN_ID` has been released, it is possible to join the testnet. If the node joining is registered as a genesis-validator in the genesis file, it will be able to participate in the consensus and produce blocks from the start of the chain. - -#### Joining the network -As a genesis validator, it is then possible to join the network with the `CHAIN_ID` distributed. Let's say this `CHAIN_ID` is `namada-mainnet`. - -In this case, the genesis validator can join the network with: - -``` bash copy -export CHAIN_ID="namada-mainnet" -namada client utils join-network \ ---chain-id $CHAIN_ID --genesis-validator $ALIAS -``` - -#### Start your node and sync -```bash copy -NAMADA_LOG=info CMT_LOG_LEVEL=p2p:none,pex:error NAMADA_CMT_STDOUT=true namada node ledger run -``` -Optional: If you want more logs, you can instead run -```bash copy -NAMADA_LOG=debug CMT_LOG_LEVEL=p2p:none,pex:error NAMADA_CMT_STDOUT=true namada node ledger run -``` -And if you want to save your logs to a file, you can instead run: -```bash copy -TIMESTAMP=$(date +%s) -NAMADA_LOG=debug CMT_LOG_LEVEL=p2p:none,pex:error NAMADA_CMT_STDOUT=true namada node ledger run &> logs-${TIMESTAMP}.txt -tail -f -n 20 logs-${TIMESTAMP}.txt ## (in another shell) -``` -#### If started correctly you should see the following log: -`[] This node is a validator ...` - diff --git a/packages/docs/pages/operators/validators/post-genesis-validator-setup.en-US.mdx b/packages/docs/pages/operators/validators/validator-setup.mdx similarity index 63% rename from packages/docs/pages/operators/validators/post-genesis-validator-setup.en-US.mdx rename to packages/docs/pages/operators/validators/validator-setup.mdx index b3a4499f..dcb991d9 100644 --- a/packages/docs/pages/operators/validators/post-genesis-validator-setup.en-US.mdx +++ b/packages/docs/pages/operators/validators/validator-setup.mdx @@ -1,19 +1,43 @@ import { Callout } from 'nextra-theme-docs' -# Generating a validator account +# Setting up a validator account + +## Genesis validators + +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](../hardware.mdx) for running a validator node +- an associated public IPv4 address with ports 26656 reachable from anywhere for P2P connections + +### 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. + + +## Post-genesis validators + +Post-genesis validators are validators that become initialised after the genesis block. This is the most common way of becoming a validator, and is the method described in this section. Note the use of the placeholder `aliace` for the alias parameter. This is a completely configurable parameter, and should just refer to the alias of the key/address generated. + +### Initialising a new validator account + +The user must first generate a key pair for their validator account. + ```bash copy KEY_ALIAS="aliace" -namada wallet address gen --alias $KEY_ALIAS +namada wallet key gen --alias $KEY_ALIAS ``` Now choose a name for your validator: ```bash copy export VALIDATOR_ALIAS="" +export EMAIL="" ``` A validator account requires additional keys compared to a user account, so start by initialising a validator account: @@ -24,9 +48,23 @@ namada client init-validator \ --account-keys $KEY_ALIAS \ --signing-keys $KEY_ALIAS \ --commission-rate \ - --max-commission-rate-change + --max-commission-rate-change \ + --email $EMAIL +``` + +It is also possible to convert an established account to a validator account: + +```bash copy +namada client become-validator \ + --address $ESTABLISHED_ACCOUNT_ADDRESS \ + --signing-keys $KEY_ALIAS \ + --commission-rate \ + --max-commission-rate-change \ + --email $EMAIL ``` +The validator account will now have the same alias as the established account. + When initialising a validator account, it is also mandatory to specify both the `commission-rate` charged by the validator for delegation rewards (in decimal format) as well as the `maximum-commission-rate-change` per epoch in the `commission-rate`. Both are expressed as a decimal between 0 and 1. The standard for mainnet will be set by social consensus, but for testnets, the standard has been `0.01` and `0.05`, respectively. This command will generate the keys required for running a validator: @@ -38,10 +76,12 @@ Then, it submits a transaction to the ledger that generates the new validator ac The keys and the alias of the address will be saved in your wallet. +### Start validating + **IMPORTANT** -Our 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 as before. +The 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 as before. ```shell copy diff --git a/packages/docs/pages/users/public-goods-stewards/electing.en-US.mdx b/packages/docs/pages/users/public-goods-stewards/electing.en-US.mdx index 28e567dd..66cad2c5 100644 --- a/packages/docs/pages/users/public-goods-stewards/electing.en-US.mdx +++ b/packages/docs/pages/users/public-goods-stewards/electing.en-US.mdx @@ -35,12 +35,10 @@ The `steward_proposal.json` file contains the information about the proposal. It "voting_end_epoch": 6, "grace_epoch": 12, }, - "data" : [ - { - "action" : "add", - "address" : "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn" - } - ] + "data" : { + "add" : "atestatest1v4ehgw36g4pyg3j9x3qnjd3cxgmyz3fk8qcrys3hxdp5xwfnx3zyxsj9xgunxsfjg5u5xvzyzrrqtn", + "remove": [] + } } ``` @@ -90,4 +88,4 @@ Through the CLI it can be done with the command: namadac resign-steward --steward my-steward-address ``` -Read more about the other methods of losing stewardship in the [specs](https://specs.namada.net/economics/public-goods-funding/becoming-a-steward#losing-stewardship-status). \ No newline at end of file +Read more about the other methods of losing stewardship in the [specs](https://specs.namada.net/economics/public-goods-funding/becoming-a-steward#losing-stewardship-status).