edit and reorganize ws checkpoint content

docs/concepts/weak-subjectivity.md

@@ -6,31 +6,62 @@ sidebar_position: 7
 
 # 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.
+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 finalized 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.
+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 finalized 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
+At a high-level, the weak subjectivity period is the period of time that a node can be behind the
+chain and trust that it is following the correct chain.
+In practice, the weak subjectivity mechanism tells Teku if the latest checkpoint is too old to
+continue syncing from it (either when starting a new node or after your node has been offline for a while).
 
-Teku provides two methods to safely sync a node that is new to the network or has been offline for an extended period.
 
-1. Use [`--initial-state`](../reference/cli/index.md#initial-state) to supply an SSZ encoded state file from which to sync.
-2. Use [`--ws-checkpoint`](../reference/cli/index.md#ws-checkpoint) to supply a weak subjectivity checkpoint by which a node can securely validate its view of the current state.
+## Safely sync your node
 
-We recommend using `--initial-state`. It provides the same security benefits as `--ws-checkpoint`, but syncs faster. The only exception is when syncing an archive node, in which case, use `--ws-checkpoint`.
+Teku provides three methods to safely sync a node that is new to the network or has been offline for an extended period.
 
-:::tip
+1. Use [`--checkpoint-sync-url`](../reference/cli/index.md#checkpoint-sync-url) to supply a URL of a
+    checkpoint state endpoint from which to sync.
+2. Use [`--initial-state`](../reference/cli/index.md#initial-state) to supply an SSZ encoded state
+    file from which to sync.
+3. Use [`--ws-checkpoint`](../reference/cli/index.md#ws-checkpoint) to supply a weak subjectivity
+    checkpoint by which a node can securely validate its view of the current state.
 
-Use the [`/eth/v2/debug/beacon/states/<state_id>`](https://consensys.github.io/teku/#operation/getEthV2DebugBeaconStatesWithState_id) API on an updated node to download a recent finalized state as an SSZ encoded state file.
+We recommend using `--checkpoint-sync-url` or `--initial-state`.
+They provide the same security benefits as `--ws-checkpoint`, but sync faster.
+The only exception is when syncing an archive node, in which case, use `--ws-checkpoint`.
 
+:::tip
+Use the [`/eth/v2/debug/beacon/states/<state_id>`](https://consensys.github.io/teku/#operation/getEthV2DebugBeaconStatesWithState_id)
+API on an updated node to download a recent finalized state as an SSZ encoded state file.
 :::
 
 Another option is to [reconstruct historical states](../how-to/reconstruct-historical-states.md).
 This allows the creation of a full archive node, ensuring that once the node is
 up-to-date, the concerns associated with weak subjectivity are cleared.
+
+## Sync outside the weak subjectivity period
+
+Originally, Teku's default behavior was to sync from any point in the chain without the weak
+subjectivity check, including syncing all the way from the genesis of the chain.
+However, this is not considered safe.
+
+If you want to allow Teku to sync outside the weak subjectivity period, you can use the
+[`--ignore-weak-subjectivity-period-enabled`](../reference/cli/index.md#ignore-weak-subjectivity-period-enabled)
+CLI option.
+
+## Learn more
+
+See the following resources to learn more about weak subjectivity:
+
+- [Ethereum weak subjectivity documentation](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/weak-subjectivity/)
+- [Proof of Stake: How I Learned to Love Weak Subjectivity](https://blog.ethereum.org/2014/11/25/proof-stake-learned-love-weak-subjectivity)
+- [Exploring Ethereum 2: Weak Subjectivity Period](https://www.symphonious.net/2019/11/27/exploring-ethereum-2-weak-subjectivity-period/)

docs/get-started/checkpoint-start.md

@@ -6,16 +6,19 @@ sidebar_position: 4
 
 # Start Teku from a recent state
 
-To get Teku up and running in only a few minutes, you can start Teku from a recent finalized checkpoint state rather than syncing from genesis.
+To get Teku up and running in only a few minutes, you can start Teku from a recent finalized
+checkpoint state rather than syncing from genesis.
+Using a checkpoint state enables Teku to sync within the
+[weak subjectivity](../concepts/weak-subjectivity.md) period.
 
 When starting from a recent checkpoint, Teku downloads historic chain data in the background.
 
 :::tip
+You need access to a beacon node with [REST API enabled] (for example, Teku) to download the
+finalized checkpoint state file.
 
-You need access to a beacon node with [REST API enabled] (for example, Teku) to download the finalized checkpoint state file.
-
-Alternatively, you can use a Checkpointz endpoint from [this community-maintained list of checkpoint state endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints/).
-
+Alternatively, you can use a Checkpointz endpoint from
+[this community-maintained list of checkpoint state endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints/).
 :::
 
 The following command downloads a recent finalized checkpoint state from a beacon node, and starts Teku:
@@ -26,11 +29,13 @@ teku --eth1-endpoint=http://localhost:8545 \
 --checkpoint-sync-url=https://beaconstate.ethstaker.cc
 ```
 
-The command uses the [`--checkpoint-sync-url`](../reference/cli/index.md#checkpoint-sync-url) option to download the finalized checkpoint state.
+The command uses the [`--checkpoint-sync-url`](../reference/cli/index.md#checkpoint-sync-url) option
+to download the finalized checkpoint state.
 
 :::note
-
-You can also download a finalized checkpoint state file, and specify the location using the [`--initial-state`](../reference/cli/index.md#initial-state) option. To download the file and name it `state.ssz` run:
+You can also download a finalized checkpoint state file, and specify the location using the
+[`--initial-state`](../reference/cli/index.md#initial-state) option.
+To download the file and name it `state.ssz` run:
 
 ```bash
 curl -o state.ssz -H 'Accept: application/octet-stream' http://other-node:5051/eth/v2/debug/beacon/states/finalized
@@ -44,7 +49,8 @@ teku --eth1-endpoint=http://localhost:8545 \
 --initial-state=state.ssz
 ```
 
-Another option is to use [`--initial-state`](../reference/cli/index.md#initial-state) with the URL of the state you want to use:
+Another option is to use [`--initial-state`](../reference/cli/index.md#initial-state) with the URL
+of the state you want to use:
 
 ```bash
 teku --eth1-endpoint=http://localhost:8545 \
@@ -53,25 +59,6 @@ teku --eth1-endpoint=http://localhost:8545 \
 ```
 :::
 
-## Syncing outside of weak subjectivity period
-
-The weak subjectivity period is the period of time (or more specifically epochs) that a node can be behind the chain and trust that the chain it is following is the correct chain. The mechanism on how the weak subjectivity period works are a bit more complex but in practice, it will tell Teku if the state you have as your latest checkpoint (either starting a new node or because your node was offline for a while) is too old to continue syncing from.
-
-During startup, as soon as Teku loads its initial state (e.g. downloading it using `--checkpoint-sync-url` or reading its existing database), it will check if the latest finalized state epoch is within the weak subjectivity period. If it is, Teku will start looking for peers and downloading the missing blocks to catch-up with the chain. If it is too old, Teku will log an error message and exit.
-
-:::caution
-
-Originally, Teku's default behavior was to sync from any point in the chain without the weak subjectivity check, including syncing all the way from the genesis of the chain. However, this is not considered safe.
-
-If you really want to allow Teku to sync from outside the weak subjectivity period, you can use the CLI flag: [`--ignore-weak-subjectivity-period-enabled`](../reference/cli/index.md#ignore-weak-subjectivity-period-enabled)
-
-:::
-
-For more information on the weak subjectivity period and how it works, check out these links:
-- https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/weak-subjectivity/
-- https://blog.ethereum.org/2014/11/25/proof-stake-learned-love-weak-subjectivity
-- https://www.symphonious.net/2019/11/27/exploring-ethereum-2-weak-subjectivity-period/
-
 <!--links-->
 
 [REST API enabled]: ../reference/cli/index.md#rest-api-enabled

docs/reference/cli/index.md

@@ -184,6 +184,45 @@ builder-set-user-agent-header: true
 
 Set the User-Agent header to `teku/v<version>` (for example, `teku/v23.4.0`) when making a builder bid request to help builders identify clients and versions. The default is `true`.
 
+### checkpoint-sync-url
+
+<!--tabs-->
+
+# Syntax
+
+```bash
+--checkpoint-sync-url=<URL>
+```
+
+# Example
+
+```bash
+--checkpoint-sync-url="https://beaconstate.ethstaker.cc"
+```
+
+# Environment variable
+
+```bash
+TEKU_CHECKPOINT_SYNC_URL="https://beaconstate.ethstaker.cc"
+```
+
+# Configuration file
+
+```bash
+checkpoint-sync-url: "https://beaconstate.ethstaker.cc"
+```
+
+<!--/tabs-->
+
+URL of a Checkpointz endpoint used to [start Teku from a recent state](../../get-started/checkpoint-start.md).
+
+By default, Teku tries to download the finalized state from the endpoint.
+If it can't download the finalized state, it tries to download the genesis state.
+
+:::tip
+See [this community-maintained list of checkpoint state endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints/).
+:::
+
 ### config-file
 
 <!--tabs-->
@@ -811,46 +850,6 @@ See [this community-maintained list of checkpoint state endpoints](https://eth-c
 
 :::
 
-### checkpoint-sync-url
-
-<!--tabs-->
-
-# Syntax
-
-```bash
---checkpoint-sync-url=<URL>
-```
-
-# Example
-
-```bash
---checkpoint-sync-url="https://beaconstate.ethstaker.cc"
-```
-
-# Environment variable
-
-```bash
-TEKU_CHECKPOINT_SYNC_URL="https://beaconstate.ethstaker.cc"
-```
-
-# Configuration file
-
-```bash
-checkpoint-sync-url: "https://beaconstate.ethstaker.cc"
-```
-
-<!--/tabs-->
-
-URL of a Checkpointz endpoint used to [start Teku from a recent state](../../get-started/checkpoint-start.md).
-
-By default, Teku tries to download the finalized state from the endpoint. If it can't download the finalized state, it tries to download the genesis state.
-
-:::tip
-
-See [this community-maintained list of checkpoint state endpoints](https://eth-clients.github.io/checkpoint-sync-endpoints/).
-
-:::
-
 ### ignore-weak-subjectivity-period-enabled
 
 <!--tabs-->
@@ -881,12 +880,11 @@ ignore-weak-subjectivity-period-enabled: true
 
 <!--/tabs-->
 
-Ignores the [weak subjectivity period verification](../../get-started/checkpoint-start.md#syncing-outside-of-weak-subjectivity-period) that Teku performs at startup.
+Ignores the [weak subjectivity](../../concepts/weak-subjectivity.md) period verification that Teku
+performs at startup.
 
 :::caution
-
-Syncing out of the weak subjectivity period is considered unsafe.
-
+Syncing outside the weak subjectivity period is not considered safe.
 :::
 
 ### logging
@@ -3294,11 +3292,16 @@ ws-checkpoint: "0x5a642bb8f367e98c0d11426d98d28c465f8988fc960500886cb49faf037288
 
 <!--/tabs-->
 
-A recent checkpoint within the [weak subjectivity period]. Accepts the checkpoint using `<blockRoot>:<epochNumber>`, where `<blockRoot>` must start with `0x`.
+A recent checkpoint within the [weak subjectivity period].
+Accepts the checkpoint using `<blockRoot>:<epochNumber>`, where `<blockRoot>` must start with `0x`.
 
-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 period follow the correct chain. It protects the node from long-range attacks by malicious actors.
+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
+period follow the correct chain.
+It protects the node from long-range attacks by malicious actors.
 
-Use the [`admin weak-subjectivity`](subcommands/admin.md#weak-subjectivity) subcommand to display or clear your weak subjectivity settings.
+Use the [`admin weak-subjectivity`](subcommands/admin.md#weak-subjectivity) subcommand to display or
+clear your weak subjectivity settings.
 
 <!-- links -->