diff --git a/docs/validators/admin-guide/configuring.mdx b/docs/validators/admin-guide/configuring.mdx index 066d28569..c3f47a0d9 100644 --- a/docs/validators/admin-guide/configuring.mdx +++ b/docs/validators/admin-guide/configuring.mdx @@ -255,6 +255,31 @@ Additionally, configuring `PREFERRED_PEER_KEYS` with the keys from your quorum s Without those settings, your validator depends on other nodes on the network to forward you the right messages, which is typically done as a best effort. +### Impact of Validator Quality on Nomination + +The Stellar Consensus Protocol uses validator quality levels in determining which validator should nominate the next transaction set for inclusion in a ledger. This process of choosing the validator that will nominate the next transaction set is called _leader election_. To start, the leader election algorithm assigns organizations and validators weights as follows: + +- Let $O_q$ be the set of all organizations with a given quality level $q$. $O_q$ includes all explicitly defined organizations in the configuration file at quality level $q$ as well as a single virtual organization containing $O_r$ where $r$ is the next quality level below $q$. +- All organizations of some quality level $q$ have weight $w_q$. +- If an organization of quality level $q$ has $n$ nodes, then the weight of each node is $\frac{w_q}{n}$. +- $w_\top$ is `1`, where $\top$ is the highest quality value assigned to any organization. +- $w_\texttt{LOW} = 0$. + - This allows a validator to participate in some SCP activities without being trusted to nominate transaction sets. +- For all other $q$ values, $w_q = \frac{w_p}{10 \times \left|\ O_p\ \right|}$ where $p$ is the next quality value above $q$. + +The leader election algorithm then assigns each validator a probability of winning leader election of the validator's weight divided by the total weight of all validators. Altogether, these win probabilities ensure that Stellar Core's leader election algorithm has the following properties: + +1. Higher quality organizations have a greater chance of winning leader election than lower quality organizations. +2. Organizations of equal quality have an equal chance of winning leader election. + +#### Validator Nomination Weight Example + +Let there be 3 `HIGH` quality organizations, 2 `MEDIUM` quality organizations, and 1 `LOW` quality organization. The weight of each organization is as follows: + +- Each `HIGH` quality organization has a weight of `1`. +- Each `MEDIUM` quality organization has a weight of `1/(10 * 3)`, or `1/30`. +- Each `LOW` quality organization has a weight of `0`. + [complete example config]: https://github.com/stellar/stellar-core/blob/master/docs/stellar-core_example.cfg [example testnet config]: https://github.com/stellar/quickstart/blob/master/testnet/core/etc/stellar-core.cfg [example mainnet config]: https://github.com/stellar/packages/blob/master/docs/examples/pubnet-validator-full/stellar-core.cfg