@ -60,7 +60,7 @@ Images should be saved to `public/images/docs` and included in the markdown as f
#### Frontmatter metadata
`title` and `description` are **required** metadata props for a post: `title` will generate the main heading on the doc page and `description` is used for SEO purposes, to serve as a concise and appropiate description of the content.
`title` and `description` are **required** metadata props for a post: `title` will generate the main heading on the doc page and `description` is used for SEO purposes, to serve as a concise and appropriate description of the content.
@ -5,7 +5,7 @@ description: Introduction to account management in Go native applications.
Geth provides a simple, yet thorough accounts package that includes all the tools developers need to leverage all the security of Geth's crypto implementation in a Go native application. The account management is done client side with all sensitive data held inside the application. This gives the user control over access permissions without relying on any third party.
**Note: Geth's built-in account management is convenient and straightforward to use, but best practise is to use the external tool _Clef_ for key management.**
**Note: Geth's built-in account management is convenient and straightforward to use, but best practice is to use the external tool _Clef_ for key management.**
## Encrypted keystores {#encrypted-keystores}
@ -53,7 +53,7 @@ This individuality means that any operation requiring access to an account will
- When exporting an existing account, the caller must supply both the current passphrase to decrypt the account, as well as an export passphrase to re-encrypt it with before returning the key-file to the user. This is required to allow moving accounts between machines and applications without sharing original credentials.
- When importing a new account, the caller must supply both the encryption passphrase of the key-file being imported, as well as a new passhprase with which to store the account. This is required to allow storing account with different credentials than used for moving them around.
- When importing a new account, the caller must supply both the encryption passphrase of the key-file being imported, as well as a new passphrase with which to store the account. This is required to allow storing account with different credentials than used for moving them around.
**_Please note, there are no recovery mechanisms for lost passphrases. The cryptographic properties of the encrypted keystore (using the provided parameters) guarantee that account credentials cannot be brute forced in any meaningful time._**
@ -121,4 +121,4 @@ Note that [`SignWithPassphrase`](https://godoc.org/github.com/ethereum/go-ethere
## Summary {#summary}
Account management is a fundamental pillar of Ethereum development. Geth's Go API provides the tools required to integrate best-practise account security into Go native applications using a simple set of Go functions.
Account management is a fundamental pillar of Ethereum development. Geth's Go API provides the tools required to integrate best-practice account security into Go native applications using a simple set of Go functions.
_Note that both `ethclient` and `gethclient` have a `CallContract()` function - the difference is that the `gethclient` version includes an `overrides` argument._
Details relating to these endpoints can be found at [pkg.go.dev](https://pkg.go.dev/github.com/ethereum/go-ethereum@v1.10.19/ethclient/gethclient) or the Geth [GitHub](https://github.com/ethereum/go-ethereum/tree/master/ethclient). The code snippets in this tutorial were adapted from a more more in-depth set of examples available on [GitHub](https://github.com/MariusVanDerWijden/web3go).
Details relating to these endpoints can be found at [pkg.go.dev](https://pkg.go.dev/github.com/ethereum/go-ethereum@v1.10.19/ethclient/gethclient) or the Geth [GitHub](https://github.com/ethereum/go-ethereum/tree/master/ethclient). The code snippets in this tutorial were adapted from a more in-depth set of examples available on [GitHub](https://github.com/MariusVanDerWijden/web3go).
@ -24,7 +24,7 @@ The struct logger (aka opcode logger) is a native Go tracer which executes a tra
| refund | uint64 | Refund counter |
| error | string | Error message if any |
Note that the fields `memory`, `stack`, `returnData`, and `storage` have dynamic size and depending on the exact transaction they could grow large in size. This is specially true for `memory` which could blow up the trace size. It is recommended to keep them disabled unless they are explicitly required for a given use-case.
Note that the fields `memory`, `stack`, `returnData`, and `storage` have dynamic size and depending on the exact transaction they could grow large in size. This is specially true for `memory` which could blow up the trace size. It is recommended to keep them disabled unless they are explicitly required for a given usecase.
It is also possible to configure the trace by passing Boolean (true/false) values for four parameters that tweak the verbosity of the trace. By default, the _EVM memory_ and _Return data_ are not reported but the _EVM stack_ and _EVM storage_ are. To report the maximum amount of data:
@ -96,9 +96,9 @@ The following tracers are implement in Go. This means they are much more perform
### 4byteTracer {#4byte-tracer}
Solidity contract functions are
[addressed](https://docs.soliditylang.org/en/develop/abi-spec.html#function-selector) using the first four four byte of the Keccak-256 hash of their signature. Therefore when calling the function of a contract, the caller must send this function selector as well as the ABI-encoded arguments as call data.
[addressed](https://docs.soliditylang.org/en/develop/abi-spec.html#function-selector) using the first four byte of the Keccak-256 hash of their signature. Therefore when calling the function of a contract, the caller must send this function selector as well as the ABI-encoded arguments as call data.
The `4byteTracer` collects the function selectors of every function executed in the lifetime of a transaction, along with the size of the supplied call data. The result is a `map[string]int` where the keys are `SELECTOR-CALLDATASIZE` and the values are number of occurances of this key. For example:
The `4byteTracer` collects the function selectors of every function executed in the lifetime of a transaction, along with the size of the supplied call data. The result is a `map[string]int` where the keys are `SELECTOR-CALLDATASIZE` and the values are number of occurrences of this key. For example:
Example call:
@ -446,7 +446,7 @@ Returns:
### unigram {#unigram}
`unigramTracer` counts the frequency of occurrance of each opcode.
`unigramTracer` counts the frequency of occurrence of each opcode.
Example:
@ -477,7 +477,7 @@ Returns:
## State overrides {#state-overrides}
It is possible to give temporary state modifications to Geth in order to simulate the effects of `eth_call`. For example, some new byetcode could be deployed to some address _temporarily just for the duration of the execution_ and then a transaction interacting with that address canm be traced. This can be used for scenario testing or determining the outcome of some hypothetical transaction before executing for real.
It is possible to give temporary state modifications to Geth in order to simulate the effects of `eth_call`. For example, some new bytecode could be deployed to some address _temporarily just for the duration of the execution_ and then a transaction interacting with that address can be traced. This can be used for scenario testing or determining the outcome of some hypothetical transaction before executing for real.
To do this, the tracer is written as normal, but the parameter `stateOverrides` is passed an address and some bytecode.
@ -34,7 +34,7 @@ _This image shows the state stored by each sync-mode - red indicates stored stat
More detailed information about syncing is available on the [sync modes page](/docs/fundamentals/sync-modes).
When a trace of a specific transaction is executed, the state is prepared by fetching the state of the parent block from the database. If it is not available, Geth will crawl backwards in time to find the next available state but only up to a limit defined in the `reexec` parameter which defaults to 128 blocks. If no state is available within the `reexec` window then the trace fails with `Error: required historical state unavailable` and the `reexec` parameter must be increased. If a valid state _is_ found in the `reexec` window, then Geth sequentially re-executes the transcations in each block between the last available state and the target block. The greater the value of `reexec` the longer the tracing will take because more blocks have to be re-executed to regenerate the target state.
When a trace of a specific transaction is executed, the state is prepared by fetching the state of the parent block from the database. If it is not available, Geth will crawl backwards in time to find the next available state but only up to a limit defined in the `reexec` parameter which defaults to 128 blocks. If no state is available within the `reexec` window then the trace fails with `Error: required historical state unavailable` and the `reexec` parameter must be increased. If a valid state _is_ found in the `reexec` window, then Geth sequentially re-executes the transactions in each block between the last available state and the target block. The greater the value of `reexec` the longer the tracing will take because more blocks have to be re-executed to regenerate the target state.
The `debug_getAccessibleStates` endpoint is a useful tool for estimating a suitable value for `reexec`. Passing the number of the block that contains the target transaction and a search distance to this endpoint will return the number of blocks behind the current head where the most recent available state exists. This value can be passed to the tracer as `re-exec`.
@ -52,7 +52,7 @@ Read more about Geth's basic traces on the [basic traces page](/docs/developers/
### Built-in tracers {#built-in-tracers}
The tracing API accepts an optional `tracer` parameter that defines how the data returned to the API call should be processed. If this parameter is ommitted the default tracer is used. The default is the struct (or 'opcode') logger. These raw opcode traces are sometimes useful, but the returned data is very low level and can be too extensive and awkward to read for many use-cases. A full opcode trace can easily go into the hundreds of megabytes, making them very resource intensive to get out of the node and process externally. For these reasons, there are a set of non-default built-in tracers that can be named in the API call to return different data from the method. Under the hood, these tracers are Go or Javascript
The tracing API accepts an optional `tracer` parameter that defines how the data returned to the API call should be processed. If this parameter is omitted the default tracer is used. The default is the struct (or 'opcode') logger. These raw opcode traces are sometimes useful, but the returned data is very low level and can be too extensive and awkward to read for many usecases. A full opcode trace can easily go into the hundreds of megabytes, making them very resource intensive to get out of the node and process externally. For these reasons, there are a set of non-default built-in tracers that can be named in the API call to return different data from the method. Under the hood, these tracers are Go or Javascript
functions that do some specific preprocessing on the trace data before it is returned.
More information about Geth's built-in tracers is available on the [built-in tracers](/docs/developers/evm-tracing/built-in-tracers) page.
More information about the `JSON.stringify` function is available [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).
The commands above worked by calling the same `debug.traceTransaction` function that was previously explained in [basic traces](/docs/developers/evm-tracing/basic-traces), but with a new parameter, `tracer`. This parameter takes the JavaScript object formated as a string. In the case of the trace above, it is:
The commands above worked by calling the same `debug.traceTransaction` function that was previously explained in [basic traces](/docs/developers/evm-tracing/basic-traces), but with a new parameter, `tracer`. This parameter takes the JavaScript object formatted as a string. In the case of the trace above, it is:
```js
{
@ -167,7 +167,7 @@ The output is similar to:
#### Operation Results
One piece of information missing from the function above is the result on an `SLOAD` operation. The state we get inside `log` is the state prior to the execution of the opcode, so that value is not known yet. For more operations we can figure it out for ourselves, but we don't have access to the
One piece of information missing from the function above is the result of an `SLOAD` operation. The state we get inside `log` is the state prior to the execution of the opcode, so that value is not known yet. For more operations we can figure it out for ourselves, but we don't have access to the
storage, so here we can't.
The solution is to have a flag, `afterSload`, which is only true in the opcode right after an `SLOAD`, when we can see the result at the top of the stack.
@ -60,7 +60,7 @@ issue notices, e.g. "Fixes #42353".
### Special Situations And How To Deal With Them {#special-situations}
Reviewers may find themselves in one of the sitations below. Here's how to deal with them:
Reviewers may find themselves in one of the situations below. Here's how to deal with them:
- The author doesn't follow up: ping them after a while (i.e. after a few days). If there is no further response, close the PR or complete the work yourself.
Geth logs the location of the IPC endpoint on startup. It is typically under `/home/user/.ethereum/geth.ipc` or `/tmp/geth.ipc`.
`debug.stacks()` also takes an optional `filter` argument. Passing a package name or filepath to `filter` restricts the output to stack traces involcing only that package/file. For example:
`debug.stacks()` also takes an optional `filter` argument. Passing a package name or filepath to `filter` restricts the output to stack traces involving only that package/file. For example:
```sh
debug.stacks("enode")
@ -144,4 +144,4 @@ This will dump stack traces for each instance to their respective log file.
## Where to go next {#where-next}
Read the remaning pages in the Geth developer section, and get building!
Read the remaining pages in the Geth developer section, and get building!
@ -5,13 +5,13 @@ description: Instructions for disclosing vulnerabilities to the Geth team
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:
Vulnerabilities typically take two forms:
1. Vulnerabilies that, if exploited, would harm the software operator. In the case of Geth, examples would be:
1. Vulnerabilities that, if exploited, would harm the software operator. In the case of Geth, 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 Geth, examples would be:
2. Vulnerabilities that, if exploited, would harm the Ethereum mainnet. In the case of Geth, 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
@ -43,7 +43,7 @@ In keeping with this policy, we have taken inspiration from [Solidity bug disclo
There is a JSON-formatted list ([`vulnerabilities.json`](/public/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](/public/docs/vulnerabilities/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](/public/docs/vulnerabilities/vulnerabilities.json.minisig), and cross-check the data against its own version number.
The list of vulnerabilities was started in November 2020, and covers mainly `v1.9.7` and forward.
@ -70,7 +70,7 @@ The JSON file of known vulnerabilities below is a list of objects, one for each
- 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.
matches, the node is with a high likelihood affected by the vulnerability.
- `CVE`
- The assigned `CVE` identifier, if available (optional)
@ -5,7 +5,7 @@ description: Instructions for setting up DNS discovery
This document explains how to set up an [EIP 1459](https://eips.ethereum.org/EIPS/eip-1459) node list using the devp2p developer tool. The focus of this guide is creating a public list for the Ethereum mainnet and public testnets, but it may also be helpful for setting up DNS-based discovery for a private network.
DNS-based node lists can serve as a fallback option when connectivity to the discovery DHT is unavailable. In this guide, node lists will be reated by crawling the discovery DHT, then publishing the resulting node sets under chosen DNS names.
DNS-based node lists can serve as a fallback option when connectivity to the discovery DHT is unavailable. In this guide, node lists will be created by crawling the discovery DHT, then publishing the resulting node sets under chosen DNS names.
## Installing the devp2p command {#installing-devp2p}
@ -23,7 +23,7 @@ go get github.com/ethereum/go-ethereum/cmd/ethkey
## Crawling the v4 DHT {#crawling-v4-dht}
Our first step is to compile a list of all reachable nodes. The DHT crawler in cmd/devp2p is a batch process which runs for a set amount of time. You should should schedule this command to run at a regular interval. To create a node list, run
Our first step is to compile a list of all reachable nodes. The DHT crawler in cmd/devp2p is a batch process which runs for a set amount of time. You should schedule this command to run at a regular interval. To create a node list, run
```sh
devp2p discv4 crawl -timeout 30m all-nodes.json
@ -71,7 +71,7 @@ To turn a node list into a DNS node tree, the list needs to be signed. To do thi
ethkey generate dnskey.json
```
Now use `devp2p dns sign` to update the signature of the node list. If the list's directory name differs from the name it will be published at,specify the DNS name the using the `-domain` flag. This command will prompt for the key file password and update the tree signature.
Now use `devp2p dns sign` to update the signature of the node list. If the list's directory name differs from the name it will be published at,specify the DNS name using the `-domain` flag. This command will prompt for the key file password and update the tree signature.
```sh
devp2p dns sign mainnet.nodes.example.org dnskey.json
@ -19,7 +19,7 @@ Geth has many features that support dapp developers. There are many built-in tra
## Geth developers {#geth-developers}
Geth developers add/remove features and fix bugs in Geth. The `geth-developer` section includes contribution guidelines and documentation relating to testing and disclosing vulnerabilities that willhep you get started with working on Geth.
Geth developers add/remove features and fix bugs in Geth. The `geth-developer` section includes contribution guidelines and documentation relating to testing and disclosing vulnerabilities that willhelp you get started with working on Geth.
@ -78,13 +78,13 @@ Light sync relies on full nodes that serve data to light clients. Historically,
## Why do I need another client in addition to Geth? {#consensus-client}
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.
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 separation of concerns between the two clients, meaning that both are required for a computer function as an Ethereum node.
## What is staking and how do I participate? {#what-is-staking}
Staking is how node operators participate in proof-of-stake based consensus. Staking requires validators to deposit 32 ETH to a smart contract and run validator software connected to their node. The validator software broadcasts a vote ("attestation") in favour of checkpoint blocks that it determines to be in the canonical blockchain. The corrct chain is then the one with the greatest accumulation of votes, weighted by the validators stake (up to a maximum of 32 ETH). Geth, as an execution client, does not directly handle consensus logic but it does provide the node with the execution and state-management tools required to validate incoming blocks. Validators are also occasionally picked to propose the next block broadcast across the network. In this case Geth's role is to bundle transactions it has received over the execution layer gossip network, pass them to the consensus client to be included in the block and execute them to determine the resulting state change.
Staking is how node operators participate in proof-of-stake based consensus. Staking requires validators to deposit 32 ETH to a smart contract and run validator software connected to their node. The validator software broadcasts a vote ("attestation") in favour of checkpoint blocks that it determines to be in the canonical blockchain. The correct chain is then the one with the greatest accumulation of votes, weighted by the validators stake (up to a maximum of 32 ETH). Geth, as an execution client, does not directly handle consensus logic but it does provide the node with the execution and state-management tools required to validate incoming blocks. Validators are also occasionally picked to propose the next block broadcast across the network. In this case Geth's role is to bundle transactions it has received over the execution layer gossip network, pass them to the consensus client to be included in the block and execute them to determine the resulting state change.
It is entirely possible to run a node without staking any ETH. In this case the node runs the execution and consensus clients but not the validator software. In order to participate in consensus and earn ETH rewards, the node must run an execution cleint, consensus client and a validator. The validator software comes bundled with the consensus client.
It is entirely possible to run a node without staking any ETH. In this case the node runs the execution and consensus clients but not the validator software. In order to participate in consensus and earn ETH rewards, the node must run an execution client, consensus client and a validator. The validator software comes bundled with the consensus client.
For step-by-step instruction for staking and spinning up a validating node, see [ethereum.org](https://ethereum.org/en/staking/) or get started on the Ethereum Foundation's [Staking Launchpad](https://launchpad.ethereum.org/).
omahs
2 years ago
committed by
GitHub