forks/go-ethereum
1
0
Fork 1
mirror of https://github.com/ethereum/go-ethereum.git synced 2026-07-18 10:50:44 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs: update merge pages now merge is done (#25842)

Browse source
This commit is contained in:
Joseph Cook 2022-09-23 11:06:51 +01:00 committed by GitHub
parent 2c070c6a7e
commit a0aac03ffa
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 51 additions and 109 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

81
docs/_interface/consensus-clients.md
View file

@ -3,19 +3,15 @@ title: Connecting to Consensus Clients
sort_key: A3 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. Geth is an [execution client][ex-client-link]. Historically, an execution client alone has been
However, Ethereum will soon swap its consensus mechanism from [proof-of-work][pow-link] (PoW) to enough to run a full Ethereum node. However, since Ethereum swapped its consensus mechanism from
[proof-of-stake][pos-link] (PoS) in a transition known as [The Merge](/docs/interface/merge). [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 Instead, Geth needs to be coupled to another piece of software called a ["consensus client"][con-client-link].
be coupled to another piece of software called a ["consensus client"][con-client-link]. For Geth users that There are five consensus clients available, all of which connect to Geth in the same way.
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.
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). This page will provide a general outline for how Geth can be set up with a consensus client.
{% 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." %}
## Configuring Geth ## 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 `*` to `--authrpc.vhosts` so that incoming requests from virtual hosts are accepted by Geth because it only
applies to the port authenticated using `jwtsecret`. 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: A complete command to start Geth so that it can connect to a consensus client looks as follows:
```shell ```shell
@ -46,7 +38,7 @@ geth --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --a
## Consensus clients ## 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 [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 [Prysm](https://docs.prylabs.network/docs/install/install-with-script): written in Go
[Teku](https://pegasys.tech/teku): written in Java [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 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 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 ## 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 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
After the merge, Geth will follow the head of the chain via its connection to the consensus client. However, Geth is still that is described in detail in their respective documentation. The easiest way to handle staking and validator key generation
the portal for users to send transactions to Ethereum. Overall, Geth will not change very much from a user-perspective. is to use the Ethereum Foundation [Staking Launchpad][launchpad-link].
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.
## Summary ## Summary
As The Merge approaches it is important for Geth users to prepare by installing and running a consensus client. Otherwise, Geth will stop Geth requires a connection to a consensus client in order to follow the Etheruem blockchain. There are five consensus clients
following the head of the chain immediately after The Merge. There are five consensus clients to choose from. This page provided an overview to choose from. This page provided an overview of how to choose a consensus client and configure Geth to connect to it. More
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 information can be found on the clients' respective documentation sites or in numerous
result of The Merge. [online guides](https://github.com/SomerEsat/ethereum-staking-guides).
[pow-link]:https://ethereum.org/en/developers/docs/consensus-mechanisms/pow [pow-link]:https://ethereum.org/en/developers/docs/consensus-mechanisms/pow

79
docs/_interface/merge.md
View file

@ -3,36 +3,32 @@ title: The Merge
sort_key: A2 sort_key: A2
--- ---
The Merge is probably the most significant upgrade to Ethereum since Homestead. This page explains what The Merge is The Merge was probably the most significant upgrade to Ethereum since Homestead. This page explains what The Merge was
and how it will affect Geth users. Instructions on how to configure an Ethereum node in and how it affected Geth users.
anticipation of The Merge are provided on the [Consensus Clients page](/docs/interface/consensus-clients).
## What is The Merge ## What was The Merge
[The Merge](https://ethereum.org/en/upgrades/merge/) is an upcoming upgrade to Ethereum that swaps out its current [The Merge](https://ethereum.org/en/upgrades/merge/) was an upgrade to Ethereum that swapped out its original
proof-of-work (PoW) consensus mechanism for a proof-of-stake (PoS) mechanism. The term "Merge" refers 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 to the fact that the initial phase of the transition involved launching a PoS chain in parallel with the
the existing PoW Ethereum Mainnet. This PoS chain, known as the Beacon Chain, has been executing the PoS PoW Ethereum Mainnet. That PoS chain, known as the Beacon Chain, was been executing the PoS consensus logic but
consensus logic since November 2020 but without integrating real Ethereum transaction data. The Merge refers without including any real Ethereum transaction data. The Merge was the moment when Ethereum's blockchain
to the moment when Ethereum's existing blockchain and the Beacon Chain join together to form one unified chain. and the Beacon Chain joined together to form one unified chain. At the moment of The Merge, execution clients
At the moment of the merge, execution clients will switch off their proof-of-work and block gossiping functions switched off their proof-of-work and block gossiping functions and handed responsibility for all consensus and
and hand responsibility for all consensus and fork choice logic over to consensus clients. This is a profound fork choice logic over to consensus clients. This was a profound change to how Ethereum operates. Now that The Merge
change to how Ethereum operates and it will require node operators to run a consensus client in addition to is done, node operators are required to run a consensus client in addition to an execution client such as Geth.
Geth.
## How will Geth change? ## How did Geth change?
Geth is an execution client. Historically, an execution client alone has been enough to run a full Ethereum node. Geth is an execution client. Historically, running an execution client alone was enough to turn a computer
However, when The Merge happens, Geth will not be able to track the Ethereum chain on its own. Instead, it will need to into a full Ethereum node. However, since The Merge, Geth has not been able to track the Ethereum chain on
be coupled to another piece of software called a ["consensus client"][con-client-link]. In this configuration, its own. Instead, it needs to be coupled to another piece of software called a ["consensus client"][con-client-link].
the execution client will be responsible for transaction handling, transaction gossip, state management and The execution client is 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 the Ethereum Virtual Machine (EVM). However, Geth is no longer responsible for block proposals or
gossiping or handling consensus logic. These will be in the remit of the consensus client. handling consensus logic. These are 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 There are five consensus clients available, all of which connect to Geth in the same way.
a consensus client in advance, so that The Merge can happen smoothly. There are five consensus clients available, all Instructions for this are available on the [Consensus Clients page](/docs/interface/consensus-clients).
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 ## 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 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 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 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 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. This inter-client communication is handled by a local RPC connection using the include in the new block and a resulting state change. This inter-client communication is handled by a local RPC
[`engine` API][engine-api-link] which is part of the JSON-RPC API exposed by Geth. connection using the [`engine` API][engine-api-link] which is part of the JSON-RPC API exposed by Geth.
## Transition ## Using Geth since The Merge
The transition from PoW to PoS will happen when a pre-announced total difficulty is reached by the chain. Although The Merge was a profound change to Ethereum's underlying achitecture, there were minimal changes to how Geth
This is different to other forks which usually occur at a certain scheduled block number. The total difficulty threshold users interact with Ethereum. At The Merge responsibility for consensus logic and block propagation were handed over to
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
the consensus layer, but all of Geth’s other functionality remains intact. This means transactions, contract deployments 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 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 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 ## Summary
The Merge is an upcoming upgrade to Ethereum that swaps the existing PoW consensus mechanism for a PoS consensus The Merge was an upgrade to Ethereum that swapped the original PoW based consensus mechanism for a PoS based consensus
mechanism. This changes the client software organization for Ethereum nodes. After The Merge, nodes are required to mechanism. This changed the client software organization for Ethereum nodes. Since The Merge, both execution and consensus
run both execution and consensus clients that each have responsibility for specific parts of the Ethereum protocol clients are required. Each client has responsibility for specific parts of the Ethereum protocol and communicate with each
and communicate with each other over a local RPC connection. Although there is some necessary configuration in advance other over a local RPC connection.
of The Merge, the experience for Geth users should change minimally as a result of The Merge.
[engine-api-link]: https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md [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 [cl-list]: https://ethereum.org/en/developers/docs/nodes-and-clients/#consensus-clients