initial merge documentation (#989)
* [WIP] initial merge documentation Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * more updates Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * fix md Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * update accept.txt Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * more updates Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * fix link format Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * minor edits Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * minor edits Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * reviewer suggestions Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * add tutorial Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * fix md Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * add beacon node note Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * integrate reviewer feedback Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * add diagram Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * apply reviewer feedback Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * update nav Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net> * fix md Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net>pull/1000/head
Alexandra Tran
3 years ago
committed by
GitHub
parent
0bfe32f4a6
commit
3898aed1d4
@ -0,0 +1,40 @@ |
||||
--- |
||||
description: Ethereum proof of stake |
||||
--- |
||||
|
||||
# Proof of stake |
||||
|
||||
[The Merge](../Merge.md) transitions Ethereum Mainnet to |
||||
[proof of stake (PoS)](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/) consensus. |
||||
|
||||
In Ethereum's PoS, you must run a [full node](../Merge.md#execution-and-consensus-clients) and |
||||
[stake 32 ETH](https://ethereum.org/en/staking/) to become a validator. |
||||
|
||||
!!! important |
||||
|
||||
Withdrawing staked ETH isn't yet supported and will be included in a separate upgrade following The Merge. |
||||
|
||||
The PoS mechanism randomly chooses validators to propose or validate blocks on the |
||||
[Beacon Chain](https://ethereum.org/en/upgrades/beacon-chain/) (consensus blocks) in defined time frames (slots). |
||||
|
||||
Proposers are responsible for proposing new consensus blocks, and non-proposing validators are responsible for |
||||
validating (attesting to) proposed blocks. |
||||
Validators are rewarded for proposing and attesting to consensus blocks eventually included in the Beacon Chain, and |
||||
their stake is slashed if they fail to validate or if they attest to malicious blocks, incentivizing good behavior. |
||||
|
||||
Each consensus block contains an execution payload, which contains a list of transactions and other data required to |
||||
execute and validate the payload. |
||||
|
||||
When a node validates a consensus block, its [consensus client](../Merge.md#execution-and-consensus-clients) processes |
||||
the block and sends the execution payload to the [execution client](../Merge.md#execution-and-consensus-clients), which: |
||||
|
||||
1. Assembles a block on the execution layer (execution block). |
||||
1. Verifies pre-conditions. |
||||
1. Executes transactions. |
||||
1. Verifies post-conditions. |
||||
1. Sends the validity result back to the consensus client. |
||||
|
||||
If the block is valid, the execution client includes it in the execution chain and stores the new state in execution |
||||
state storage. |
||||
|
||||
If at least 128 validators attest to a consensus block within a slot, it's included in the Beacon Chain. |
||||
@ -0,0 +1,57 @@ |
||||
--- |
||||
description: What is the Merge? |
||||
--- |
||||
|
||||
# The Merge |
||||
|
||||
The Ethereum upgrade known as [The Merge](https://ethereum.org/en/upgrades/merge/) will merge the [Beacon Chain] into |
||||
Ethereum Mainnet, turning Mainnet into a combination of an |
||||
[execution layer and consensus layer](#execution-and-consensus-clients). |
||||
The Merge will transition Mainnet from proof of work to [proof of stake consensus](Consensus-Protocols/Proof-of-Stake.md). |
||||
|
||||
## Execution and consensus clients |
||||
|
||||
After The Merge, a full Ethereum Mainnet node will be a combination of an execution client (previously called an |
||||
[Ethereum 1.0](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/) client) and a consensus client (previously |
||||
called an [Ethereum 2.0](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/) client). |
||||
|
||||
Execution clients, such as Besu, manage the state and execute transactions on the execution layer. |
||||
Consensus clients, such as [Teku], maintain [consensus](Consensus-Protocols/Proof-of-Stake.md) on the [Beacon Chain] |
||||
(consensus layer). |
||||
|
||||
Execution and consensus clients communicate with each other using the |
||||
[Engine API](https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md). |
||||
Execution clients serve [JSON-RPC API](../Reference/API-Methods.md) requests and consensus clients serve |
||||
[REST API](https://docs.teku.consensys.net/en/stable/Reference/Rest_API/Rest/) requests. |
||||
Execution clients communicate among each other in a peer-to-peer network, and consensus clients do the same. |
||||
|
||||
 |
||||
|
||||
### Run a node |
||||
|
||||
After The Merge, a Mainnet node operator must run both an execution client and a consensus client at the same time. |
||||
You must run a node to become a Mainnet [validator](Consensus-Protocols/Proof-of-Stake.md), but you can also run a |
||||
non-validator node. |
||||
|
||||
!!! note |
||||
|
||||
Consensus clients that don't perform validator duties are referred to as "beacon nodes" or "Beacon Chain clients." |
||||
|
||||
You can |
||||
[test Besu as an execution client on the Merge testnet](../Tutorials/Merge-Testnet.md). |
||||
You must test it with a consensus client, for example, [Teku]. |
||||
|
||||
You can run Besu as an execution client on Ethereum Mainnet using the same |
||||
[installation options](../HowTo/Get-Started/Installation-Options). |
||||
|
||||
Consensus clients compatible with Besu include: |
||||
|
||||
- [Teku] (recommended) |
||||
- [Lighthouse](https://lighthouse.sigmaprime.io/) |
||||
- [Lodestar](https://lodestar.chainsafe.io/) |
||||
- [Prysm](https://github.com/prysmaticlabs/prysm) |
||||
- [Nimbus](https://nimbus.team/) |
||||
|
||||
<!-- links --> |
||||
[Beacon Chain]: https://ethereum.org/en/upgrades/beacon-chain/ |
||||
[Teku]: https://docs.teku.consensys.net/en/stable/ |
||||
@ -0,0 +1,94 @@ |
||||
--- |
||||
Description: How to run Besu and Teku on the Merge testnet |
||||
--- |
||||
|
||||
# Run clients on the Merge testnet |
||||
|
||||
You can test Besu as an [execution client](../Concepts/Merge.md) and [Teku](https://docs.teku.consensys.net/en/stable/) |
||||
as a [consensus client](../Concepts/Merge.md) on the [Kiln Merge testnet](https://blog.ethereum.org/2022/03/14/kiln-merge-testnet/). |
||||
|
||||
## Prerequisites |
||||
|
||||
- Install [Besu](../HowTo/Get-Started/Installation-Options/Options.md) and |
||||
[Teku](https://docs.teku.consensys.net/en/stable/HowTo/Get-Started/Installation-Options/Install-Binaries/). |
||||
|
||||
- Generate the JWT secret: |
||||
|
||||
```bash |
||||
openssl rand -hex 32 | tr -d "\n" > jwtsecret.hex |
||||
``` |
||||
|
||||
You must pass this file to both Besu and Teku. |
||||
This is a shared secret the clients use to authenticate each other when using the Engine API. |
||||
|
||||
- Create a test Ethereum address to use as the |
||||
[default fee recipient](https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/#validators-proposer-default-fee-recipient) |
||||
when starting Teku. |
||||
|
||||
## Start Besu |
||||
|
||||
Run the following command: |
||||
|
||||
```bash |
||||
besu \ |
||||
--network=kiln \ |
||||
--rpc-http-enabled=true \ |
||||
--rpc-http-host="0.0.0.0" \ |
||||
--rpc-http-cors-origins="*" \ |
||||
--rpc-ws-enabled=true \ |
||||
--rpc-ws-host="0.0.0.0" \ |
||||
--host-allowlist="*" \ |
||||
--engine-host-allowlist="*" \ |
||||
--engine-jwt-enabled=true \ |
||||
--engine-rpc-http-port=8550 \ |
||||
--engine-rpc-ws-port=8551 \ |
||||
--Xmerge-support=true \ |
||||
--engine-jwt-secret=<path_to_jwtsecret> |
||||
``` |
||||
|
||||
See the [`--engine-*`](../Reference/CLI/CLI-Syntax.md#engine-host-allowlist) CLI options for more information on running |
||||
Besu as an execution client. |
||||
|
||||
## Start Teku |
||||
|
||||
Run the following command: |
||||
|
||||
```bash |
||||
teku \ |
||||
--data-path "datadir-teku" \ |
||||
--network kiln \ |
||||
--p2p-discovery-bootnodes "enr:-Iq4QMCTfIMXnow27baRUb35Q8iiFHSIDBJh6hQM5Axohhf4b6Kr_cOCu0htQ5WvVqKvFgY28893DHAg8gnBAXsAVqmGAX53x8JggmlkgnY0gmlwhLKAlv6Jc2VjcDI1NmsxoQK6S-Cii_KmfFdUJL2TANL3ksaKUnNXvTCv1tLwXs0QgIN1ZHCCIyk" \ |
||||
--ee-endpoint http://localhost:8550 \ |
||||
--Xee-version kilnv2 \ |
||||
--ee-jwt-secret-file <path_to_jwtsecret> \ |
||||
--log-destination console \ |
||||
--validators-proposer-default-fee-recipient=<eth_address_of_default_fee_recipient> |
||||
``` |
||||
|
||||
This runs Teku as a beacon node (without validator duties). |
||||
See the Teku [`--validators-*`](https://docs.teku.consensys.net/en/latest/Reference/CLI/CLI-Syntax/#validator-keys) CLI |
||||
options for information on running Teku as a validator. |
||||
|
||||
After starting Besu and Teku, your node should start syncing and connecting to peers. |
||||
|
||||
!!! example |
||||
|
||||
=== "Besu logs" |
||||
|
||||
```bash |
||||
2022-03-21 20:42:09.295-07:00 | EthScheduler-Timer-0 | INFO | FullSyncTargetManager | No sync target, waiting for peers. Current peers: 0 |
||||
2022-03-21 20:42:14.298-07:00 | EthScheduler-Timer-0 | INFO | FullSyncTargetManager | No sync target, waiting for peers. Current peers: 0 |
||||
2022-03-21 20:42:14.848-07:00 | nioEventLoopGroup-3-8 | INFO | FullSyncTargetManager | No sync target, waiting for peers. Current peers: 4 |
||||
2022-03-21 20:42:18.452-07:00 | nioEventLoopGroup-3-8 | INFO | SyncTargetManager | Found common ancestor with peer Peer 0xab3a286b181721c794... at block 55127 |
||||
2022-03-21 20:42:18.454-07:00 | nioEventLoopGroup-3-8 | INFO | PipelineChainDownloader | PipelineChain download complete |
||||
``` |
||||
|
||||
=== "Teku logs" |
||||
|
||||
```bash |
||||
2022-03-21 20:43:24.355 INFO - Syncing *** Target slot: 76092, Head slot: 2680, Remaining slots: 73412, Connected peers: 8 |
||||
2022-03-21 20:43:36.363 INFO - Syncing *** Target slot: 76093, Head slot: 2879, Remaining slots: 73214, Connected peers: 10 |
||||
2022-03-21 20:43:48.327 INFO - Syncing *** Target slot: 76094, Head slot: 3080, Remaining slots: 73014, Connected peers: 8 |
||||
2022-03-21 20:44:00.339 INFO - Syncing *** Target slot: 76095, Head slot: 3317, Remaining slots: 72778, Connected peers: 6 |
||||
2022-03-21 20:44:12.353 INFO - Syncing *** Target slot: 76096, Head slot: 3519, Remaining slots: 72577, Connected peers: 9 |
||||
``` |
||||
|
After Width: | Height: | Size: 106 KiB |
Loading…
Reference in new issue