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 1 commit
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
106 changes: 98 additions & 8 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 @@ -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,92 @@ 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).

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

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

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

```bash
{
"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, call
[`clique_getSigners`](../../../reference/api/index.md#clique_getsigners),
specifying `latest`.
alexandratran marked this conversation as resolved.
Show resolved Hide resolved

## 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
108 changes: 50 additions & 58 deletions docs/private-networks/how-to/configure/consensus/ibft.md
View file
Open in desktop
Expand Up @@ -174,13 +174,13 @@ Optional configuration options in the genesis file are:

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 @@ -250,27 +250,30 @@ Non-validator nodes don't affect performance and don't count towards the maximum

## Transitions

The `transitions` genesis configuration item allows you to specify a future block number at which to change IBFT 2.0 network configuration in an existing network. For example, you can update the [block time](#configure-block-time-on-an-existing-network-deployment), [block reward](#configure-block-rewards-on-an-existing-network-deployment), or [mining beneficiary](#configure-the-mining-beneficiary-on-an-existing-network-deployment).
The `transitions` genesis configuration item allows you to specify a future block number at which to
change the IBFT 2.0 network configuration in an existing network.
For example, you can update the [block time](#configure-block-time-on-an-existing-network),
[block reward](#configure-block-rewards-on-an-existing-network), or
[mining beneficiary](#configure-the-mining-beneficiary-on-an-existing-network).

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

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 deployment
### Configure block time on an existing network

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:
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>
<Tabs>
<TabItem value="Syntax" label="Syntax" default>

```bash
{
Expand All @@ -294,9 +297,8 @@ To update an existing network with a new `blockperiodseconds`:
}
```

</TabItem>

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

```bash
{
Expand All @@ -320,25 +322,26 @@ To update an existing network with a new `blockperiodseconds`:
}
```

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

</Tabs>
1. Restart all nodes in the network using the updated genesis file.
1. To verify the changes after the transition block, call [`ibft_getValidatorsByBlockNumber`](../../../../public-networks/reference/api/index.md#ibft_getvalidatorsbyblocknumber), specifying `latest`.
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, call
[`ibft_getValidatorsByBlockNumber`](../../../reference/api/index.md#ibft_getvalidatorsbyblocknumber),
alexandratran marked this conversation as resolved.
Show resolved Hide resolved
specifying `latest`.

### Configure block rewards on an existing network deployment
### Configure block rewards on an existing network

To update an existing network with a new `blockreward`:

1. Stop all nodes in the network.
1. In the [genesis file](#genesis-file), add the `transitions` configuration item where:
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 `blockreward`.
- `<NewValue>` is the updated value for `blockreward`.

<Tabs>

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

```bash
{
Expand Down Expand Up @@ -371,9 +374,8 @@ To update an existing network with a new `blockreward`:
}
```

</TabItem>

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

```bash
{
Expand Down Expand Up @@ -406,30 +408,29 @@ To update an existing network with a new `blockreward`:
}
```

</TabItem>

</Tabs>
</TabItem>
</Tabs>
:::note

You can add multiple `blockreward` updates in one transition object by specifying multiple future blocks.

:::

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

### Configure the mining beneficiary on an existing network deployment
### Configure the mining beneficiary on an existing network

To update an existing network with a new mining beneficiary:

1. Stop all nodes in the network.
1. In the [genesis file](#genesis-file), add the `transitions` configuration item where:
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 `miningbeneficiary`.
- `<NewAddress>` is the updated 20-byte address for `miningbeneficiary`. Starting at `<FutureBlockNumber>`, block rewards go to this address.

<Tabs>

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

```bash
{
Expand Down Expand Up @@ -460,9 +461,8 @@ To update an existing network with a new mining beneficiary:
}
```

</TabItem>

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

```bash
{
Expand Down Expand Up @@ -493,21 +493,13 @@ To update an existing network with a new mining beneficiary:
}
```

</TabItem>

</Tabs>
</TabItem>
</Tabs>
:::note

Setting the `miningbeneficiary` to an empty value clears out any override so that block rewards go to the block producer rather than a global override address.

:::

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

<!-- Acronyms and Definitions -->

_[vanity data]: Validators can include anything they like as vanity data. _[RLP]: Recursive Length Prefix

```

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