Merge branch 'master' into homepage-mobile
This commit is contained in:
Nicolás Quiroz
commit
3006ec831f
BIN
public/images/clef_ruleset.png
Normal file
BIN
public/images/clef_ruleset.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 299 KiB |
190
src/pages/docs/fundamentals/logs.md
Normal file
190
src/pages/docs/fundamentals/logs.md
Normal file
@ -0,0 +1,190 @@
|
||||
---
|
||||
title: Geth logs
|
||||
description: Geth's log messages explained
|
||||
---
|
||||
|
||||
A Geth node continually reports messages to the console allowing users to monitor Geth's current status in real-time. The logs indicate when Geth is running normally and indicates when some attention is required. However, reading these logs can be difficult for new users. This page will help to interpret the log messages to better understand what Geth is doing.
|
||||
|
||||
Note that there are a large number of log messages covering a wide range of possible scenarios for a Geth node. This page will only address a subset of commonly seen messages. For more, see the [Geth Github](https://github.com/ethereum/go-ethereum), [Discord](https://discord.gg/WHNkYDsAKU) or search on [ethereum.stackexchange](https://ethereum.stackexchange.com/). Log messages are usually sufficiently self-descrining that they do not require additional explanation.
|
||||
|
||||
|
||||
## Configuring log messages
|
||||
|
||||
Log messages are displayed to the console by default. The messages can be tuned to be more or less detailed by passing `--verbosity` and a value between 0 and 6 to Geth at startup:
|
||||
|
||||
```sh
|
||||
0 = silent (no log messages)
|
||||
1 = error (error messages only)
|
||||
2 = warn (error messages and warnings only)
|
||||
3 = info (error messages, warnings and normal activity logs)
|
||||
4 = debug (all info plus additional messages for debugging)
|
||||
5 = detail (all info plus detailed debugging messages)
|
||||
```
|
||||
The default is `--verbosity 3`.
|
||||
|
||||
Log messages can also be redirected so they are saved to a text file instead of being displayed in the console. In Linux the syntax `>> <path> 2>&1` redirects both `stdout` and `stderr` messages to `<path>`. For example:
|
||||
|
||||
```sh
|
||||
# saves detailed logs to path/eth.log
|
||||
geth --verbosity 5 >> /path/eth.log 2>&1
|
||||
```
|
||||
|
||||
### Startup
|
||||
|
||||
When Geth starts up it immediately reports a fairly long page of configuration details and status reports that allow the user to confirm Geth is on the right network and operating in its intended modes. The basic structure of a log message is as follows:
|
||||
|
||||
```
|
||||
MESSAGE_TYPE [MONTH-DAY][TIME] MESSAGE VALUE
|
||||
```
|
||||
Where `MESSAGE_TYPE` can be `INFO`, `WARN`, `ERROR` or `DEBUG`. These tags categorize log messages according to their purpose. `INFO` messages inform the user about Geth's current configuration and status. `WARN` messages are for alerting the user to details that affect the way Geth is running. `ERROR` messages are for alerting the user to problems. `DEBUG` is for messages that are relevant to troubleshooting or for developers working on Geth.
|
||||
|
||||
The messages displayed on startup break down as follows:
|
||||
|
||||
```
|
||||
INFO [10-04|10:20:52.028] Starting Geth on Ethereum mainnet...
|
||||
INFO [10-04|10:20:52.028] Bumping default cache on mainnet provided=1024 updated=4096
|
||||
INFO [10-04|10:20:52.030] Maximum peer count ETH=50 LES=0 total=50
|
||||
INFO [10-04|10:20:52.031] Smartcard socket not found, disabling err="stat /run/pcscd/pcscd.comm: no such file or directory"
|
||||
INFO [10-04|10:20:52.034] Set global gas cap cap=50,000,000
|
||||
INFO [10-04|10:20:52.035] Allocated trie memory caches clean=614.00MiB dirty=1024.00MiB
|
||||
INFO [10-04|10:20:52.035] Allocated cache and file handles database=/home/go-ethereum/devnet/geth/chaindata cache=2.00GiB handles=524,288
|
||||
INFO [10-04|10:20:52.128] Opened ancient database database=/home/go-ethereum/devnet/geth/chaindata/ancient/chain readonly=false
|
||||
INFO [10-04|10:20:52.129] Disk storage enabled for ethash caches dir=/home/go-ethereum/devnet/geth/ethash count=3
|
||||
INFO [10-04|10:20:52.129] Disk storage enabled for ethash DAGs dir=/home/.ethash count=2
|
||||
INFO [10-04|10:20:52.129] Initialising Ethereum protocol network=1 dbversion=<nil>
|
||||
INFO [10-04|10:20:52.129] Writing default main-net genesis block
|
||||
INFO [10-04|10:20:52.372] Persisted trie from memory database nodes=12356 size=1.78MiB time=21.535537ms gcnodes=0 gcsize=0.00B gctime=0s livenodes=1 livesize=0.00B
|
||||
```
|
||||
|
||||
The logs above show the user that the node is connecting to Ethereum Mainnet and some low level configuration details. The cache size is bumped to the Mainnet default (4096). The maximum peer count is the highest number of peers this node is allowed to connect to and can be used to control the bandwidth requirements of the node. Logs relating to `ethash` are out of date since Ethereum moved to proof-of-stake based consensus and can safely be ignored.
|
||||
|
||||
|
||||
```
|
||||
---------------------------------------------------------------------------------------------------------------------------------------------------------
|
||||
INFO [10-04|10:20:52.386] Chain ID: 1 (mainnet)
|
||||
INFO [10-04|10:20:52.386] Consensus: Beacon (proof-of-stake), merged from Ethash (proof-of-work)
|
||||
INFO [10-04|10:20:52.386]
|
||||
INFO [10-04|10:20:52.386] Pre-Merge hard forks:
|
||||
INFO [10-04|10:20:52.386] - Homestead: 1150000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/homestead.md)
|
||||
INFO [10-04|10:20:52.386] - DAO Fork: 1920000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/dao-fork.md)
|
||||
INFO [10-04|10:20:52.386] - Tangerine Whistle (EIP 150): 2463000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/tangerine-whistle.md)
|
||||
INFO [10-04|10:20:52.386] - Spurious Dragon/1 (EIP 155): 2675000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/spurious-dragon.md)
|
||||
INFO [10-04|10:20:52.386] - Spurious Dragon/2 (EIP 158): 2675000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/spurious-dragon.md)
|
||||
INFO [10-04|10:20:52.386] - Byzantium: 4370000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/byzantium.md)
|
||||
INFO [10-04|10:20:52.386] - Constantinople: 7280000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/constantinople.md)
|
||||
INFO [10-04|10:20:52.386] - Petersburg: 7280000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/petersburg.md)
|
||||
INFO [10-04|10:20:52.386] - Istanbul: 9069000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/istanbul.md)
|
||||
INFO [10-04|10:20:52.387] - Muir Glacier: 9200000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/muir-glacier.md)
|
||||
INFO [10-04|10:20:52.387] - Berlin: 12244000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/berlin.md)
|
||||
INFO [10-04|10:20:52.387] - London: 12965000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/london.md)
|
||||
INFO [10-04|10:20:52.387] - Arrow Glacier: 13773000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/arrow-glacier.md)
|
||||
INFO [10-04|10:20:52.387] - Gray Glacier: 15050000 (https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/gray-glacier.md)
|
||||
```
|
||||
|
||||
The above block of messages are related to past Ethereum hard forks. The names are the names of the hard forks and the numbers are the blocks at which the hard fork occurs. This means that blocks with numbers that exceed these values have the configuration required by that hard fork. The specification of each hard fork is available at the provided links (and more information is available on [ethereum.org](https://ethereum.org/en/history/)). The message `Consensus: Beacon (proof-of-stake), merged from Ethash (proof-of-work)` indicates that the node requires a Beacon node to follow the canonical chain - Geth cannot participate in consensus on its own.
|
||||
|
||||
```
|
||||
INFO [10-04|10:20:52.387] Merge configured:
|
||||
INFO [10-04|10:20:52.387] - Hard-fork specification: https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/paris.md
|
||||
INFO [10-04|10:20:52.387] - Network known to be merged: true
|
||||
INFO [10-04|10:20:52.387] - Total terminal difficulty: 58750000000000000000000
|
||||
INFO [10-04|10:20:52.387] - Merge netsplit block: <nil>
|
||||
INFO [10-04|10:20:52.387]
|
||||
INFO [10-04|10:20:52.388] Chain post-merge, sync via beacon client
|
||||
WARN [10-04|10:20:52.388] Engine API enabled protocol=eth
|
||||
---------------------------------------------------------------------------------------------------------------------------------------------------------
|
||||
```
|
||||
|
||||
The messages above relate to [The Merge](https://ethereum.org/en/upgrades/merge/). The Merge was Ethereum's transition from proof-of-work to proof-of-stake based consensus. In Geth, The Merge came in the form of the Paris hard fork which was triggered at a [terminal total difficulty](https://ethereum.org/en/glossary/#terminal-total-difficulty) of 58750000000000000000000 instead of a preconfigured block number like previous hard forks. The hard fork specification is linked in the log message. The message `network known to be merged: true` indicates that the node is following a chain that has passed the terminal total difficulty and undergone the Paris hard fork. Since September 15 2022 this will always be true for nodes on Ethereum Mainnet (and the merged testnets Sepolia and Goerli). The warning `Engine API enabled` informs the user that Geth is exposing the set of API methods required for communication with a consensus client.
|
||||
|
||||
```
|
||||
INFO [10-04|10:20:52.389] Starting peer-to-peer node instance=Geth/v1.11.0-unstable-e004e7d2-20220926/linux-amd64/go1.19.1
|
||||
INFO [10-04|10:20:52.409] New local node record seq=1,664,875,252,408 id=9aa0e5b14ccd75ec ip=127.0.0.1 udp=30303 tcp=30303
|
||||
INFO [10-04|10:20:52.409] Started P2P networking self=enode://1ef45ab610c2893b70483bf1791b550e5a93763058b0abf7c6d9e6201e07212d61c4896d64de07342c9df734650e3b40812c2dc01f894b6c385acd180ed30fc8@127.0.0.1:30303
|
||||
INFO [10-04|10:20:52.410] IPC endpoint opened url=/home/go-ethereum/devnet/geth.ipc
|
||||
INFO [10-04|10:20:52.410] Generated JWT secret path=/home/go-ethereum/devnet/geth/jwtsecret
|
||||
INFO [10-04|10:20:52.411] HTTP server started endpoint=127.0.0.1:8545 auth=false prefix= cors= vhosts=localhost
|
||||
INFO [10-04|10:20:52.411] WebSocket enabled url=ws://127.0.0.1:8551
|
||||
INFO [10-04|10:20:52.411] HTTP server started endpoint=127.0.0.1:8551 auth=true prefix= cors=localhost vhosts=localhost
|
||||
INFO [10-04|10:20:54.785] New local node record seq=1,664,875,252,409 id=9aa0e5b14ccd75ec ip=82.11.59.221 udp=30303 tcp=30303
|
||||
INFO [10-04|10:20:55.267] Mapped network port proto=udp extport=30303 intport=30303 interface="UPNP IGDv1-IP1"
|
||||
INFO [10-04|10:20:55.833] Mapped network port proto=tcp extport=30303 intport=30303 interface="UPNP IGDv1-IP1"
|
||||
INFO [10-04|10:21:03.100] Looking for peers peercount=0 tried=20 static=0
|
||||
```
|
||||
|
||||
The logs above relate to Geth starting up its peer-to-peer components and seeking other nodes to connect to. The long address reported to `Started P2P networking` is the nodes own enode address. The `IPC Endpoint` is the location of the node's IPC file that can be used to connect a Javascript console. There is a log message confirming that a JWT secret was generated and reporting its path. This is required to authenticate communication between Geth and the consensus client. There are also messages here reporting on the HTTP server that can be used to send requests to Geth. There should be two HTTP servers - one for interacting with Geth (defaults to `localhost:8545`) and one for communication with the consensus client (defaults to `localhost:8551`).
|
||||
|
||||
|
||||
### Syncing
|
||||
|
||||
The default for Geth is to sync in snap mode. This requires a block header to be provided to Geth by the consensus client. The header is then used as a target to sync to. Geth requests block headers from its peers that are parents of the target until there is a continuous chain of sequential headers of sufficient length. Then, Geth requests block bodies and receipts for each header and simultaneously starts downloading state data. This state data is stored in the form of a [Patricia Merkle Trie](https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie/). Only the leaves of the trie are downloaded, the full trie structure is then locally regenerated from the leaves up. Meanwhile, the blockchain continues to progress and the target header is updated. This means some of the regenerated state data needs to be updated. This is known as *healing*.
|
||||
|
||||
Assuming Geth has a synced consensus client and some peers it will start importing headers, block bodies and receipts. The log messages for data downloading look as follows:
|
||||
|
||||
```
|
||||
INFO [07-28|10:29:49.681] Block synchronisation started
|
||||
INFO [07-28|10:29:50.427] Imported new block headers count=1 elapsed=253.434ms number=12,914,945 hash=ee1a08..9ce38a
|
||||
INFO [07-28|10:30:00.224] Imported new block receipts count=64 elapsed=13.703s number=12,914,881 hash=fef964..d789fc age=18m5s size=7.69MiB
|
||||
INFO [07-28|10:30:18.658] Imported new block headers count=1 elapsed=46.715ms number=12,914,946 hash=7b24c8..2d8006
|
||||
INFO [07-28|10:30:21.665] Imported new state entries
|
||||
```
|
||||
|
||||
For state sync, Geth reports when the state heal is in progress. This can takea long time. The log message includes values for the number of `accounts`, `slots`, `codes` and `nodes` that were downloaded in the current healing phase, and the pending field is the number of state entires waiting to be downloaded. The `pending` value is not necessarily the number of state entries remaining until the healing is finished. As the blockchain progresses the state trie is updated and therefore the data that needs to be downloaded to heal the trie can increase as well as decrease over time. Ultimately, the state should heal faster than the blockchain progresses so the node can get in sync. When the state healing is finished there is a post-sync snapshot generation phase. The node is not in sync until the state healing phase is over.
|
||||
|
||||
```
|
||||
INFO [07-28|10:30:21.965] State heal in progress accounts=169,633@7.48MiB slots=57314@4.17MiB codes=4895@38.14MiB nodes=43,293,196@11.70GiB pending=112,626
|
||||
INFO [09-06|01:31:59.885] Rebuilding state snapshot
|
||||
INFO [09-06|01:31:59.910] Resuming state snapshot generation root=bc64d4..fc1edd accounts=0 slots=0 storage=0.00B dangling=0 elapsed=18.838ms
|
||||
```
|
||||
|
||||
There are other log messages that are commonly seen during syncing. For example:
|
||||
|
||||
```sh
|
||||
WARN [09-28|11:06:01.363] Snapshot extension registration failed
|
||||
```
|
||||
|
||||
This warning is nothing to worry about - it is reporting a configuration mismatch between the node and a peer. It does not mean syncing is stalling or failing, it simply results in the peer being dropped and replaced.
|
||||
|
||||
```sh
|
||||
# consensus client has identified a new head to use as a sync target - account for this in state sync
|
||||
INFO [10-03|15:34:01.336] Forkchoice requested sync to new head number=15,670,037 hash=84d4ec..4c0e2b
|
||||
```
|
||||
|
||||
The message above indicates that the fork choice algorithm, which is run by the consensus client, has identified a new target Geth should sync up to. This redirects the sync to prevent syncing to an outdated target and is a natural part of syncing a live blockchain.
|
||||
|
||||
|
||||
## Transaction logs
|
||||
|
||||
Transactions submitted over local IPC, Websockets or HTTP connections are reported in the console logs. For example, a simple ETH transaction appears in the console logs as follows:
|
||||
|
||||
```sh
|
||||
INFO [09-06|01:31:59.910] Submitted transaction hash=0x2893b70483bf1791b550e5a93763058b0abf7c6d9e6201e07212dbc64d4764532 from: 0xFB48587362536C606d6e89f717Fsd229673246e6 nonce: 43 recipient: 0x7C60662d63536e89f717F9673sd22246F6eB4858 value: 100,000,000,000,000,000
|
||||
```
|
||||
|
||||
Other user actions have similar log messages that are displayed to the console.
|
||||
|
||||
## Common warnings
|
||||
|
||||
There are many warnings that can be emitted by Geth as part of its normal operation. However, some are asked about especially frequently on the [Geth Github](https://github.com/ethereum/go-ethereum) and [Discord](https://discord.gg/WHNkYDsAKU) channel.
|
||||
|
||||
```sh
|
||||
WARN [10-03|18:00:40.413] Unexpected trienode heal packet peer=9f0e8fbf reqid=6,915,308,639,612,522,441
|
||||
```
|
||||
|
||||
The above is often seen and misinterpreted as a problem with snap sync. In reality, it indicates a request timeout that may be because I/O speed is low. It is usually not an issue, but if this message is seen very often over prolonged periods of time it might be rooted in a local connectivity or hardware issue.
|
||||
|
||||
```sh
|
||||
WARN [10-03|13:10:26.441] Post-merge network, but no beacon client seen. Please launch one to follow the chain!
|
||||
```
|
||||
|
||||
The above message is emitted when Geth is run without a consensus client on a post-merge proof-of-stake network. Since Ethereum moved to proof-of-stake Geth alone is not enough to follow the chain because the consensus logic is now implemented by a separate piece of software called a consensus client. This log message is displayed when the consensus client is missing. Read more about this on our [consensus clients](/docs/interface/consensus-clients.md) page.
|
||||
|
||||
```sh
|
||||
WARN [10-03 |13:10:26.499] Beacon client online, but never received consensus updates. Please ensure your beacon client is operational to follow the chain!
|
||||
```
|
||||
|
||||
The message above indicates that a consensus client is present but not working correctly. The most likely reason for this is that the client is not yet in sync. Waiting for the consensus client to sync should solve the issue.
|
||||
|
||||
## Summary
|
||||
|
||||
There are a wide range of log messages that are emitted while Geth is running. The level of detail in the logs can be configured using the `verbosity` flag at startup. This page has outlined some of the common messages users can expect to see when Geth is run with default verbosity, without attempting to be comprehensive. For more, please see the [Geth Github](https://github.com/ethereum/go-ethereum) and [Discord](https://discord.gg/WHNkYDsAKU).
|
||||
@ -3,17 +3,22 @@ title: Proof-of-work mining with Ethash
|
||||
description: Introduction to proof-of-work mining with Geth
|
||||
---
|
||||
|
||||
{% include note.html content=" Proof-of-work mining is **no longer used to secure Ethereum Mainnet**. The information below is included because the Ethash code is still part of Geth and it could be used to create a private proof-of-work network or testnet. %}
|
||||
{% include note.html content=" Proof-of-work mining is no longer used to secure Ethereum Mainnet. The information below is included because the Ethash code is still part of Geth and it could be used to create a private proof-of-work network or testnet." %}
|
||||
|
||||
Blockchains grow when nodes add blocks and distribute them to their peers. Nodes that add blocks are rewarded with ether payouts. On Ethereum Mainnet, the proof-of-stake consensus engine randomyl selects a node to produce each block. Under proof-of-work, however, block producers are selected by competition. The node that computes a certain value that can only be found using repeated random guesses wins the right to propose the next block. Only if a node can demonstrate that they have calculated this value, and therefore expended energy, will their block be accepted by other nodes. This secures the network. This process of creating blocks and securing them using proof-of-work is known as "mining".
|
||||
Blockchains grow when individual nodes create valid blocks and distribute them to their peers who check the blocks and add them to their own local databases.
|
||||
Nodes that add blocks are rewarded with ether payouts. On Ethereum Mainnet, the proof-of-stake consensus engine randomly selects a node to produce each block.
|
||||
|
||||
Much more information about mining, including details about the specific algorithm ("Ethash") used by Ethereum nodes is available on [ethereum.org](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/mining).
|
||||
Ethereum wasn't always secured this way. Originally, a proof-of-work based consensus mechanism was used instead. Under proof-of-work, block producers are not selected randomly in each slot. Instead they compete for the right to add a block. The node that is fastest to compute a certain value that can only be found using brute force calculations is the one that gets to add a block. Only if a node can demonstrate that they have calculated this value, and therefore expended energy, will their block be accepted by other nodes. This process of creating blocks and securing them using proof-of-work is known as "mining".
|
||||
|
||||
Much more information about mining, including details about the specific algorithm
|
||||
("Ethash") used by Ethereum nodes is available on [ethereum.org](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/mining-algorithms/ethash).
|
||||
|
||||
## CPU vs GPU
|
||||
|
||||
Participating in Ethereum's PoW mining requires running an algorithm called ["Ethash"](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/mining-algorithms/ethash). Geth includes a CPU miner which runs Ethash within the Geth process. This might be useful for mining on testnets or private networks where competition for producing new blocks is small. When minign was used to secure Ethereum Mainnet, CPU mining was not viable because CPU miners were easily outcompeted by more efficient GPU miners. To mine using GPUs an additional piece of third-party software is required. The recommended GPU mining software is [Ethminer](https://github.com/ethereum-mining/ethminer).
|
||||
Ethereum mining used an algorithm called ["Ethash"](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/mining-algorithms/ethash). Geth includes a CPU miner which runs Ethash within the Geth process. Everything required to mine on a CPU is bundled with Geth. However, to mine using GPUs an additional piece of third-party software is required. The most commonly used GPU mining software is [Ethminer](https://github.com/ethereum-mining/ethminer).
|
||||
|
||||
Regardless of the mining method, the blockchain must be fully synced before mining is started, otherwise the miner will build on an outdated side chain,meaning block rewards will not be recognized by the main network.
|
||||
|
||||
Regardless of the mining method, the blockchain must be fully synced before mining is started, otherwise the miner will build on an outdated side chain, meaning block rewards will not be recognized by the main network.
|
||||
|
||||
## GPU Mining
|
||||
|
||||
@ -23,15 +28,16 @@ The Ethminer software can be installed from a downloaded binary or built from so
|
||||
|
||||
### Using Ethminer with Geth
|
||||
|
||||
An account to receive block rewards must first be defined. The address of the account is all that is required to start mining - the mining rewards will be credited to that address. This can be an existing address or one that is newly created by Geth. More detailed instructions on creating and importing accounts are available on the [Account Management](/content/docs/fundamentals/account-management.md) page.
|
||||
|
||||
The account address can be provided to `--mining.etherbase` when Geth is started. This instructs Geth to direct any block rewards to this address. Once started, Geth will sync the blockchain. If Geth has not connected to this network before, or if the data directory has been deleted, this can take several days. Also, enable HTTP traffic with the `--http` command. To reiterate, mining does **not work on Ethereum, Mainnet** since the transition to proof-of-stake.
|
||||
An account to receive block rewards must first be defined. The address of the account is all that is required to start mining - the mining rewards will be credited to that address. This can be an existing address or one that is newly created by Geth. More detailed instructions on creating and importing accounts are available on the [Account Management](/docs/interface/managing-your-accounts) page.
|
||||
|
||||
The account address can be provided to `--mining.etherbase` when Geth is started. This instructs Geth to direct any block rewards to this address. Once started, Geth will sync the blockchain. If Geth has not connected to this network before, or if the data directory has been deleted, this can take several days. Also, enable HTTP traffic with the `--http` command.
|
||||
|
||||
```shell
|
||||
geth --http --miner.etherbase 0xC95767AC46EA2A9162F0734651d6cF17e5BfcF10
|
||||
```
|
||||
|
||||
The progress of the blockchain syncing can be monitored by attaching a JavaScript console in another terminal. More detailed information about the console can be found on the [Javascript Console](/content/docs/interacting_with_geth/JavaScript-Console.md) page. To attach and open a console:
|
||||
The progress of the blockchain syncing can be monitored by attaching a JavaScript console in another terminal. More detailed information about the console can be found on the [Javascript Console](/docs/interface/javascript-console) page. To attach and open a console:
|
||||
|
||||
```shell
|
||||
geth attach http://127.0.0.1:8545
|
||||
@ -65,7 +71,7 @@ If the sync is progressing correctly the output will look similar to the followi
|
||||
}
|
||||
```
|
||||
|
||||
Once the blockchain is sync'd, mining can begin. In order to begin mining, Ethminer must be run and connected to Geth in a new terminal. OpenCL can be used for a wide range of GPUs, CUDA can be used specifically for Nvidia GPUs:
|
||||
Once the blockchain is synced, mining can begin. In order to begin mining, Ethminer must be run and connected to Geth in a new terminal. OpenCL can be used for a wide range of GPUs, CUDA can be used specifically for Nvidia GPUs:
|
||||
|
||||
```shell
|
||||
#OpenCL
|
||||
@ -87,9 +93,10 @@ Benchmarking on platform: { "platform": "NVIDIA CUDA", "device": "GeForce GTX 75
|
||||
Benchmarking on platform: { "platform": "Apple", "device": "Intel(R) Xeon(R) CPU E5-1620 v2 @ 3.70GHz", "version": "OpenCL 1.2 " }
|
||||
```
|
||||
|
||||
Note that the Geth command `miner.hashrate` only works for CPU mining - it always reports zero for GPU mining. To check the GPU mining hashrate, check the logs `ethminer` displays to its terminal. More verbose logs can be configured using `-v` and a value between 0-9.
|
||||
Note that the Geth command `miner.hashrate` only works for CPU mining - it always reports zero for GPU mining. To check the GPU mining hashrate, check the logs `ethminer` displays to its terminal.
|
||||
|
||||
More verbose logs can be configured using `-v` and a value between 0-9. The Ethash algorithm is [memory-hard](https://crypto.stackexchange.com/questions/84002/memory-hard-vs-memory-bound-functions) and requires a large dataset to be loaded into memory. Each GPU requires 4-5 GB of RAM. The error message `Error GPU mining. GPU memory fragmentation?` indicates that there is insufficient memory available.
|
||||
|
||||
The Ethash algorithm is [memory-hard](https://crypto.stackexchange.com/questions/84002/memory-hard-vs-memory-bound-functions) and requires a large dataset to be loaded into memory. Each GPU requires 4-5 GB of RAM. The error message `Error GPU mining. GPU memory fragmentation?` indicates that there is insufficient memory available.
|
||||
|
||||
## CPU Mining with Geth
|
||||
|
||||
@ -102,13 +109,13 @@ geth --mine --miner.threads=4
|
||||
CPU mining can also be started and stopped at runtime using the [console](/docs/interface/javascript-console). The command `miner.start` takes an optional parameter for the number of miner threads.
|
||||
|
||||
```js
|
||||
miner.start(8);
|
||||
true;
|
||||
miner.stop();
|
||||
true;
|
||||
miner.start(8)
|
||||
true
|
||||
miner.stop()
|
||||
true
|
||||
```
|
||||
|
||||
Note that mining for real ether only makes sense if you are in sync with the network (since you mine on top of the consensus block). Therefore the Ethereum blockchain downloader/synchroniser will delay mining until syncing is complete, and after that mining automatically starts unless you cancel your intention with `miner.stop()`.
|
||||
Note that mining only makes sense if you are in sync with the network (since you mine on top of the consensus block). Therefore the blockchain downloader/synchroniser will delay mining until syncing is complete, and after that mining automatically starts unless you cancel with `miner.stop()`.
|
||||
|
||||
Like with GPU mining, an etherbase account must be set. This defaults to the primary account in the keystore but can be set to an alternative address using the `--miner.etherbase` command:
|
||||
|
||||
@ -150,26 +157,29 @@ It is also possible to check which blocks were mined by a particular miner (addr
|
||||
function minedBlocks(lastn, addr) {
|
||||
addrs = [];
|
||||
if (!addr) {
|
||||
addr = eth.coinbase;
|
||||
addr = eth.coinbase
|
||||
}
|
||||
limit = eth.blockNumber - lastn;
|
||||
limit = eth.blockNumber - lastn
|
||||
for (i = eth.blockNumber; i >= limit; i--) {
|
||||
if (eth.getBlock(i).miner == addr) {
|
||||
addrs.push(i);
|
||||
addrs.push(i)
|
||||
}
|
||||
}
|
||||
return addrs;
|
||||
return addrs
|
||||
}
|
||||
|
||||
// scans the last 1000 blocks and returns the blocknumbers of blocks mined by your coinbase
|
||||
// (more precisely blocks the mining reward for which is sent to your coinbase).
|
||||
minedBlocks(1000, eth.coinbase)[(352708, 352655, 352559)];
|
||||
minedBlocks(1000, eth.coinbase)
|
||||
[352708, 352655, 352559]
|
||||
|
||||
```
|
||||
|
||||
The etherbase balance will fluctuate because quite often a mined block may be re-org'd out of the canonical chain. This means that when the local Geth node includes the mined block in its own local blockchain the account balance appears higher because the block rewards are applied. When the node switches to another version of the chain due to information received from peers, that block may not be included and the block rewards are not applied.
|
||||
The etherbase balance will fluctuate if a mined block is re-org'd out of the canonical chain. This means that when the local Geth node includes the mined block
|
||||
in its own local blockchain the account balance appears higher because the block rewards are applied. When the node switches to another version of the chain due to information received from peers, that block may not be included and the block rewards are not applied.
|
||||
|
||||
The logs show locally mined blocks confirmed after 5 blocks.
|
||||
|
||||
## Summary
|
||||
|
||||
The page describes how to start Geth as a mining node. Mining can be done on CPUs - in which case Geth's built-in miner can be used - or on GPUs which requires third party software. Mining is no longer used on Ethereum Mainnet so this information is only applicable to private proof-of-work networks or testnets.
|
||||
The page describes how to start Geth as a mining node. Mining can be done on CPUs - in which case Geth's built-in miner can be used - or on GPUs which requires third party software. Mining is **no longer used to secure Ethereum Mainnet**.
|
||||
|
||||
@ -3,37 +3,31 @@ title: Connecting To The Network
|
||||
description: Guide to connecting Geth to a peer-to-peer network
|
||||
---
|
||||
|
||||
The default behaviour for Geth is to connect to Ethereum Mainnet. However, Geth can also connect to public testnets, [private networks](/docs/getting-started/private-net) and [local testnets](/docs/getting-started/dev-mode). Command line flags are provided for connecting to the popular public testnets:
|
||||
The default behaviour for Geth is to connect to Ethereum Mainnet. However, Geth can also connect to public testnets, [private networks](/docs/getting-started/private-net) and [local testnets](/docs/getting-started/dev-mode). For convenience, the two public testnets with long term support, Goerli and Sepolia, have their own command line flag. Geth can connect to these testnets simpyl by passing:
|
||||
|
||||
- `--ropsten`, Ropsten proof-of-work test network
|
||||
- `--rinkeby`, Rinkeby proof-of-authority test network
|
||||
- `--goerli`, Goerli proof-of-authority test network
|
||||
- `--sepolia` Sepolia proof-of-work test network
|
||||
|
||||
Providing these flags at startup instructs Geth to connect to the specific public testnet instead of Ethereum Mainnet. Because these are public testnets that have been running for several years, Geth has to download the historical blockchain data from genesis, just the same as for Ethereum Mainnet.
|
||||
These testnets started as proof-of-work and proof-of-authority testnets, but they were transitioned to proof-of-stake in 2022 in preparation for doing the same to Ethereum Mainnet. This means that to run a node on Goerli or Sepolia it is now necessary to run a consensus client connected to Geth. This is also true for Ethereum Mainnet. **Geth does not work on proof-of-stake networks without a consensus client**! The remainder of this page will assume that Geth is connected to a consensus client that is synced to the desired network. For instructions on how to set up a consensus client please see the [Consensus Clients](/docs/interface/consensus-clients.md) page.
|
||||
|
||||
**Note:** network selection is not persisted in the config file. To connect to a pre-defined network you must always enable it explicitly, even when using the `--config` flag to load other configuration values. For example:
|
||||
|
||||
```shell
|
||||
**Note:** Network selection is not persisted from a config file. To connect to a pre-defined network you must always enable it explicitly, even when using the `--config` flag to load other configuration values. For example:
|
||||
|
||||
```shell
|
||||
# Generate desired config file. You must specify testnet here.
|
||||
geth --goerli --syncmode "full" ... dumpconfig > goerli.toml
|
||||
|
||||
# Start geth with given config file. Here too the testnet must be specified.
|
||||
geth --goerli --config goerli.toml
|
||||
|
||||
```
|
||||
|
||||
## Finding peers
|
||||
|
||||
Geth continuously attempts to connect to other nodes on the network until it has enough peers. If UPnP (Universal Plug and Play) is enabled at the router or Ethereum is run on an Internet-facing server, it will also accept connections from other nodes. Geth finds peers using the [discovery protocol](https://ethereum.org/en/developers/docs/networking-layer/#discovery). In the discovery protocol, nodes exchange connectivity details and then establish sessions ([RLPx](https://github.com/ethereum/devp2p/blob/master/rlpx.md)). If the nodes support compatible sub-protocols they can start exchanging Ethereum data [on the wire](https://ethereum.org/en/developers/docs/networking-layer/#wire-protocol).
|
||||
Geth continuously attempts to connect to other nodes on the network until it has enough peers. If UPnP (Universal Plug and Play) is enabled at the router or Ethereum is run on an Internet-facing server, it will also accept connections from other nodes. Geth finds peers using the [discovery protocol](https://ethereum.org/en/developers/docs/networking-layer/#discovery). In the discovery protocol, nodes exchange connectivity details and then establish sessions ([RLPx](https://github.com/ethereum/devp2p/blob/master/rlpx.md)). If the nodes support compatible sub-protocols they can start exchanging Ethereum data [on the wire](https://ethereum.org/en/developers/docs/networking-layer/#wire-protocol).
|
||||
|
||||
A new node entering the network for the first time gets introduced to a set of peers by a bootstrap node ("bootnode") whose sole purpose is to connect new nodes to peers. The endpoints for these bootnodes are hardcoded into Geth, but they can also be specified by providing the `--bootnode` flag along with comma-separated bootnode addresses in the form of [enodes](https://ethereum.org/en/developers/docs/networking-layer/network-addresses/#enode) on startup. For example:
|
||||
|
||||
```shell
|
||||
|
||||
geth --bootnodes enode://pubkey1@ip1:port1,enode://pubkey2@ip2:port2,enode://pubkey3@ip3:port3
|
||||
|
||||
```
|
||||
|
||||
There are scenarios where disabling the discovery process is useful, for example for running a local test node or an experimental test network with known, fixed nodes. This can be achieved by passing the `--nodiscover` flag to Geth at startup.
|
||||
@ -46,22 +40,22 @@ There are occasions when Geth simply fails to connect to peers. The common reaso
|
||||
|
||||
- Some firewall configurations can prohibit UDP traffic. The static nodes feature or `admin.addPeer()` on the console can be used to configure connections manually.
|
||||
|
||||
- Running Geth in [light mode](/docs/interface/les) often leads to connectivity issues because there are few nodes running light servers. There is no easy fix for this except to switch Geth out of light mode.
|
||||
- Running Geth in [light mode](/docs/interface/les) often leads to connectivity issues because there are few nodes running light servers. There is no easy fix for this except to switch Geth out of light mode. **Note that light mode does not curently work on proof-of-stake networks**.
|
||||
|
||||
- The public test network Geth is connecting to might be deprecated or have a low number of active nodes that are hard to find. In this case, the best action is to switch to an alternative test network.
|
||||
|
||||
|
||||
## Checking Connectivity
|
||||
|
||||
The `net` module has two attributes that enable checking node connectivity from the [interactive Javascript console](/docs/interface/javascript-console). These are `net.listening` which reports whether the Geth node is listening for inbound requests, and `peerCount` which returns the number of active peers the node is connected to.
|
||||
|
||||
```javascript
|
||||
|
||||
```javascript
|
||||
> net.listening
|
||||
true
|
||||
|
||||
> net.peerCount
|
||||
4
|
||||
|
||||
```
|
||||
|
||||
Functions in the `admin` module provide more information about the connected peers, including their IP address, port number, supported protocols etc. Calling `admin.peers` returns this information for all connected peers.
|
||||
@ -116,17 +110,16 @@ The `admin` module also includes functions for gathering information about the l
|
||||
|
||||
It is often useful for developers to connect to private test networks rather than public testnets or Etheruem mainnet. These sandbox environments allow block creation without competing against other miners, easy minting of test ether and give freedom to break things without real-world consequences. A private network is started by providing a value to `--networkid` that is not used by any other existing public network ([Chainlist](https://chainlist.org)) and creating a custom `genesis.json` file. Detailed instructions for this are available on the [Private Networks page](/docs/interface/private-network).
|
||||
|
||||
|
||||
## Static nodes
|
||||
|
||||
Geth also supports static nodes. Static nodes are specific peers that are always connected to. Geth reconnects to these peers automatically when it is restarted. Specific nodes are defined to be static nodes by adding their enode addresses to a config file. The easiest way to create this config file is to run:
|
||||
|
||||
```
|
||||
geth --datadir <datadir> dumpconfig > datadir/config.toml
|
||||
geth --datadir <datadir> dumpconfig > config.toml
|
||||
```
|
||||
|
||||
Remember also that for public testnets (`goerli`, `sepolia` etc) the network name must be passed explicitly as a command line flag.
|
||||
|
||||
This will create `config.toml` in the `datadir`. The enode addresses for static nodes can then be added in square brackets to the `StaticNodes` field in the `Node.P2P` section in `config.toml`. When Geth is started, pass `--config datadir/config.toml`. The relevant line in `config.toml` looks as follows:
|
||||
This will create `config.toml` in the current directory. The enode addresses for static nodes can then be added as a list to the `StaticNodes` field of the `Node.P2P` section in `config.toml`. When Geth is started, pass `--config config.toml`. The relevant line in `config.toml` looks as follows:
|
||||
|
||||
```toml
|
||||
StaticNodes = ["enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303"]
|
||||
@ -137,9 +130,7 @@ Ensure the other lines in `config.toml` are also set correctly before starting G
|
||||
Static nodes can also be added at runtime in the Javascript console by passing an enode address to `admin.addPeer()`:
|
||||
|
||||
```javascript
|
||||
admin.addPeer(
|
||||
'enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303'
|
||||
);
|
||||
admin.addPeer("enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303")
|
||||
```
|
||||
|
||||
## Peer limit
|
||||
@ -147,23 +138,19 @@ admin.addPeer(
|
||||
It is sometimes desirable to cap the number of peers Geth will connect to in order to limit on the computational and bandwidth cost associated with running a node. By default, the limit is 50 peers, however, this can be updated by passing a value to `--maxpeers`:
|
||||
|
||||
```shell
|
||||
|
||||
geth <otherflags> --maxpeers 15
|
||||
|
||||
```
|
||||
|
||||
## Trusted nodes
|
||||
|
||||
Trusted nodes can be added to `config.toml` in the same way as for static nodes. Add the trusted node's enode address to the `TrustedNodes` field in `config.toml` before starting Geth with `--config datadir/config.toml`.
|
||||
Trusted nodes can be added to `config.toml` in the same way as for static nodes. Add the trusted node's enode address to the `TrustedNodes` field in `config.toml` before starting Geth with `--config config.toml`.
|
||||
|
||||
Nodes can be added using the `admin.addTrustedPeer()` call in the Javascript console and removed using `admin.removeTrustedPeer()` call.
|
||||
|
||||
```javascript
|
||||
admin.addTrustedPeer(
|
||||
'enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303'
|
||||
);
|
||||
admin.addTrustedPeer("enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303")
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
Geth connects to Ethereum Mainnet by default. However, this behaviour can be changed using combinations of command line flags and files. This page has described the various options available for connecting a Geth node to Ethereum, public testnets and private networks.
|
||||
Geth connects to Ethereum Mainnet by default. However, this behaviour can be changed using combinations of command line flags and files. This page has described the various options available for connecting a Geth node to Ethereum, public testnets and private networks. Remember that to connect to a proof-of-stake network (e.g. Ethereum Mainnet, Goerli, Sepolia) a consensus client is also required.
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
---
|
||||
title: Sync modes
|
||||
description: Introduction to Geth's sync modes
|
||||
---
|
||||
|
||||
Syncing is the process by which Geth catches up to the latest Ethereum block and current global state. There are several ways to sync a Geth node that differ in their speed, storage requirements and trust assumptions. This page outlines three sync configurations for full nodes and one for light nodes.
|
||||
|
||||
## Full nodes
|
||||
@ -6,35 +11,47 @@ There are two types of full node that use different mechanisms to sync up to the
|
||||
|
||||
### Snap (default)
|
||||
|
||||
A snap sync'd node holds the most recent 128 blocks in memory, so transactions in that range are always accessible. However, snap-sync only starts processing from a relatively recent block (as opposed to genesis for a full node). Between the initial sync block and the 128 most recent blocks, the node stores occasional checkpoints that can be used to rebuild the state on-the-fly. This means transactions can be traced back as far as the block that was used for the initial sync. Tracing a single transaction requires reexecuting all preceding transactions in the same block **and** all preceding blocks until the previous stored snapshot. Snap-sync'd nodes are therefore functionally equal to full nodes, but the initial synchronization required a checkpoint block to sync from instead of independently verifying the chain all the way from genesis. Snap sync then only verifies the proof-of-work and ancestor-child block progression and assumes that the state transitions are correct rather than re-executing the transactions in each block to verify the state changes. Snap sync is much faster than full sync. To start a node with snap sync pass `--syncmode snap` at startup.
|
||||
A snap sync'd node holds the most recent 128 block states in memory, so transactions in that range are always quickly accessible. However, snap-sync only starts processing from a relatively recent block (as opposed to genesis for a full node). Between the initial sync block and the 128 most recent blocks, the node stores occasional checkpoints that can be used to rebuild the state on-the-fly. This means transactions can be traced back as far as the block that was used for the initial sync. Tracing a single transaction requires reexecuting all preceding transactions in the same block **and** all preceding blocks until the previous stored snapshot. Snap-sync'd nodes are therefore full nodes, with the only difference being the initial synchronization required a checkpoint block to sync from instead of independently verifying the chain all the way from genesis. Snap sync then only verifies the proof-of-work and ancestor-child block progression and assumes that the state transitions are correct rather than re-executing the transactions in each block to verify the state changes. Snap sync is much faster than block-by-block sync. To start a node with snap sync pass `--syncmode snap` at startup.
|
||||
|
||||
Snap sync starts by downloading the blocks between the head of the chain and the previous checkpoint. Then it downloads the leaves of the state trie for each block without the intermediate nodes. The state trie is then regenerated locally. The state download is the part of the snap-sync that takes the most time to complete and the progress can be monitored using the ETA values in the log messages. However, the blockchain is also progressing at the same time and invalidating some of the regenerated state data. This means it is also necessary to have a 'healing' phase where errors in the state are fixed. It is not possible to monitor the progress of the state heal because the extent of the errors cannot be known until the current state has already been regenerated. The healing has to outpace the growth of the blockchain, otherwise the node will never catch up to the current state. There are some hardware factors that determine the speed of the state healing (speed of disk read/write and internet connection) and also the total gas used in each block (more gas means more changes to the state that have to be handled).
|
||||
Snap sync starts by downloading the headers for a chunk of blocks. Once the headers have been verified, the block bodies and receipts for those blocks are downloaded. In parallel, Geth also sync begins state-sync. In state-sync, Geth first downloads the leaves of the state trie for each block without the intermediate nodes along with a range proof. The state trie is then regenerated locally. The state download is the part of the snap-sync that takes the most time to complete and the progress can be monitored using the ETA values in the log messages. However, the blockchain is also progressing at the same time and invalidating some of the regenerated state data. This means it is also necessary to have a 'healing' phase where errors in the state are fixed. It is not possible to monitor the progress of the state heal because the extent of the errors cannot be known until the current state has already been regenerated.
|
||||
The healing has to outpace the growth of the blockchain, otherwise the node will never catch up to the current state. There are some hardware factors that determine the speed of the state healing (speed of disk read/write and internet connection) and also the total gas used in each block (more gas means more changes to the state that have to be handled).
|
||||
|
||||
To summarize, snap sync progresses in the following sequence:
|
||||
- download and verify headers
|
||||
- download block bodies and receipts. In parallel, download raw state data and build state trie
|
||||
- heal state trie to account for newly arriving data
|
||||
|
||||
**Note** Snap sync is the default behaviour, so if the `--syncmode` value is not passed to Geth at startup, Geth will use snap sync. A node that is started using `snap` will switch to block-by-block sync once it has caught up to the head of the chain.
|
||||
|
||||
### Full
|
||||
|
||||
A full sync generates the current state by executing every block starting from the genesis block. A full sync indendently verifies proof-of-work and block provenance as well as all state transitions by re-executing the transactions in the entire historical sequence of blocks. Only the most recent 128 blocks are stored in a full node - older blocks are pruned periodically and represented as a series of checkpoints from which any previous state can be regenerated on request. 128 blocks is about 25.6 minutes of history with a block time of 12 seconds. To create a full node pass `--syncmode full` at startup.
|
||||
A full sync generates the current state by executing every block starting from the genesis block. A full sync indendently verifies proof-of-work and block provenance as well as all state transitions by re-executing the transactions in the entire historical sequence of blocks. Only the most recent 128 block states are stored in a full node - older block states are pruned periodically and represented as a series of checkpoints from which any previous state can be regenerated on request. 128 blocks is about 25.6 minutes of history with a block time of 12 seconds.
|
||||
|
||||
To create a full node pass `--syncmode full` at startup.
|
||||
|
||||
## Archive nodes
|
||||
|
||||
An archive node is a node that retains all historical data right back to genesis. There is no need to regenerate any data from checkpoints because all data is directly available in the node's own storage. Archive nodes are therefore ideal for making fast queries about historical states. At the time of writing (September 2022) a full archive node that stores all data since genesis occupies nearly 12 TB of disk space (keep up with the current size on [Etherscan](https://etherscan.io/chartsync/chainarchive)). Archive nodes are created by configuring Geth's garbage collection so that old data is never deleted: `geth --syncmode full --gcmode archive`.
|
||||
An archive node is a node that retains all historical data right back to genesis. There is no need to regenerate any data from checkpoints because all data is directly available in the node's own storage. Archive nodes are therefore ideal for making fast queries about historical states. At the time of writing (September 2022) a full archive node that stores all data since genesis occupies nearly 12 TB of disk space (keep up with the current size on [Etherscan](https://etherscan.io/chartsync/chainarchive)). Archive nodes are created by configuring Geth's garbage collection so that old data is never deleted: `geth --syncmode full --gcmode archive`.
|
||||
|
||||
It is also possible to create a partial/recent archive node where the node was synced using `snap` but the state is never pruned. This creates an archive node that saves all state data from the point that the node first syncs. This is configured by starting Geth with `--syncmode snap gcmode archive`.
|
||||
It is also possible to create a partial/recent archive node where the node was synced using `snap` but the state is never pruned. This creates an archive node that saves all state data from the point that the node first syncs. This is configured by starting Geth with `--syncmode snap --gcmode archive`.
|
||||
|
||||
## Light nodes
|
||||
|
||||
A light node syncs very quickly and stores the bare minimum of blockchain data. Light nodes only process block headers, not entire blocks. This greatly reduces the computation time, storage and bandwidth required relative to a full node. This means light nodes are suitable for resource-constrained devices and can catch up to the head of the chain much faster when they are new or have been offline for a while. The trade-off is that light nodes rely heavily on data served by altruistic full nodes. A light client can be used to query data from Ethereum and submit transactions, acting as a locally-hosted Ethereum wallet. However, because they don't keep local copies of the Ethereum state, light nodes can't validate blocks in the same way as full nodes - they have to trust that the data they receive is honest. To start a node in light mode, pass `--syncmode light`. Be aware that full nodes serving light data are relative scarce so light nodes can struggle to find peers.
|
||||
A light node syncs very quickly and stores the bare minimum of blockchain data. Light nodes only process block headers, not entire blocks. This greatly reduces the computation time, storage and bandwidth required relative to a full node. This means light nodes are suitable for resource-constrained devices and can catch up to the head of the chain much faster when they are new or have been offline for a while. The trade-off is that light nodes rely heavily on data served by altruistic full nodes. A light client can be used to query data from Ethereum and submit transactions, acting as a locally-hosted Ethereum wallet. However, because they don't keep local copies of the Ethereum state, light nodes can't validate blocks in the same way as full nodes - they receive a proof from the full node and verify it against their local header chain. To start a node in light mode, pass `--syncmode light`. Be aware that full nodes serving light data are relative scarce so light nodes can struggle to find peers.
|
||||
|
||||
Read more about light nodes on our [LES page](/content/docs/fundamentals/les.md).
|
||||
Read more about light nodes on our [LES page](/docs/interface/les.md).
|
||||
|
||||
## Consensus layer syncing
|
||||
|
||||
At the transition to proof-of-stake, all consensus logic and block propagation is handed over to consensus clients. This means that syncing the blockchain is a process shared between the consensus and execution clients. Blocks are downloaded by the consensus client and verified by the execution client. There are two ways to sync a consensus client: optimistic sync and checkpoint sync.
|
||||
Now that Ethereum has switched to proof-of-stake, all consensus logic and block propagation is handled by consensus clients. This means that syncing the blockchain is a process shared between the consensus and execution clients. Blocks are downloaded by the consensus client and verified by the execution client. In order for Geth to sync, it requires a header from its connected consensus client. Geth does not import any data until it is instructed to by the consensus client.
|
||||
|
||||
Once a header is available to use as a syncing target, Geth retrieves all headers between that target header and the local header chain in reverse chronological order. These headers show that the sequence of blocks is correct because the parenthashes link one block to the next right up to the target block. Eventually, the sync will reach a block held in the local database, at which point the local data and the target data are considered 'linked' and there is a very high chance the node is syncing the correct chain. The block bodies are then downloaded and then the state data. The consensus client can update the target header - as long as the syncing outpaces the growth of the blockchain then the node will eventually get in sync.
|
||||
|
||||
There are two ways for the consensus client to find a block header that Geth can use as a sync target: optimistic syncing and checkpoint syncing:
|
||||
|
||||
### Optimistic sync
|
||||
|
||||
Optimistic sync downloads blocks before the execution client has validated them. This means the execution client can constantly be fed with up-to-date states to snap-sync to. Assuming the blocks are valid, eventually the sync catches up to the optimistically downloaded head and the blockchain is in sync. From this point, verification is done block-by-block (i.e. the sync mode switches to `full`). In optimistic sync the node assumes the data it receives from its peers is correct during the downloading phase but then retroactively verifies each downloaded block. Nodes are not allowed to attest or propose blocks while they are still 'optimistic' because they can't yet guarantee their view of the ehad of the chain is correct.
|
||||
Optimistic sync downloads blocks before the execution client has validated them. In optimistic sync the node assumes the data it receives from its peers is correct during the downloading phase but then retroactively verifies each downloaded block. Nodes are not allowed to attest or propose blocks while they are still 'optimistic' because they can't yet guarantee their view of the head of the chain is correct.
|
||||
|
||||
Read more in the [optimistic sync specs](https://github.com/ethereum/consensus-specs/blob/dev/sync/optimistic.md).
|
||||
|
||||
@ -46,4 +63,4 @@ Alternatively, the consensus client can grab a checkpoint from a trusted source
|
||||
|
||||
## Summary
|
||||
|
||||
There are several ways to sync a Geth node. The default is to use snap sync to create a full node. This verifies all blocks starting at a recent checkpoint. A trust-minimized alternative is full-sync, which verifies every block since genesis. These modes prune the blockchain data older than 128 blocks, keeping only checkpoints that enable on-request regeneration of historical states. For rapid queries of historical data an archive node is required. Archive nodes keep local copies of all historical data right back to genesis - currently about 12 TB and growing. The opposite extreme is a light node that doesn't store any blockchain data - it requests everything from full nodes. These configurations are controlled by passing `full`, `snap` or `light` to `--syncmode` at startup. For an archive node, `--syncmode` should be `full` and `--gcmode` should be set to `archive`. At the transition to proof-of-stake, light-sync will no longer work (until new light client protocols are shipped).
|
||||
There are several ways to sync a Geth node. The default is to use snap sync to create a full node. This verifies all blocks using some recent block that is old enough to be safe from re-orgs as a sync target. A trust-minimized alternative is full-sync, which verifies every block since genesis. These modes drop state data older than 128 blocks, keeping only checkpoints that enable on-request regeneration of historical states. For rapid queries of historical data an archive node is required. Archive nodes keep local copies of all historical data right back to genesis - currently about 12 TB and growing. The opposite extreme is a light node that doesn't store any blockchain data - it requests everything from full nodes. These configurations are controlled by passing `full`, `snap` or `light` to `--syncmode` at startup. For an archive node, `--syncmode` should be `full` and `--gcmode` should be set to `archive`. Currently, due to the transition to proof-of-stake, light-sync does not work (new light client protocols are being developed).
|
||||
@ -3,7 +3,7 @@ title: Hardware requirements
|
||||
description: Overview of the hardware needed to run an Ethereum node
|
||||
---
|
||||
|
||||
The hardware requirements for running an Ethereum node depend upon the node configuration and can change over time as upgrades to the network are implemented. Ethereum nodes can be run on low power, resource-constrained devices such as Raspberry Pi's. Prebuilt, dedicated staking machines are available from several companies - these might be good choices for users who want plug-and-play hardware specifically designed for Ethereum. However, many users will choose to run nodes on laptop or desktop computers. Those users need to know the basic minimum requirements.
|
||||
The hardware requirements for running a Geth node depend upon the node configuration and can change over time as upgrades to the network are implemented. Ethereum nodes can be run on low power, resource-constrained devices such as Raspberry Pi's. Prebuilt, dedicated staking machines are available from several companies - these might be good choices for users who want plug-and-play hardware specifically designed for Ethereum. However, many users will choose to run nodes on laptop or desktop computers.
|
||||
|
||||
## Processor
|
||||
|
||||
@ -18,10 +18,8 @@ It is recommended to use at least 16GB RAM.
|
||||
Disk space is usually the primary bottleneck for node operators. At the time of writing (September 2022) a 2TB SSD is recommended for a full node running Geth and a consensus client. Geth itself requires >650GB of disk space for a snap-synced full node and, with the default cache size, grows about 14GB/week. Pruning brings the total storage back down to the original 650GB.
|
||||
Archive nodes require additional space. A "full" archive node that keeps all state back to genesis requires more than 12TB of space. Partial archive nodes can also be created by turning off the garbage collector after some initial sync - the storage requirement depends how much state is saved.
|
||||
|
||||
There are future updates to Ethereum that will reduce the amount of disk space required to run a node. In particular, [EIP-4444](https://eips.ethereum.org/EIPS/eip-4444#preserving-historical-data) aims to bound the historical state stored by nodes and instead make it available from offchain storage (e.g. torrents or IPFS).
|
||||
|
||||
As well as storage capacity, Geth nodes rely on fast read and write operations. This means HDDs and cheaper HDDS struggle to sync the blockchain. There is a list of SSD models that can and cannot sync Geth in this [Github Gist](https://gist.github.com/yorickdowne/f3a3e79a573bf35767cd002cc977b038).
|
||||
As well as storage capacity, Geth nodes rely on fast read and write operations. This means HDDs and cheaper HDDS can sometimes struggle to sync the blockchain. A list of SSD models that users report being able and unable to sync Geth is available in this [Github Gist](https://gist.github.com/yorickdowne/f3a3e79a573bf35767cd002cc977b038). Please note that the list has _not_ been verified by the Geth team.
|
||||
|
||||
## Bandwidth
|
||||
|
||||
It is important to have a stable and reliable internet connection, especially for running a validator because downtime can result in missed rewards or penalties. It is recommended to have at least 25Mbps download speed to run a node. Running a node also requires a lot of data to be uploaded and downloaded so it is better to use a ISP that does not have a capped data allowance.
|
||||
It is important to have a stable and reliable internet connection, especially for running a validator because downtime can result in missed rewards or penalties. It is recommended to have at least 25Mbps download speed to run a node. Running a node also requires a lot of data to be uploaded and downloaded so it is better to use an ISP that does not have a capped data allowance.
|
||||
|
||||
29
src/pages/docs/index.md
Normal file
29
src/pages/docs/index.md
Normal file
@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Welcome to go-ethereum documentation
|
||||
description: Documentation for the go-ethereum client
|
||||
---
|
||||
|
||||
## Welcome to go-ethereum
|
||||
|
||||
Go-ethereum (aka Geth) is an Ethereum client built in [Golang](https://go.dev). It is one of the original and most popular Ethereum clients.
|
||||
These documentation pages are intended to help users download, install and use Geth.
|
||||
|
||||
## Where to go from here
|
||||
|
||||
First, make sure you have sufficient [hardware](/pages/docs/getting-started/hardware-requirements.md), then [download](/pages/downloads) and [install](/pages/docs/getting-started/installing-geth.md) Geth. Make sure you are familiar with the [security considerations](/pages/docs/fundamentals/security.md) and have your firewall set up.
|
||||
|
||||
If you are just starting out with Geth, head to the [Getting started](src/pages/docs/getting-started/getting-started.md) page. That page guides a new user through some basic functions of Geth such as creating and securing accounts and making a transaction using Geth's built-in account tools.
|
||||
|
||||
A more secure but slightly more advanced setup is to use an external signer instead of Geth's built-in account manager. We have a [getting started](src/pages/docs/getting-started/getting-started-with-clef.md) guide for that too.
|
||||
|
||||
Then, it is recommended to read the material in the [Fundamentals](src/pages/docs/fundamentals) section - these pages will help build a foundational understanding of how Geth works from a user perspective and under the hood.
|
||||
|
||||
More advanced topics are also available - explore them using the sidebar!
|
||||
|
||||
## Developers and contributors
|
||||
|
||||
If you want to help develop Geth or build decentralized apps on top of it, head to our [Developers](src/pages/docs/developers) documentation.
|
||||
|
||||
## More resources
|
||||
|
||||
We have a library of videos and articles on our [Resources](/pages/docs/resources.md) page and answers to common questions on the [FAQs](/pages/docs/faq.md) page.
|
||||
@ -42,7 +42,3 @@ Here are more resources for a deeper understanding of Geth and related topics.
|
||||
[Péter at DevCon 2: Import Geth in Go](https://www.youtube.com/watch?v=R0Ia1U9Gxjg)
|
||||
|
||||
[Péter at dotGo 2016: Immutability in Go](https://www.youtube.com/watch?v=fNUx4jHTaIc)
|
||||
|
||||
## Listen
|
||||
|
||||
Podcasts relating to Geth will be posted here!
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
OLD Geth website URLS,Equivalent NEW website URLs,Relative path to markdown file,Notes
|
||||
https://geth.ethereum.org/,https://geth.ethereum.org,src/pages/homepage,will be react page
|
||||
https://geth.ethereum.org/downloads/,https://geth.ethereum.org/downloads,src/pages/downloads,will be react page
|
||||
https://geth.ethereum.org/docs/,https://geth.ethereum.org/docs,src/pages/docs,n/a
|
||||
https://geth.ethereum.org/docs/getting-started,https://geth.ethereum.org/docs/getting_started,src/pages/docs/getting_started/getting_started.md,n/a
|
||||
https://geth.ethereum.org/docs/getting-started/geth-and-clef,https://geth.ethereum.org/docs/getting_started_with_clef.md,src/pages/docs/getting_started/getting-started-with-clef.md,n/a
|
||||
https://geth.ethereum.org/docs/,https://geth.ethereum.org/docs,src/pages/docs/index.md,n/a
|
||||
https://geth.ethereum.org/docs/getting-started,https://geth.ethereum.org/docs/getting_started/getting-started,src/pages/docs/getting_started/getting_started.md,n/a
|
||||
https://geth.ethereum.org/docs/getting-started/geth-and-clef,https://geth.ethereum.org/docs/getting_started_with_clef,src/pages/docs/getting_started/getting-started-with-clef.md,n/a
|
||||
https://geth.ethereum.org/docs/getting-started/dev-mode,https://geth.ethereum.org/docs/developers/geth-developers/dev-mode,src/pages/docs/developers/geth-developer/dev-mode.md,n/a
|
||||
https://geth.ethereum.org/docs/install-and-build/installing-geth,https://geth.ethereum.org/docs/getting_started/install-geth,src/pages/docs/getting_started/backup-restore.md,n/a
|
||||
https://geth.ethereum.org/docs/install-and-build/backup-restore,https://geth.ethereum.org/docs/getting_started/backup-restore,src/pages/docs/getting_started/installing-geth.md,n/a
|
||||
@ -53,6 +53,8 @@ https://geth.ethereum.org/docs/clef/rules,https://geth.ethereum.org/docs/tools/c
|
||||
https://geth.ethereum.org/docs/clef/setup,https://geth.ethereum.org/docs/tools/clef/setup,src/pages/docs/tools/clef/setup.md,n/a
|
||||
https://geth.ethereum.org/docs/clef/apis,https://geth.ethereum.org/docs/tools/clef/apis,src/pages/docs/tools/clef/apis.md,n/a
|
||||
https://geth.ethereum.org/docs/clef/datatypes,https://geth.ethereum.org/docs/tools/clef/datatypes,src/pages/docs/tools/clef/datatypes.md,n/a
|
||||
https://geth.ethereum.org/docs/interface/sync-modes,https://geth.ethereum.org/docs/interface/sync-modes,src/pages/docs/fundamentals/sync-modes.md,n/a
|
||||
https://geth.ethereum.org/docs/interface/hardware,https://geth.ethereum.org/docs/interface/getting_started/hardware-requirements.md,,
|
||||
https://github.com/ethereum/go-ethereum/tree/gh-pages/docs/_vulnerabilities/vulnerabilities.json,https://github.com/ethereum/go-ethereum/tree/gh-pages/docs/_vulnerabilities/vulnerabilities.json,src/pages/docs/vulnerabilities/vulnerabilities.json,must be served at original URL
|
||||
https://github.com/ethereum/go-ethereum/tree/gh-pages/docs/_vulnerabilities/vulnerabilities.json.minisig,https://github.com/ethereum/go-ethereum/tree/gh-pages/docs/_vulnerabilities/vulnerabilities.json.minisig,src/pages/docs/vulnerabilities/vulnerabilities.json.minisig,must be served at original URL
|
||||
https://github.com/ethereum/go-ethereum/tree/gh-pages/docs/_vulnerabilities/vulnerabilities.md,https://geth.ethereum.org/docs/developers/geth-developers/discloures,src/pages/docs/developers/geth-developers/disclosures,moved to /docs and renamed
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user