diff --git a/packages/docs/pages/operators/validators/_meta.json b/packages/docs/pages/operators/validators/_meta.json index 4763b468..da8dba24 100644 --- a/packages/docs/pages/operators/validators/_meta.json +++ b/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" } \ No newline at end of file diff --git a/packages/docs/pages/operators/validators/validator-actions.mdx b/packages/docs/pages/operators/validators/validator-actions.mdx index fe5e155d..223df242 100644 --- a/packages/docs/pages/operators/validators/validator-actions.mdx +++ b/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. diff --git a/packages/docs/pages/operators/validators/validator-sets.mdx b/packages/docs/pages/operators/validators/validator-sets.mdx new file mode 100644 index 00000000..42c60131 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/packages/docs/pages/users/governance/governance-actions.mdx b/packages/docs/pages/users/governance/governance-actions.mdx index 8658634c..5650234b 100644 --- a/packages/docs/pages/users/governance/governance-actions.mdx +++ b/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).