# Teku Doppelganger Detection

## Enabling doppelganger detection
Running the BN and VC in a single process:
`teku --doppelganger-detection=<BOOLEAN>`

Running the clients separately:
`teku validator-client --doppelganger-detection=<BOOLEAN>`

Default value: `false`

## How it works
When the doppelganger detection is activated, the VC will load the validator keys and wait for the doppelganger service signal to schedule validators duties or shutdown.
the doppelganger service will listen to the network during the first 2 epochs (13 minutes approximately).
If a doppelganger is detected, the VC logs an alert and shuts down. Otherwise it start scheduling its validators duties

## Expected behaviour
When a doppelganger is detected:
1. An alert is logged with the detected validator doppelganger details (validator index and public key)
2. If at least one of the loaded validator is detected as a doppelganger, the VC shuts down

## Side effects
When the doppelganger detection is activated, the VC will connect to the network without performing its duties during the first 2 epochs. This inevitably results in some penalties:
1. 2 missed attestations which results in penalties and missed rewards
2. 2 epoch of missed sync commitee contribution if the VC is in a sync commitee which results in penalties and missed rewards (unlikely)
3. Possibly missing block proposing rewards if the VC is elected to propose a block (unlikely)

## Edge cases

## Design (draft)


\* Components in blue color are not implemented yet
## Subtasks

- Add the `--doppelganger-detection` command line option
- Update the `ValidatorApiChannel`: Add the validators liveness check (Which will use the `NodeDataProvider`)
- Create a doppelganger detection service
- Timer: runs for 2 epochs and then stops
- Check if the loaded validators have been seen (through the `ValidatorApiChannel`)

## Things to test/check
- Attestions reception frequency (ActiveValidatorCache updates): This could help to adjust the doppelganger service checks
- Active validators cache: check if the current implementation is suitable for the doppelganger detection

## Useful links
- [Lighthouse Book - Doppelganger Protection](https://lighthouse-book.sigmaprime.io/validator-doppelganger.html)
- [Doppelganger Detection: Lessons Learned](https://hackmd.io/Szjk_d1gTrWGuUsLojmoqA?view)
- [Lighthouse Doppelganger Service source code](https://github.com/sigp/lighthouse/blob/stable/validator_client/src/doppelganger_service.rs)
- [Lighthouse validator check source code](https://github.com/sigp/lighthouse/blob/7c88f582d955537f7ffff9b2c879dcf5bf80ce13/beacon_node/beacon_chain/src/beacon_chain.rs#L3757-L3782)
- [Teku Liveness API PR](https://github.com/ConsenSys/teku/issues/4453)
- [Lighthouse liveness check source code](https://github.com/sigp/lighthouse/blob/7c88f582d955537f7ffff9b2c879dcf5bf80ce13/beacon_node/http_api/src/lib.rs#L2139-L2180)
- [Lighthouse Doppelganger Protection initial proposal](https://github.com/sigp/lighthouse/issues/2069)
- [Nimbus Doppelganger note](https://our.status.im/nimbus-update-v1-0-7-release/)
- [Liveness endpoint spec](https://github.com/ethereum/beacon-APIs/pull/131)