diff --git a/docs/HowTo/Configure/Consensus-Protocols/IBFT.md b/docs/HowTo/Configure/Consensus-Protocols/IBFT.md index ca43d63fe36..65c4738b5a7 100644 --- 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, 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: + + * `` is the upcoming block at which to change `blockperiodseconds`. + * `` is the updated value for `blockperiodseconds`. + + !!! example "Transitions configuration" + + === "Syntax" + + ```bash + { + "config": { + ... + "ibft2": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + }, + "transitions": { + "ibft2": [ + { + "block": , + "blockperiodseconds": + } + ] + } + }, + ... + } + ``` + + === "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!} diff --git a/docs/HowTo/Configure/Consensus-Protocols/QBFT.md b/docs/HowTo/Configure/Consensus-Protocols/QBFT.md index 0dfc4c2d18e..51e975d09eb 100644 --- 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: + + * `` is the upcoming block at which to change `blockperiodseconds`. + * `` is the updated value for `blockperiodseconds`. + + !!! example "Transitions configuration" + + === "Syntax" + + ```bash + { + "config": { + ... + "qbft": { + "blockperiodseconds": 2, + "epochlength": 30000, + "requesttimeoutseconds": 4 + }, + "transitions": { + "qbft": [ + { + "block": , + "blockperiodseconds": + } + ] + } + }, + ... + } + ``` + + === "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!} *[Vanity]: Validators can include anything they like as vanity data. diff --git a/docs/HowTo/Troubleshoot/Troubleshooting.md b/docs/HowTo/Troubleshoot/Troubleshooting.md index 45e41bce7fc..99df18cd6ca 100644 --- 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