From 1660d4dd83b368cefeaecca276e239be614ad0ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=A1s=20Quiroz?= Date: Wed, 14 Sep 2022 19:01:44 +0200 Subject: [PATCH] chore: sync content with master branch --- .../{vulnerabilities.md => disclosures.md} | 14 ++- .../geth-developer/private-network.md | 2 +- src/pages/docs/faq.md | 36 ++---- .../docs/fundamentals/node-architecture.md | 4 +- src/pages/docs/fundamentals/security.md | 4 +- src/pages/docs/fundamentals/sync-modes.md | 38 ++++-- .../docs/getting_started/backup-restore.md | 64 ---------- .../docs/getting_started/consensus-clients.md | 2 +- .../docs/interacting-with-geth/rpc/ns-eth.md | 28 ++--- .../docs/interacting-with-geth/rpc/server.md | 8 +- .../docs/vulnerabilities/vulnerabilities.md | 113 ------------------ src/pages/homepage.md | 4 + src/pages/resources.md | 19 ++- 13 files changed, 99 insertions(+), 237 deletions(-) rename src/pages/docs/developers/geth-developer/{vulnerabilities.md => disclosures.md} (88%) delete mode 100644 src/pages/docs/getting_started/backup-restore.md delete mode 100644 src/pages/docs/vulnerabilities/vulnerabilities.md diff --git a/src/pages/docs/developers/geth-developer/vulnerabilities.md b/src/pages/docs/developers/geth-developer/disclosures.md similarity index 88% rename from src/pages/docs/developers/geth-developer/vulnerabilities.md rename to src/pages/docs/developers/geth-developer/disclosures.md index 06dd9558e1..719b0db9fb 100644 --- a/src/pages/docs/developers/geth-developer/vulnerabilities.md +++ b/src/pages/docs/developers/geth-developer/disclosures.md @@ -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/). diff --git a/src/pages/docs/developers/geth-developer/private-network.md b/src/pages/docs/developers/geth-developer/private-network.md index 526ce46453..5de6c64b73 100644 --- a/src/pages/docs/developers/geth-developer/private-network.md +++ b/src/pages/docs/developers/geth-developer/private-network.md @@ -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({ diff --git a/src/pages/docs/faq.md b/src/pages/docs/faq.md index bd5d5b704f..a2be123f8c 100644 --- a/src/pages/docs/faq.md +++ b/src/pages/docs/faq.md @@ -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 -``` - -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 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 -``` - -_See https://eth.wiki/en/howto/blockchain-import-and-export-instructions for more info_ - -And finally: **REMEMBER YOUR PASSWORD** and **BACKUP YOUR KEYSTORE** diff --git a/src/pages/docs/getting_started/consensus-clients.md b/src/pages/docs/getting_started/consensus-clients.md index 464dab434e..d38e544a93 100644 --- a/src/pages/docs/getting_started/consensus-clients.md +++ b/src/pages/docs/getting_started/consensus-clients.md @@ -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 diff --git a/src/pages/docs/interacting-with-geth/rpc/ns-eth.md b/src/pages/docs/interacting-with-geth/rpc/ns-eth.md index 48cc0af164..b610e41afb 100644 --- a/src/pages/docs/interacting-with-geth/rpc/ns-eth.md +++ b/src/pages/docs/interacting-with-geth/rpc/ns-eth.md @@ -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. diff --git a/src/pages/docs/interacting-with-geth/rpc/server.md b/src/pages/docs/interacting-with-geth/rpc/server.md index 8cc4d49687..dfd56076c2 100644 --- a/src/pages/docs/interacting-with-geth/rpc/server.md +++ b/src/pages/docs/interacting-with-geth/rpc/server.md @@ -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. diff --git a/src/pages/docs/vulnerabilities/vulnerabilities.md b/src/pages/docs/vulnerabilities/vulnerabilities.md deleted file mode 100644 index bec5e4c9e3..0000000000 --- a/src/pages/docs/vulnerabilities/vulnerabilities.md +++ /dev/null @@ -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--` -- `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). diff --git a/src/pages/homepage.md b/src/pages/homepage.md index d1205524dd..a57c0a78f7 100644 --- a/src/pages/homepage.md +++ b/src/pages/homepage.md @@ -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). diff --git a/src/pages/resources.md b/src/pages/resources.md index 054f9c9c24..4b2367ab80 100644 --- a/src/pages/resources.md +++ b/src/pages/resources.md @@ -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