Update weak subjectivity content (#214)

* Add CLI option to disable built-in slashing protection for external signers. Signed-off-by: Byron Gravenorst <[email protected]> * Add instructions to connect to mainnet. Signed-off-by: Byron Gravenorst <[email protected]> * updating submodule to latest * Add instructions to connect to mainnet. Signed-off-by: Byron Gravenorst <[email protected]> * Fix markdown issue. Signed-off-by: Byron Gravenorst <[email protected]> * Added weak subjectivity concept material. Signed-off-by: Byron Gravenorst <[email protected]> * Address reviewer feedback. Signed-off-by: Byron Gravenorst <[email protected]>
Consensys · Nov 30, 2020 · 38b3865 · 38b3865
1 parent 5d94e9e
commit 38b3865
Show file tree

Hide file tree

Showing 3 changed files with 56 additions and 4 deletions.
diff --git a/docs/Concepts/Weak-Subjectivity.md 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/<state-id>`](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.
+
+<!-- links -->
+[BeaconScan chain explorer]: https://beaconscan.com/ws_checkpoint
diff --git 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.
+
 <!-- links -->
 [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
@@ -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