update block time content (#845)

* update block time content Signed-off-by: Roland Tyler <[email protected]> * markdown corrections Signed-off-by: Roland Tyler <[email protected]> * markdown corrections Signed-off-by: Roland Tyler <[email protected]> * Incorporating feedback Signed-off-by: Roland Tyler <[email protected]> * Incorporating comments Signed-off-by: Roland Tyler <[email protected]>
hyperledger · Oct 28, 2021 · 349faf3 · 349faf3
1 parent de4911c
commit 349faf3
Show file tree

Hide file tree

Showing 3 changed files with 164 additions and 5 deletions.
diff --git a/docs/HowTo/Configure/Consensus-Protocols/IBFT.md b/docs/HowTo/Configure/Consensus-Protocols/IBFT.md
@@ -74,7 +74,8 @@ The properties specific to IBFT 2.0 are:
 * `extraData` - `RLP([32 bytes Vanity, List<Validators>, No Vote, Round=Int(0), 0 Seals])`.
 
 !!!caution
-    The `blockperiodseconds`, `blockreward`, and  `miningbeneficiary` properties
+
+    The `blockreward` and  `miningbeneficiary` properties
     cannot be updated once your network is started.
 
     We do not recommend changing `epochlength` in a running network. Changing the `epochlength`
@@ -135,7 +136,7 @@ expires, the protocol proposes the next new block.
 
 !!! warning
 
-    If more than 1/3 of validators stop participating, new blocks can no longer be created and 
+    If more than 1/3 of validators stop participating, new blocks can no longer be created and
     `requesttimeoutseconds` doubles with each round change. The quickest method
     to resume block production is to restart all validators, which resets `requesttimeoutseconds` to
     its genesis value.
@@ -161,6 +162,76 @@ To tune the block timeout for your network deployment:
 
     View [`TRACE` logs](../../../Reference/API-Methods.md#admin_changeloglevel) to see round change
     log messages.
+
+#### Configure block time on an existing network deployment
+
+To update an existing network with a new `blockperiodseconds`:
+
+1. Stop all nodes in the network.
+1. In the [genesis file](#genesis-file), add the `transitions` configuration item where:
+
+    * `<FutureBlockNumber>` is the upcoming block at which to change `blockperiodseconds`.
+    * `<NewValue>` is the updated value for `blockperiodseconds`.
+
+    !!! example "Transitions configuration"
+
+        === "Syntax"
+
+            ```bash
+            {
+              "config": {
+                 ...
+                 "ibft2": {
+                   "blockperiodseconds": 2,
+                   "epochlength": 30000,
+                   "requesttimeoutseconds": 4
+                 },
+                 "transitions": {
+                   "ibft2": [
+                   {
+                     "block": <FutureBlockNumber>,
+                     "blockperiodseconds": <NewValue>
+                   }
+                   ]
+                }
+              },
+              ...
+            }
+            ```
+
+        === "Example"
+
+            ```bash
+            {
+              "config": {
+                 ...
+                 "ibft2": {
+                   "blockperiodseconds": 2,
+                   "epochlength": 30000,
+                   "requesttimeoutseconds": 4
+                 },
+                 "transitions": {
+                   "ibft2": [
+                   {
+                     "block": 1240,
+                     "blockperiodseconds": 4
+                   }
+                   ]
+                 }
+              },
+              ...
+            }
+            ```
+
+1. Restart all nodes in the network using the updated genesis file.
+1. To verify the changes after the transition block, call
+   [`ibft_getValidatorsByBlockNumber`](../../../Reference/API-Methods.md#ibft_getvalidatorsbyblocknumber), specifying `latest`.
+
+!!! caution
+
+    Do not specify a transition block in the past.
+    Specifying a transition block in the past could result in unexpected behavior, such as causing
+    the network to fork.
 {!global/Config-Options.md!}
 
 <!-- Acronyms and Definitions -->

diff --git a/docs/HowTo/Configure/Consensus-Protocols/QBFT.md b/docs/HowTo/Configure/Consensus-Protocols/QBFT.md
@@ -99,7 +99,7 @@ The QBFT properties are:
 
 !!! caution
 
-    The `blockperiodseconds`, `blockreward`, and  `miningbeneficiary` properties
+    The `blockreward` and  `miningbeneficiary` properties
     cannot be updated once your network is started.
 
     We do not recommend changing `epochlength` in a running network. Changing the `epochlength`
@@ -171,7 +171,7 @@ expires, the protocol proposes the next new block.
 
 !!! warning
 
-    If more than 1/3 of validators stop participating, new blocks can no longer be created and 
+    If more than 1/3 of validators stop participating, new blocks can no longer be created and
     `requesttimeoutseconds` doubles with each round change. The quickest method
     to resume block production is to restart all validators, which resets `requesttimeoutseconds` to
     its genesis value.
@@ -192,8 +192,77 @@ To tune the block timeout for your network deployment:
 
     View [`TRACE` logs](../../../Reference/API-Methods.md#admin_changeloglevel) to see round change
     log messages.
-{!global/Config-Options.md!}
 
+#### Configure block time on an existing network deployment
+
+To update an existing network with a new `blockperiodseconds`:
+
+1. Stop all nodes in the network.
+2. In the [genesis file](#genesis-file), add the `transitions` configuration item where:
+
+    * `<FutureBlockNumber>` is the upcoming block at which to change `blockperiodseconds`.
+    * `<NewValue>` is the updated value for `blockperiodseconds`.
+
+    !!! example "Transitions configuration"
+
+        === "Syntax"
+
+            ```bash
+            {
+              "config": {
+                 ...
+                 "qbft": {
+                   "blockperiodseconds": 2,
+                   "epochlength": 30000,
+                   "requesttimeoutseconds": 4
+                 },
+                 "transitions": {
+                   "qbft": [
+                   {
+                     "block": <FutureBlockNumber>,
+                     "blockperiodseconds": <NewValue>
+                   }
+                   ]
+                 }
+              },
+              ...
+            }
+            ```
+
+        === "Example"
+
+            ```bash
+            {
+              "config": {
+                 ...
+                 "qbft": {
+                   "blockperiodseconds": 2,
+                   "epochlength": 30000,
+                   "requesttimeoutseconds": 4
+                 },
+                 "transitions": {
+                   "qbft": [
+                   {
+                     "block": 1240,
+                     "blockperiodseconds": 4
+                   }
+                   ]
+                 }
+              },
+              ...
+            }
+            ```
+
+3. Restart all nodes in the network using the updated genesis file.
+4. To verify the changes after the transition block, call
+   [`qbft_getValidatorsByBlockNumber`](../../../Reference/API-Methods.md#ibft_getvalidatorsbyblocknumber), specifying `latest`.
+
+!!! caution
+
+    Do not specify a transition block in the past.
+    Specifying a transition block in the past could result in unexpected behavior, such as causing
+    the network to fork.
+{!global/Config-Options.md!}
 <!-- Acronyms and Definitions -->
 
 *[Vanity]: Validators can include anything they like as vanity data.

diff --git a/docs/HowTo/Troubleshoot/Troubleshooting.md b/docs/HowTo/Troubleshoot/Troubleshooting.md
@@ -13,6 +13,25 @@ matching the genesis block of the data directory, or use the
 [`--data-path`](../../Reference/CLI/CLI-Syntax.md#data-path) option to specify a different data
 directory.
 
+## Invalid block header
+
+If a `TimeStampMoreRecentThanParent | Invalid block header` error occurs, the [genesis file](../Configure/Genesis-File.md) of the new node is specifying a higher
+[`blockperiodseconds`](../Configure/Consensus-Protocols/IBFT.md#block-time) than the imported chain.
+The imported chain makes new blocks faster than the genesis file allows and Besu rejects them with this error.
+This error most often occurs when importing chains from older versions of Besu.
+
+To correct this error, decrease the `blockperiodseconds` in the new [IBFT 2.0 genesis file](../Configure/Consensus-Protocols/IBFT.md#genesis-file)
+or [QFBT genesis file](../Configure/Consensus-Protocols/QBFT.md#genesis-file) to a lower value that satisfies the block header validation.
+
+!!! example
+
+    If the error reads `| TimestampMoreRecentThanParent | Invalid block header: timestamp 1619660141 is only 3 seconds newer than parent timestamp 1619660138. Minimum 4 seconds`,
+    decrease the `blockperiodseconds` from 4 seconds to 3 seconds to match the imported chain.
+
+After you have updated the new genesis file, if the imported chain has a `blockperiodseconds` value set lower than you prefer, you can adjust it by configuring the block time on an
+[existing IBFT 2.0](../Configure/Consensus-Protocols/IBFT.md#block-time)
+or [existing QBFT](../Configure/Consensus-Protocols/QBFT.md#block-time) network.
+
 ## Host not authorized
 
 If a `Host not authorized` error occurs when attempting to access the JSON-RPC API, ensure