Skip to content

Commit

Permalink
Add description of nomination leader election algorithm (#990)
Browse files Browse the repository at this point in the history
* Add description of nomination leader election algorithm

Part of stellar/stellar-core#4387

This change adds a section to the admin guide explaining the impact of
validator quality levels on SCP nomination leader election.

* Add more generic description of nomination weight algo + example
  • Loading branch information
bboston7 authored Oct 21, 2024
1 parent 0ad1667 commit 76d30f8
Showing 1 changed file with 25 additions and 0 deletions.
25 changes: 25 additions & 0 deletions docs/validators/admin-guide/configuring.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 76d30f8

Please sign in to comment.