Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document Clique transitions #1583

Merged
merged 2 commits into from May 2, 2024
Merged

Document Clique transitions #1583

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3dd714f
Document Clique block period transition
Apr 24, 2024
48bae22
fix syntax and add empty blocks transition
Apr 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
77 changes: 35 additions & 42 deletions docs/private-networks/how-to/configure/consensus/add-validators-without-voting.md
View file
Open in desktop
Expand Up @@ -27,11 +27,10 @@ To add or remove validators without voting:
- `<BlockNumber>` is the upcoming block at which to change validators.
- `<ValidatorAddressX> ... <ValidatorAddressZ>` are strings representing the account addresses of the validators after `<BlockNumber>`.

<Tabs>
<Tabs>
<TabItem value="QBFT syntax" label="QBFT syntax" default>

<TabItem value="QBFT syntax" label="QBFT syntax" default>

```bash
```json
{
"config": {
...
Expand All @@ -57,11 +56,10 @@ To add or remove validators without voting:
}
```

</TabItem>

<TabItem value="QBFT example" label="QBFT example">
</TabItem>
<TabItem value="QBFT example" label="QBFT example">

```bash
```json
{
"config": {
...
Expand All @@ -86,9 +84,10 @@ To add or remove validators without voting:
}
```

# IBFT 2.0 syntax
</TabItem>
<TabItem value="IBFT 2.0 syntax">

```bash
```json
{
"config": {
...
Expand All @@ -114,9 +113,10 @@ To add or remove validators without voting:
}
```

# IBFT 2.0 example
</TabItem>
<TabItem value="IBFT 2.0 example">

```bash
```json
{
"config": {
...
Expand All @@ -141,9 +141,8 @@ To add or remove validators without voting:
}
```

</TabItem>

</Tabs>
</TabItem>
</Tabs>

2. Restart all nodes in the network using the updated genesis file. You can make a rolling update of the nodes, as long as they're all up before the transition block is processed.
3. To verify the changes after the transition block, call [`qbft_getValidatorsByBlockNumber`](../../../reference/api/index.md#qbft_getvalidatorsbyblocknumber) or [`ibft_getValidatorsByBlockNumber`](../../../reference/api/index.md#ibft_getvalidatorsbyblocknumber), specifying `latest`.
Expand All @@ -164,17 +163,16 @@ This requires temporarily [switching to block header validator selection mode](q

To bypass the smart contract and specify new validators:

1. In the genesis file, add a `transitions` configuration item where:
1. In the genesis file, add a `transitions` configuration item where:

- `<BlockNumber>` is the upcoming block at which to change validators.
- `<SelectionMode>` is the validator selection mode to switch to. In this case we'll switch to the `blockheader` mode temporarily.
- `<ValidatorAddressX> ... <ValidatorAddressZ>` are strings representing the account addresses of the validators after `<BlockNumber>`. These validators only need to be sufficient to progress the chain and allow a new contract to be deployed.

<Tabs>
<Tabs>
<TabItem value="Syntax" label="Syntax" default>

<TabItem value="Syntax" label="Syntax" default>

```bash
```json
{
"config": {
...
Expand Down Expand Up @@ -202,11 +200,10 @@ To bypass the smart contract and specify new validators:
}
```

</TabItem>

<TabItem value="Example" label="Example">
</TabItem>
<TabItem value="Example" label="Example">

```bash
```json
{
"config": {
...
Expand All @@ -233,23 +230,21 @@ To bypass the smart contract and specify new validators:
}
```

</TabItem>
</TabItem>
</Tabs>

</Tabs>

1. Restart all nodes in the network using the updated genesis file. You can make a rolling update of the nodes, as long as they're all up before the transition block is processed.
1. Deploy a new contract to the blockchain containing the desired list of validators.
1. In the genesis file, add another `transitions` configuration item where:
2. Restart all nodes in the network using the updated genesis file. You can make a rolling update of the nodes, as long as they're all up before the transition block is processed.
3. Deploy a new contract to the blockchain containing the desired list of validators.
4. In the genesis file, add another `transitions` configuration item where:

- `<BlockNumber>` is the upcoming block at which to change validators.
- `<SelectionMode>` is the validator selection mode to switch to. In this case we'll switch to `contract` mode.
- `<NewValidatorContractAddress>` is the address of the new smart contract.

<Tabs>

<TabItem value="Syntax" label="Syntax" default>
<Tabs>
<TabItem value="Syntax" label="Syntax" default>

```bash
```json
{
"config": {
...
Expand Down Expand Up @@ -281,11 +276,10 @@ To bypass the smart contract and specify new validators:
}
```

</TabItem>
</TabItem>
<TabItem value="Example" label="Example">

<TabItem value="Example" label="Example">

```bash
```json
{
"config": {
...
Expand Down Expand Up @@ -317,8 +311,7 @@ To bypass the smart contract and specify new validators:
}
```

</TabItem>

</Tabs>
</TabItem>
</Tabs>

1. Restart all nodes in the network using the updated genesis file. You can make a rolling update of the nodes, as long as they're all up before the transition block is processed.
5. Restart all nodes in the network using the updated genesis file. You can make a rolling update of the nodes, as long as they're all up before the transition block is processed.
175 changes: 166 additions & 9 deletions docs/private-networks/how-to/configure/consensus/clique.md
View file
Open in desktop
Expand Up @@ -8,6 +8,9 @@ tags:
- private networks
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Configure Clique consensus

Besu implements the [Clique](https://eips.ethereum.org/EIPS/eip-225) proof of authority (PoA) [consensus protocol](index.md). Private networks can use Clique.
Expand Down Expand Up @@ -35,7 +38,8 @@ A Clique genesis file defines properties specific to Clique.
"berlinBlock": 0,
"clique": {
"blockperiodseconds": 15,
"epochlength": 30000
"epochlength": 30000,
"createemptyblocks": true
}
},
"coinbase": "0x0000000000000000000000000000000000000000",
Expand Down Expand Up @@ -65,7 +69,7 @@ By default, Clique creates empty blocks. For large private networks using Clique

To skip creating empty blocks, set `createemptyblocks` to `false` in the genesis file:

```bash
```json
{
"config": {
"londonBlock": 0,
Expand Down Expand Up @@ -102,13 +106,13 @@ The `extraData` property consists of:

After [The Merge](../../../../public-networks/concepts/the-merge.md), the following block fields are modified or deprecated. Their fields **must** contain only the constant values from the following chart.

| Field | Constant value | Comment |
| --- | --- | --- |
| **`ommersHash`** | `0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347` | `= Keccak256(RLP([]))` |
| **`difficulty`** | `0` | Replaced with `prevrandao` |
| **`mixHash`** | `0x0000000000000000000000000000000000000000000000000000000000000000` | Replaced with `prevrandao` |
| **`nonce`** | `0x0000000000000000` | |
| **`ommers`** | `[]` | `RLP([]) = 0xc0` |
| Field | Constant value | Comment |
|------------------|----------------------------------------------------------------------|----------------------------|
| **`ommersHash`** | `0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347` | `= Keccak256(RLP([]))` |
| **`difficulty`** | `0` | Replaced with `prevrandao` |
| **`mixHash`** | `0x0000000000000000000000000000000000000000000000000000000000000000` | Replaced with `prevrandao` |
| **`nonce`** | `0x0000000000000000` | |
| **`ommers`** | `[]` | `RLP([]) = 0xc0` |

Additionally, [`extraData`](#extra-data) is limited to 32 bytes of vanity data after The Merge.

Expand Down Expand Up @@ -164,6 +168,159 @@ At each epoch transition, Clique discards all pending votes collected from recei

Define the number of blocks between epoch transitions in the [Clique genesis file](#genesis-file).

## Transitions

The `transitions` genesis configuration item allows you to specify a future block number at which to
change the Clique network configuration in an existing network.
For example, you can update the [block time](#configure-block-time-on-an-existing-network) and
whether to [create empty blocks](#configure-empty-blocks-on-an-existing-network).
alexandratran marked this conversation as resolved.
Show resolved Hide resolved

:::caution
Do not specify a transition block in the past.
Specifying a transition block in the past can result in unexpected behavior, such as causing the
network to fork.
:::

### Configure block time on an existing network

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:
alexandratran marked this conversation as resolved.
Show resolved Hide resolved

- `<FutureBlockNumber>` is the upcoming block at which to change `blockperiodseconds`.
- `<NewValue>` is the updated value for `blockperiodseconds`.

<Tabs>
<TabItem value="Syntax" label="Syntax" default>

```json
{
"config": {
...
"clique": {
"blockperiodseconds": 3,
"epochlength": 30,
"requesttimeoutseconds": 6,
"createemptyblocks": true
},
"transitions": {
"clique": [
{
"block": <FutureBlockNumber>,
"blockperiodseconds": <NewValue>
}
]
}
},
...
}
```

</TabItem>
<TabItem value="Example" label="Example">

```json
{
"config": {
...
"clique": {
"blockperiodseconds": 3,
"epochlength": 30,
"requesttimeoutseconds": 6,
"createemptyblocks": true
},
"transitions": {
"clique": [
{
"block": 3,
"blockperiodseconds": 1
},
{
"block": 6,
"blockperiodseconds": 2
},
]
}
},
...
}
```

</TabItem>
</Tabs>

3. Restart all nodes in the network using the updated genesis file.
alexandratran marked this conversation as resolved.
Show resolved Hide resolved
4. To verify the changes after the transition block, view the Besu logs and check that the time
alexandratran marked this conversation as resolved.
Show resolved Hide resolved
difference between each block matches the updated block period.

### Configure empty blocks on an existing network

To update an existing network with a new [`createemptyblocks`](#skip-empty-blocks):

1. Stop all nodes in the network.
2. In the [genesis file](#genesis-file), add the `transitions` configuration item where:
alexandratran marked this conversation as resolved.
Show resolved Hide resolved

- `<FutureBlockNumber>` is the upcoming block at which to change `createemptyblocks`.
- `<NewValue>` is the updated value for `createemptyblocks`.

<Tabs>
<TabItem value="Syntax" label="Syntax" default>

```json
{
"config": {
...
"clique": {
"blockperiodseconds": 3,
"epochlength": 30,
"requesttimeoutseconds": 6,
"createemptyblocks": true
},
"transitions": {
"clique": [
{
"block": <FutureBlockNumber>,
"createemptyblocks": <NewValue>
}
]
}
},
...
}
```

</TabItem>
<TabItem value="Example" label="Example">

```json
{
"config": {
...
"clique": {
"blockperiodseconds": 3,
"epochlength": 30,
"requesttimeoutseconds": 6,
"createemptyblocks": true
},
"transitions": {
"clique": [
{
"block": 10,
"createemptyblocks": false
}
]
}
},
...
}
```

</TabItem>
</Tabs>

3. Restart all nodes in the network using the updated genesis file.

## Limitations

In Clique, blocks created by in-turn validators are published immediately. Out-of-turn validators create blocks that are published after a short delay. In-turn blocks have a higher difficulty than out-of-turn blocks, which allows small forks to resolve to the chain with more in-turn blocks.
Expand Down