Summary
The slashing protection concept page (concepts/slashing-protection.md) is around 140 words. It defines the term but does not explain the mechanisms an operator needs in order to reason about safety. Expand it.
Current state
The page states that slashing penalises validators that sign conflicting blocks or attestations, that Web3Signer records what has been signed in a PostgreSQL database, that slashing protection is on by default, and that database locking means only one instance signs when several share a database.
It stops there. In particular it never mentions watermarks, even though they are a core part of how the protection works, and they already appear in the CLI reference under the watermark-repair subcommand. A reader who encounters watermark-repair in the reference has nowhere to go to find out what a watermark is.
What the page should cover
What slashing actually is. The specific offences, rather than a general statement about conflicting messages: double proposals, double votes, and surround votes.
The low watermark and the high watermark. Both exist and both constrain signing, and neither is explained anywhere in conceptual terms.
The high watermark sets an upper bound: signing is permitted only below it. The low watermark sets a floor and can be raised but not lowered. Please confirm the precise semantics of each with a maintainer, and describe when an operator would care about them.
The interchange format. Web3Signer can import and export slashing protection data using the format defined in EIP-3076, which is how history moves between clients. Note that EIP-3076 is in Last Call rather than Final, so describe its status accurately. Spell out the standard on first mention, following the terminology rules in this repository.
Why the database is safety critical. Explain why the shared database, rather than the number of instances, is what makes running several Web3Signer instances safe, and what the consequences are if that database is lost or restored to an earlier state.
Interaction with doppelganger detection. Validator clients have their own protections. Explain how these relate, so operators understand what each layer covers.
What slashing protection does not do. It prevents conflicting signatures. It is not an access control and does not protect key material.
Pruning. Mention that the database can be pruned to manage size, and any constraints on when pruning is safe.
Keep it a concept page
This page explains why something exists and how it works. It should not contain step-by-step procedures. Link to how-to/configure-slashing-protection.md for configuration, and to the CLI reference for subcommand detail, rather than repeating them.
Verifying technical claims
Do not state any behaviour, default, or guarantee that you have not verified against the reference documentation or the Web3Signer source. Watermark semantics and the exact guarantee provided by database locking should both be confirmed with a maintainer before publishing, since a reader may make operational decisions based on them.
Summary
The slashing protection concept page (
concepts/slashing-protection.md) is around 140 words. It defines the term but does not explain the mechanisms an operator needs in order to reason about safety. Expand it.Current state
The page states that slashing penalises validators that sign conflicting blocks or attestations, that Web3Signer records what has been signed in a PostgreSQL database, that slashing protection is on by default, and that database locking means only one instance signs when several share a database.
It stops there. In particular it never mentions watermarks, even though they are a core part of how the protection works, and they already appear in the CLI reference under the
watermark-repairsubcommand. A reader who encounterswatermark-repairin the reference has nowhere to go to find out what a watermark is.What the page should cover
What slashing actually is. The specific offences, rather than a general statement about conflicting messages: double proposals, double votes, and surround votes.
The low watermark and the high watermark. Both exist and both constrain signing, and neither is explained anywhere in conceptual terms.
The high watermark sets an upper bound: signing is permitted only below it. The low watermark sets a floor and can be raised but not lowered. Please confirm the precise semantics of each with a maintainer, and describe when an operator would care about them.
The interchange format. Web3Signer can import and export slashing protection data using the format defined in EIP-3076, which is how history moves between clients. Note that EIP-3076 is in Last Call rather than Final, so describe its status accurately. Spell out the standard on first mention, following the terminology rules in this repository.
Why the database is safety critical. Explain why the shared database, rather than the number of instances, is what makes running several Web3Signer instances safe, and what the consequences are if that database is lost or restored to an earlier state.
Interaction with doppelganger detection. Validator clients have their own protections. Explain how these relate, so operators understand what each layer covers.
What slashing protection does not do. It prevents conflicting signatures. It is not an access control and does not protect key material.
Pruning. Mention that the database can be pruned to manage size, and any constraints on when pruning is safe.
Keep it a concept page
This page explains why something exists and how it works. It should not contain step-by-step procedures. Link to
how-to/configure-slashing-protection.mdfor configuration, and to the CLI reference for subcommand detail, rather than repeating them.Verifying technical claims
Do not state any behaviour, default, or guarantee that you have not verified against the reference documentation or the Web3Signer source. Watermark semantics and the exact guarantee provided by database locking should both be confirmed with a maintainer before publishing, since a reader may make operational decisions based on them.