Add docs for slashing protection (#1760)
## Proposed Changes * Add documentation about slashing protection, including how to troubleshoot issues and move between clients. * Add an error message if the validator client is started with 0 validators. Previously it would hit an error relating to the slashing protection database not existing, which wrongly pushed people towards using the unsafe `--init-slashing-protection` flag.
This commit is contained in:
Michael Sproul
parent
95c96ac567
commit
467de4c8d0
@ -14,6 +14,7 @@
|
|||||||
* [Key recovery](./key-recovery.md)
|
* [Key recovery](./key-recovery.md)
|
||||||
* [Validator Management](./validator-management.md)
|
* [Validator Management](./validator-management.md)
|
||||||
* [Importing from the Eth2 Launchpad](./validator-import-launchpad.md)
|
* [Importing from the Eth2 Launchpad](./validator-import-launchpad.md)
|
||||||
|
* [Slashing Protection](./slashing-protection.md)
|
||||||
* [APIs](./api.md)
|
* [APIs](./api.md)
|
||||||
* [Beacon Node API](./api-bn.md)
|
* [Beacon Node API](./api-bn.md)
|
||||||
* [/lighthouse](./api-lighthouse.md)
|
* [/lighthouse](./api-lighthouse.md)
|
||||||
|
|||||||
139
book/src/slashing-protection.md
Normal file
139
book/src/slashing-protection.md
Normal file
@ -0,0 +1,139 @@
|
|||||||
|
# Slashing Protection
|
||||||
|
|
||||||
|
The security of Ethereum 2.0's proof of stake protocol depends on penalties for misbehaviour, known
|
||||||
|
as _slashings_. Validators that sign conflicting messages (blocks or attestations), can be slashed
|
||||||
|
by other validators through the inclusion of a `ProposerSlashing` or `AttesterSlashing` on chain.
|
||||||
|
|
||||||
|
The Lighthouse validator client includes a mechanism to protect its validators against
|
||||||
|
accidental slashing, known as the slashing protection database. This database records every
|
||||||
|
block and attestation signed by validators, and the validator client uses this information to
|
||||||
|
avoid signing any slashable messages.
|
||||||
|
|
||||||
|
Lighthouse's slashing protection database is an SQLite database located at
|
||||||
|
`$datadir/validators/slashing_protection.sqlite` which is locked exclusively when the validator
|
||||||
|
client is running. In normal operation, this database will be automatically created and utilized,
|
||||||
|
meaning that your validators are kept safe by default.
|
||||||
|
|
||||||
|
If you are seeing errors related to slashing protection, it's important that you act slowly
|
||||||
|
and carefully to keep your validators safe. See the [Troubleshooting](#troubleshooting) section.
|
||||||
|
|
||||||
|
## Initialization
|
||||||
|
|
||||||
|
The database will be automatically created, and your validators registered with it when:
|
||||||
|
|
||||||
|
* Importing keys from another source (e.g. Launchpad, Teku, Prysm, `ethdo`).
|
||||||
|
See [the docs on importing keys](./validator-import-launchpad.md).
|
||||||
|
* Creating keys using Lighthouse itself (`lighthouse account validator create`)
|
||||||
|
* Creating keys via the [validator client API](./api-vc.md).
|
||||||
|
|
||||||
|
## Avoiding Slashing
|
||||||
|
|
||||||
|
The slashing protection database is designed to protect against many common causes of slashing,
|
||||||
|
but is unable to prevent against some others.
|
||||||
|
|
||||||
|
Examples of circumstances where the slashing protection database is effective are:
|
||||||
|
|
||||||
|
* Accidentally running two validator clients on the same machine with the same datadir.
|
||||||
|
The exclusive and transactional access to the database prevents the 2nd validator client
|
||||||
|
from signing anything slashable (it won't even start).
|
||||||
|
* Deep re-orgs that cause the shuffling to change, prompting validators to re-attest in
|
||||||
|
an epoch where they have already attested. The slashing protection checks all messages
|
||||||
|
against the slashing conditions and will refuse to attest on the new chain until it is safe
|
||||||
|
to do so (usually after one epoch).
|
||||||
|
* Importing keys and signing history from another client, where that history is complete.
|
||||||
|
If you run another client and decide to switch to Lighthouse, you can export data from
|
||||||
|
your client to be imported into Lighthouse's slashing protection database. See
|
||||||
|
[Import and Export](#import-and-export).
|
||||||
|
* Misplacing `slashing_protection.sqlite` during a datadir change or migration between machines.
|
||||||
|
By default Lighthouse will refuse to start if it finds validator keys that are not registered
|
||||||
|
in the slashing protection database.
|
||||||
|
|
||||||
|
Examples where it is **ineffective** are:
|
||||||
|
|
||||||
|
* Running two validator client instances simultaneously. This could be two different
|
||||||
|
clients (e.g. Lighthouse and Prysm) running on the same machine, two Lighthouse instances using
|
||||||
|
different datadirs, or two clients on completely different machines (e.g. one on a cloud server
|
||||||
|
and one running locally). You are responsible for ensuring that your validator keys are never
|
||||||
|
running simultanously – the slashing protection DB **cannot protect you in this case**.
|
||||||
|
* Importing keys from another client without also importing voting history.
|
||||||
|
* If you use `--init-slashing-protection` to recreate a missing slashing protection database.
|
||||||
|
|
||||||
|
## Import and Export
|
||||||
|
|
||||||
|
Lighthouse supports v4 of the slashing protection interchange format described
|
||||||
|
[here][interchange-spec]. An interchange file is a record of all blocks and attestations
|
||||||
|
signing by a set of validator keys – basically a portable slashing protection database!
|
||||||
|
|
||||||
|
You can import a `.json` interchange file from another client using this command:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
lighthouse account validator slashing-protection import <my_interchange.json>
|
||||||
|
```
|
||||||
|
|
||||||
|
Instructions for exporting your existing client's database are out of scope for this document,
|
||||||
|
please check the other client's documentation for instructions.
|
||||||
|
|
||||||
|
When importing an interchange file, you still need to import the validator keystores themselves
|
||||||
|
separately, using the instructions about [importing keystores into
|
||||||
|
Lighthouse](./validator-import-launchpad.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
You can export Lighthouse's database for use with another client with this command:
|
||||||
|
|
||||||
|
```
|
||||||
|
lighthouse account validator slashing-protection export <lighthouse_interchange.json>
|
||||||
|
```
|
||||||
|
|
||||||
|
[interchange-spec]: https://hackmd.io/@sproul/Bk0Y0qdGD
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Misplaced Slashing Database
|
||||||
|
|
||||||
|
If the slashing protection database cannot be found, it will manifest in an error like this:
|
||||||
|
|
||||||
|
```
|
||||||
|
Oct 12 14:41:26.415 CRIT Failed to start validator client reason: Failed to open slashing protection database: SQLError("Unable to open database: Error(Some(\"unable to open database file: /home/karlm/.lighthouse/medalla/validators/slashing_protection.sqlite\"))").
|
||||||
|
Ensure that `slashing_protection.sqlite` is in "/home/karlm/.lighthouse/medalla/validators" folder
|
||||||
|
```
|
||||||
|
|
||||||
|
Usually this indicates that during some manual intervention the slashing database has been
|
||||||
|
misplaced. This error can also occur if you have upgraded from Lighthouse v0.2.x to v0.3.x without
|
||||||
|
moving the slashing protection database. If you have imported your keys into a new node, you should
|
||||||
|
never see this error (see [Initialization](#initialization)).
|
||||||
|
|
||||||
|
The safest way to remedy this error is to find your old slashing protection database and move
|
||||||
|
it to the correct location. In our example that would be
|
||||||
|
`~/.lighthouse/medalla/validators/slashing_protection.sqlite`. You can search for your old database
|
||||||
|
using a tool like `find`, `fd`, or your file manager's GUI. Ask on the Lighthouse Discord if you're
|
||||||
|
not sure.
|
||||||
|
|
||||||
|
If you are absolutely 100% sure that you need to recreate the missing database, you can start
|
||||||
|
the Lighthouse validator client with the `--init-slashing-protection` flag. This flag is incredibly
|
||||||
|
dangerous and should not be used lightly, and we **strongly recommend** you try finding
|
||||||
|
your old slashing protection database before using it. If you do decide to use it, you should
|
||||||
|
wait at least 1 epoch (~7 minutes) from when your validator client was last actively signing
|
||||||
|
messages. If you suspect your node experienced a clock drift issue you should wait
|
||||||
|
longer. Remember that the inactivity penalty for being offline for even a day or so
|
||||||
|
is approximately equal to the rewards earned in a day. You will get slashed if you use
|
||||||
|
`--init-slashing-protection` incorrectly.
|
||||||
|
|
||||||
|
### Slashable Attestations and Re-orgs
|
||||||
|
|
||||||
|
Sometimes a re-org can cause the validator client to _attempt_ to sign something slashable,
|
||||||
|
in which case it will be blocked by slashing protection, resulting in a log like this:
|
||||||
|
|
||||||
|
```
|
||||||
|
Sep 29 15:15:05.303 CRIT Not signing slashable attestation error: InvalidAttestation(DoubleVote(SignedAttestation { source_epoch: Epoch(0), target_epoch: Epoch(30), signing_root: 0x0c17be1f233b20341837ff183d21908cce73f22f86d5298c09401c6f37225f8a })), attestation: AttestationData { slot: Slot(974), index: 0, beacon_block_root: 0xa86a93ed808f96eb81a0cd7f46e3b3612cafe4bd0367aaf74e0563d82729e2dc, source: Checkpoint { epoch: Epoch(0), root: 0x0000000000000000000000000000000000000000000000000000000000000000 }, target: Checkpoint { epoch: Epoch(30), root: 0xcbe6901c0701a89e4cf508cfe1da2bb02805acfdfe4c39047a66052e2f1bb614 } }
|
||||||
|
```
|
||||||
|
|
||||||
|
This log is still marked as `CRIT` because in general it should occur only very rarely,
|
||||||
|
and _could_ indicate a serious error or misconfiguration (see [Avoiding Slashing](#avoiding-slashing)).
|
||||||
|
|
||||||
|
## Limitation of Liability
|
||||||
|
|
||||||
|
The Lighthouse developers do not guarantee the perfect functioning of this software, or accept
|
||||||
|
liability for any losses suffered. For more information see the [Lighthouse license][license].
|
||||||
|
|
||||||
|
[license]: https://github.com/sigp/lighthouse/blob/master/LICENSE
|
||||||
@ -107,6 +107,20 @@ impl<T: EthSpec> ProductionValidatorClient<T> {
|
|||||||
.await
|
.await
|
||||||
.map_err(|e| format!("Unable to initialize validators: {:?}", e))?;
|
.map_err(|e| format!("Unable to initialize validators: {:?}", e))?;
|
||||||
|
|
||||||
|
info!(
|
||||||
|
log,
|
||||||
|
"Initialized validators";
|
||||||
|
"disabled" => validators.num_total().saturating_sub(validators.num_enabled()),
|
||||||
|
"enabled" => validators.num_enabled(),
|
||||||
|
);
|
||||||
|
|
||||||
|
if validators.num_enabled() == 0 {
|
||||||
|
return Err("Cannot run with 0 enabled validators. \
|
||||||
|
Please create or import validators before starting the validator client, \
|
||||||
|
or check your datadir configuration"
|
||||||
|
.to_string());
|
||||||
|
}
|
||||||
|
|
||||||
// Initialize slashing protection.
|
// Initialize slashing protection.
|
||||||
let slashing_db_path = config.validator_dir.join(SLASHING_PROTECTION_FILENAME);
|
let slashing_db_path = config.validator_dir.join(SLASHING_PROTECTION_FILENAME);
|
||||||
let slashing_protection = if config.init_slashing_protection {
|
let slashing_protection = if config.init_slashing_protection {
|
||||||
@ -145,13 +159,6 @@ impl<T: EthSpec> ProductionValidatorClient<T> {
|
|||||||
})?;
|
})?;
|
||||||
}
|
}
|
||||||
|
|
||||||
info!(
|
|
||||||
log,
|
|
||||||
"Initialized validators";
|
|
||||||
"disabled" => validators.num_total().saturating_sub(validators.num_enabled()),
|
|
||||||
"enabled" => validators.num_enabled(),
|
|
||||||
);
|
|
||||||
|
|
||||||
let beacon_node_url: Url = config
|
let beacon_node_url: Url = config
|
||||||
.beacon_node
|
.beacon_node
|
||||||
.parse()
|
.parse()
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user