diff --git a/common b/common index 1c952a0b8..41353b629 160000 --- a/common +++ b/common @@ -1 +1 @@ -Subproject commit 1c952a0b8a0d71005c98a2c0fb8565161fadba7f +Subproject commit 41353b629cc037d1c949cd6992fb90f8ed957977 diff --git a/docs/Concepts/Slashing-Protection.md b/docs/Concepts/Slashing-Protection.md index 2d2a19651..52454b019 100644 --- a/docs/Concepts/Slashing-Protection.md +++ b/docs/Concepts/Slashing-Protection.md @@ -1,10 +1,10 @@ --- -description: Describe how slash protection works in Teku +description: Describe how slashing protection works in Teku --- # Slashing protection -Teku provides slashing protection to prevent validators from signing blocks or attestations +Teku implements slashing protection to prevent validators from signing blocks or attestations based on what it has already signed. By default, Teku also locks keystore files listed in the @@ -27,11 +27,16 @@ blocks for each validator in the `/validator/slashprotection/` direct Set `` using the [`--data-path`](../Reference/CLI/CLI-Syntax.md#data-path) command line option. -Teku provides command line options to [import] or [export] the slash protection file. +Teku provides command line options to [import] or [export] the slashing protection file. -## Validator slash protection file +!!! tip + Teku also supports [doppelganger detection](../HowTo/Doppelganger-Detection.md) to help prevent + slashing. + This is an early access feature. -The slash protection file records multiple values that protects the validator from incorrectly +## Validator slashing protection file + +The slashing protection file records multiple values that protects the validator from incorrectly signing blocks or attestations. !!! example @@ -62,14 +67,14 @@ The following rules apply to the file: These rules guarantee the validator does not sign anything that is slashable. -## Migrate the slash protection file +## Migrate the slashing protection file -Use the Teku command line options to [import] or [export] the slash protection file. +Use the Teku command line options to [import] or [export] the slashing protection file. Alternatively you can manually migrate or create the database. ### Between Teku nodes -If moving a validator from one Teku node to another, you can manually migrate the slash protection +If moving a validator from one Teku node to another, you can manually migrate the slashing protection file. For example, to manually move the file from node A to node B: @@ -86,9 +91,9 @@ For example, to manually move the file from node A to node B: If moving a validator from a different client to Teku, you can either: -* Manually [create a new slash protection file] by setting the values based on the validator's last +* Manually [create a new slashing protection file] by setting the values based on the validator's last signing details. -* [Import] the slashing-protection file. +* [Import] the slashing protection file. To manually create the file, stop the other client to ensure it isn't signing, then set `lastSignedBlockSlot` to the current chain head slot + 1, `lastSignedAttestationSourceEpoch` to the @@ -97,7 +102,7 @@ current justified checkpoint, and set `lastSignedAttestationTargetEpoch` to the Start the Teku node with the validator key. -[YAML file is stored per validator]: #validator-slash-protection-file -[create a new slash protection file]: #validator-slash-protection-file -[import]: ../HowTo/Prevent-Slashing.md#importing-a-slashing-protection-file -[export]: ../HowTo/Prevent-Slashing.md#exporting-a-slashing-protection-file +[YAML file is stored per validator]: #validator-slashing-protection-file +[create a new slashing protection file]: #validator-slashing-protection-file +[import]: ../HowTo/Prevent-Slashing.md#import-a-slashing-protection-file +[export]: ../HowTo/Prevent-Slashing.md#export-a-slashing-protection-file diff --git a/docs/HowTo/Doppelganger-Detection.md b/docs/HowTo/Doppelganger-Detection.md new file mode 100644 index 000000000..210e4bed8 --- /dev/null +++ b/docs/HowTo/Doppelganger-Detection.md @@ -0,0 +1,94 @@ +--- +description: How to enable doppelganger detection +--- + +# Enable doppelganger detection + +Doppelganger detection checks if the validators keys are already active before scheduling any of +their duties (the validators stay inactive for at most two epochs). +This can help prevent slashing offences. + +When enabled, doppelganger detection is triggered from two entry points: + +1. At [validator client startup](Get-Started/Run-Teku.md#start-teku): If at least one + doppelganger is detected, the validator client shuts down after it finishes the check. +1. When importing keys via the [key manager API](https://ethereum.github.io/keymanager-APIs/): Any + detected doppelganger's keys are ignored (not imported). + The other keys are imported and the validators start performing their duties after it finishes + the check. + +!!! warning + + Doppelganger detection is an early access feature. + This feature is imperfect and might fail to detect doppelgangers. + Use this as a last resort option that might prevent validators from being slashed. + +## Enable doppelganger detection + +Enable doppelganger detection by setting the `--Xdoppelganger-detection-enabled` option to `true`. + +Your validator client must be connected to a beacon node with liveness tracking enabled. +Enable liveness tracking by setting the `--Xbeacon-liveness-tracking-enabled` option to `true`. + +## Side effects + +Doppelganger detection runs until one of the following occurs: + +- All the loaded keys are detected as active. +- The check runs for two epochs. + +This means that the validators being checked are inactive for at most two epochs. + +!!! warning + + Keeping the validators inactive might cause: + + - Missed attestations. + - Missed sync committee contributions. + - Missed block proposals. + + These side effects result in penalties and missed rewards. + +You might still consider these side effects a worthwhile trade-off of doppelganger detection, since +it can prevent slashing. + +## Logs + +When running, doppelganger detection prints various logs. + +!!! example "Example startup logs" + + ```bash + Starting doppelganger detection for public keys: b28ab22, c2bab15, cd26f5e + ``` + +!!! example "Example logs when a check is performed (every 12 seconds)" + + ```bash + Performing doppelganger check. Epoch 148220, Public keys b28ab22, c2bab15, cd26f5e + ``` + +!!! example "Example logs when a doppelganger is detected" + + ```bash + Detected 2 validators doppelganger: + Index: xxxxxx, Public key: 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001 + Index: xxxxxx, Public key: 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002 + ``` + +!!! example "Example logs: list of detected doppelgangers" + + ```bash + Detected 5 validators doppelganger: + Index: xxxxxx, Public key: 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001 + Index: xxxxxx, Public key: 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002 + Index: xxxxxx, Public key: 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003 + Index: xxxxxx, Public key: 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004 + Index: xxxxxx, Public key: 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000005 + ``` + +!!! example "Example logs when doppelganger detection ends" + + ```bash + Doppelganger detection check finished. Stopping doppelganger detection for public keys b28ab22, c2bab15, cd26f5e + ``` diff --git a/docs/HowTo/Prevent-Slashing.md b/docs/HowTo/Prevent-Slashing.md index f35257373..18cccffc9 100644 --- a/docs/HowTo/Prevent-Slashing.md +++ b/docs/HowTo/Prevent-Slashing.md @@ -4,12 +4,12 @@ title: Import or export a slashing protection file # Slashing protection -[Teku implements slashing protection] to prevent validators from signing incorrect +Teku implements [slashing protection] to prevent validators from signing incorrect blocks or attestations. -You can import and export the slashing-protection file when migrating validator keys between +You can import and export the slashing protection file when migrating validator keys between validator clients. Teku supports the [validator client interchange format] when importing or -exporting the slashing-protection file. +exporting the slashing protection file. !!! note @@ -18,9 +18,13 @@ exporting the slashing-protection file. [`--validators-external-signer-slashing-protection-enabled`](../Reference/CLI/CLI-Syntax.md#validators-external-signer-slashing-protection-enabled) command line option. -## Importing a slashing-protection file +!!! tip + You can also [enable doppelganger detection](Doppelganger-Detection.md) to help prevent slashing. + This is an early access feature. -When importing the slashing-protection file, Teku imports the file to the +## Import a slashing protection file + +When importing the slashing protection file, Teku imports the file to the `/validators/slashprotection/` directory in the format `.yml` (with no 0x prefix). @@ -35,13 +39,13 @@ In the command line: * [`--data-path`](../Reference/CLI/Subcommands/Slashing-Protection.md#data-path) specifies the location of the Teku `data` directory. * [`--from`](../Reference/CLI/Subcommands/Slashing-Protection.md#from) specifies the location of the - slashing-protection file. + slashing protection file. In this example, Teku imports the file to the `/home/me/me_node/data/validators/slashprotection/` directory. -## Exporting a slashing-protection file +## Export a slashing protection file -Export the slashing-protection file when migrating a validator to a different Teku, or non-Teku +Export the slashing protection file when migrating a validator to a different Teku, or non-Teku node. !!! example @@ -55,12 +59,12 @@ In the command line: * [`--data-path`](../Reference/CLI/Subcommands/Slashing-Protection.md#data-path_1) specifies the location of the Teku `data` directory. * [`--to`](../Reference/CLI/Subcommands/Slashing-Protection.md#to) specifies the file to export the - slashing-protection data to. + slashing protection data to. -You can now import the slashing-protection file in a Teku, or non-Teku node. +You can now import the slashing protection file in a Teku, or non-Teku node. -[Teku implements slashing protection]: ../Concepts/Slashing-Protection.md +[slashing protection]: ../Concepts/Slashing-Protection.md [data path directory when starting Teku]: ../Reference/CLI/CLI-Syntax.md#data-path [validator client interchange format]: https://eips.ethereum.org/EIPS/eip-3076 [Web3Signer]: https://docs.web3signer.consensys.net/en/latest/ diff --git a/docs/Reference/CLI/Subcommands/Slashing-Protection.md b/docs/Reference/CLI/Subcommands/Slashing-Protection.md index 7af0e8e29..4124affd2 100644 --- a/docs/Reference/CLI/Subcommands/Slashing-Protection.md +++ b/docs/Reference/CLI/Subcommands/Slashing-Protection.md @@ -207,7 +207,7 @@ Exports the database in the [validator client interchange format] format. ## `repair` -Repairs corrupted slashing-protection data files used by Teku. +Repairs corrupted slashing protection data files used by Teku. ### `check-only-enabled` @@ -223,7 +223,7 @@ Repairs corrupted slashing-protection data files used by Teku. teku slashing-protection repair --checking-only-enabled=false ``` -Reads and reports potential slashing-protection file problems, but doesn't update any files. +Reads and reports potential slashing protection file problems, but doesn't update any files. You can specify which files are checked using [`--config-file`](#config-file_2), [`--data-base-path`](#data-base-path-data-path). ### `config-file` @@ -351,7 +351,7 @@ slot, or after when the validators stopped performing duties. teku slashing-protection repair --update-all-enabled=false ``` -Enables all slashing-protection records to be updated. The default is `false`. +Enables all slashing protection records to be updated. The default is `false`. [slashing protection data]: ../../../Concepts/Slashing-Protection.md diff --git a/mkdocs.yml b/mkdocs.yml index 3d14d9649..18fd417ae 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -76,6 +76,7 @@ nav: - Configure Teku to use a builder network: HowTo/Configure/Builder-Network.md - Configure TLS: HowTo/Configure/Configure-TLS.md - Prevent slashing offences: HowTo/Prevent-Slashing.md + - Enable doppelganger detection: HowTo/Doppelganger-Detection.md - Find and connect to peers: - Improve P2P connectivity: HowTo/Find-and-Connect/Improve-Connectivity.md - Specify NAT methods: HowTo/Find-and-Connect/Specifying-NAT.md