chore: sync content with master branch
This commit is contained in:
Nicolás Quiroz
parent
5febc1e80d
commit
1660d4dd83
@ -19,7 +19,7 @@ Vulnerabilies typically take two forms:
|
||||
|
||||
In most cases so far, vulnerabilities in Geth have been of the second type, where the health of the network is a concern, rather than individual node operators. For such issues, Geth reserves the right to silently patch and ship fixes in new releases.
|
||||
|
||||
## Why silent patches
|
||||
### Why silent patches
|
||||
|
||||
In the case of Ethereum, it takes a lot of time (weeks, months) to get node operators to update even to a scheduled hard fork. If we were to highlight that a release contains important consensus or DoS fixes, there is always a risk of someone trying to beat node operators to the punch, and exploit the vulnerability. Delaying a potential attack sufficiently to make the majority of node operators immune may be worth the temporary loss of transparency.
|
||||
|
||||
@ -27,7 +27,7 @@ The primary goal for the Geth team is the health of the Ethereum network as a wh
|
||||
|
||||
At certain times, it's better to remain silent. This practice is also followed by other projects such as [Monero](https://www.getmonero.org/2017/05/17/disclosure-of-a-major-bug-in-cryptonote-based-currencies.html), [ZCash](https://electriccoin.co/blog/zcash-counterfeiting-vulnerability-successfully-remediated/) and [Bitcoin](https://www.coindesk.com/the-latest-bitcoin-bug-was-so-bad-developers-kept-its-full-details-a-secret).
|
||||
|
||||
## Public transparency
|
||||
### Public transparency
|
||||
|
||||
As of November 2020, our policy going forward is:
|
||||
|
||||
@ -41,9 +41,9 @@ In keeping with this policy, we have taken inspiration from [Solidity bug disclo
|
||||
|
||||
## Disclosed vulnerabilities
|
||||
|
||||
On the Geth Github can find a JSON-formatted list ([`vulnerabilities.json`](vulnerabilities.json)) of some of the known security-relevant vulnerabilities concerning Geth.
|
||||
There is a JSON-formatted list ([`vulnerabilities.json`](/docs/vulnerabilities/vulnerabilities.json)) of some of the known security-relevant vulnerabilities concerning Geth.
|
||||
|
||||
As of version `1.9.25`, Geth has a built-in command to check whether it is affected by any publically disclosed vulnerability, using the command `geth version-check`. This command will fetch the latest json file (and the accompanying [signature-file](vulnerabilities.json.minisig), and cross-check the data against it's own version number.
|
||||
As of version `1.9.25`, Geth has a built-in command to check whether it is affected by any publically disclosed vulnerability, using the command `geth version-check`. This command will fetch the latest json file (and the accompanying [signature-file](/docs/vulnerabilities/vulnerabilities.json.minisig), and cross-check the data against it's own version number.
|
||||
|
||||
The list of vulnerabilities was started in November 2020, and covers mainly `v1.9.7` and forward.
|
||||
|
||||
@ -74,8 +74,12 @@ The JSON file of known vulnerabilities below is a list of objects, one for each
|
||||
- `CVE`
|
||||
- The assigned `CVE` identifier, if available (optional)
|
||||
|
||||
## What about Github security advisories
|
||||
### What about Github security advisories
|
||||
|
||||
We prefer to not rely on Github as the only/primary publishing protocol for security advisories, but we plan to use the Github-advisory process as a second channel for disseminating vulnerability-information.
|
||||
|
||||
Advisories published via Github can be accessed [here](https://github.com/ethereum/go-ethereum/security/advisories?state=published).
|
||||
|
||||
## Bug Bounties
|
||||
|
||||
The Ethereum Foundation run a bug bounty program to reward responsible disclosures of bugs in client software and specs. The details are provided on [ethereum.org](https://ethereum.org/en/bug-bounty/).
|
||||
@ -441,7 +441,7 @@ This account can then be unlocked and some ether sent to Node 2, using the follo
|
||||
|
||||
```javascript
|
||||
// unlock account
|
||||
personal.unlock(eth.accounts[0]);
|
||||
personal.unlockAccount(eth.accounts[0]);
|
||||
|
||||
// send some Wei
|
||||
eth.sendTransaction({
|
||||
|
||||
@ -3,7 +3,7 @@ title: FAQ
|
||||
description: Frequently asked questions related to Geth
|
||||
---
|
||||
|
||||
This page contains answers to common questions about Geth. The Geth team have also started to run AMA's on Reddit:
|
||||
This page contains answers to common questions about Geth. The Geth team have also recently started to run AMA's on Reddit:
|
||||
|
||||
[Aug 2022 AMA](https://www.reddit.com/r/ethereum/comments/wpqmo1/ama_we_are_the_go_ethereum_geth_team_18_august/)
|
||||
|
||||
@ -42,9 +42,11 @@ Additional details and/or any updates on more robust handling are at <https://gi
|
||||
|
||||
## How does Ethereum syncing work?
|
||||
|
||||
The current default syncing mode used by Geth is called [snap sync](https://github.com/ethereum/devp2p/blob/master/caps/snap.md). Instead of starting from the genesis block and processing all the transactions that ever occurred (which could take weeks), snap sync downloads the blocks, and only verifies the associated proof-of-works. Downloading all the blocks is a straightforward and fast procedure and will relatively quickly reassemble the entire chain.
|
||||
The current default syncing mode used by Geth is called [snap sync](https://github.com/ethereum/devp2p/blob/master/caps/snap.md). Instead of starting from the genesis block and processing all the transactions that ever occurred (which could take weeks), snap sync downloads the blocks, and only verifies the associated proof-of-works, assuming state transitions to be correct. Downloading all the blocks is a straightforward and fast procedure and will relatively quickly reassemble the entire chain.
|
||||
|
||||
Many people falsely assume that because they have the blocks, they are in sync. Unfortunately this is not the case. Since no transaction was executed, so we do not have any account state available (ie. balances, nonces, smart contract code and data). These need to be downloaded separately and cross-checked with the latest blocks. This phase is called the state trie download phase. Snap sync tries to hasten this process by downloading contiguous chunks of useful state data, instead of doing so one-by-one, as in previous synchronization methods.
|
||||
Many people assume that because they have the blocks, they are in sync. Unfortunately this is not the case. Since no transaction was executed, so we do not have any account state available (ie. balances, nonces, smart contract code and data). These need to be downloaded separately and cross-checked with the latest blocks. This phase is called the state trie download phase. Snap sync tries to hasten this process by downloading contiguous chunks of useful state data, instead of doing so one-by-one, as in previous synchronization methods. Geth downloads the leaves of the trie without the intermediate nodes that connect the leaves to the root. The full trie is regenerated locally. However, while this is happening, the blockchain is progressing, meaning some of the regenerated state trie becomes invalid. Therefor, there is also a healing phase that corrects any errors in the state trie. The state sync has to progress faster than the chain growth otherwise it will never finish.
|
||||
|
||||
Geth can also be sync'd with `--syncmode full`. In this case, Geth downloads and independently verifies every block since genesis in sequence, including re-executing transactions to verify state transitions. Although Geth verifies every block since genesis, only 128 blocks are stored in memory.
|
||||
|
||||
## What's the state trie?
|
||||
|
||||
@ -52,6 +54,8 @@ In the Ethereum mainnet, there are a ton of accounts already, which track the ba
|
||||
|
||||
This cryptographic linking is done by creating a tree-like data structure, where each leaf corresponds to an account, and each intermediary level aggregates the layer below it into an ever smaller layer, until you reach a single root. This gigantic data structure containing all the accounts and the intermediate cryptographic proofs is called the state trie.
|
||||
|
||||
Read more about Merkle Tries in general and the Ethereum state trie specifically on [ethereum.org](https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie)
|
||||
|
||||
## Why does the state trie download phase require a special syncing mode?
|
||||
|
||||
The trie data structure is an intricate interlink of hundreds of millions of tiny cryptographic proofs (trie nodes). To truly have a synchronized node, you need to download all the account data, as well as all the tiny cryptographic proofs to verify that no one in the network is trying to cheat you. This itself is already a crazy number of data items.
|
||||
@ -62,28 +66,12 @@ The part where it gets even messier is that this data is constantly morphing: at
|
||||
|
||||
Snap syncing was introduced by version [1.10.0](https://blog.ethereum.org/2021/03/03/geth-v1-10-0/) and was adopted as the default mode in version [1.10.4](https://github.com/ethereum/go-ethereum/releases/tag/v1.10.4). Before that, the default was the "fast" syncing mode, which was dropped in version [1.10.14](https://github.com/ethereum/go-ethereum/releases/tag/v1.10.14). Even though support for fast sync was dropped, Geth still serves the relevant `eth` requests to other client implementations still relying on it. The reason being that snap sync relies on an alternative data structure called the [snapshot](https://blog.ethereum.org/2020/07/17/ask-about-geth-snapshot-acceleration/) which not all clients implement.
|
||||
|
||||
You can read more in the article posted above why snap sync replaced fast sync in Geth. Below is a table taken from the article summarising the benefits:
|
||||
|
||||
|
||||
|
||||
## When doing a fast sync, the node just hangs on importing state enties?!
|
||||
|
||||
The node doesn’t hang, it just doesn’t know how large the state trie is in advance so it keeps on going and going and going until it discovers and downloads the entire thing.
|
||||
|
||||
The reason is that a block in Ethereum only contains the state root, a single hash of the root node. When the node begins synchronizing, it knows about exactly 1 node and tries to download it. That node, can refer up to 16 new nodes, so in the next step, we’ll know about 16 new nodes and try to download those. As we go along the download, most of the nodes will reference new ones that we didn’t know about until then. This is why you might be tempted to think it’s stuck on the same numbers. It is not, rather it’s discovering and downloading the trie as it goes along.
|
||||
|
||||
During this phase you might see that your node is 64 blocks behind mainnet. You aren't actually synchronized. That's a side-effect of how fast sync works and you need to wait out until all state entries are downloaded.
|
||||
|
||||
## I have good bandwidth, so why does downloading the state take so long when using fast sync?
|
||||
|
||||
State sync is mostly limited by disk IO, not bandwidth.
|
||||
|
||||
The state trie in Ethereum contains hundreds of millions of nodes, most of which take the form of a single hash referencing up to 16 other hashes. This is a horrible way to store data on a disk, because there's almost no structure in it, just random numbers referencing even more random numbers. This makes any underlying database weep, as it cannot optimize storing and looking up the data in any meaningful way. Snap sync solves this issue by adopting the Snapshot data structure.
|
||||
|
||||
## Wait, so I can't use fast sync on an HDD?
|
||||
|
||||
Doing a "fast" sync on an HDD will take more time than you're willing to wait, because the data structures used are not optimized for HDDs. Even if you do wait it out, an HDD will not be able to keep up with the read/write requirements of transaction processing on mainnet. You however should be able to run a light client on an HDD with minimal impact on system resources.
|
||||
You can read more in the article posted above why snap sync replaced fast sync in Geth.
|
||||
|
||||
## What is wrong with my light client?
|
||||
|
||||
Light sync relies on full nodes that serve data to light clients. Historically, this has been hampered by the fact that serving light clients was turned off by default in geth full nodes and few nodes chose to turn it on. Therefore, light nodes often struggled to find peers. Since Ethereum switched to proof-of-stake, Geth light clients have stopped working altogether. Light clients for proof-of-stake Ethereum are expected to be implemented soon!
|
||||
|
||||
## Why do I need another client in addition to Geth?
|
||||
|
||||
Historically, running Geth was enough to turn a computer into an Ethereum node. However, when Ethereum transitioned to proof-of-stake, responsibility for consensus logic and block gossip was handed over to a separate consensus layer client. However, Geth still handles transactions and state management. When the consensus client is required to create a new block, it requests Geth to gather transactions from the transaction pool, execute them to compute a state transition and pass this information back to the consensus client. When the consensus client receives a new block from a peer, it passes the transactions to Geth to re-execute to verify the proposed state-transition. There is a clear separationm of concerns between the two clients, meaning that both are required for a computer function as an Ethereum node.
|
||||
|
||||
@ -7,13 +7,13 @@ description: Introduction to how Ethereum nodes are organized and where Geth fit
|
||||
|
||||
Geth is an [execution client](https://ethereum.org/en/developers/docs/nodes-and-clients/#execution-clients). Originally, an execution client alone was enough to run a full Ethereum node. However, ever since Ethereum turned off [proof-of-work](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/) and implemented [proof-of-stake](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/), Geth has needed to be coupled to another piece of software called a [“consensus client”](https://ethereum.org/en/developers/docs/nodes-and-clients/#consensus-clients) in order to keep track of the Ethereum blockchain.
|
||||
|
||||
The execution client is responsible for transaction handling, transaction gossip, state management and supporting the Ethereum Virtual Machine ([EVM])(https://ethereum.org/en/developers/docs/evm/). However, Geth is **not** responsible for block building, block gossiping or handling consensus logic. These are in the remit of the consensus client.
|
||||
The execution client (Geth) is responsible for transaction handling, transaction gossip, state management and supporting the Ethereum Virtual Machine ([EVM])(https://ethereum.org/en/developers/docs/evm/). However, Geth is **not** responsible for block building, block gossiping or handling consensus logic. These are in the remit of the consensus client.
|
||||
|
||||
The relationship between the two Ethereum clients is shown in the schematic below. The two clients each connect to their own respective peer-to-peer (P2P) networks. This is because the execution clients gossip transactions over their P2P network enabling them to manage their local transaction pool. The consensus clients gossip blocks over their P2P 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](https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md) which is exposed internally over port 8551 by default.
|
||||
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](https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md).
|
||||
|
||||
## What does Geth do?
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ description: A primer on Geth security best practice.
|
||||
|
||||
## Downloading Geth
|
||||
|
||||
Download Geth using the links on our [Downloads](/downloads) page. The SHA256 hashes of the downloaded files can be compared to ours to ensure precise consistency with our releases. This protects against malicious code being inadvertently downloaded from an adversarial source. The same measures should also be taken to download trusted consensus client software.
|
||||
Download Geth using the links on the [Downloads](/downloads) page. The SHA256 hashes of the downloaded files can be used to confirm precise consistency with our releases. This protects against malicious code being inadvertently downloaded from an adversarial source. The same measures should also be taken to download trusted consensus client software.
|
||||
|
||||
## Networking security
|
||||
|
||||
@ -23,7 +23,7 @@ Geth has built-in account management tools that are sufficiently secure for most
|
||||
|
||||
Geth allows account unlocking by passing account passwords at startup. This unlocks the account all the while that Geth is running. This is not allowed when `http` traffic is enabled, even with appropriate firewall settings. The combination of `http` and `-unlock` poses too much of a security risk because an attacker able to access the node over the exposed HTTP port would be able to make JSON-RPC requests to the node from the unlocked account, including sending funds to other addresses.
|
||||
|
||||
**back up your keystore and passwords safely and securely!**
|
||||
**Back up your keystore and passwords safely and securely!**
|
||||
|
||||
## Other security considerations
|
||||
|
||||
|
||||
@ -7,19 +7,25 @@ Syncing is the process by which Geth catches up to the latest Ethereum block and
|
||||
|
||||
## Full nodes
|
||||
|
||||
There are three types of full node with different sync modes:
|
||||
There are two types of full node that use different mechanisms to sync up to the head of the chain:
|
||||
|
||||
### 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.
|
||||
|
||||
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).
|
||||
|
||||
**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 is the trust-minimized option since there it does not rely upon any information from any trusted source apart from the genesis configuration. All other information is indendently verified as the node re-executes 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 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.
|
||||
|
||||
### Archive
|
||||
## Archive nodes
|
||||
|
||||
An archive node is a full-sync'd 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 (August 2022) an archive node 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`.
|
||||
|
||||
### Snap
|
||||
|
||||
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 some trusted information (a checkpoint block) to sync from instead of independently verifying the chain all the way from genesis. Snap sync is much faster than full sync. To start a node with snap sync pass `--syncmode snap` at startup.
|
||||
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
|
||||
|
||||
@ -27,8 +33,22 @@ A light node syncs very quickly and stores the bare minimum of blockchain data.
|
||||
|
||||
Read more about light nodes on our [LES page](/content/docs/fundamentals/les.md).
|
||||
|
||||
{% include note.html content="Light nodes do not currently work on proof-of-stake Ethereum, but they are expected to ship soon!" %}
|
||||
## 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.
|
||||
|
||||
### 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.
|
||||
|
||||
Read more in the [optimistic sync specs](https://github.com/ethereum/consensus-specs/blob/dev/sync/optimistic.md).
|
||||
|
||||
### Checkpoint sync
|
||||
|
||||
Alternatively, the consensus client can grab a checkpoint from a trusted source which provides a target state to sync up to, before switching to full sync and verifying each block in turn. In this mode, the node trusts that the checkpoint is correct. There are many possible sources for this checkpoint - the gold standard would be to get it out-of-band from another trusted friend, but it could also come from block explorers or public APIs/web apps.
|
||||
|
||||
**Note** it is not currently possible to use a Geth light node as an execution client on proof-of-stake Ethereum.
|
||||
|
||||
## 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`.
|
||||
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).
|
||||
|
||||
@ -1,64 +0,0 @@
|
||||
---
|
||||
title: Backup & Restore
|
||||
sort_key: C
|
||||
---
|
||||
|
||||
Most important info first: **REMEMBER YOUR PASSWORD** and **BACKUP YOUR KEYSTORE**.
|
||||
|
||||
## Data Directory
|
||||
|
||||
Everything `geth` persists gets written inside its data directory. The default data
|
||||
directory locations are platform specific:
|
||||
|
||||
- Mac: `~/Library/Ethereum`
|
||||
- Linux: `~/.ethereum`
|
||||
- Windows: `%LOCALAPPDATA%\Ethereum`
|
||||
|
||||
Accounts are stored in the `keystore` subdirectory. The contents of this directories
|
||||
should be transportable between nodes, platforms, implementations (C++, Go, Python).
|
||||
|
||||
To configure the location of the data directory, the `--datadir` parameter can be
|
||||
specified. See [CLI Options](../interface/command-line-options) for more details.
|
||||
|
||||
Note the [ethash dag](../interface/mining) is stored at `~/.ethash` (Mac/Linux) or
|
||||
`%APPDATA%\Ethash` (Windows) so that it can be reused by all clients. You can store this
|
||||
in a different location by using a symbolic link.
|
||||
|
||||
## Cleanup
|
||||
|
||||
Geth's blockchain and state databases can be removed with:
|
||||
|
||||
```
|
||||
geth removedb
|
||||
```
|
||||
|
||||
This is useful for deleting an old chain and sync'ing to a new one. It only affects data
|
||||
directories that can be re-created on synchronisation and does not touch the keystore.
|
||||
|
||||
## Blockchain Import/Export
|
||||
|
||||
Export the blockchain in binary format with:
|
||||
|
||||
```
|
||||
geth export <filename>
|
||||
```
|
||||
|
||||
Or if you want to back up portions of the chain over time, a first and last block can be
|
||||
specified. For example, to back up the first epoch:
|
||||
|
||||
```
|
||||
geth export <filename> 0 29999
|
||||
```
|
||||
|
||||
Note that when backing up a partial chain, the file will be appended rather than
|
||||
truncated.
|
||||
|
||||
Import binary-format blockchain exports with:
|
||||
|
||||
```
|
||||
geth import <filename>
|
||||
```
|
||||
|
||||
_See https://eth.wiki/en/howto/blockchain-import-and-export-instructions for more info_
|
||||
|
||||
And finally: **REMEMBER YOUR PASSWORD** and **BACKUP YOUR KEYSTORE**
|
||||
@ -23,7 +23,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
|
||||
|
||||
|
||||
@ -1,31 +1,31 @@
|
||||
---
|
||||
title: eth Namespace
|
||||
sort_key: Documentation for the JSON-RPC API "eth" namespace
|
||||
description: Documentation for the JSON-RPC API "eth" namespace
|
||||
---
|
||||
|
||||
Geth provides several extensions to the standard "eth" JSON-RPC namespace.
|
||||
|
||||
## eth_subscribe, eth_unsubscribe
|
||||
### eth_subscribe, eth_unsubscribe
|
||||
|
||||
These methods are used for real-time events through subscriptions. See the [subscription documentation](/content/docs/interacting_with_geth/RPC/pubsub.md) for more information.
|
||||
|
||||
## eth_call
|
||||
### eth_call
|
||||
|
||||
Executes a new message call immediately, without creating a transaction on the block chain. The `eth_call` method can be used to query internal contract state, to execute validations coded into a contract or even to test what the effect of a transaction would be without running it live.
|
||||
|
||||
### Parameters
|
||||
#### Parameters
|
||||
|
||||
The method takes 3 parameters: an unsigned transaction object to execute in read-only mode; the block number to execute the call against; and an optional state override-set to allow executing the call against a modified chain state.
|
||||
|
||||
#### 1. `Object` - Transaction call object
|
||||
##### 1. `Object` - Transaction call object
|
||||
|
||||
The _transaction call object_ is mandatory. Please see [here](/content/docs/interacting_with_geth/RPC/objects.md) for details.
|
||||
|
||||
#### 2. `Quantity | Tag` - Block number or the string `latest` or `pending`
|
||||
##### 2. `Quantity | Tag` - Block number or the string `latest` or `pending`
|
||||
|
||||
The _block number_ is mandatory and defines the context (state) against which the specified transaction should be executed. It is not possible to execute calls against reorged blocks; or blocks older than 128 (unless the node is an archive node).
|
||||
|
||||
#### 3. `Object` - State override set
|
||||
##### 3. `Object` - State override set
|
||||
|
||||
The _state override set_ is an optional address-to-state mapping, where each entry specifies some state to be ephemerally overridden prior to executing the call. Each address maps to an object containing:
|
||||
|
||||
@ -59,11 +59,11 @@ Example:
|
||||
}
|
||||
```
|
||||
|
||||
### Return Values
|
||||
#### Return Values
|
||||
|
||||
The method returns a single `Binary` consisting the return value of the executed contract call.
|
||||
|
||||
### Simple example
|
||||
#### Simple example
|
||||
|
||||
With a synced Rinkeby node with RPC exposed on localhost (`geth --rinkeby --http`) we can make a call against the [CheckpointOracle](https://rinkeby.etherscan.io/address/0xebe8efa441b9302a0d7eaecc277c09d20d684540) to retrieve the list of administrators:
|
||||
|
||||
@ -90,7 +90,7 @@ Just for the sake of completeness, decoded the response is:
|
||||
0xb86e2b0ab5a4b1373e40c51a7c712c70ba2f9f8e
|
||||
```
|
||||
|
||||
### Override example
|
||||
#### Override example
|
||||
|
||||
The above _simple example_ showed how to call a method already exposed by an on-chain smart contract. What if we want to access some data not exposed by it?
|
||||
|
||||
@ -134,24 +134,24 @@ And the result is the Ethereum ABI encoded threshold number:
|
||||
|
||||
Just for the sake of completeness, decoded the response is: `2`.
|
||||
|
||||
## eth_createAccessList
|
||||
### eth_createAccessList
|
||||
|
||||
This method creates an [EIP2930](https://eips.ethereum.org/EIPS/eip-2930) type `accessList` based on a given `Transaction`. The `accessList` contains all storage slots and addresses read and written by the transaction, except for the sender account and the precompiles. This method uses the same `transaction` call [object](/docs/rpc/objects#transaction-call-object) and `blockNumberOrTag` object as `eth_call`. An `accessList` can be used to unstuck contracts that became inaccessible due to gas cost increases.
|
||||
|
||||
### Parameters
|
||||
#### Parameters
|
||||
|
||||
| Field | Type | Description |
|
||||
| :----------------- | :------- | :--------------------------------------------- |
|
||||
| `transaction` | `Object` | `TransactionCall` object |
|
||||
| `blockNumberOrTag` | `Object` | Optional, blocknumber or `latest` or `pending` |
|
||||
|
||||
### Usage
|
||||
#### Usage
|
||||
|
||||
```
|
||||
curl --data '{"method":"eth_createAccessList","params":[{"from": "0x8cd02c6cbd8375b39b06577f8d50c51d86e8d5cd", "data": "0x608060806080608155"}, "pending"],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
|
||||
```
|
||||
|
||||
### Response
|
||||
#### Response
|
||||
|
||||
The method `eth_createAccessList` returns list of addresses and storage keys used by the transaction, plus the gas consumed when the access list is added.
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: JSON-RPC Server
|
||||
sort_key: Introduction to the JSON-RPC server
|
||||
description: Introduction to the JSON_RPC server
|
||||
---
|
||||
|
||||
Interacting with Geth requires sending requests to specific JSON-RPC API methods. Geth supports all standard [JSON-RPC API](https://github.com/ethereum/execution-apis) endpoints.
|
||||
@ -114,6 +114,12 @@ The following table summarizes the relative strengths and weaknesses of each tra
|
||||
As a general rule IPC is most secure because it is limited to interactions on the local machine and cannot be exposed to external traffic. It can also be used
|
||||
to subscribe to events. HTTP is a familiar and idempotent transport that closes connections between requests and can therefore have lower overall overheads if the number of requests is fairly low. Websockets provides a continuous open channel that can enable event subscriptions and streaming and handle large volumes of requests with smaller per-message overheads.
|
||||
|
||||
## Engine-API
|
||||
|
||||
The Engine-API is a set of RPC methods that enable communication between Geth and the [consensus client](/docs/getting_started/consensus-clients.md). These are not designed to be exposed to the user - instead they are called automatically by the clients when they need to exchange information. The Engine API is enabled by default - the user is not required to pass any instruction to Geth to enable these methods.
|
||||
|
||||
Read more in the [Engine API spec](https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md).
|
||||
|
||||
## Summary
|
||||
|
||||
RPC requests to a Geth node can be made using three different transport protocols. The protocols are enabled at startup using their respective flags. The right choice of transport protocol depends on the specific use case.
|
||||
|
||||
@ -1,113 +0,0 @@
|
||||
---
|
||||
title: Vulnerability disclosure
|
||||
sort_key: A
|
||||
---
|
||||
|
||||
## About disclosures
|
||||
|
||||
In the software world, it is expected for security vulnerabilities to be immediately
|
||||
announced, thus giving operators an opportunity to take protective measure against
|
||||
attackers.
|
||||
|
||||
Vulnerabilies typically take two forms:
|
||||
|
||||
1. Vulnerabilies that, if exploited, would harm the software operator. In the case of
|
||||
go-ethereum, examples would be:
|
||||
- A bug that would allow remote reading or writing of OS files, or
|
||||
- Remote command execution, or
|
||||
- Bugs that would leak cryptographic keys
|
||||
2. Vulnerabilies that, if exploited, would harm the Ethereum mainnet. In the case of
|
||||
go-ethereum, examples would be:
|
||||
- Consensus vulnerabilities, which would cause a chain split,
|
||||
- Denial-of-service during block processing, whereby a malicious transaction could cause the geth-portion of the network to crash.
|
||||
- Denial-of-service via p2p networking, whereby portions of the network could be made
|
||||
inaccessible due to crashes or resource consumption.
|
||||
|
||||
In most cases so far, vulnerabilities in `geth` have been of the second type, where the
|
||||
health of the network is a concern, rather than individual node operators. For such
|
||||
issues, we reserve the right to silently patch and ship fixes in new releases.
|
||||
|
||||
### Why silent patches
|
||||
|
||||
In the case of Ethereum, it takes a lot of time (weeks, months) to get node operators to
|
||||
update even to a scheduled hard fork. If we were to highlight that a release contains
|
||||
important consensus or DoS fixes, there is always a risk of someone trying to beat node
|
||||
operators to the punch, and exploit the vulnerability. Delaying a potential attack
|
||||
sufficiently to make the majority of node operators immune may be worth the temporary loss
|
||||
of transparency.
|
||||
|
||||
The primary goal for the Geth team is the health of the Ethereum network as a whole, and
|
||||
the decision whether or not to publish details about a serious vulnerability boils down to
|
||||
minimizing the risk and/or impact of discovery and exploitation.
|
||||
|
||||
At certain times, it's better to remain silent. This practice is also followed by other
|
||||
projects such as
|
||||
[Monero](https://www.getmonero.org/2017/05/17/disclosure-of-a-major-bug-in-cryptonote-based-currencies.html),
|
||||
[ZCash](https://electriccoin.co/blog/zcash-counterfeiting-vulnerability-successfully-remediated/)
|
||||
and
|
||||
[Bitcoin](https://www.coindesk.com/the-latest-bitcoin-bug-was-so-bad-developers-kept-its-full-details-a-secret).
|
||||
|
||||
### Public transparency
|
||||
|
||||
As of November 2020, our policy going forward is:
|
||||
|
||||
- If we silently fix a vulnerability and include the fix in release `X`, then,
|
||||
- After 4-8 weeks, we will disclose that `X` contained a security-fix.
|
||||
- After an additional 4-8 weeks, we will publish the details about the vulnerability.
|
||||
|
||||
We hope that this provides sufficient balance between transparency versus the need for
|
||||
secrecy, and aids node operators and downstream projects in keeping up to date with what
|
||||
versions to run on their infrastructure.
|
||||
|
||||
In keeping with this policy, we have taken inspiration from [Solidity bug disclosure](https://solidity.readthedocs.io/en/develop/bugs.html) - see below.
|
||||
|
||||
## Disclosed vulnerabilities
|
||||
|
||||
In this folder, you can find a JSON-formatted list
|
||||
([`vulnerabilities.json`](vulnerabilities.json)) of some of the known security-relevant
|
||||
vulnerabilities concerning `geth`.
|
||||
|
||||
As of `geth` version `1.9.25`, geth has a built-in command to check whether it is affected
|
||||
by any publically disclosed vulnerability, using the command `geth version-check`. This
|
||||
command will fetch the latest json file (and the accompanying
|
||||
[signature-file](vulnerabilities.json.minisig), and cross-check the data against it's own
|
||||
version number.
|
||||
|
||||
The file itself is hosted in the Github repository, on the `gh-pages`-branch. The list was
|
||||
started in November 2020, and covers mainly `v1.9.7` and forward.
|
||||
|
||||
The JSON file of known vulnerabilities below is a list of objects, one for each
|
||||
vulnerability, with the following keys:
|
||||
|
||||
- `name`
|
||||
- Unique name given to the vulnerability.
|
||||
- `uid`
|
||||
- Unique identifier of the vulnerability. Format `GETH-<year>-<sequential id>`
|
||||
- `summary`
|
||||
- Short description of the vulnerability.
|
||||
- `description`
|
||||
- Detailed description of the vulnerability.
|
||||
- `links`
|
||||
- List of relevant URLs with more detailed information (optional).
|
||||
- `introduced`
|
||||
- The first published Geth version that contained the vulnerability (optional).
|
||||
- `fixed`
|
||||
- The first published Geth version that did not contain the vulnerability anymore.
|
||||
- `published`
|
||||
- The date at which the vulnerability became known publicly (optional).
|
||||
- `severity`
|
||||
- Severity of the vulnerability: `low`, `medium`, `high`, `critical`.
|
||||
- Takes into account the severity of impact and likelihood of exploitation.
|
||||
- `check`
|
||||
- This field contains a regular expression, which can be used against the reported `web3_clientVersion` of a node. If the check
|
||||
matches, the node is with a high likelyhood affected by the vulnerability.
|
||||
- `CVE`
|
||||
- The assigned `CVE` identifier, if available (optional)
|
||||
|
||||
### What about Github security advisories
|
||||
|
||||
We prefer to not rely on Github as the only/primary publishing protocol for security
|
||||
advisories, but we plan to use the Github-advisory process as a second channel for
|
||||
disseminating vulnerability-information.
|
||||
|
||||
Advisories published via Github can be accessed [here](https://github.com/ethereum/go-ethereum/security/advisories?state=published).
|
||||
@ -30,3 +30,7 @@ Running your own node enables you to use Ethereum in a truly private, self-suffi
|
||||
## Contribute to Geth
|
||||
|
||||
We welcome contributions from anyone on the internet, and are grateful for even the smallest of fixes! If you'd like to contribute to the Geth source code, please fork the [Github repository](https://github.com/ethereum/go-ethereum), fix, commit and send a pull request for the maintainers to review and merge into the main code base. See our [contribution guidelines](/content/docs/developers/contributing.md) for more information.
|
||||
|
||||
## About the Team
|
||||
|
||||
The Geth team comprises 10 developers distributed across the world. The Geth team is funded directly by [The Ethereum Foundation](https://ethereum.foundation).
|
||||
|
||||
@ -1,29 +1,46 @@
|
||||
---
|
||||
title: resources
|
||||
description: read, watch and listen more about Geth and Ethereum
|
||||
description: Read, watch and listen more about Geth and Ethereum
|
||||
---
|
||||
|
||||
Here are more resources for a deeper understanding of Geth and related topics.
|
||||
|
||||
## Read
|
||||
|
||||
[Geth team AMA: August 2022](https://www.reddit.com/r/cryptoall/comments/wpr6dk/ama_we_are_the_go_ethereum_geth_team_18_august/)
|
||||
|
||||
[Ethereum stack exchange](https://ethereum.stackexchange.com/)
|
||||
|
||||
## Watch
|
||||
|
||||
[Péter at ETH Prage 2022: Ethereum in numbers: where TPS meets physics](https://www.youtube.com/watch?v=TdsaVoJiy3g)
|
||||
|
||||
[Marius at ETH Amsterdam 2022: Deep dive into Geth](https://www.youtube.com/watch?v=c4N79UXZqSc)
|
||||
|
||||
[Péter interview at ETH Prage 2022:](https://www.youtube.com/watch?v=cfxGzZZ_uOI)
|
||||
|
||||
[Guillame at Devconnect 2022: Stateless Ethereum](https://www.youtube.com/watch?v=XkzJncPYj0M&list=PLJijNYoOwnsuqDH9ITSvbqDOaUdA1vp2O&index=9)
|
||||
|
||||
[lightclients at Devconnect 2022: Future of Ethereum accounts](https://www.youtube.com/watch?v=pS5asEp6ry8&list=PLJijNYoOwnsuqDH9ITSvbqDOaUdA1vp2O&index=7)
|
||||
|
||||
[Zsolt at Devconnect 2022: Geth in the pos light client ecosystem](https://www.youtube.com/watch?v=EPZeFXau-RE&list=PLJijNYoOwnst-feT7PsCLaSdiFYzWtf7j&index=2)
|
||||
|
||||
[Jared at Devconnect 2022: Removing SELFDESTRUCT](https://www.youtube.com/watch?v=pDr-h334-Cs&list=PLJijNYoOwnsuqDH9ITSvbqDOaUdA1vp2O&index=5)
|
||||
|
||||
[Marius interview at ETH Prague 2022](https://www.youtube.com/watch?v=QKr3KHTjbjQ)
|
||||
|
||||
[Marius at ETHOnline 2021: The Megre from the perspective of the execution layer](https://www.youtube.com/watch?v=3DDjfUvQ2TE)
|
||||
|
||||
[Péter's 2020 online Geth AMA](https://www.youtube.com/watch?v=gVMDw66atr4)
|
||||
|
||||
[Martin at Devcon 5: Protecting the base layer](https://www.youtube.com/watch?v=wLcyIgblIxE)
|
||||
|
||||
[Péter at DevCon 5: Monitoring Ethereum infrastructure](https://www.youtube.com/watch?v=2I_Cfr-OUp4)
|
||||
|
||||
[Péter at DevCon 4: Plugging metadata leaks in Ethereum](https://www.youtube.com/watch?v=J1JenTo7oLE)
|
||||
|
||||
[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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user