Merge branch 'brent/validator-sets' (#378)

Validator sets desc

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

@@ -3,5 +3,6 @@
   "validator-setup": "Validator setup",
   "validator-actions": "Validator actions",
   "staking": "Staking",
+  "validator-sets": "Validator sets",
   "jailing": "Jailing"
 }

packages/docs/pages/operators/validators/validator-actions.mdx

@@ -49,21 +49,23 @@ namadac change-metadata --validator $VALIDATOR_ADDRESS \
 
 ### Deactivation and reactivation
 
-You can deactivate your validator with the `deactivate` command:
+You can manually remove your active validator from its validator set with the `deactivate` command:
 
 ```bash copy
 namadac deactivate-validator --validator $VALIDATOR_ADDRESS
 ```
-Once deactivated, the validator will no longer participate in the consensus protocol. 
-This will take effect at the end of the current epoch + `pipeline_length`. All bonds and delegations associated with the validator remain intact. 
-Delegators can still delegate to the validator, but as the validator is inactive, it will not generate staking rewards until it is reactivated.
+Once deactivated, the validator's state will become `inactive` and it will be removed from the validator set. 
+This will take effect at the beginning of `current epoch + pipeline_len`. All bonds associated with the validator remain intact, and new bonds and unbonds are still accepted. 
+From a user perspective, the deactivation of a validator would more commonly be a signal to unbond or redelegate to a new active or consensus validator.
 
-To reactivate your validator, use the `reactivate` command:
+Deactivating a `jailed` validator is prohibited, so such an operator would have to wait until they can `unjail` and then subsequently `deactivate`.
+
+To rejoin one of the validator sets and resume operations, use the `reactivate` command:
 
 ```bash copy
 namadac reactivate-validator --validator $VALIDATOR_ADDRESS
 ```
-This will reactivate the validator at the end of the current epoch + `pipeline_length`.
+The validator will be appropriately placed into one of the active validator sets at the beginning of `current_epoch + pipeline_len`.
 
 ### Changing the Consensus Key
 A validator's consensus key is used to sign blocks and participate in the CometBFT consensus protocol. 

packages/docs/pages/operators/validators/validator-sets.mdx

@@ -0,0 +1,37 @@
+import { Callout } from "nextra-theme-docs";
+
+# Validator sets
+
+Validators are grouped into sets that determine what behaviors are permitted to the validator and what data is stored on-chain.
+
+There are three validator sets - consensus, below-capacity, and below-threshold - that are discriminated by the stake / voting power of their respective validators.
+
+Two protocol parameters determine the composition of each validator set:
+- `max_validator_slots`: the maximum number of validators allowed to participate in consensus of any block
+- `validator_stake_threshold`: the minimum stake required to participate in consensus
+
+With this in mind, each of the three validator sets is defined:
+- **Consensus:** the set of validators that participates in consensus and voting on blocks. It contains the validators with the most voting power and cannot exceed `max_validator_slots` size. Validators in this set also require greater than `validator_stake_threshold` staked tokens.
+- **Below-capacity:** contains the validators who have greater than `validator_stake_threshold` stake but are not one of the top `max_validator_slots` validators. These are next in line to join the `consensus` set should space open up.
+- **Below-threshold:** contains all active validators with less than `validator_stake_threshold` stake
+
+Any validator that is in one of the three validator sets above can be considered an ***active*** validator.
+
+## Querying the validator set of a given validator
+
+A validator's `state` can indicate the validator set to which it belongs. This can be queried at the CLI with:
+```bash copy
+namadac validator-state --validator $VALIDATOR_ADDRESS --epoch $EPOCH
+```
+The `--epoch` argument is optional; if not provided, the `state` will be queried at the current epoch.
+
+## Jailed and Inactive validators
+
+Validators that are considered to be `jailed` or `inactive` cannot belong to one of the three aforementioned validator sets.
+Extra restrictions are enforced and other transactions may be required in order for these validators to become eligible for consideration in consensus.
+
+**Jailed** validators have committed protocol infractions or not maintained liveness requirements of consensus validators.
+They can only return to an active validator set by submitting a successful `unjail` transaction. See more details [here](./jailing.mdx). 
+
+**Inactive** validators have manually removed themselves from consideration in consensus activities with a `deactivate` transaction.
+This can typically signal that a validator has ceased operations and might signal delegators to unbond from it. See more details [here](./validator-actions.mdx#deactivation-and-reactivation).

packages/docs/pages/users/governance/governance-actions.mdx

@@ -78,7 +78,7 @@ The governance mechanism defines different criteria depending on proposal type i
 
 **Default proposals** require at least 2/3 of the total active voting power to have voted AND the `yay` voting power must be at least 2/3 of the combined `yay + nay` voting power.
 
-**PGF steward proposals** require at least 1/3 of the total acive voting power to have voted AND the `yay` voting power must be larger than the `nay` voting power.
+**PGF steward proposals** require at least 1/3 of the total active voting power to have voted AND the `yay` voting power must be larger than the `nay` voting power.
 
 **Funding proposals** are tallied differently depending on if the proposal author is a PGF steward:
 - Non-steward: the funding proposal is tallied in the same way as the PGF steward proposal (above).