Added documentation for --ignore-weak-subjectivity-period-enabled

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` on Mainnet.
+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`.
 
+:::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 considered unsafe.
+
+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, 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 \

docs/get-started/connect/mainnet.md

@@ -82,10 +82,16 @@ teku \
     --ee-endpoint=http://localhost:8551          \
     --ee-jwt-secret-file=<path to jwtsecret.hex> \
     --metrics-enabled=true                       \
-    --rest-api-enabled=true
+    --rest-api-enabled=true                      \
+    --checkpoint-sync-url=<checkpoint sync URL>
 ```
 
-Specify the path to the `jwtsecret.hex` file generated in [step 1] using the [`--ee-jwt-secret-file`](../../reference/cli/index.md#ee-jwt-secret-file) option.
+Specify:
+
+- The path to the `jwtsecret.hex` file generated in [step 1] using the
+  [`--ee-jwt-secret-file`](../../reference/cli/index.md#ee-jwt-secret-file) option.
+- The URL of a checkpoint sync endpoint using the
+  [`--checkpoint-sync-url`](../../reference/cli/index.md#checkpoint-sync-url) option.
 
 Also, in the command:
 
@@ -113,13 +119,16 @@ teku \
   --ee-jwt-secret-file=<path to jwtsecret.hex>              \
   --metrics-enabled=true                                    \
   --rest-api-enabled=true                                   \
+  --checkpoint-sync-url=<checkpoint sync URL>              \
   --validators-proposer-default-fee-recipient=<ETH address> \
   --validator-keys=<path to key file>:<path to password file>[,<path to key file>:<path to password file>,...]
 ```
 
 Specify:
 
 - The path to the `jwtsecret.hex` file generated in [step 1] using the [`--ee-jwt-secret-file`](../../reference/cli/index.md#ee-jwt-secret-file) option.
+- The URL of a checkpoint sync endpoint using the
+  [`--checkpoint-sync-url`](../../reference/cli/index.md#checkpoint-sync-url) option.
 - An Ethereum address you own as the default fee recipient using the [`--validators-proposer-default-fee-recipient`](../../reference/cli/index.md#validators-proposer-default-fee-recipient) option.
 - The paths to the keystore `.json` file and password `.txt` file created in [step 2](#create-a-password-file-for-each-validator-key) for each validator using the [`--validator-keys`](../../reference/cli/index.md#validator-keys) option. Separate the `.json` and `.txt` files with a colon, and separate entries for multiple validators with commas. Alternatively, specify paths to directories to load multiple keys and passwords from.
 

docs/get-started/connect/testnet.md

@@ -95,7 +95,8 @@ teku \
     --ee-endpoint=http://localhost:8551          \
     --ee-jwt-secret-file=<path to jwtsecret.hex> \
     --metrics-enabled=true                       \
-    --rest-api-enabled=true
+    --rest-api-enabled=true                      \
+    --checkpoint-sync-url=<checkpoint sync URL>
 ```
 
 # Sepolia
@@ -106,12 +107,18 @@ teku \
     --ee-endpoint=http://localhost:8551          \
     --ee-jwt-secret-file=<path to jwtsecret.hex> \
     --metrics-enabled=true                       \
-    --rest-api-enabled=true
+    --rest-api-enabled=true                      \
+    --checkpoint-sync-url=<checkpoint sync URL>
 ```
 
 <!--/tabs-->
 
-Specify the path to the `jwtsecret.hex` file generated in [step 1] using the [`--ee-jwt-secret-file`](../../reference/cli/index.md#ee-jwt-secret-file) option.
+Specify:
+
+- The path to the `jwtsecret.hex` file generated in [step 1] using the
+  [`--ee-jwt-secret-file`](../../reference/cli/index.md#ee-jwt-secret-file) option.
+- The URL of a checkpoint sync endpoint using the
+  [`--checkpoint-sync-url`](../../reference/cli/index.md#checkpoint-sync-url) option.
 
 You can modify the option values and add other [command line options](../../reference/cli/index.md) as needed.
 
@@ -139,6 +146,7 @@ teku \
   --ee-jwt-secret-file=<path to jwtsecret.hex>              \
   --metrics-enabled=true                                    \
   --rest-api-enabled=true                                   \
+  --checkpoint-sync-url=<checkpoint sync URL>              \
   --validators-proposer-default-fee-recipient=<ETH address> \
   --validator-keys=<path to key file>:<path to password file>[,<path to key file>:<path to password file>,...]
 ```
@@ -152,6 +160,8 @@ Sepolia is a permissioned network and you can't run a validator client on it wit
 Specify:
 
 - The path to the `jwtsecret.hex` file generated in [step 1] using the [`--ee-jwt-secret-file`](../../reference/cli/index.md#ee-jwt-secret-file) option.
+- The URL of a checkpoint sync endpoint using the
+  [`--checkpoint-sync-url`](../../reference/cli/index.md#checkpoint-sync-url) option.
 - An Ethereum address you own as the default fee recipient using the [`--validators-proposer-default-fee-recipient`](../../reference/cli/index.md#validators-proposer-default-fee-recipient) option.
 - The paths to the keystore `.json` file and password `.txt` file created in [step 2](#create-a-password-file-for-each-validator-key) for each validator using the [`--validator-keys`](../../reference/cli/index.md#validator-keys) option. Separate the `.json` and `.txt` files with a colon, and separate entries for multiple validators with commas. Alternatively, specify paths to directories to load multiple keys and passwords from.
 

docs/get-started/start-teku.md

@@ -32,6 +32,7 @@ teku \
   --ee-jwt-secret-file=jwtsecret.hex                        \
   --metrics-enabled=true                                    \
   --rest-api-enabled=true                                   \
+  --checkpoint-sync-url=https://beaconstate.ethstaker.cc    \
   --validators-proposer-default-fee-recipient=0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73 \
   --validator-keys=validator/keys/validator_888eef.json:validator/passwords/validator_888eef.txt
 ```
@@ -48,10 +49,11 @@ Run Teku as a beacon node.
 
 ```bash title="Example"
 teku \
-    --ee-endpoint=http://localhost:8551 \
-    --ee-jwt-secret-file=jwtsecret.hex  \
-    --metrics-enabled=true              \
-    --rest-api-enabled=true
+    --ee-endpoint=http://localhost:8551                    \
+    --ee-jwt-secret-file=jwtsecret.hex                     \
+    --metrics-enabled=true                                 \
+    --rest-api-enabled=true                                \
+    --checkpoint-sync-url=https://beaconstate.ethstaker.cc \
 ```
 
 Specify [`--rest-api-enabled`](../reference/cli/index.md#rest-api-enabled) to allow validators to connect to the beacon node.

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,44 +850,42 @@ See [this community-maintained list of checkpoint state endpoints](https://eth-c
 
 :::
 
-### checkpoint-sync-url
+### ignore-weak-subjectivity-period-enabled
 
 <!--tabs-->
 
 # Syntax
 
 ```bash
---checkpoint-sync-url=<URL>
+--ignore-weak-subjectivity-period-enabled[=<BOOLEAN>]
 ```
 
 # Example
 
 ```bash
---checkpoint-sync-url="https://beaconstate.ethstaker.cc"
+--ignore-weak-subjectivity-period-enabled=true
 ```
 
 # Environment variable
 
 ```bash
-TEKU_CHECKPOINT_SYNC_URL="https://beaconstate.ethstaker.cc"
+TEKU_IGNORE_WEAK_SUBJECTIVITY_PERIOD_ENABLED=true
 ```
 
 # Configuration file
 
 ```bash
-checkpoint-sync-url: "https://beaconstate.ethstaker.cc"
+ignore-weak-subjectivity-period-enabled: true
 ```
 
 <!--/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/).
+Ignores the [weak subjectivity](../../concepts/weak-subjectivity.md) period verification that Teku
+performs at startup.
+The default is `false`.
 
+:::caution
+Syncing from outside the weak subjectivity period is considered unsafe.
 :::
 
 ### logging
@@ -3256,11 +3293,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 -->