Ian/update operators section

packages/docs/pages/operators.mdx

@@ -1,7 +1,7 @@
 # Operators Guide
 
-This guide is intended for operators of Namada full nodes. This includes both full nodes as well as validator nodes.
-The guide assumes that you have already installed the node and are familiar with the basics of running a node.
+This section of the guide is intended for operators of Namada full nodes and validator nodes.
+It assumes you have already completed the steps to [install Namada](./introduction/install.mdx).
 
 ## Table of Contents
 

packages/docs/pages/operators/ledger.mdx

@@ -1,41 +1,36 @@
 import { Callout } from 'nextra-theme-docs'
 
-# The Namada Ledger
+# Running a Full Node
+This section of the guide covers running a full (non-consensus) node. For information on running a validator node, see [Validator setup](./validators/validator-setup.mdx).  
 
-In order to make any interactions with the Namada blockchain through the Namada *client* `namadac`, the ledger must be running. 
+A step-by-step guide to setting up and running a full node can be found [here](./ledger/running-a-full-node.mdx).
 
-To start a local Namada ledger node, one can run:
+## The Namada ledger
+
+By starting the ledger process, your node will attempt to connect with network peers and sync to the latest block:
 
 ```shell copy
-namada ledger
+namada node ledger run
 ```
 
 <Callout>
 **Note**: You must have [joined a network](../networks.mdx) before you start the ledger. It throws an error if no network has been configured.
-
-The node will attempt to connect to the persistent validator nodes and other peers in the network, and synchronize to the latest block.
-
-By default, the ledger will store its configuration and state in your [base directory](./ledger/base-directory.mdx). 
-You can use the `--base-dir` CLI global argument or `BASE_DIR` environment variable to change it.
-
-Assuming you do not have a custom base_dir, you can export the BASE_DIR environment variable as follows:
-
-```shell copy
-export BASE_DIR=$(namadac utils default-base-dir)
-```
 </Callout>
 
-When the ledger is run for the first time, the MASP-parameters will be downloaded. This is essential for producing the zero knowledge proofs required to make shielded transactions.
+### MASP parameters
+When the ledger is run for the first time, the MASP-parameters will be downloaded. This is essential for producing the zero knowledge proofs required to make shielded transactions.  
+
+The default location of the MASP params is `$HOME/.masp-params`.
 
 ### The ledger wasm files
-The ledger will also download the genesis block, which contains the initial state of the blockchain.
+When running the `join-network` command, the ledger will also download the genesis files, which contain the initial state of the blockchain.
 The ledger also needs access to the built WASM files that are used in the genesis block. 
 These files are included in release and shouldn't be modified, otherwise your node will fail with a consensus error on the genesis block. 
 By default, these are expected to be in the `wasm` directory inside the chain directory that's in the base directory, i.e `$BASE_DIR/$CHAIN_ID/wasm`.
 The wasm directory can also be set with the `--wasm-dir` CLI global argument, `NAMADA_WASM_DIR` [environment variable](./ledger/env-vars.mdx) or the configuration file.
 
 ### Ledger configuration
-The ledger configuration is stored in `$BASE_DIR/$CHAIN_ID/config.toml` (with
+The [ledger configuration](./ledger/env-vars.mdx) is stored in `$BASE_DIR/$CHAIN_ID/config.toml` (with
 default `--base-dir`). It is created when you join the network. You can modify
 that file to change the configuration of your node. All values can also be set
 via [environment variables](./ledger/env-vars.mdx). 

packages/docs/pages/operators/ledger/_meta.json

@@ -1,6 +1,6 @@
 {
-    "env-vars": "Environment variables",
-    "running-a-full-node": "Setting up the full node",
+    "env-vars": "Node Configuration",
+    "running-a-full-node": "Full node step-by-step",
     "logging-config": "Logging configurations",
     "base-directory": "Base directory"
 }

packages/docs/pages/operators/ledger/base-directory.mdx

@@ -37,8 +37,21 @@ $HOME/Library/Application\ Support/Namada
 Within these folders, you should see the following files and folders:
 
 ```bash copy
-global-config.toml
-<some-chain-id>/
-<some-chain-id>.toml
-pre-genesis # If you are a pre-genesis validator
+.
+└── $BASE_DIR/
+    ├── global-config.toml
+    └── $CHAIN_ID/
+        ├── balances.toml
+        ├── chain.toml
+        ├── cometbft/
+        ├── config.toml
+        ├── db/
+        ├── parameters.toml
+        ├── tokens.toml
+        ├── transactions.toml
+        ├── tx_wasm_cache/
+        ├── validity_predicates.toml
+        ├── vp_wasm_cache/
+        ├── wallet.toml
+        └── wasm/
 ```

packages/docs/pages/operators/ledger/env-vars.mdx

@@ -1,9 +1,9 @@
 import { Callout } from 'nextra-theme-docs'
 import Expandable from "../../../components/Expandable";
 
-# Environment variables
+# Node Configuration
 
-By default, whenever the namada ledger is started, it will apply the confirguration found in the ledger configuration file.
+By default, whenever the namada ledger is started, it will apply the confirguration found in the ledger configuration file `$BASE_DIR/$CHAIN_ID/config.toml`.
 
 An example of a ledger configuration file is displayed below.
 
@@ -12,36 +12,39 @@ An example of a ledger configuration file is displayed below.
 wasm_dir = "wasm"
 
 [ledger]
-genesis_time = "2023-06-29T17:00:00+00:00"
-chain_id = "<namada-mainnet>"
+genesis_time = "2024-06-03T17:32:06+00:00"
+chain_id = "<chain-id>"
 
 [ledger.shell]
-base_dir = "/Users/fraccaman/Library/Application Support/Namada"
+base_dir = "/root/.local/share/namada/<chain-id>"
 storage_read_past_height_limit = 3600
 db_dir = "db"
 cometbft_dir = "cometbft"
 tendermint_mode = "Full"
 
 [ledger.cometbft]
 proxy_app = "tcp://127.0.0.1:26658"
-moniker = "1337-leet-1337"
+moniker = "technodrome"
+fast_sync = true
 db_backend = "goleveldb"
 db_dir = "data"
 log_level = "info"
 log_format = "plain"
 genesis_file = "config/genesis.json"
-node_key_file = "config/node_key.json"
-abci = "socket"
-filter_peers = false
 priv_validator_key_file = "config/priv_validator_key.json"
 priv_validator_state_file = "data/priv_validator_state.json"
 priv_validator_laddr = ""
+node_key_file = "config/node_key.json"
+abci = "socket"
+filter_peers = false
 
 [ledger.cometbft.rpc]
 laddr = "tcp://127.0.0.1:26657"
 cors_allowed_origins = []
 cors_allowed_methods = ["HEAD", "GET", "POST"]
 cors_allowed_headers = ["Origin", "Accept", "Content-Type", "X-Requested-With", "X-Server-Time"]
+grpc_laddr = ""
+grpc_max_open_connections = 900
 unsafe = false
 max_open_connections = 900
 max_subscription_clients = 100
@@ -89,27 +92,31 @@ max_batch_bytes = 0
 
 [ledger.cometbft.consensus]
 wal_file = "data/cs.wal/wal"
-double_sign_check_height = 0
-create_empty_blocks = true
-create_empty_blocks_interval = "0ms"
-peer_gossip_sleep_duration = "100ms"
-peer_query_maj23_sleep_duration = "2000ms"
 timeout_propose = "3000ms"
 timeout_propose_delta = "500ms"
 timeout_prevote = "1000ms"
 timeout_prevote_delta = "500ms"
 timeout_precommit = "1000ms"
 timeout_precommit_delta = "500ms"
 timeout_commit = "10000ms"
+double_sign_check_height = 0
+skip_timeout_commit = false
+create_empty_blocks = true
+create_empty_blocks_interval = "0ms"
+peer_gossip_sleep_duration = "100ms"
+peer_query_maj23_sleep_duration = "2000ms"
+
+[ledger.cometbft.storage]
+discard_abci_responses = false
 
 [ledger.cometbft.tx_index]
 indexer = "null"
 
 [ledger.cometbft.instrumentation]
-prometheus = false
+prometheus = true
 prometheus_listen_addr = ":26660"
 max_open_connections = 3
-namespace = "namada_tm"
+namespace = "tendermint"
 
 [ledger.cometbft.statesync]
 enable = false
@@ -119,13 +126,25 @@ trust_hash = ""
 trust_period = "168h0m0s"
 discovery_time = "15000ms"
 temp_dir = ""
+
+[ledger.cometbft.fastsync]
+version = "v0"
+
+[ledger.ethereum_bridge]
+mode = "RemoteEndpoint"
+oracle_rpc_endpoint = "http://127.0.0.1:8545"
+channel_buffer_size = 1000
 ```
 </Expandable>
 
-However, it is possible to override the configuration by setting environment variables.
-Any variable found in the config can be accessed through environment variables that are constructed in the below manner.
+<Callout>
+CometBFT has its own `config.toml` located inside the `cometbft` directory, however it should not be edited directly.
+</Callout>
 
 ### Constructing environment variables
+It is possible to override the configuration by setting environment variables; these will take precedence over any existing settings in `config.toml`.
+Any variable found in the config can be accessed through environment variables that are constructed in the below manner.  
+
 Names of the recognized environment variables are derived from the configuration keys by:
 
 1. Prepend `NAMADA_` to the key

packages/docs/pages/operators/ledger/running-a-full-node.mdx

@@ -1,16 +1,41 @@
 import { Callout } from 'nextra-theme-docs'
+import { Steps } from 'nextra-theme-docs'
 
 # Full Node Setup
-Before starting a full node, the unique identifier of the `chain-id` will be needed, which will be released as soon as the genesis file is ready. 
+This section details the setup procedure for a full node. If you intend to run a validator node, please see the [Validator setup](../validators/validator-setup.mdx) guide instead.
 
+### Prerequisites
+- A machine that meets the [requirements](../hardware.mdx) for a full node
+- An associated public IPv4 address with port 26656 reachable from anywhere for P2P connections 
+- You have already [installed](../../introduction/install.mdx) Namada and its prerequisites
+- You know the unique `chain-id` identifier of the network you wish to join. The chain-id is publicly released once the genesis files have been prepared
+
+<Steps>
 ### Join the network
-Once the `chain-id` has been distributed, it is possible to join the network with the `CHAIN_ID`:
+Once the `chain-id` has been distributed, it is possible to [join the network](../networks.mdx) with the `CHAIN_ID`. This step will download the `.tar.gz` archive 
+containing the genesis files for the chain and initialize the node store in your [`BASE_DIR`](../ledger/base-directory.mdx).
 ```bash copy
   export CHAIN_ID="namada-mainnet" ## (replace with the actual chain-id)
-  NAMADA_NETWORK_CONFIGS_SERVER="https://github.com/anoma/namada-shielded-expedition/releases/download/shielded-expedition.88f17d1d14" namada client utils join-network --chain-id $CHAIN_ID
-  ```
+  namada client utils join-network --chain-id $CHAIN_ID --add-persistent-peers
+```
+<Callout>
+You can specify the location from which to download the genesis `.tar.gz` by exporting the environment variable `NAMADA_NETWORK_CONFIGS_SERVER` prior to running the `join-network` command. 
+This is useful for joining a community-run or local testnet.  
+
+By default, `join-network` will attempt to download the genesis files from `https://github.com/heliaxdev/anoma-network-config/releases/download/$CHAIN_ID`.
+</Callout>
+
+
+### Check/Update persistent peers
+To sync block data, your node will need to connect with existing peers on the network. Peer addresses can be provided in the node's [configuration](./env-vars.mdx) in 
+the field `persistent_peers`.  
+
+Your `persistent_peers` entry will need to contain at least one peer which is active and accepting incoming connections (the more, the better). If you used the 
+`--add-persistent-peers` flag during the join-network step, your persistent peers will be pre-populated with the addresses of the genesis validators. However, if you're [having trouble](../troubleshooting.mdx) 
+syncing, you may wish to check the Discord server for an updated list.
 
 ### Start your node and sync
+This command will start syncing your node with the network (an environment variable is being used here to set the [logging configuration](./logging-config.mdx)):
 ```bash copy
   CMT_LOG_LEVEL=p2p:none,pex:error namada node ledger run
 ```
@@ -25,18 +50,39 @@ NAMADA_LOG=info CMT_LOG_LEVEL=p2p:none,pex:error NAMADA_CMT_STDOUT=true namada n
 tail -f -n 20 logs-${TIMESTAMP}.txt ## (in another shell)
 ```
 
-### Running namada as a systemd service
+### Done!
+You should soon see messages similar to the following in your logs to indicate that your node has begun syncing blocks:
+```bash copy
+INFO namada_node::shell: Committed block hash: 0c56ebc5ae17ef503c675ad8a9b255e69258e7e4915f91e161f98d3b0040a0c1, height: 2650
+committed state                              module=state height=2650 num_txs=0 app_hash=0C56EBC5AE17EF503C675AD8A9B255E69258E7E4915F91E161F98D3B0040A0C1
+indexed block exents                         module=txindex height=2650
+```
+
+You can also easily check your node's last committed block with the following command:
+```
+# namadac block
+Last committed block height: 8612, time: 2024-06-04T18:17:06.136117438+00:00
+```
+By comparing it with the current height of the chain from a public source (such as a block explorer), you can monitor how your node is progressing.  
+
+If your node does not show indications of syncing, proceed to the [troubleshooting](../troubleshooting.mdx) section.
+</Steps>
+## Running the `namada ledger` as a systemd service
 <Callout type="info">
 The below script is a community contribution by Encipher88, and currently only works on Ubuntu machines.
 It has served useful for many validators.
 </Callout>
+
+For operators using Ubuntu, it is common to use the `systemd` service manager to run the ledger process in the background. Advantages of this method 
+include automatic restart upon crash and integrated logging.  
+
 The below assumes you have installed namada from source, with `make install`. It at least assumes the respective binaries are in `/usr/local/bin/`.
 
 ```bash copy
 which namada ## (should return /usr/local/bin/namada)
 ```
 
-The below makes a service file for systemd, which will run namada as a service. This is useful for running a node in the background, and also for auto-restarting the node if it crashes.
+We define a new process as a systemd service by creating a `unit file` in `/etc/systemd/system/`:
 ```bash copy
 sudo tee /etc/systemd/system/namadad.service > /dev/null <<EOF
 [Unit]
@@ -57,7 +103,7 @@ LimitNOFILE=65535
 WantedBy=multi-user.target
 EOF
 ```
-Enable the service with the below commands:
+Enable the service with the below commands. This sets the service to start automatically on system reboot.
 ```bash copy
 sudo systemctl daemon-reload
 sudo systemctl enable namadad
@@ -79,6 +125,4 @@ sudo systemctl restart namadad
 - Show node logs
 ```bash copy
 sudo journalctl -u namadad -f -o cat
-```
-
-
+```

packages/docs/pages/operators/validators.mdx

@@ -1,19 +1,36 @@
 # Validators on Namada
 
-Namada is a proof-of-stake blockchain, which means that the validators are the ones who are responsible for both voting on state-transitions and proposing new blocks.
+Namada is a proof-of-stake blockchain, which means that the validators are the ones who are responsible for both voting on state-transitions and proposing new blocks.  
 
-### What is a genesis validator? How does it differ from a post-genesis Validator?
+Validating on Namada is permissionless; the only requirement is that a validator has sufficient [stake](./validators/staking.mdx) bonded to qualify for the active 
+consensus set.  
 
-A (pre-)genesis validator is a validator who is proposed to be a validator in the genesis block of the blockchain. If the genesis file is accepted by the network, then the (pre-)genesis validators are able to conduct validating activities on the blockchain, with the stake specified in the genesis file. These validators are setup with the correct consensus keys, which must match those specified in the genesis file.
+Active validators not meeting a liveness threshold (by signing a specified percentage of recent blocks) are subject to [jailing](./validators/jailing.mdx) for 
+inactivity. Validators who double-sign are subject to [cubic slashing](https://specs.namada.net/modules/proof-of-stake/cubic-slashing).
 
-A post-genesis validator, on the other hand, is a validating account which was created sometime after the genesis block. These accounts are initiated by the `init-validator` command.
+### Pre-genesis vs Post-genesis validators
+The procedure for initializing a validator differs on whether it's done before or after the genesis block of the network.
+- A pre-genesis validator is a validator who is proposed to be a validator in the genesis block of the blockchain. If the genesis file is accepted by the network, 
+then the pre-genesis validators are able to conduct validating activities on the blockchain, with the stake specified in the genesis file, 
+from the very first block. These validators are setup with the correct consensus keys, which must match those specified in the genesis file. The procedure for a 
+pre-genesis is slightly more involved because it involves generating and signing a pre-genesis transaction and coordinating offchain with the community for inclusion in the 
+proposed genesis block.
+
+- A post-genesis validator, on the other hand, is a validating account which was created sometime after the genesis block. The procedure for initializing a 
+post-genesis validator is to begin by [syncing a full node](./ledger/running-a-full-node.mdx) and then instantiate a validator account with the 
+`init-validator` command.
 
 ### How do I become a validator?
 
-#### Pre-requisites
-Validators require stake in the form of NAM in order to participate in the consensus process. The amount of stake required is specified in the genesis file. In order to become a validator, you must have at least the minimum amount of stake required.
+#### Hardware requirements
+A validator node must meet the [minimum hardware requirements](./hardware.mdx), which may be higher than those of a full node.
 
-In addition, the validator node must meet the [minimum hardware requirements](./hardware.mdx).
+#### Stake requirements
+Validators require stake in the form of NAM in order to participate in the consensus process. There are two stake thresholds to keep in mind: 
+- There are a limited number of validating slots in the active consensus set, as specified by the genesis file parameter `max_validator_slots`. For example, if
+`max_validator_slots = 100`, then you must rank within the top 100 active validators by stake to participate in consensus.
+- Additionally, a minimum stake amount is specified by the genesis file parameter `validator_stake_threshold`. You must have at least this amount of stake to 
+participate in consensus, regardless of whether the active set is full.
 
 #### Steps
 
@@ -22,9 +39,10 @@ See these steps for [setting up a genesis validator](./networks/genesis-flow/par
 See these steps for [setting up a post-genesis validator](./validators/validator-setup.mdx).
 
 
-## Outline
+## Contents
 The validator docs describe the process and actions available to validators on the Namada blockchain. The following is a list of the topics covered in the validator docs:
 - [Validator setup](./validators/validator-setup.mdx)
 - [Staking](./validators/staking.mdx)
 - [Validator actions](./validators/validator-actions.mdx)
-- [Jailing](./validators/jailing.mdx)
+- [Jailing](./validators/jailing.mdx)
+- [Cubic proof of stake](./validators/proof-of-stake.mdx)