Skip to content

Commit

Permalink
Rm content related to Im-Online Pallet (#5825)
Browse files Browse the repository at this point in the history 
* rm content

* re-added involuntary chilling

- edits

* rm

- imonline errors
- online message
- heartbeats

* rm heartbeat stuff

* Maciej feedback
  • Loading branch information
@filippoweb3
filippoweb3 authored May 3, 2024
1 parent 3d8be6f commit dcf5afa
Show file tree
Hide file tree
Showing 14 changed files with 43 additions and 184 deletions.
8 changes: 1 addition & 7 deletions docs/general/glossary.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -427,12 +427,6 @@ governance allows decisions to be made transparently. Note that there are a vari
algorithms for making these decisions, such as simple majority voting, adaptive quorum biasing, or
identity-based quadratic voting.

## Online Message

This is a message that is broadcast by a validator to verify to the network that the validator is
online, even if they haven't published a block this epoch. This is sometimes referred to as
"ImOnline".

## Polkadot OpenGov

Previously known as Governance v2 (Gov2) during early development,
Expand Down Expand Up @@ -647,7 +641,7 @@ attacker would need to attack the entire
## Slashing

The removal of a percentage of an account's DOT as a punishment for a validator acting maliciously
or incompetently (e.g., equivocating or remaining offline for an extended period).
or incompetently.

## Soft Fork

Expand Down
1 change: 0 additions & 1 deletion docs/learn/learn-cryptography.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,6 @@ broadcast this certificate via an extrinsic.
- BABE: sr25519
- BEEFY: ecdsa
- GRANDPA: ed25519
- I'm Online: sr25519
- Parachain Assignment: sr25519
- Parachain Validator: ed25519

Expand Down
14 changes: 6 additions & 8 deletions docs/learn/learn-nominator.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -249,11 +249,11 @@ example, `ZUG CAPITAL/07` is one of the numerous validators belonging to the ope

:::warning Single Operators with Multiple Validators

Recall that slashing is an additive function; the more validators offline or equivocating in a given
session, the harsher the penalties. Since validators that are controlled by a single operator are
more at risk of a "synchronized" failure, nominating them implies a greater risk of having a large
slash of your nominated funds. Generally, it is safer to nominate validators whose behavior is
independent of others in many ways (different hardware, geographic location, owner, etc.).
Recall that slashing is an additive function; the more validators equivocating in a given session,
the harsher the penalties. Since validators that are controlled by a single operator are more at
risk of a "synchronized" failure, nominating them implies a greater risk of having a large slash of
your nominated funds. Generally, it is safer to nominate validators whose behavior is independent of
others in many ways (different hardware, geographic location, owner, etc.).

:::

Expand Down Expand Up @@ -300,9 +300,7 @@ over the validators' websites to see who they are, what kind of infrastructure s
reputation, the vision behind the validator, and more.

Any problematic behavior must be taken seriously. An example of problematic behavior will be if a
validator is regularly offline. In this case, nominators most likely would get fewer rewards. If
many validators are [unreachable](learn-staking.md#unresponsiveness), such validators and
corresponding nominators will be slashed.
validator is regularly offline. In this case, nominators will get fewer rewards.

![Validator Stats](../assets/validator_stats.png)

Expand Down
62 changes: 5 additions & 57 deletions docs/learn/learn-staking-advanced.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -260,10 +260,10 @@ since staking participation is changing dynamically, it works well as an indicat

#### Commission Fees & Slashes

The network slashes a validator for a misbehavior (e.g. validator offline, equivocation, etc.) the
slashed amount is a fixed percentage (and not a fixed amount), which means that validators with more
stake get slashed more DOT. Again, this is done to provide nominators with an economic incentive to
shift their preferences and back less popular validators whom they consider to be trustworthy.
The network slashes a validator for a misbehavior. The slashed amount is a fixed percentage (and not
a fixed amount), which means that validators with more stake get slashed more DOT. Again, this is
done to provide nominators with an economic incentive to shift their preferences and back less
popular validators whom they consider to be trustworthy.

Also, note that each validator candidate is free to name their desired commission fee (as a
percentage of rewards) to cover operational costs. Since validators are paid the same, validators
Expand All @@ -275,57 +275,6 @@ reputation will be able to charge slightly higher commission fees (which is fair

## Slashing

### Unresponsiveness

For every session, validators will send an "I'm online" heartbeat to indicate they are live. If a
validator produces no blocks during an epoch and fails to send the heartbeat, it will be reported as
unresponsive. Slashing may occur depending on the repeated offenses and how many other validators
were unresponsive or offline during the epoch.

Validators should have a well-architected network infrastructure to ensure the node runs to reduce
the risk of slashing or chilling. A high availability setup is desirable, preferably with backup
nodes that kick in **only once the original node is verifiably offline** (to avoid double-signing
and being slashed for equivocation - see below). A comprehensive guide on validator setup is
available [here](../maintain/maintain-guides-secure-validator.md).

Here is the formula for calculating slashing due to unresponsiveness:

Let x = offenders, n = total no. validators in the active set

min((3 * (x - (n / 10 + 1))) / n, 1) * 0.07

The examples demonstrate how to calculate the slashing penalty for unresponsiveness.

:::note

In all of the examples, assume that there are 100 validators in the active set.

:::

No slashing would enact if <= 10% of all validators are unresponsive.

For example, if exactly 10 validators were unresponsive, the expression 3 _ (x - (n / 10 + 1))) / n
would be 3 _ (10 - (100 / 10 + 1)) / 100 = 3 \* (10 - (10 + 1)) / 100 = -0.03 which is rounded to 0.

:::note

The minimum value between 0 and 1 is 0. 0 multiplied by 0.07 is 0.

:::

If 14 validators are unresponsive, then slashing would occur, as > 10% of validators are
unresponsive.

The slashing penalty would be min((3 _ (14 - (100 / 10 + 1))) / 100, 1) _ 0.07 = min((3 _ (14 -
11))/100, 1) _ 0.07 = min(0.09, 1) \* 0.07 = 0.6%

Similarly, if one-third of the validator set (around 33/100) are unresponsive, the slashing penalty
would be about 5%.

The maximum slashing that can occur due to unresponsiveness is 7%. After around 45% of the
validators go offline, the expression 3 _ (x - (n / 10 + 1))) / n will go beyond 1. Hence, min((3 _
(x - (n / 10 + 1))) / n, 1) \* 0.07 will be ceiled to 7%.

### Equivocation

**GRANDPA Equivocation**: A validator signs two or more votes in the same round on different chains.
Expand Down Expand Up @@ -361,8 +310,7 @@ staking rewards as one), slashing grows exponentially. A single validator equivo
Validators may run their nodes on multiple machines to make sure they can still perform validation
work in case one of their nodes goes down, but validator operators should be extremely careful in
setting these up. If they do not have good coordination to manage signing machines, equivocation is
possible, and equivocation offenses are slashed at much higher rates than equivalent offline
offenses.
possible.

If a validator is reported for any one of the offenses they will be removed from the validator set
([chilled](#chilling)) and they will not be paid while they are out. They will be considered
Expand Down
27 changes: 7 additions & 20 deletions docs/learn/learn-staking.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -282,16 +282,7 @@ Understandably, most of the validator nodes run on cloud service providers that
hardware specifications and high levels of availability and connectivity. Keep in mind that a
validator in the active set is supposed to be fully online and available for producing blocks. If
the active validator node goes offline due to network interruptions or a power outage, that
validator might be subject to
[slashing due to unresponsiveness](./learn-staking-advanced#unresponsiveness). As
[Polkadot's block production mechanism](./learn-consensus.md#block-production-babe) is reasonably
resilient to a small proportion of validators going offline, no slashing is imposed until 10% of the
validators in the active set go offline. Hence, if multiple nodes are running on a single cloud
service provider and go offline simultaneously due to an outage or due to a change in their terms
and conditions policy regarding the support of Proof-of-Stake (PoS) operations, the offline
validators and all the nominators backing them can be slashed up 7% of their stake on Polkadot.
Hence, it is recommended that you check if you are nominating the validator nodes that are running
on cloud service providers, and if they do, check if they allow for Proof-of-Stake operations.
validator will get fewer rewards.

:::tip Checking Validators using Network Providers

Expand Down Expand Up @@ -446,9 +437,8 @@ for details. For specific details about validator payouts, please see

### Slashing

Slashing will happen if a validator misbehaves (e.g. goes offline, attacks the network, or runs
modified software) in the network. They and their nominators will get slashed by losing a percentage
of their bonded/staked DOT.
Slashing will happen if a validator misbehaves in the network. They and their nominators will get
slashed by losing a percentage of their bonded/staked DOT.

Any slashed DOT will be added to the [Treasury](./archive/learn-treasury.md). The rationale for this
(rather than burning or distributing them as rewards) is that slashes may then be reverted by the
Expand Down Expand Up @@ -487,15 +477,12 @@ particular levels are not implemented or referred to in the code or in the syste
guidelines for different levels of severity for offenses. To understand how slash amounts are
calculated, see the equations in the section below.

- Level 1: isolated [unresponsiveness](./learn-staking-advanced.md/#unresponsiveness), i.e. being
offline for an entire session. Generally no slashing, only [chilling](#chilling).
- Level 2: concurrent unresponsiveness or isolated
[equivocation](./learn-staking-advanced.md/#equivocation), slashes a very small amount of the
stake and chills.
- Level 3: misconducts unlikely to be accidental, but which do not harm the network's security to
- Level 1: Isolated [equivocation](./learn-staking-advanced.md/#equivocation), slashes a very small
amount of the stake.
- Level 2: misconducts unlikely to be accidental, but which do not harm the network's security to
any large extent. Examples include concurrent equivocation or isolated cases of unjustified voting
in [GRANDPA](learn-consensus.md). Slashes a moderately small amount of the stake and chills.
- Level 4: misconduct that poses serious security or monetary risk to the system, or mass collusion.
- Level 3: misconduct that poses serious security or monetary risk to the system, or mass collusion.
Slashes all or most of the stake behind the validator and chills.

If you want to know more details about slashing, please look at our
Expand Down
6 changes: 2 additions & 4 deletions docs/learn/learn-transactions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,10 +50,8 @@ account that has funds, and therefore {{ polkadot: Polkadot :polkadot }}{{ kusam
can charge a transaction fee as a way to prevent spam.

Unsigned transactions are for special cases where a user needs to submit an extrinsic from a key
pair that does not control funds. For example, validators submit unsigned transactions in the form
of "heartbeat" messages to indicate that they are online. These heartbeats must be signed by one of
the validator's [session keys](learn-cryptography.md). Session keys never control funds. Unsigned
transactions are only used in special cases because, since
pair that does not control funds. For example, validator's [session keys](learn-cryptography.md)
never control funds. Unsigned transactions are only used in special cases because, since
{{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :kusama }} cannot charge a fee for them, each
one needs its own, custom validation logic.

Expand Down
4 changes: 2 additions & 2 deletions docs/learn/xcm/testing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,8 @@ An example of how the emulator is used for testing common good parachains can be

The xcm-emulator uses the transport layer pallets. However, the messages do not utilize the same
messaging infrastructure as live networks, as the transport mechanism is being mocked out. Also,
consensus related events are not tested, like disputes, staking and iamonline events. To test for
these events, parachains can use E2E tests.
consensus related events are not tested, like disputes and staking. To test for these events,
parachains can use E2E tests.

## End-to-End testing

Expand Down
7 changes: 2 additions & 5 deletions docs/maintain/maintain-errors.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ The below table is a reference to the errors that exists in Polkadot. It is gene
runtime's metadata.

| Pallet | Error | Documentation |
| ----------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| ----------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --- |
| System (0) | | |
| | InvalidSpecName (0) | The name of specification does not match between the current runtime and the new runtime. |
| | SpecVersionNeedsToIncrease (1) | The specification version is not allowed to decrease between the current runtime and the new runtime. |
Expand Down Expand Up @@ -165,10 +165,7 @@ runtime's metadata.
| | TooSoon (3) | Cannot signal forced change so soon after last. |
| | InvalidKeyOwnershipProof (4) | A key ownership proof provided as part of an equivocation report is invalid. |
| | InvalidEquivocationProof (5) | An equivocation proof provided as part of an equivocation report is invalid. |
| | DuplicateOffenceReport (6) | A given equivocation report is valid but already previously reported. |
| ImOnline (12) | | |
| | InvalidKey (0) | Non existent public key. |
| | DuplicatedHeartbeat (1) | Duplicated heartbeat. |
| | DuplicateOffenceReport (6) | A given equivocation report is valid but already previously reported. | |
| Democracy (14) | | |
| | ValueLow (0) | Value too low |
| | ProposalMissing (1) | Proposal does not exist |
Expand Down
Loading

0 comments on commit dcf5afa

Please sign in to comment.