Skip to content

Commit

Permalink
Add more generic description of nomination weight algo + example
Browse files Browse the repository at this point in the history
  • Loading branch information
bboston7 committed Oct 11, 2024
1 parent 3a12867 commit 08e671f
Showing 1 changed file with 14 additions and 4 deletions.
18 changes: 14 additions & 4 deletions docs/validators/admin-guide/configuring.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -259,17 +259,27 @@ Without those settings, your validator depends on other nodes on the network to

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:

- Each `HIGH` quality organization has a weight of `1`.
- Each `MEDIUM` quality organization has a weight of `1/(10*n)` where `n` is the number of `HIGH` quality organizations.
- Each `LOW` quality organization has a weight of `0`.
- 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.
- Each validator in an organization has a weight of `o/v` where `o` is the organization's weight and `v` is the total number of validators in that organization.
- 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
Expand Down

0 comments on commit 08e671f

Please sign in to comment.