From 38b3865198906edeec0b79e298598bdaf249a71b Mon Sep 17 00:00:00 2001 From: bgravenorst <50852695+bgravenorst@users.noreply.github.com> Date: Tue, 1 Dec 2020 09:41:33 +1000 Subject: [PATCH] Update weak subjectivity content (#214) * Add CLI option to disable built-in slashing protection for external signers. Signed-off-by: Byron Gravenorst * Add instructions to connect to mainnet. Signed-off-by: Byron Gravenorst * updating submodule to latest * Add instructions to connect to mainnet. Signed-off-by: Byron Gravenorst * Fix markdown issue. Signed-off-by: Byron Gravenorst * Added weak subjectivity concept material. Signed-off-by: Byron Gravenorst * Address reviewer feedback. Signed-off-by: Byron Gravenorst --- docs/Concepts/Weak-Subjectivity.md | 38 ++++++++++++++++++++++++++++++ docs/Reference/CLI/CLI-Syntax.md | 19 ++++++++++++--- mkdocs.yml | 3 ++- 3 files changed, 56 insertions(+), 4 deletions(-) create mode 100644 docs/Concepts/Weak-Subjectivity.md diff --git a/docs/Concepts/Weak-Subjectivity.md b/docs/Concepts/Weak-Subjectivity.md new file mode 100644 index 000000000..1ec81f98c --- /dev/null +++ b/docs/Concepts/Weak-Subjectivity.md @@ -0,0 +1,38 @@ +--- +description: Describe weak subjectivity +--- + +# Weak subjectivity + +The weak subjectivity period refers to how far behind the chain head a node can be before 1/3 of +validators may have exited since the node was last in sync. + +For example, if 1/3 of validators withdraw their stake and continue signing blocks and +attestations, they can form a chain which conflicts with the finalised state. If your node is far +enough behind the chain head not to be aware that they've withdrawn their funds, these validators +can act dishonestly and continue feeding you blocks to lead you down the wrong chain. + +!!! note + + If a node is aware that a validator has withdrawn its funds, the node will reject the + validator's attestations. + +## Safely sync your node + +Teku provides two methods to safely sync a node that's been offline for an extended period. + +1. Use [`--ws-checkpoint`](../Reference/CLI/CLI-Syntax.md#ws-checkpoint) to supply a weak + subjectivity checkpoint from which a node can securely update its view of the current state. +1. Use [`--initial-state`](../Reference/CLI/CLI-Syntax.md#initial-state) to supply an SSZ encoded + state file from which to sync. + +!!! tip + + The [BeaconScan chain explorer] provides the most recent weak subjectivity checkpoint from + which to safely update your node's view of the current state. + + Use the [`/teku/v1/beacon/states/`](https://consensys.github.io/teku/#operation/getTekuV1BeaconStatesWithState_id) + API on an updated node to download a recent finalized state as an SSZ encoded state file. + + +[BeaconScan chain explorer]: https://beaconscan.com/ws_checkpoint diff --git a/docs/Reference/CLI/CLI-Syntax.md b/docs/Reference/CLI/CLI-Syntax.md index 84b96371b..52f4b14fe 100644 --- a/docs/Reference/CLI/CLI-Syntax.md +++ b/docs/Reference/CLI/CLI-Syntax.md @@ -328,9 +328,15 @@ Show the help message and exit. initial-state: "/home/me/genesis.ssz" ``` -Path or URL to the network genesis file. +Path or URL to an SSZ encoded state file. The state file can be used to specify the genesis state, +or a recent state from which to sync. -This option does not need to be specified if the initial state is provided by the network specified +!!! note + + If overriding the initial state in a custom network. You will need to supply the initial state + file at each restart. + +This option does not need to be specified if the genesis state is provided by the network specified using the [`--network`](#network) option. ### logging @@ -1495,7 +1501,7 @@ Attempts to lock all keystores in a directory if a directory is specified in ws-checkpoint: "0x5a642bb8f367e98c0d11426d98d28c465f8988fc960500886cb49faf0372883a:3600" ``` -A recent checkpoint within the weak subjectivity period. +A recent checkpoint within the [weak subjectivity period]. The weak subjectivity checkpoint is a recent finalized checkpoint on the correct chain. By supplying a weak subjectivity checkpoint, you ensure that nodes that have been offline for a long @@ -1504,8 +1510,15 @@ period follow the correct chain. It protects the node from long-range attacks by Use the [`admin weak-subjectivity`](Subcommands/Admin.md#weak-subjectivity) subcommand to display or clear your weak subjectivity settings. +!!! tip + + The [BeaconScan chain explorer] provides the most recent weak subjectivity checkpoint from which to + safely update your nodes view of the current state. + [Infura]: https://infura.io/ [Teku metrics]: ../../HowTo/Monitor/Metrics.md [Web3Signer]: https://docs.web3signer.consensys.net/en/latest/ [slashing protection]: ../../Concepts/Slashing-Protection.md +[weak subjectivity period]: ../../Concepts/Weak-Subjectivity.md +[BeaconScan chain explorer]: https://beaconscan.com/ws_checkpoint diff --git a/mkdocs.yml b/mkdocs.yml index 8092f8f4d..bf1c96af7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -76,6 +76,7 @@ nav: - Solve common problems: HowTo/Troubleshoot/Troubleshooting.md - Concepts: - Slashing protection: Concepts/Slashing-Protection.md + - Weak subjectivity: Concepts/Weak-Subjectivity.md - Reference: - Teku command line: - Options: Reference/CLI/CLI-Syntax.md @@ -132,5 +133,5 @@ plugins: HowTo/Get-Started/Build-From-Source.md: HowTo/Get-Started/Installation-Options/Build-From-Source.md HowTo/Get-Started/Install-Binaries.md: HowTo/Get-Started/Installation-Options/Install-Binaries.md HowTo/Get-Started/Run-Docker-Image.md: HowTo/Get-Started/Installation-Options/Run-Docker-Image.md - Reference/Rest_API/API-Objects.md: Reference/Rest_API/Rest.md HowTo/Get-Started/Connect-To-Testnet.md: HowTo/Get-Started/Connect/Connect-To-Testnet.md + Reference/Rest_API/API-Objects.md: Reference/Rest_API/Rest.md