Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add description of nomination leader election algorithm #990

Merged
merged 2 commits into from
Oct 21, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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