DG detection doc (#426)

* DG detection doc

* edit dg detection and slashing prevention

* remove trailing space

* updating submodule to latest

* updating submodule to latest

* updating submodule to latest

Co-authored-by: Alexandra Tran <[email protected]>

Author: mehdi-aouadi

common

@@ -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 `<data-path>/validator/slashprotection/` direct
     Set `<data-path>` 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.
 
 <!-- links -->
-[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

docs/Concepts/Slashing-Protection.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
+    ```

docs/HowTo/Doppelganger-Detection.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
 `<data-path>/validators/slashprotection/` directory in the format `<validator-pubkey>.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.
 
 <!--links -->
-[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/

docs/HowTo/Prevent-Slashing.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`.
 
 <!-- links -->
 [slashing protection data]: ../../../Concepts/Slashing-Protection.md

docs/Reference/CLI/Subcommands/Slashing-Protection.md

@@ -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