From a0aac03ffad3d79c00177749e11fe9691f7827be Mon Sep 17 00:00:00 2001 From: Joseph Cook <33655003+jmcook1186@users.noreply.github.com> Date: Fri, 23 Sep 2022 11:06:51 +0100 Subject: [PATCH] docs: update merge pages now merge is done (#25842) --- docs/_interface/consensus-clients.md | 81 ++++++------------------ docs/_interface/merge.md | 93 ++++++++++++---------------- 2 files changed, 58 insertions(+), 116 deletions(-) diff --git a/docs/_interface/consensus-clients.md b/docs/_interface/consensus-clients.md index 2a97551ab2..3327f5ab17 100644 --- a/docs/_interface/consensus-clients.md +++ b/docs/_interface/consensus-clients.md @@ -3,19 +3,15 @@ title: Connecting to Consensus Clients sort_key: A3 --- -Geth is an [execution client][ex-client-link]. Historically, an execution client alone has been enough to run a full Ethereum node. -However, Ethereum will soon swap its consensus mechanism from [proof-of-work][pow-link] (PoW) to -[proof-of-stake][pos-link] (PoS) in a transition known as [The Merge](/docs/interface/merge). +Geth is an [execution client][ex-client-link]. Historically, an execution client alone has been +enough to run a full Ethereum node. However, since Ethereum swapped its consensus mechanism from +[proof-of-work][pow-link] (PoW) to [proof-of-stake][pos-link] (PoS) Geth is no longer able to track +the Ethereum chain on its own. -When that happens, Geth will not be able to track the Ethereum chain on its own. Instead, it will need to -be coupled to another piece of software called a ["consensus client"][con-client-link]. For Geth users that -intend to continue to run full nodes after The Merge, it is sensible to start running a consensus client now, -so that The Merge can happen smoothly. There are five consensus clients available, all of which connect to Geth in the same way. +Instead, Geth needs to be coupled to another piece of software called a ["consensus client"][con-client-link]. +There are five consensus clients available, all of which connect to Geth in the same way. -This page will outline how Geth can be set up with a consensus client in advance of The Merge (or to interact with an alread-merged testnet). - -{% include note.html content=" It is recommended to practise connecting a consensus client to Geth on a testnet such as Sepolia or Goerli but to -wait until merge-ready releases are available before doing it on Ethereum Mainnet." %} +This page will provide a general outline for how Geth can be set up with a consensus client. ## Configuring Geth @@ -33,10 +29,6 @@ The authorization must then be applied to a specific address/port. This is achie `*` to `--authrpc.vhosts` so that incoming requests from virtual hosts are accepted by Geth because it only applies to the port authenticated using `jwtsecret`. -The Merge itself will be triggered using a terminal total difficulty (TTD). The specific value for the TTD has not yet -been decided. When it is decided, Geth needs to know what it is in order to merge successfully. This will most likely be -included in a new release, so Geth will have to be stopped, updated and restarted in advance of The Merge. - A complete command to start Geth so that it can connect to a consensus client looks as follows: ```shell @@ -46,7 +38,7 @@ geth --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --a ## Consensus clients -There are currently four consensus clients that can be run alongside Geth. These are: +There are currently five consensus clients that can be run alongside Geth. These are: [Lighthouse](https://lighthouse-book.sigmaprime.io/): written in Rust @@ -55,8 +47,11 @@ There are currently four consensus clients that can be run alongside Geth. These [Prysm](https://docs.prylabs.network/docs/install/install-with-script): written in Go [Teku](https://pegasys.tech/teku): written in Java + +[Lodestar](https://github.com/ChainSafe/lodestar): written in Typescript -It is recommended to consider [client diversity][client-div-link] when choosing a consensus client. Instructions for installing each client are provided in the documentation linked in the list above. +It is recommended to consider [client diversity][client-div-link] when choosing a consensus client. +Instructions for installing each client are provided in the documentation linked in the list above. The consensus client must be started with the right port configuration to establish an RPC connection to the local Geth instance. In the example above, `localhost:8551` was authorized @@ -73,55 +68,19 @@ More information on this can be found in the documentation for each consensus cl ## Validators -After The Merge, miners are no longer responsible for securing the Ethereum blockchain. Instead, this becomes the responsibility -of validators that have staked at least 32 ETH into a deposit contract and run validator software. Each of the consensus clients -have their own validator software that is described in detail in their respective documentation. The easiest way to handle -staking and validator key generation is to use the Ethereum Foundation [Staking Launchpad][launchpad-link]. The launchpad is also -available for [Prater][prater-launchpad-link], [Ropsten][ropsten-launchpad-link] and [Kiln][kiln-launchpad-link] testnets. It is -also highly recommended to review the [Merge readiness checklist][checklist-link]. - -## Using Geth - -After the merge, Geth will follow the head of the chain via its connection to the consensus client. However, Geth is still -the portal for users to send transactions to Ethereum. Overall, Geth will not change very much from a user-perspective. -The Geth Javascript console is still available for this purpose, and the majority of the [JSON-RPC API](/docs/rpc/server) will -remain available via web3js or HTTP requests with commands as json payloads. These options are explained in more detail on the -[Javascript Console page](/docs/interface/javascript-console). The Javascript console can be started using the following command -in a separate terminal (assuming Geth's IPC file is saved in `datadir`): - -```shell -geth attach datadir/geth.ipc -``` - - -## Testnets - -Ethereum Mainnet has not yet undergone The Merge, but some public testnets have. This means that running Geth alone is no longer -enough to interact with merged testnets. This includes two testnets that were purpose built to test The Merge (Kiln, Kintsugi) and -the long-standing public PoW chain, Ropsten, as well as the relatively new testnet Sepolia. If Geth is connected to these merged networks alone it will simply stall when it syncs as far -as the merge block, awaiting information from a consensus client. Therefore, any activity on these testnets requires Geth to be -connected to a consensus client. There are many instructional articles that explain how to connect to these testnets using Geth in -combination with various consensus clients, for example: - -[Connecting to Kiln using Teku](https://github.com/chrishobcroft/TestingTheMerge/blob/main/geku.md) - -[Connecting to Kiln using Lighthouse](https://github.com/remyroy/ethstaker/blob/main/merge-devnet.md) - -[Connecting to Kiln using Prysm](https://hackmd.io/@prysmaticlabs/B1Q2SluWq) - -[Connecting to Ropsten using Lighthouse](https://github.com/remyroy/ethstaker/blob/main/merge-ropsten.md) - -The Merge testing will soon progress to merging the Goerli testnet. Once this has happened Geth will require a connection -to a consensus client to work on those networks too. +Validators are responsible for securing the Ethereum blockchain. Validators are node oeprators that have staked at least +32 ETH into a deposit contract and run validator software. Each of the consensus clients have their own validator software +that is described in detail in their respective documentation. The easiest way to handle staking and validator key generation +is to use the Ethereum Foundation [Staking Launchpad][launchpad-link]. ## Summary -As The Merge approaches it is important for Geth users to prepare by installing and running a consensus client. Otherwise, Geth will stop -following the head of the chain immediately after The Merge. There are five consensus clients to choose from. This page provided an overview -of how to choose a consensus client and configure Geth to connect to it. This pre-emptive action will protect against disruption to users as a -result of The Merge. +Geth requires a connection to a consensus client in order to follow the Etheruem blockchain. There are five consensus clients +to choose from. This page provided an overview of how to choose a consensus client and configure Geth to connect to it. More +information can be found on the clients' respective documentation sites or in numerous +[online guides](https://github.com/SomerEsat/ethereum-staking-guides). [pow-link]:https://ethereum.org/en/developers/docs/consensus-mechanisms/pow diff --git a/docs/_interface/merge.md b/docs/_interface/merge.md index ed8044c84c..dcbf718529 100644 --- a/docs/_interface/merge.md +++ b/docs/_interface/merge.md @@ -3,36 +3,32 @@ title: The Merge sort_key: A2 --- -The Merge is probably the most significant upgrade to Ethereum since Homestead. This page explains what The Merge is -and how it will affect Geth users. Instructions on how to configure an Ethereum node in -anticipation of The Merge are provided on the [Consensus Clients page](/docs/interface/consensus-clients). - -## What is The Merge - -[The Merge](https://ethereum.org/en/upgrades/merge/) is an upcoming upgrade to Ethereum that swaps out its current -proof-of-work (PoW) consensus mechanism for a proof-of-stake (PoS) mechanism. The term "Merge" refers -to the fact that the initial phase of the transition involved launching a PoS chain in parallel with -the existing PoW Ethereum Mainnet. This PoS chain, known as the Beacon Chain, has been executing the PoS -consensus logic since November 2020 but without integrating real Ethereum transaction data. The Merge refers -to the moment when Ethereum's existing blockchain and the Beacon Chain join together to form one unified chain. -At the moment of the merge, execution clients will switch off their proof-of-work and block gossiping functions -and hand responsibility for all consensus and fork choice logic over to consensus clients. This is a profound -change to how Ethereum operates and it will require node operators to run a consensus client in addition to -Geth. - -## How will Geth change? - -Geth is an execution client. Historically, an execution client alone has been enough to run a full Ethereum node. -However, when The Merge happens, Geth will not be able to track the Ethereum chain on its own. Instead, it will need to -be coupled to another piece of software called a ["consensus client"][con-client-link]. In this configuration, -the execution client will be responsible for transaction handling, transaction gossip, state management and -the Ethereum Virtual Machine (EVM). However, Geth will no longer be responsible for block building, block -gossiping or handling consensus logic. These will be in the remit of the consensus client. - -For Geth users that intend to continue to run full nodes after The Merge, it is sensible to start running -a consensus client in advance, so that The Merge can happen smoothly. There are five consensus clients available, all -of which connect to Geth in the same way. Instructions for this are available on the -[Consensus Clients page](/docs/interface/consensus-clients). +The Merge was probably the most significant upgrade to Ethereum since Homestead. This page explains what The Merge was +and how it affected Geth users. + +## What was The Merge + +[The Merge](https://ethereum.org/en/upgrades/merge/) was an upgrade to Ethereum that swapped out its original +proof-of-work (PoW) based consensus mechanism for a proof-of-stake based (PoS) mechanism. The term "Merge" refers +to the fact that the initial phase of the transition involved launching a PoS chain in parallel with the +PoW Ethereum Mainnet. That PoS chain, known as the Beacon Chain, was been executing the PoS consensus logic but +without including any real Ethereum transaction data. The Merge was the moment when Ethereum's blockchain +and the Beacon Chain joined together to form one unified chain. At the moment of The Merge, execution clients +switched off their proof-of-work and block gossiping functions and handed responsibility for all consensus and +fork choice logic over to consensus clients. This was a profound change to how Ethereum operates. Now that The Merge +is done, node operators are required to run a consensus client in addition to an execution client such as Geth. + +## How did Geth change? + +Geth is an execution client. Historically, running an execution client alone was enough to turn a computer +into a full Ethereum node. However, since The Merge, Geth has not been able to track the Ethereum chain on +its own. Instead, it needs to be coupled to another piece of software called a ["consensus client"][con-client-link]. +The execution client is responsible for transaction handling, transaction gossip, state management and +the Ethereum Virtual Machine (EVM). However, Geth is no longer responsible for block proposals or +handling consensus logic. These are in the remit of the consensus client. + +There are five consensus clients available, all of which connect to Geth in the same way. +Instructions for this are available on the [Consensus Clients page](/docs/interface/consensus-clients). ## Client architecture @@ -47,26 +43,14 @@ network, enabling consensus and chain growth. For this two-client structure to work, consensus clients must be able to pass bundles of transactions to Geth to be executed. Executing the transactions locally is how the client validates that the transactions do not violate any Ethereum rules and that the proposed update to Ethereum's state is correct. Likewise, when the node -is selected to be a block producer the consensus client must be able to request bundles of transactions from Geth to -include in the new block. This inter-client communication is handled by a local RPC connection using the -[`engine` API][engine-api-link] which is part of the JSON-RPC API exposed by Geth. - -## Transition - -The transition from PoW to PoS will happen when a pre-announced total difficulty is reached by the chain. -This is different to other forks which usually occur at a certain scheduled block number. The total difficulty threshold -that will trigger the Merge is also known as the [*Terminal -Total Difficulty* (TTD)](https://ethereum.org/en/glossary/#terminal-total-difficulty). In -case of an emergency delay, the TTD can be overriden in Geth using the `--override.terminaltotaldifficulty` command-line -flag. Once the merge block exists, Geth will no longer be able to follow the head of the chain without a consensus -client. If Geth is not connected to a consensus client it will simply stall at the merge block. -Assuming a consensus client is connected in advance, the two clients will automatically -handle the merge together with no disruption to the user. - -## Using Geth after The Merge - -Although The Merge is a profound change to Ethereum's underlying achitecture, there will be minimal changes to how Geth -users interact with Ethereum. At The Merge responsibility for consensus logic and block propagation are handed over to +is selected to be a block producer the consensus client must be able to request executable data from Geth including bundles of transactions and metadata to +include in the new block and a resulting state change. This inter-client communication is handled by a local RPC +connection using the [`engine` API][engine-api-link] which is part of the JSON-RPC API exposed by Geth. + +## Using Geth since The Merge + +Although The Merge was a profound change to Ethereum's underlying achitecture, there were minimal changes to how Geth +users interact with Ethereum. At The Merge responsibility for consensus logic and block propagation were handed over to the consensus layer, but all of Geth’s other functionality remains intact. This means transactions, contract deployments and data queries can still be handled by Geth using the same methods as before. This includes interacting with Geth using the JSON_RPC_API directly using tools such as [curl](https//curl.se), third party libraries such as @@ -76,11 +60,10 @@ Much more information about the Javascript console is available on the [Javascri ## Summary -The Merge is an upcoming upgrade to Ethereum that swaps the existing PoW consensus mechanism for a PoS consensus -mechanism. This changes the client software organization for Ethereum nodes. After The Merge, nodes are required to -run both execution and consensus clients that each have responsibility for specific parts of the Ethereum protocol -and communicate with each other over a local RPC connection. Although there is some necessary configuration in advance -of The Merge, the experience for Geth users should change minimally as a result of The Merge. +The Merge was an upgrade to Ethereum that swapped the original PoW based consensus mechanism for a PoS based consensus +mechanism. This changed the client software organization for Ethereum nodes. Since The Merge, both execution and consensus +clients are required. Each client has responsibility for specific parts of the Ethereum protocol and communicate with each +other over a local RPC connection. [engine-api-link]: https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md [cl-list]: https://ethereum.org/en/developers/docs/nodes-and-clients/#consensus-clients