Skip to content

Commit

Permalink
Document Clique transitions (#1583)
Browse files Browse the repository at this point in the history 
* Document Clique block period transition

Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net>

* fix syntax and add empty blocks transition

Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net>

---------

Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net>
Co-authored-by: Alexandra Tran <alexandra.tran@consensys.net>
  • Loading branch information
@alexandratran
alexandratran and Alexandra Tran committed May 2, 2024
1 parent 898070c commit 38ddde3
Show file tree
Hide file tree
Showing 4 changed files with 311 additions and 180 deletions.
77 changes: 35 additions & 42 deletions docs/private-networks/how-to/configure/consensus/add-validators-without-voting.md
View file
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
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).

:::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:

- `<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.
4. To verify the changes after the transition block, view the Besu logs and check that the time
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:

- `<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

0 comments on commit 38ddde3

Please sign in to comment.