interesting
/
go-ethereum
mirror of https://github.com/ethereum/go-ethereum.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

various content updates

This commit is contained in:
Joe 2022-11-25 14:43:48 +00:00
parent 865802bdff
commit dd4929f40d
11 changed files with 273 additions and 1017 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
docs/developers/evm-tracing/basic-traces.md Normal file
View File

@ -0,0 +1,98 @@
---
title: Basic traces
description: Introduction to basic EVM traces
---
The simplest type of transaction trace that Geth can generate are raw EVM opcode traces. For every VM instruction the transaction executes, a structured log entry is emitted, containing all contextual metadata deemed useful. This includes the *program counter*, *opcode name*, *opcode cost*, *remaining gas*, *execution depth* and any *occurred error*. The structured logs can optionally also contain the content of the *execution stack*, *execution memory* and *contract storage*.
The entire output of a raw EVM opcode trace is a JSON object having a few metadata fields: *consumed gas*, *failure status*, *return value*; and a list of *opcode entries*:
```json
{
"gas": 25523,
"failed": false,
"returnValue": "",
"structLogs": []
}
```
An example log for a single opcode entry has the following format:
```json
{
"pc": 48,
"op": "DIV",
"gasCost": 5,
"gas": 64532,
"depth": 1,
"error": null,
"stack": [
"00000000000000000000000000000000000000000000000000000000ffffffff",
"0000000100000000000000000000000000000000000000000000000000000000",
"2df07fbaabbe40e3244445af30759352e348ec8bebd4dd75467a9f29ec55d98d"
],
"memory": [
"0000000000000000000000000000000000000000000000000000000000000000",
"0000000000000000000000000000000000000000000000000000000000000000",
"0000000000000000000000000000000000000000000000000000000000000060"
],
"storage": {
}
}
```
### Generating basic traces
To generate a raw EVM opcode trace, Geth provides a few [RPC API endpoints](/docs/rpc/ns-debug). The most commonly used is [`debug_traceTransaction`](/docs/rpc/ns-debug#debug_tracetransaction).
In its simplest form, `traceTransaction` accepts a transaction hash as its only argument. It then traces the transaction, aggregates all the generated
data and returns it as a **large** JSON object. A sample invocation from the Geth console would be:
```js
debug.traceTransaction("0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f")
```
The same call can also be invoked from outside the node too via HTTP RPC (e.g. using Curl). In this case, the HTTP endpoint must be enabled in Geth using the `--http` command and the `debug` API namespace must be exposed using `--http.api=debug`.
```
$ curl -H "Content-Type: application/json" -d '{"id": 1, "method": "debug_traceTransaction", "params": ["0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f"]}' localhost:8545
```
To follow along with this tutorial, transaction hashes can be found from a local Geth node (e.g. by attaching a [Javascript console](/docs/interface/javascript-console) and running `eth.getBlock('latest')` then passing a transaction hash from the returned block to `debug.traceTransaction()`) or from a block explorer (for [Mainnet](https://etherscan.io/) or a [testnet](https://goerli.etherscan.io/)).
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:
```shell
enableMemory: true
disableStack: false
disableStorage: false
enableReturnData: true
```
An example call, made in the Geth Javascript console, configured to report the maximum amount of data looks as follows:
```js
debug.traceTransaction("0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f",{enableMemory: true, disableStack: false, disableStorage: false, enableReturnData: true})
```
The above operation was run on the (now-deprecated) Rinkeby network (with a node retaining enough history), resulting in this [trace dump](https://gist.github.com/karalabe/c91f95ac57f5e57f8b950ec65ecc697f).
Alternatively, disabling *EVM Stack*, *EVM Memory*, *Storage* and *Return data* (as demonstrated in the Curl request below) results in the following, much shorter, [trace dump](https://gist.github.com/karalabe/d74a7cb33a70f2af75e7824fc772c5b4).
```
$ curl -H "Content-Type: application/json" -d '{"id": 1, "method": "debug_traceTransaction", "params": ["0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f", {"disableStack": true, "disableStorage": true}]}' localhost:8545
```
### Limits of basic traces
Although the raw opcode traces generated above are useful, having an individual log entry for every single opcode is too low level for most use cases,
and will require developers to create additional tools to post-process the traces. Additionally, 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.
To avoid those issues, Geth supports running custom JavaScript tracers *within* the Ethereum node, which have full access to the EVM stack, memory and contract storage. This means developers only have to gather the data they actually need, and do any processing at the source.
## Summary
This page described how to do basic traces in Geth. Basic traces are very low level and can generate lots of data that might not all be useful. Therefore, it is also possible to use a set of built-in tracers or write custom ones in Javascript or Go.
Read more about [built-in](/docs/evm-tracing/builtin-tracers) and [custom](/docs/evm-tracing/custom-tracer) traces.

112
docs/developers/evm-tracing/built-in-tracers.md
View File

@ -3,7 +3,8 @@ title: Built-in tracers
description: Explanation of the tracers that come bundled in Geth as part of the tracing API.
---
Geth comes bundled with a choice of tracers that can be invoked via the [tracing API](/docs/rpc/ns-debug). Some of these built-in tracers are implemented natively in Go, and others in Javascript. The default tracer is the opcode logger (otherwise known as struct logger) which is the default tracer for all the methods. Other tracers have to be specified by passing their name to the `tracer` parameter in the API call.
Geth comes bundled with a choice of tracers that can be invoked via the [tracing API](/docs/rpc/ns-debug). Some of these built-in tracers are implemented natively in Go, and others in Javascript. The default tracer is the opcode logger (otherwise known as struct logger) which is the default tracer for all the methods. Other tracers have to be specified by passing their name to the `tracer` parameter in the API call.
## Struct/opcode logger
@ -85,7 +86,7 @@ Return:
}
},
...
...
```
@ -93,9 +94,11 @@ Return:
The following tracers are implement in Go. This means they are much more performant than other tracers that are written in Javascript. The tracers are selected by passing their name to the `tracer` parameter when invoking a tracing API method, e.g. `debug.traceTransaction(<txhash>, { tracer: 'callTracer' })`.
### 4byteTracer
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.
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.
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:
@ -121,18 +124,20 @@ Return:
The `callTracer` tracks all the call frames executed during a transaction, including depth 0. The result will be a nested list of call frames, resembling how EVM works. They form a tree with the top-level call at root and sub-calls as children of the higher levels. Each call frame has the following fields:
| field | type | description |
| ------- | ----------- | ------------------------------------ |
| type | string | CALL or CREATE |
| from | string | address |
| to | string | address |
| value | string | hex-encoded amount of value transfer |
| gas | string | hex-encoded gas provided for call |
| gasUsed | string | hex-encoded gas used during call |
| input | string | call data |
| output | string | return data |
| error | string | error, if any |
| calls | []callframe | list of sub-calls |
| field | type | description |
| ------------ | ----------- | ------------------------------------ |
| type | string | CALL or CREATE |
| from | string | address |
| to | string | address |
| value | string | hex-encoded amount of value transfer |
| gas | string | hex-encoded gas provided for call |
| gasUsed | string | hex-encoded gas used during call |
| input | string | call data |
| output | string | return data |
| error | string | error, if any |
| revertReason | string | Solidity revert reason, if any |
| calls | []callframe | list of sub-calls |
Example Call:
@ -174,7 +179,14 @@ Return:
Things to note about the call tracer:
- Calls to precompiles are also included in the result
- In case a frame reverts, the field `output` will contain the raw return data, unlike [revertReasonTracer](#revertreasontracer) which parses the data and returns the revert message
- In case a frame reverts, the field `output` will contain the raw return data
- In case the top level frame reverts, its `revertReason` field will contain the parsed reason of revert as returned by the Solidity contract
`callTracer` has an option to only trace the main (top-level) call and none of the sub-calls. This avoids extra processing for each call frame if only the top-level call info are required. Here's how it can be configured:
```terminal
> debug.traceTransaction('0xc73e70f6d60e63a71dabf90b9983f2cdd56b0cb7bcf1a205f638d630a95bba73', { tracer: 'callTracer', tracerConfig: { onlyTopCall: true } })
```
### prestateTracer
@ -192,15 +204,7 @@ To run this tracer in `diff` mode, pass `tracerConfig: {diffMode: true}` in the
Example:
```js
debug.traceCall(
{
from: '0x35a9f94af726f07b5162df7e828cc9dc8439e7d0',
to: '0xc8ba32cab1757528daf49033e3673fae77dcf05d',
data: '0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000'
},
'latest',
{ tracer: 'prestateTracer' }
);
debug.traceCall({from: "0x35a9f94af726f07b5162df7e828cc9dc8439e7d0", to: "0xc8ba32cab1757528daf49033e3673fae77dcf05d", data: "0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000"}, 'latest', {tracer: 'prestateTracer'})
```
Return:
@ -249,26 +253,11 @@ Return (same call with `{diffMode: True}`):
}
```
### revertReasonTracer
The `revertReasonTracer` is useful for analyzing failed transactions. If the transaction reverted, the reason for the revert (according to the Solidity contract) is returned. For any other failure, the error message is returned.
Example:
```js
> debug.traceTransaction('0x97695ffb034be7e1faeb372a564bb951ba4ebf4fee4caff2f9d1702497bb2b8b', { tracer: 'revertReasonTracer' })
```
Returns:
```terminal
"execution reverted: tokensMintedPerAddress exceed MAX_TOKENS_MINTED_PER_ADDRESS"
```
### noopTracer
This tracer is noop. It returns an empty object and is only meant for testing the setup.
## Javascript tracers
There are also a set of tracers written in Javascript. These are less performant than the Go native tracers because of overheads associated with interpreting the Javascript in Geth's Go environment.
@ -280,15 +269,7 @@ There are also a set of tracers written in Javascript. These are less performant
Example:
```js
debug.traceCall(
{
from: '0x35a9f94af726f07b5162df7e828cc9dc8439e7d0',
to: '0xc8ba32cab1757528daf49033e3673fae77dcf05d',
data: '0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000'
},
'latest',
{ tracer: 'bigramTracer' }
);
debug.traceCall({from: "0x35a9f94af726f07b5162df7e828cc9dc8439e7d0", to: "0xc8ba32cab1757528daf49033e3673fae77dcf05d", data: "0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000"}, 'latest', {tracer: 'bigramTracer'})
```
Returns:
@ -382,15 +363,7 @@ Returns:
Example:
```js
debug.traceCall(
{
from: '0x35a9f94af726f07b5162df7e828cc9dc8439e7d0',
to: '0xc8ba32cab1757528daf49033e3673fae77dcf05d',
data: '0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000'
},
'latest',
{ tracer: 'opcountTracer' }
);
debug.traceCall({from: "0x35a9f94af726f07b5162df7e828cc9dc8439e7d0", to: "0xc8ba32cab1757528daf49033e3673fae77dcf05d", data: "0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000"}, 'latest', {tracer: 'opcountTracer'})
```
Returns:
@ -400,25 +373,15 @@ Returns:
```
### trigram
`trigramTracer` counts the opcode trigrams. Trigrams are the possible combinations of three opcodes this tracer reports how many times each combination is seen during execution.
Example:
```js
debug.traceCall(
{
from: '0x35a9f94af726f07b5162df7e828cc9dc8439e7d0',
to: '0xc8ba32cab1757528daf49033e3673fae77dcf05d',
data: '0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000'
},
'latest',
{ tracer: 'trigramTracer' }
);
debug.traceCall({from: "0x35a9f94af726f07b5162df7e828cc9dc8439e7d0", to: "0xc8ba32cab1757528daf49033e3673fae77dcf05d", data: "0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000"}, 'latest', {tracer: 'trigramTracer'})
```
Returns:
```terminal
{
--PUSH1: 1,
@ -443,18 +406,17 @@ Returns:
}
```
### unigram
`unigramTracer` counts the frequency of occurrance of each opcode.
Example:
```js
> debug.traceCall({from: "0x35a9f94af726f07b5162df7e828cc9dc8439e7d0", to: "0xc8ba32cab1757528daf49033e3673fae77dcf05d", data: "0xd1a2eab2000000000000000000000000000000000000000000000000000000000024aea100000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000050000000204895cd480cc8412691a880028a25aec86786f1ed2aa5562bc400000000000000c6403c14f35be1da6f433eadbb6e9178a47fbc7c6c1d568d2f2b876e929089c8d8db646304fd001a187dc8a600000000000000000000000000000000"}, 'latest', {tracer: 'unigramTracer'})
```
Returns:
```terminal
{
ADD: 36,
@ -477,9 +439,9 @@ Returns:
## 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 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.
To do this, the tracer is written as normal, but the parameter `stateOverrides` is passed an address and some bytecode.
To do this, the tracer is written as normal, but the parameter `stateOverrides` is passed an address and some bytecode.
```js
var code = //contract bytecode
@ -489,4 +451,4 @@ debug.traceCall({from: , to: , input: }, 'latest', {stateOverrides: {'0x...': {c
## Summary
This page showed how to use the tracers that come bundled with Geth. There are a set written in Go and a set written in Javascript. They are invoked by passing their names when calling an API method.
This page showed how to use the tracers that come bundled with Geth. There are a set written in Go and a set written in Javascript. They are invoked by passing their names when calling an API method. State overrides can be used in combination with tracers to examine precisely what the EVM will do in some hypothetical scenario.

21
docs/developers/evm-tracing/custom-tracer.md
View File

@ -7,7 +7,7 @@ In addition to the default opcode tracer and the built-in tracers, Geth offers t
## Custom Javascript tracing
Transaction traces include the complete status of the EVM at every point during the transaction execution, which can be a very large amount of data. Often, users are only interested in a small subset of that data. Javascript trace filters are available to isolate the useful information. Detailed information about `debug_traceTransaction` and its component parts is available in the [reference documentation](/docs/developers/interacting-with-geth/rpc/ns-debug#debug_tracetransaction).
Transaction traces include the complete status of the EVM at every point during the transaction execution, which can be a very large amount of data. Often, users are only interested in a small subset of that data. Javascript trace filters are available to isolate the useful information. Detailed information about `debug_traceTransaction` and its component parts is available in the [reference documentation](/docs/rpc/ns-debug#debug_tracetransaction).
### A simple filter
@ -29,7 +29,7 @@ Filters are Javascript functions that select information from the trace to persi
}; // tracer = function ...
```
2. Run the [JavaScript console](/docs/interface/javascript-console).
2. Run the [JavaScript console](https://geth.ethereum.org/docs/interface/javascript-console).
3. Get the hash of a recent transaction from a node or block explorer.
4. Run this command to run the script:
@ -60,7 +60,7 @@ Filters are Javascript functions that select information from the trace to persi
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/dapp/tracing), 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](https://geth.ethereum.org/docs/dapp/tracing), 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:
```javascript
{
@ -75,7 +75,8 @@ This object has three member functions:
- `step`, called for each opcode.
- `fault`, called if there is a problem in the execution.
- `result`, called to produce the results that are returned by `debug.traceTransaction` after the execution is done.
- `result`, called to produce the results that are returned by `debug.traceTransaction`
- after the execution is done.
In this case, `retVal` is used to store the list of strings to return in `result`.
@ -304,14 +305,14 @@ The output is similar to:
## Other traces
This tutorial has focused on `debug_traceTransaction()` which reports information about individual transactions. There are also RPC endpoints that provide different information, including tracing the EVM execution within a block, between two blocks, for specific `eth_call`s or rejected blocks. The full list of trace functions can be explored in the [reference documentation](/docs/interacting_with_geth/RPC/ns-debug).
This tutorial has focused on `debug_traceTransaction()` which reports information about individual transactions. There are also RPC endpoints that provide different information, including tracing the EVM execution within a block, between two blocks, for specific `eth_call`s or rejected blocks. The full list of trace functions can be explored in the [reference documentation](/content/docs/interacting_with_geth/RPC/ns-debug.md).
## Custom Go tracing
Custom tracers can also be made more performant by writing them in Go. The gain in performance mostly comes from the fact that Geth doesn't need
to interpret JS code and can execute native functions. Geth comes with several built-in [native tracers](https://github.com/ethereum/go-ethereum/tree/master/eth/tracers/native) which can serve as examples. Please note that unlike JS tracers, Go tracing scripts cannot be simply passed as an argument to the API. They will need to be added to and compiled with the rest of the Geth source code.
In this section a simple native tracer that counts the number of opcodes will be covered. First follow the instructions to [clone and build](/docs/getting_started/Installing-Geth) Geth from source code. Next save the following snippet as a `.go` file and add it to `eth/tracers/native`:
In this section a simple native tracer that counts the number of opcodes will be covered. First follow the instructions to [clone and build](/content/docs/getting_started/Installing-Geth.md) Geth from source code. Next save the following snippet as a `.go` file and add it to `eth/tracers/native`:
```go
package native
@ -339,7 +340,7 @@ type opcounter struct {
reason error // Textual reason for the interruption
}
func newOpcounter(ctx *tracers.Context) tracers.Tracer {
func newOpcounter(ctx *tracers.Context, cfg json.RawMessage) tracers.Tracer {
return &opcounter{counts: make(map[string]int)}
}
@ -397,7 +398,9 @@ func (t *opcounter) Stop(err error) {
}
```
Every method of the [EVMLogger interface](https://pkg.go.dev/github.com/ethereum/go-ethereum/core/vm#EVMLogger) needs to be implemented (even if empty). Key parts to notice are the `init()` function which registers the tracer in Geth, the `CaptureState` hook where the opcode counts are incremented and `GetResult` where the result is serialized and delivered. To test this, the source is first compiled with `make geth`. Then in the console it can be invoked through the usual API methods by passing in the name it was registered under:
Every method of the [EVMLogger interface](https://pkg.go.dev/github.com/ethereum/go-ethereum/core/vm#EVMLogger) needs to be implemented (even if empty). Key parts to notice are the `init()` function which registers the tracer in Geth, the `CaptureState` hook where the opcode counts are incremented and `GetResult` where the result is serialized and delivered. Note that the constructor takes in a `cfg json.RawMessage`. This will be filled with a JSON object that user provides to the tracer to pass in optional config fields.
To test out this tracer the source is first compiled with `make geth`. Then in the console it can be invoked through the usual API methods by passing in the name it was registered under:
```console
> debug.traceTransaction('0x7ae446a7897c056023a8104d254237a8d97783a92900a7b0f7db668a9432f384', { tracer: 'opcounter' })
@ -411,4 +414,4 @@ Every method of the [EVMLogger interface](https://pkg.go.dev/github.com/ethereum
## Summary
This page described how to write custom tracers for Geth. Custom tracers can be written in Javascript or Go.
This page described how to write custom tracers for Geth. Custom tracers can be written in Javascript or Go.

57
docs/developers/evm-tracing/index.md
View File

@ -3,13 +3,6 @@ title: EVM Tracing
description: Introduction to tracing EVM transactions using Geth
---
---
title: EVM Tracing
sort-key: A
---
Tracing allows users to examine precisely what was executed by the EVM during some specific transaction or set of transactions. There are two different types of [transactions](https://ethereum.org/en/developers/docs/transactions) in Ethereum: value transfers and contract executions. A value transfer just moves ETH from one account to another. A contract interaction executes some code stored at a contract address which can include altering stored data and transacting multiple times with other contracts and externally-owned accounts. A contract execution transaction can therefore be a complicated web of interactions that can be difficult to unpick. The transaction receipt contains a status code that shows whether the transaction succeeded or failed, but more detailed information is not readily available, meaning it is very difficult to know what a contract execution actually did, what data was modified and which addresses were touched. This is the problem that EVM tracing solves. Geth traces transactions by re-running them locally and collecting data about precisely what was executed by the EVM.
Also see this [Devcon 2022 talk](https://www.youtube.com/watch?v=b8RdmGsilfU) on tracing in Geth.
@ -18,53 +11,63 @@ Also see this [Devcon 2022 talk](https://www.youtube.com/watch?v=b8RdmGsilfU) on
In its simplest form, tracing a transaction entails requesting the Ethereum node to reexecute the desired transaction with varying degrees of data collection and have it return an aggregated summary. In order for a Geth node to reexecute a transaction, all historical state accessed by the transaction must be available. This includes:
- Balance, nonce, bytecode and storage of both the recipient as well as all internally invoked contracts.
- Block metadata referenced during execution of both the outer as well as all internally created transactions.
- Intermediate state generated by all preceding transactions contained in the same block as the one being traced.
- Balance, nonce, bytecode and storage of both the recipient as well as all
internally invoked contracts.
- Block metadata referenced during execution of both the outer as well as all
internally created transactions.
- Intermediate state generated by all preceding transactions contained in the
same block as the one being traced.
This means there are limits on the transactions that can be traced imposed by the synchronization and pruning configuration of a node:
- An **archive** node retains **all historical data** back to genesis. It can therefore trace arbitrary transactions at any point in the history of the chain. Tracing a single transaction requires reexecuting all preceding transactions in the same block.
- A **node synced from genesis** node only retains the most recent 128 block states in memory. Older states are represented by a sequence of occasional checkpoints that intermediate states can be regenerated from. This means that states within the msot recent 128 blocks are immediately available, older states have to be regenerated from snapshots "on-the-fly". If the distance between the requested transaction and the most recent checkpoint is large, rebuilding the state can take a long time. Tracing a single transaction requires reexecuting all preceding transactions in the same block **and** all preceding blocks until the previous stored snapshot.
- A **node synced from genesis** node only retains the most recent 128 block states in memory. Older states are represented by a sequence of occasional checkpoints that intermediate states can be regenerated from. This means that states within the most recent 128 blocks are immediately available, older states have to be regenerated from snapshots "on-the-fly". If the distance between the requested transaction and the most recent checkpoint is large, rebuilding the state can take a long time. Tracing a single transaction requires reexecuting all preceding transactions in the same block **and** all preceding blocks until the previous stored snapshot.
- A **snap synced** 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.
- A **snap synced** 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.
- A **light synced** node retrieving data **on demand** can in theory trace transactions for which all required historical state is readily available in the network. This is because the data required to generate the trace is requested from an les-serving full node. In practice, data
availability **cannot** be reasonably assumed.
- A **light synced** node retrieving data **on demand** can in theory trace transactions for which all required historical state is readily available in the network. This is because the data required to generate the trace is requested from an les-serving full node. In practice, data availability **cannot** be reasonably assumed.
![state pruning options](/public/images/state-pruning.png)
![state pruning options](/public/images/docs/state-pruning.png)
*This image shows the state stored by each sync-mode - red indicates stored state. The full width of each line represents origin to present head*
_This image shows the state stored by each sync-mode - red indicates stored state. The full width of each line represents origin to present head_
More detailed information about syncing is available on the [sync modes page](/docs/interface/sync-modes).
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 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.
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`.
It is also possible to force Geth to store the state for specific sequences of block by stopping Geth, running again with `--gcmode archive` for some period - this prevents state prunign for blocks that arrive while Geth is running with `--gcmode archive`.
It is also possible to force Geth to store the state for specific sequences of block by stopping Geth, running again with `--gcmode archive` for some period - this prevents state pruning for blocks that arrive while Geth is running with `--gcmode archive`.
_There are exceptions to the above rules when running batch traces of entire blocks or chain segments. Those will be detailed later._
## Types of trace
### Basic traces
The simplest type of transaction trace that Geth can generate are raw EVM opcode traces. For every EVM instruction the transaction executes, a structured log entry is emitted, containing all contextual metadata deemed useful. This includes the *program counter*, *opcode name*, *opcode cost*, *remaining gas*, *execution depth* and any *occurred error*. The structured logs can optionally also contain the content of the *execution stack*, *execution memory* and *contract storage*.
Read more about Geth's basic traces on the [basic traces page](/docs/evm-tracing/basic-traces).
### 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 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
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 Geth's built-in tracers is available on the [built-in tracers](/docs/evm-tracing/builtin-tracers) page.
### Custom tracers
In addition to built-in tracers, it is possible to provide custom code that hooks to events in the EVM to process and return data in a consumable format. Custom tracers can be written either in Javascript or Go. JS tracers are good for quick prototyping and experimentation as well as for less intensive applications. Go tracers are performant but require the tracer to be compiled together with the Geth source code. This means developers only have to gather the data they actually need, and do any processing at the source.
More information about custom tracers is available on the [custom tracers](/docs/developers/evm-tracing/custom-tracers) page.
More information about custom tracers is available on the [custom tracers](/docs/evm-tracing/custom-tracer) page.
## Summary
This page gave an introduction to the concept of tracing and explained issues around state availability. More detailed information on Geth's built-in and custom tracers can be found on their dedicated pages. on their dedicated pages.
This page gave an introduction to the concept of tracing and explained issues around state availability. More detailed information on Geth's built-in and custom tracers can be found on their dedicated pages.

6
docs/fundamentals/account-management.md
View File

@ -3,7 +3,7 @@ title: Account Management with Clef
description: Guide to basic account management using Geth's built-in tools
---
Geth uses an external signer called [Clef](/docs/clef/introduction) to manage accounts. This is a standalone pieve of software that runs independently of, but connects to, a Geth instance. Clef handles account creation, key management and signing transactions/data. This page explains how to use Clef to create and manage accounts for use with Geth. More information about Clef, including advanced setup options, are available in our dedicated Clef docs.
Geth uses an external signer called [Clef](/docs/clef/introduction) to manage accounts. This is a standalone piece of software that runs independently of - but connects to - a Geth instance. Clef handles account creation, key management and signing transactions/data. This page explains how to use Clef to create and manage accounts for use with Geth. More information about Clef, including advanced setup options, are available in our dedicated Clef docs.
## Initialize Clef
@ -108,7 +108,7 @@ Make sure to backup keystore and passwords in a safe location.
The accounts in the keystore can be listed to the terminal using a simple CLI command as follows:
```
```sh
clef list-accounts --keystore <path-to-keystore>
```
@ -130,7 +130,7 @@ Accounts can also be listed in the Javascript console using `eth.accounts`, whic
As well as individual account, any wallets managed by Clef can be listed (which will also print the wallet status and the address and URl of any accounts they contain. This uses the `list-wallets` CLI command.
```
```sh
clef list-wallets --keystore <path-to-keystore>
```

4
docs/fundamentals/security.md
View File

@ -19,9 +19,7 @@ The local machine's firewall settings should:
Account security comes down to keeping private keys and account passwords backed up and inaccessible to adversaries. This is something that users take responsibility for. Geth provides an encrypted store for keys that are unlocked using an account password. If the key files or the passwors are lost, the account is impossible to access and the funds are effectively lost forever. If access to the unencrypted keys is obtained by an adversary they gain control of any funds associated with the account.
Geth has built-in account management tools that are sufficiently secure for most purposes. However, Clef is recommended as an external account management and signing tool. It can be run decoupled from Geth and can even be run on dedicated secure external hardware such as a VM or a secure USB drive. This is considered best practise because the user is required to manually review all actions that touch sensitive data, except where specific predefined rules are implemented. Signing is done locally to Clef rather than giving key access to a node.
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.
Geth has built-in account management tools. However, Clef is recommended as an external account management and signing tool. It can be run decoupled from Geth and can even be run on dedicated secure external hardware such as a VM or a secure USB drive. This is considered best practise because the user is required to manually review all actions that touch sensitive data, except where specific predefined rules are implemented. Signing is done locally to Clef rather than giving key access to a node. Geth's built-in management tools are intended to be deprecated in the near future.
**Back up your keystore and passwords safely and securely!**

19
docs/fundamentals/sync-modes.md
View File

@ -11,9 +11,14 @@ There are two types of full node that use different mechanisms to sync up to the
### Snap (default)
A snap sync'd node holds the most recent 128 block states in memory, so transactions in that range are always quickly accessible. However, snap-sync only starts processing from a relatively recent block (as opposed to genesis for a full node). Between the initial sync block and the 128 most recent blocks, the node stores occasional checkpoints that can be used to rebuild the state on-the-fly. This means transactions can be traced back as far as the block that was used for the initial sync. Tracing a single transaction requires reexecuting all preceding transactions in the same block **and** all preceding blocks until the previous stored snapshot. Snap-sync'd nodes are therefore full nodes, with the only difference being the initial synchronization required a checkpoint block to sync from instead of independently verifying the chain all the way from genesis. Snap sync then only verifies the proof-of-work and ancestor-child block progression and assumes that the state transitions are correct rather than re-executing the transactions in each block to verify the state changes. Snap sync is much faster than block-by-block sync. To start a node with snap sync pass `--syncmode snap` at startup.
Snap sync starts froma relatively recent block and syncs from there to the head of the chain, keeping only the most recent 128 block states in memory. The block header to sync up to is provided by the consensus client. Between the initial sync block and the 128 most recent blocks, the node stores occasional snapshots that can be used to rebuild any intermediate state "on-the-fly". The difference between the snap-synced node and a full block-by-block synced node is that a snap synced node started from an initial checkpoint that was more recent than the genesis block. Snap sync is much faster than a full block-by-block sync from genesis. To start a node with snap sync pass `--syncmode snap` at startup.
Snap sync starts by downloading the headers for a chunk of blocks. Once the headers have been verified, the block bodies and receipts for those blocks are downloaded. In parallel, Geth also sync begins state-sync. In state-sync, Geth first downloads the leaves of the state trie for each block without the intermediate nodes along with a range proof. The state trie is then regenerated locally. The state download is the part of the snap-sync that takes the most time to complete and the progress can be monitored using the ETA values in the log messages. However, the blockchain is also progressing at the same time and invalidating some of the regenerated state data. This means it is also necessary to have a 'healing' phase where errors in the state are fixed. It is not possible to monitor the progress of the state heal because the extent of the errors cannot be known until the current state has already been regenerated. Geth regularly reports `Syncing, state heal in progress` regularly during state heal - this informs the user that state heal has not finished. It is also possible to confirm this using `eth.syncing` - if this command returns `false` then the node is in sync. If it returns anything other than `false` then syncing is still in progress.
![state pruning options](/public/images/docs/state-pruning.png)
_This image shows the state stored by each sync-mode - red indicates stored state. The full width of each line represents origin to present head_
Snap sync works by first downloading the headers for a chunk of blocks. Once the headers have been verified, the block bodies and receipts for those blocks are downloaded. In parallel, Geth also sync begins state-sync. In state-sync, Geth first downloads the leaves of the state trie for each block without the intermediate nodes along with a range proof. The state trie is then regenerated locally.
The state download is the part of the snap-sync that takes the most time to complete and the progress can be monitored using the ETA values in the log messages. However, the blockchain is also progressing at the same time and invalidating some of the regenerated state data. This means it is also necessary to have a 'healing' phase where errors in the state are fixed. It is not possible to monitor the progress of the state heal because the extent of the errors cannot be known until the current state has already been regenerated. Geth regularly reports `Syncing, state heal in progress` during state healing - this informs the user that state heal has not finished. It is also possible to confirm this using `eth.syncing` - if this command returns `false` then the node is in sync. If it returns anything other than `false` then syncing is still in progress.
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).
@ -27,7 +32,7 @@ To summarize, snap sync progresses in the following sequence:
### Full
A full sync generates the current state by executing every block starting from the genesis block. A full sync indendently verifies proof-of-work and block provenance as well as all state transitions by re-executing the transactions in the entire historical sequence of blocks. Only the most recent 128 block states are stored in a full node - older block states are pruned periodically and represented as a series of checkpoints from which any previous state can be regenerated on request. 128 blocks is about 25.6 minutes of history with a block time of 12 seconds.
A full blobk-by-block sync generates the current state by executing every block starting from the genesis block. A full sync indendently verifies block provenance as well as all state transitions by re-executing the transactions in the entire historical sequence of blocks. Only the most recent 128 block states are stored in a full node - older block states are pruned periodically and represented as a series of checkpoints from which any previous state can be regenerated on request. 128 blocks is about 25.6 minutes of history with a block time of 12 seconds.
To create a full node pass `--syncmode full` at startup.
@ -49,7 +54,7 @@ The following diagram shows how Geth stores state data in the different sync mod
## Consensus layer syncing
Now that Ethereum has switched to proof-of-stake, all consensus logic and block propagation is handled by consensus clients. This means that syncing the blockchain is a process shared between the consensus and execution clients. Blocks are downloaded by the consensus client and verified by the execution client. In order for Geth to sync, it requires a header from its connected consensus client. Geth does not import any data until it is instructed to by the consensus client. **Geth cannot sync without being connected to a consensus client**. This includes block-by-block syncing from genesis.
Now that Ethereum has switched to proof-of-stake, all consensus logic and block propagation is handled by consensus clients. This means that syncing the blockchain is a process shared between the consensus and execution clients. Blocks are downloaded by the consensus client and verified by the execution client. In order for Geth to sync, it requires a header from its connected consensus client. Geth does not import any data until it is instructed to by the consensus client. **Geth cannot sync without being connected to a consensus client**. This includes block-by-block syncing from genesis. The consensus client is required to provide a header from the tip of the chain that Geth can sync towards - without it, Geth cannot know that it has followed the right sequence of blocks.
Once a header is available to use as a syncing target, Geth retrieves all headers between that target header and the local header chain in reverse chronological order. These headers show that the sequence of blocks is correct because the parenthashes link one block to the next right up to the target block. Eventually, the sync will reach a block held in the local database, at which point the local data and the target data are considered 'linked' and there is a very high chance the node is syncing the correct chain. The block bodies are then downloaded and then the state data. The consensus client can update the target header - as long as the syncing outpaces the growth of the blockchain then the node will eventually get in sync.
@ -63,10 +68,10 @@ Read more in the [optimistic sync specs](https://github.com/ethereum/consensus-s
### 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](https://eth-clients.github.io/checkpoint-sync-endpoints/).
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](https://eth-clients.github.io/checkpoint-sync-endpoints/). Checkpoint sync is very fast - a consensus cleint should be able to sync in a few minutes using this method.
Please see the pages on [syncing](/docs/interface/sync-modes) for more detail. For troubleshooting, please see the `Syncing` section on the [console log messages](/docs/interface/logs) page.
For troubleshooting, please see the `Syncing` section on the [console log messages](/docs/interface/logs) page.
## 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 using some recent block that is old enough to be safe from re-orgs as a sync target. A trust-minimized alternative is full-sync, which verifies every block since genesis. These modes drop state data older than 128 blocks, keeping only checkpoints that enable on-request regeneration of historical states. For rapid queries of historical data an archive node is required. Archive nodes keep local copies of all historical data right back to genesis - currently about 12 TB and growing. The opposite extreme is a light node that doesn't store any blockchain data - it requests everything from full nodes. These configurations are controlled by passing `full`, `snap` or `light` to `--syncmode` at startup. For an archive node, `--syncmode` should be `full` and `--gcmode` should be set to `archive`. Currently, due to the transition to proof-of-stake, light-sync does not work (new light client protocols are being developed).
There are several ways to sync a Geth node. The default is to use snap sync to create a full node. Full nodes can be created by syncing block-by-block from genesis (full-sync) or by starting at an intermediate checkpoint block (snap-sync). By default, these modes prune state data older than 128 blocks, keeping only checkpoints that enable on-request regeneration of historical states. For rapid queries of historical data an archive node is required. Archive nodes keep local copies of all historical data right back to genesis - currently about 12 TB and growing. Partial archive nodes can be created by snap-syncign a node and turning off state-pruning to create a node that keeps all states since the initial sync block. Currently, due to the transition to proof-of-stake, light-sync does not work (new light client protocols are being developed).

73
docs/getting-started/getting-started-with-clef.md
View File

@ -1,11 +1,13 @@
---
title: Geth and Clef
description: Guide to getting up and running with Geth using Clef as an external account management and signing tool.
title: Getting started with Geth
description: Guide to getting up and running with Geth using Clef.
---
This page explains how to set up Geth and execute some basic tasks using the command line tools. In order to use Geth, the software must first be installed. There are several ways Geth can be installed depending on the operating system and the user's choice of installation method, for example using a package manager, container or building from source. Instructions for installing Geth can be found on the ["Install and Build"](/docs/getting_started/Installing-Geth) pages. Geth also needs to be connected to a consensus client in order to function as an Ethereum node. The tutorial on this page assumes Geth and a consensus client have been installed successfully and that a firewall has been configured to block external traffic to the JSON-RPC port `8545` see [Security](/content/docs/fundamentals/security).
This page explains how to set up Geth and execute some basic tasks using the command line tools. In order to use Geth, the software must first be installed. There are several ways Geth can be installed depending on the operating system and the user's choice of installation method, for example using a package manager, container or building from source. Instructions for installing Geth can be found on the ["Install and Build"](/docs/getting_started/Installing-Geth) pages.
This page provides step-by-step instructions covering the fundamentals of using Geth. This includes generating accounts, joining an Ethereum network, syncing the blockchain and sending ether between accounts. This tutorial uses [Clef](/docs/tools/Clef/Tutorial). Clef is an account management tool external to Geth itself that allows users to sign transactions. It is developed and maintained by the Geth team and is intended to eventually replace the account management tool built in to Geth.
Geth also needs to be connected to a [consensus client](docs/getting-started/consensus-clients.md) in order to function as an Ethereum node. The tutorial on this page assumes Geth and a consensus client have been installed successfully and that a firewall has been configured to block external traffic to the JSON-RPC port `8545` see [Security](/docs/fundamentals/security).
This page provides step-by-step instructions covering the fundamentals of using Geth. This includes generating accounts, joining an Ethereum network, syncing the blockchain and sending ether between accounts. This tutorial uses [Clef](/docs/tools/Clef/Tutorial). Clef is an account management tool external to Geth itself that allows users to sign transactions. It is developed and maintained by the Geth team.
## Prerequisites
@ -25,8 +27,7 @@ consensus client is [here](/docs/getting_started/consensus-clients).
Geth is an Ethereum client written in Go. This means running Geth turns a computer into an Ethereum node. Ethereum is a peer-to-peer network where information is shared directly between nodes rather than being managed by a central server. Every 12 seconds one node is randomly selected to generate a new block containing a list of transactions that nodes receiving the block should execute. This "block proposer" node sends the new block to its peers. On receiving a new block, each node checks that it is valid and adds it to their database. The sequence of discrete blocks is called a "blockchain".
The information provided in each block is used by Geth to update its "state" - the ether balance of each account on Ethereum and the data stored by each smart contract. There are two types of account: externally-owned accounts (EOAs) and contract accounts. Contract accounts execute contract code when they receive transactions. EOAs are accounts that users manage locally in order to sign and submit transactions. Each EOA is a public-private key pair, where the public key is used to derive a unique address for the user and the private key is used to protect the account and securely sign messages. Therefore, in order to use Ethereum,
it is first necessary to generate an EOA (hereafter, "account"). This tutorial will guide the user through creating an account, funding it with ether and sending some to another address.
The information provided in each block is used by Geth to update its "state" - the ether balance of each account on Ethereum and the data stored by each smart contract. There are two types of account: externally-owned accounts (EOAs) and contract accounts. Contract accounts execute contract code when they receive transactions. EOAs are accounts that users manage locally in order to sign and submit transactions. Each EOA is a public-private key pair, where the public key is used to derive a unique address for the user and the private key is used to protect the account and securely sign messages. Therefore, in order to use Ethereum, it is first necessary to generate an EOA (hereafter, "account"). This tutorial will guide the user through creating an account, funding it with ether and sending some to another address.
Read more about Ethereum accounts [here](https://ethereum.org/en/developers/docs/accounts/).
@ -79,10 +80,10 @@ It is important to save the account address and the password somewhere secure. T
The previous commands used Clef's `newaccount` function to add new key pairs to the keystore. Clef uses the private key(s) saved in the keystore is used to sign transactions. In order to do this, Clef needs to be started and left running while Geth is running simultaneously, so that the two programs can communicate between one another.
To start Clef, run the Clef executable passing as arguments the keystore file location, config directory location and a chain ID. The config directory was automatically created inside the `geth-tutorial` directory during the previous step. The [chain ID](https://chainlist.org/) is an integer that defines which Ethereum network to connect to. Ethereum mainnet has chain ID 1. In this tutorial Chain ID 5 is used which is that of the Goerli testnet. It is very important that this chain ID parameter is set to 5. The following command starts Clef on Goerli:
To start Clef, run the Clef executable passing as arguments the keystore file location, config directory location and a chain ID. The config directory was automatically created inside the `geth-tutorial` directory during the previous step. The [chain ID](https://chainlist.org/) is an integer that defines which Ethereum network to connect to. Ethereum mainnet has chain ID 1. In this tutorial Chain ID 11155111 is used which is that of the Sepolia testnet. It is very important that this chain ID parameter is set to 11155111 - Clef uses the chain ID to sign messages so it must be correct. The following command starts Clef on Sepolia:
```shell
clef --keystore geth-tutorial/keystore --configdir geth-tutorial/clef --chainid 5
clef --keystore geth-tutorial/keystore --configdir geth-tutorial/clef --chainid 11155111
```
After running the command above, Clef requests the user to type “ok” to proceed. On typing "ok" and pressing enter, Clef returns the following to the terminal:
@ -110,25 +111,26 @@ This result indicates that Clef is running. This terminal should be left running
## Step 3: Start Geth
Geth is the Ethereum client that will connect the computer to the Ethereum network. In this tutorial the network is Goerli, an Ethereum testnet. Testnets are used to test Ethereum client software and smart contracts in an environment where no real-world value is at risk. To start Geth, run the Geth executable file passing argument that define the data directory (where Geth should save blockchain data), signer (points Geth to Clef), the network ID and the sync mode. For this tutorial, snap sync is recommended (see [here](https://blog.ethereum.org/2021/03/03/geth-v1-10-0/) for reasons why). The final argument passed to Geth is the `--http` flag. This enables the http-rpc server that allows external programs to interact with Geth by sending it http requests. By default the http server is only exposed locally using port 8545: `localhost:8545`.
Geth is the Ethereum client that will connect the computer to the Ethereum network. In this tutorial the network is Sepolia, an Ethereum testnet. Testnets are used to test Ethereum client software and smart contracts in an environment where no real-world value is at risk. To start Geth, run the Geth executable file passing argument that define the data directory (where Geth should save blockchain data), signer (points Geth to Clef), the network ID and the sync mode. For this tutorial, snap sync is recommended (see [here](https://blog.ethereum.org/2021/03/03/geth-v1-10-0/) for reasons why). The final argument passed to Geth is the `--http` flag. This enables the http-rpc server that allows external programs to interact with Geth by sending it http requests. By default the http server is only exposed locally using port 8545: `localhost:8545`. It is also necessary to authorize some traffic for the consensus client which is done using `--authrpc` and also to set up a JWT secret token in a known location, using `--jwt-secret`.
The following command should be run in a new terminal, separate to the one running Clef:
```shell
geth --datadir geth-tutorial --signer=geth-tutorial/clef/clef.ipc --goerli --syncmode snap --http
geth --sepolia --datadir geth-tutorial --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --authrpc.jwtsecret geth-tutorial/jwtsecret --http --http.api eth,net --signer=geth-tutorial/clef/clef.ipc --http
```
Running the above command starts Geth. The terminal should rapidly fill with status updates, starting with:
Running the above command starts Geth. Geth will not sync the blockchain correctly unless there is also a consensus client that can pass Geth a valid head to sync up to. In a separate terminal, start a consensus client. Once the consensus client gets in sync, Geth will start to sync too.
The terminal should rapidly fill with status updates that look similar to those below. To check the meaning of the logs, refer to the [logs page](docs/fundamentals/logs.md).
```terminal
INFO [02-10|13:59:06.649] Starting Geth on goerli testnet...
INFO [02-10|13:59:06.649] Dropping default light client cache provided=1024 updated=128
INFO [02-10|13:59:06.649] Starting Geth on sepolia testnet...
INFO [02-10|13:59:06.652] Maximum peer count ETH=50 LES=0 total=50
INFO [02-10|13:59:06.655] Using external signer url=geth-tutorial/clef/clef.ipc
INFO [02-10|13:59:06.660] Set global gas cap cap=50,000,000
INFO [02-10|13:59:06.661] Allocated cache and file handles database=/.../geth-tutorial/geth/chaindata cache=64.00MiB handles=5120
INFO [02-10|13:59:06.855] Persisted trie from memory database nodes=361 size=51.17KiB time="643.54µs" gcnodes=0 gcsize=0.00B gctime=0s livenodes=1 livesize=0.00B
INFO [02-10|13:59:06.855] Initialised chain configuration config="{ChainID: 5 Homestead: 0 DAO: nil DAOSupport: true EIP150: 0 EIP155: 0 EIP158: 0 Byzantium: 0 Constantinople: 0 Petersburg: 0 Istanbul: 1561651, Muir Glacier: nil, Berlin: 4460644, London: 5062605, Arrow Glacier: nil, MergeFork: nil, Engine: clique}"
INFO [02-10|13:59:06.855] Initialised chain configuration config="{ChainID: 11155111 Homestead: 0 DAO: nil DAOSupport: true EIP150: 0 EIP155: 0 EIP158: 0 Byzantium: 0 Constantinople: 0 Petersburg: 0 Istanbul: 1561651, Muir Glacier: nil, Berlin: 4460644, London: 5062605, Arrow Glacier: nil, MergeFork: nil, Engine: clique}"
INFO [02-10|13:59:06.862] Added trusted checkpoint block=5,799,935 hash=2de018..c32427
INFO [02-10|13:59:06.863] Loaded most recent local header number=6,340,934 hash=483cf5..858315 td=9,321,576 age=2d9h29m
INFO [02-10|13:59:06.867] Configured checkpoint oracle address=0x18CA0E045F0D772a851BC7e48357Bcaab0a0795D signers=5 threshold=2
@ -139,12 +141,9 @@ INFO [02-10|13:59:06.995] New local node record seq=1,644,272
INFO [02-10|13:59:06.996] Started P2P networking self=enode://4b80ebd341b5308f7a6b61d91aa0ea31bd5fc9e0a6a5483e59fd4ea84e0646b13ecd289e31e00821ccedece0bf4b9189c474371af7393093138f546ac23ef93e@127.0.0.1:30303
INFO [02-10|13:59:06.997] IPC endpoint opened url=/.../geth-tutorial/geth.ipc
INFO [02-10|13:59:06.998] HTTP server started endpoint=127.0.0.1:8545 prefix= cors= vhosts=localhost
WARN [02-10|13:59:06.998] Light client mode is an experimental feature
WARN [02-10|13:59:06.999] Failed to open wallet url=extapi://geth-tutorial/clef/cle.. err="operation not supported on external signers"
INFO [02-10|13:59:08.793] Block synchronisation started
```
This indicates that Geth has started up and is searching for peers to connect to. Once it finds peers it can request block headers from them, starting at the genesis block for the Goerli blockchain. Geth continues to download blocks sequentially, saving the data in files in `/go-ethereum/geth-tutorial/geth/chaindata/`. This is confirmed by the logs printed to the terminal. There should be a rapidly-growing sequence of logs in the terminal with the following syntax:
By default, Geth uses snap-sync which download blocks sequentially from a relatively recent block, not the genesis block. It saves the data in files in `/go-ethereum/geth-tutorial/geth/chaindata/`. One the sequence of headers has been verified, Geth downloads the block bodies and state data before starting the "state healing" phase to update the state for newly arriving data. This is confirmed by the logs printed to the terminal. There should be a rapidly-growing sequence of logs in the terminal with the following syntax:
```terminal
INFO [04-29][15:54:09.238] Looking for peers peercount=2 tried=0 static=0
@ -152,21 +151,27 @@ INFO [04-29][15:54:19.393] Imported new block headers count=2 elapsed=1.127ms
INFO [04-29][15:54:19:656] Imported new block receipts count=698 elapsed=4.464ms number=994566 hash=56dc44..007c93 age=13h9m9s
```
These logs indicate that Geth is running as expected. Sending an empty Curl request to the http server provides a quick way to confirm that this too has been started without any issues. In a third terminal, the following command can be run:
This message will be displayed periodically until state healing has finished:
```
INFO [10-20|20:20:09.510] State heal in progress accounts=313,309@17.95MiB slots=363,525@28.77MiB codes=7222@50.73MiB nodes=49,616,912@12.67GiB pending=29805
```
When state healing is finished, the node is in sync and ready to use.
Sending an empty Curl request to the http server provides a quick way to confirm that this too has been started without any issues. In a third terminal, the following command can be run:
```shell
curl http://localhost:8545
```
If there is no error message reported to the terminal, everything is OK. Geth must be running in order for a user to interact with the Ethereum network. If this terminal is closed down then Geth must be restarted in a new terminal. Geth can be started and stopped easily, but it must be running for any interaction with Ethereum to take place. To shut down Geth, simply press `CTRL+C` in the Geth terminal. To start it again, run the previous command `geth --datadir <other commands>`.
If there is no error message reported to the terminal, everything is OK. Geth must be running and synced in order for a user to interact with the Ethereum network. If the terminal running Geth is closed down then Geth must be restarted again in a new terminal. Geth can be started and stopped easily, but it must be running for any interaction with Ethereum to take place. To shut down Geth, simply press `CTRL+C` in the Geth terminal. To start it again, run the previous command `geth --datadir <other commands>`.
{% include note.html content="Snap syncing Goerli will take some time and until the sync is finished you can't use the node to transfer funds. You can also try doing a [light sync](interface/les) which will be much quicker but depends on light servers being available to serve your node the data it needs." %}
## Step 4: Get Testnet Ether
In order to make some transactions, the user must fund their account with ether. On Ethereum mainnet, ether can only be obtained in three ways: 1) by receiving it as a reward for mining/validating; 2) receiving it in a transfer from another Ethereum user or contract; 3) receiving it from an exchange, 3) having paid for it with fiat money. On Ethereum testnets, the ether has no real world value so it 4) can be made freely available via faucets. Faucets allow users to request a transfer of testnet ether to their account.
The address generated by Clef in Step 1 can be pasted into the Paradigm Multifaucet faucet [here](https://fauceth.komputing.org/?chain=1115511). This requires a Twitter login as proof of personhood. The faucets adds ether to the given address on multiple testnets simultaneously, including Goerli. In the next steps Geth will be used to check that the ether has been sent to the given address and send some of it to the second address created earlier.
The address generated by Clef in Step 1 can be pasted into the Paradigm Multifaucet faucet [here](https://faucet.sepolia.dev/). The faucets adds Sepolia ETH (not real ETH) to the given address. In the next steps Geth will be used to check that the ether has been sent to the given address and send some of it to the second address created earlier.
## Step 5: Interact with Geth
@ -197,7 +202,7 @@ at block: 6354736 (Thu Feb 10 2022 14:01:46 GMT+0100 (WAT))
To exit, press ctrl-d or type exit
```
The console is now active and connected to Geth. It can now be used to interact with the Ethereum (Goerli) network.
The console is now active and connected to Geth. It can now be used to interact with the Ethereum (Sepolia) network.
### List of accounts
@ -234,23 +239,23 @@ Entering `y` approves the request from the console. In the terminal running the
["0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec", "0xce8dba5e4157c2b284d8853afeeea259344c1653"]
```
It is also possible for this request to time out if the Clef approval took too long - in this case simply repeat the request and approval.
It is also possible for this request to time out if the Clef approval took too long - in this case simply repeat the request and approval. Accoutns can also be listed directly from Clef by opening a new terminal and running `clef list-accounts --keystore <path-to-keystore>`.
### Checking account balance.
Having confirmed that the two addresses created earlier are indeed in the keystore and accessible through the Javascript console, it is possible to retrieve information about how much ether they own. The Goerli faucet should have sent 1 ETH to the address provided, meaning that the balance of one of the accounts should be 1 ether and the other should be 0. The following command displays the account balance in the console:
Having confirmed that the two addresses created earlier are indeed in the keystore and accessible through the Javascript console, it is possible to retrieve information about how much ether they own. The Sepolia faucet should have sent 0.05 ETH to the address provided, meaning that the balance of one of the accounts should be at least 0.05 ether and the other should be 0. There are other faucets available that may dispense more ETH per request, and multipel requests can be made to accumulate more ETH. The following command displays the account balance in the console:
```javascript
web3.fromWei(eth.getBalance('0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC'), 'ether');
```
There are actually two instructions sent in the above command. The inner one is the `getBalance` function from the `eth` namespace. This takes the account address as its only argument. By default, this returns the account balance in units of Wei. There are 10<sup>18</sup> Wei to one ether. To present the result in units of ether, `getBalance` is wrapped in the `fromWei` function from the `web3` namespace. Running this command should provide the following result (for the account that received faucet funds):
There are actually two instructions sent in the above command. The inner one is the `getBalance` function from the `eth` namespace. This takes the account address as its only argument. By default, this returns the account balance in units of Wei. There are 10<sup>18</sup> Wei to one ether. To present the result in units of ether, `getBalance` is wrapped in the `fromWei` function from the `web3` namespace. Running this command should provide the following result, assuming the account balance is 1 ETH:
```terminal
1
```
Repeating the command for the other account should yield:
Repeating the command for the other (empty) account should yield:
```terminal
0
@ -292,7 +297,6 @@ Additional HTTP header data, provided by the external caller:
Approve? [y/N]:
Please enter the password for account 0xca57F3b40B42FCce3c37B8D18aDBca5260ca72EC
```
After approving the transaction, the following confirmation screen in displayed in the Clef terminal:
@ -313,7 +317,7 @@ Transaction signed:
"r": "0x66e5d23ad156e04363e68b986d3a09e879f7fe6c84993cef800bc3b7ba8af072",
"s": "0x647ff82be943ea4738600c831c4a19879f212eb77e32896c05055174045da1bc",
"to": "0xce8dba5e4157c2b284d8853afeeea259344c1653",
"chainId": "0x5",
"chainId": "0xaa36a7",
"accessList": [],
"hash": "0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb"
}
@ -325,11 +329,11 @@ In the Javascript console, the transaction hash is displayed. This will be used
"0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb"
```
It is also advised to check the account balances using Geth by repeating the instructions from earlier. At this point in the tutorial, the two accounts in the Clef keystore should have balances just below 0.9 ether (because 0.1 ether has been transferred out and some small amount paid in transaction gas) and 0.1 ether.
It is also advised to check the account balances using Geth by repeating the instructions from earlier. At this point in the tutorial, the balances of the two accounts in the Clef keystore should have changed by ~0.1 ETH (the sender's balance will have decremented by a little over 0.1 ETH because some small was amount paid in transaction gas).
### Checking the transaction hash
The transaction hash is a unique identifier for this specific transaction that can be used later to retrieve the transaction details. For example, the transaction details can be viewed by pasting this hash into the [Goerli block explorer](https://goerli.etherscan.io/). The same information can also be retrieved directly from the Geth node. The hash returned in the previous step can be provided as an argument to `eth.getTransaction` to return the transaction information:
The transaction hash is a unique identifier for this specific transaction that can be used later to retrieve the transaction details. For example, the transaction details can be viewed by pasting this hash into the [Sepolia block explorer](https://sepolia.etherscan.io/). The same information can also be retrieved directly from the Geth node. The hash returned in the previous step can be provided as an argument to `eth.getTransaction` to return the transaction information:
```javascript
eth.getTransaction('0x99d489d0bd984915fd370b307c2d39320860950666aac3f261921113ae4f95bb');
@ -342,7 +346,7 @@ This returns the following response (although the actual values for each field w
accessList: [],
blockHash: "0x1c5d3f8dd997b302935391b57dc3e4fffd1fa2088ef2836d51f844f993eb39c4",
blockNumber: 6355150,
chainId: "0x5",
chainId: "0xaa36a7",
from: "0xca57f3b40b42fcce3c37b8d18adbca5260ca72ec",
gas: 21000,
gasPrice: 2425000023,
@ -367,8 +371,7 @@ Up to this point this tutorial has interacted with Geth using the convenience li
### Checking account balance
The command below returns the balance of the given account. This is a HTTP POST request to the local port 8545. The `-H` flag is for header information. It is used here to define the format of the incoming payload, which is JSON. The `--data` flag defines the content of the payload, which is a JSON object. That JSON object contains four fields: `jsonrpc` defines the spec version for the JSON-RPC API, `method` is the specific function being invoked, `params` are the function
arguments, and `id` is used for ordering transactions. The two arguments passed to `eth_getBalance` are the account address whose balance to check and the block to query (here `latest` is used to check the balance in the most recently mined block).
The command below returns the balance of the given account. This is a HTTP POST request to the local port 8545. The `-H` flag is for header information. It is used here to define the format of the incoming payload, which is JSON. The `--data` flag defines the content of the payload, which is a JSON object. That JSON object contains four fields: `jsonrpc` defines the spec version for the JSON-RPC API, `method` is the specific function being invoked, `params` are the function arguments, and `id` is used for ordering transactions. The two arguments passed to `eth_getBalance` are the account address whose balance to check and the block to query (here `latest` is used to check the balance in the most recently mined block).
```shell
curl -X POST http://127.0.0.1:8545 \
@ -428,4 +431,4 @@ This requires approval in Clef. Once the password for the sender account has bee
## Summary
This tutorial has demonstrated how to generate accounts using Clef, fund them with testnet ether and use those accounts to interact with Ethereum (Goerli) through a Geth node. Checking account balances, sending transactions and retrieving transaction details were explained using the web3.js library via the Geth console and using the JSON-RPC directly using Curl. For more detailed information about Clef, please see [the Clef docs](/docs/tools/Clef/Tutorial).
This tutorial has demonstrated how to generate accounts using Clef, fund them with testnet ether and use those accounts to interact with Ethereum (Sepolia) through a Geth node. Checking account balances, sending transactions and retrieving transaction details were explained using the web3.js library via the Geth console and using the JSON-RPC directly using Curl. For more detailed information about Clef, please see [the Clef docs](/docs/tools/Clef/Tutorial).

8
docs/index.md
View File

@ -1,10 +1,8 @@
---
title: Welcome to go-ethereum documentation
title: Welcome to go-ethereum
description: Documentation for the go-ethereum client
---
## Welcome to go-ethereum
Go-ethereum (aka Geth) is an Ethereum client built in [Golang](https://go.dev). It is one of the original and most popular Ethereum clients.
These documentation pages are intended to help users download, install and use Geth.
@ -12,9 +10,7 @@ These documentation pages are intended to help users download, install and use G
First, make sure you have sufficient [hardware](/docs/getting-started/hardware-requirements), then [download](/downloads) and [install](/docs/getting-started/installing-geth) Geth. Make sure you are familiar with the [security considerations](/docs/fundamentals/security) and have your firewall set up.
If you are just starting out with Geth, head to the [Getting started](/docs/getting-started/) page. That page guides a new user through some basic functions of Geth such as creating and securing accounts and making a transaction using Geth's built-in account tools.
A more secure but slightly more advanced setup is to use an external signer instead of Geth's built-in account manager. We have a [getting started](/docs/getting-started/getting-started-with-clef) guide for that too.
If you are just starting out with Geth, head to the [Getting started](/docs/getting-started/) page. That page guides new users through some basic functions of Geth such as creating and securing accounts and making a transaction.
Then, it is recommended to read the material in the [Fundamentals](/docs/fundamentals) section - these pages will help build a foundational understanding of how Geth works from a user perspective and under the hood.

889
docs/interacting-with-geth/rpc/ns-debug.md
View File

@ -3,885 +3,70 @@ title: debug Namespace
description: Documentation for the JSON-RPC API "clique" namespace
---
The `debug` API gives access to several non-standard RPC methods, which allow inspection, debugging and setting certain debugging flags during runtime.
## debug_accountRange
Tracing allows users to examine precisely what was executed by the EVM during some specific transaction or set of transactions. There are two different types of [transactions](https://ethereum.org/en/developers/docs/transactions) in Ethereum: value transfers and contract executions. A value transfer just moves ETH from one account to another. A contract interaction executes some code stored at a contract address which can include altering stored data and transacting multiple times with other contracts and externally-owned accounts. A contract execution transaction can therefore be a complicated web of interactions that can be difficult to unpick. The transaction receipt contains a status code that shows whether the transaction succeeded or failed, but more detailed information is not readily available, meaning it is very difficult to know what a contract execution actually did, what data was modified and which addresses were touched. This is the problem that EVM tracing solves. Geth traces transactions by re-running them locally and collecting data about precisely what was executed by the EVM.
Enumerates all accounts at a given block with paging capability. `maxResults` are returned in the page and the items have keys that come after the `start` key (hashed address).
Also see this [Devcon 2022 talk](https://www.youtube.com/watch?v=b8RdmGsilfU) on tracing in Geth.
If `incompletes` is false, then accounts for which the key preimage (i.e: the `address`) doesn't exist in db are skipped. NB: geth by default does not store preimages.
## State availability
| Client | Method invocation |
| :------ | ---------------------------------------------------------------------------------------------------------------- |
| Console | `debug.accountRange(blockNrOrHash, start, maxResults, nocode, nostorage, incompletes)` |
| RPC | `{"method": "debug_getHeaderRlp", "params": [blockNrOrHash, start, maxResults, nocode, nostorage, incompletes]}` |
In its simplest form, tracing a transaction entails requesting the Ethereum node to reexecute the desired transaction with varying degrees of data collection and have it return an aggregated summary. In order for a Geth node to reexecute a transaction, all historical state accessed by the transaction must be available. This includes:
## debug_backtraceAt
- Balance, nonce, bytecode and storage of both the recipient as well as all internally invoked contracts.
- Block metadata referenced during execution of both the outer as well as all internally created transactions.
- Intermediate state generated by all preceding transactions contained in the same block as the one being traced.
Sets the logging backtrace location. When a backtrace location is set and a log message is emitted at that location, the stack of the goroutine executing the log statement will be printed to stderr.
This means there are limits on the transactions that can be traced imposed by the synchronization and pruning configuration of a node:
The location is specified as `<filename>:<line>`.
- An **archive** node retains **all historical data** back to genesis. It can therefore trace arbitrary transactions at any point in the history of the chain. Tracing a single transaction requires reexecuting all preceding transactions in the same block.
| Client | Method invocation |
| :------ | ----------------------------------------------------- |
| Console | `debug.backtraceAt(string)` |
| RPC | `{"method": "debug_backtraceAt", "params": [string]}` |
- A **node synced from genesis** node only retains the most recent 128 block states in memory. Older states are represented by a sequence of occasional checkpoints that intermediate states can be regenerated from. This means that states within the most recent 128 blocks are immediately available, older states have to be regenerated from snapshots "on-the-fly". If the distance between the requested transaction and the most recent checkpoint is large, rebuilding the state can take a long time. Tracing a single transaction requires reexecuting all preceding transactions in the same block **and** all preceding blocks until the previous stored snapshot.
Example:
- A **snap synced** 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.
```javascript
> debug.backtraceAt("server.go:443")
```
- A **light synced** node retrieving data **on demand** can in theory trace transactions for which all required historical state is readily available in the network. This is because the data required to generate the trace is requested from an les-serving full node. In practice, data availability **cannot** be reasonably assumed.
## debug_blockProfile
![state pruning options](/public/images/docs/state-pruning.png)
*This image shows the state stored by each sync-mode - red indicates stored state. The full width of each line represents origin to present head*
Turns on block profiling for the given duration and writes profile data to disk. It uses a profile rate of 1 for most accurate information. If a different rate is desired, set the rate and write the profile manually using `debug_writeBlockProfile`.
More detailed information about syncing is available on the [sync modes page](/docs/interface/sync-modes).
| Client | Method invocation |
| :------ | -------------------------------------------------------------- |
| Console | `debug.blockProfile(file, seconds)` |
| RPC | `{"method": "debug_blockProfile", "params": [string, number]}` |
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.
## debug_chaindbCompact
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`.
Flattens the entire key-value database into a single level, removing all unused slots and merging all keys.
It is also possible to force Geth to store the state for specific sequences of block by stopping Geth, running again with `--gcmode archive` for some period - this prevents state pruning for blocks that arrive while Geth is running with `--gcmode archive`.
| Client | Method invocation |
| :------ | -------------------------------------------------- |
| Console | `debug.chaindbCompact()` |
| RPC | `{"method": "debug_chaindbCompact", "params": []}` |
_There are exceptions to the above rules when running batch traces of entire blocks or chain segments. Those will be detailed later._
## debug_chaindbProperty
## Types of trace
Returns leveldb properties of the key-value database.
### Basic traces
| Client | Method invocation |
| :------ | ----------------------------------------------------------- |
| Console | `debug.chaindbProperty(property string)` |
| RPC | `{"method": "debug_chaindbProperty", "params": [property]}` |
The simplest type of transaction trace that Geth can generate are raw EVM opcode traces. For every EVM instruction the transaction executes, a structured log entry is emitted, containing all contextual metadata deemed useful. This includes the *program counter*, *opcode name*, *opcode cost*, *remaining gas*, *execution depth* and any *occurred error*. The structured logs can optionally also contain the content of the *execution stack*, *execution memory* and *contract storage*.
## debug_cpuProfile
Read more about Geth's basic traces on the [basic traces page](/docs/evm-tracing/basic-traces).
Turns on CPU profiling for the given duration and writes profile data to disk.
### Built-in tracers
| Client | Method invocation |
| :------ | ------------------------------------------------------------ |
| Console | `debug.cpuProfile(file, seconds)` |
| RPC | `{"method": "debug_cpuProfile", "params": [string, number]}` |
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
functions that do some specific preprocessing on the trace data before it is returned.
## debug_dbAncient
More information about Geth's built-in tracers is available on the [built-in tracers](/docs/evm-tracing/builtin-tracers)
page.
Retrieves an ancient binary blob from the freezer. The freezer is a collection of append-only immutable files. The first argument `kind` specifies which table to look up data from. The list of all table kinds are as follows:
- `headers`: block headers
- `hashes`: canonical hash table (block number -> block hash)
- `bodies`: block bodies
- `receipts`: block receipts
- `diffs`: total difficulty table (block number -> td)
### Custom tracers
| Client | Method invocation |
| :------ | ----------------------------------------------------------- |
| Console | `debug.dbAncient(kind string, number uint64)` |
| RPC | `{"method": "debug_dbAncient", "params": [string, number]}` |
In addition to built-in tracers, it is possible to provide custom code that hooks to events in the EVM to process and return data in a consumable format. Custom tracers can be written either in Javascript or Go. JS tracers are good for quick prototyping and experimentation as well as for less intensive applications. Go tracers are performant but require the tracer to be compiled together with the Geth source code. This means developers only have to gather the data they actually need, and do any processing at the source.
## debug_dbAncients
More information about custom tracers is available on the [custom tracers](/docs/evm-tracing/custom-tracer)
page.
Returns the number of ancient items in the ancient store.
| Client | Method invocation |
| :------ | -------------------------------- |
| Console | `debug.dbAncients()` |
| RPC | `{"method": "debug_dbAncients"}` |
## Summary
## debug_dbGet
Returns the raw value of a key stored in the database.
| Client | Method invocation |
| :------ | -------------------------------------------- |
| Console | `debug.dbGet(key string)` |
| RPC | `{"method": "debug_dbGet", "params": [key]}` |
## debug_dumpBlock
Retrieves the state that corresponds to the block number and returns a list of accounts (including storage and code).
| Client | Method invocation |
| :------ | ----------------------------------------------------- |
| Go | `debug.DumpBlock(number uint64) (state.World, error)` |
| Console | `debug.traceBlockByHash(number, [options])` |
| RPC | `{"method": "debug_dumpBlock", "params": [number]}` |
### Example
```javascript
> debug.dumpBlock(10)
{
fff7ac99c8e4feb60c9750054bdc14ce1857f181: {
balance: "49358640978154672",
code: "",
codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470",
nonce: 2,
root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
storage: {}
},
fffbca3a38c3c5fcb3adbb8e63c04c3e629aafce: {
balance: "3460945928",
code: "",
codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470",
nonce: 657,
root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
storage: {}
}
},
root: "19f4ed94e188dd9c7eb04226bd240fa6b449401a6c656d6d2816a87ccaf206f1"
}
```
## debug_freeOSMemory
Forces garbage collection
| Client | Method invocation |
| :------ | ------------------------------------------------ |
| Go | `debug.FreeOSMemory()` |
| Console | `debug.freeOSMemory()` |
| RPC | `{"method": "debug_freeOSMemory", "params": []}` |
## debug_freezeClient
Forces a temporary client freeze, normally when the server is overloaded. Available as part of LES light server.
| Client | Method invocation |
| :------ | ---------------------------------------------------- |
| Console | `debug.freezeClient(node string)` |
| RPC | `{"method": "debug_freezeClient", "params": [node]}` |
## debug_gcStats
Returns garbage collection statistics.
See https://golang.org/pkg/runtime/debug/#GCStats for information about the fields of the returned object.
| Client | Method invocation |
| :------ | ------------------------------------------- |
| Console | `debug.gcStats()` |
| RPC | `{"method": "debug_gcStats", "params": []}` |
## debug_getAccessibleState
Returns the first number where the node has accessible state on disk. This is the post-state of that block and the pre-state of the next block. The (from, to) parameters are the sequence of blocks to search, which can go either forwards or backwards.
| Client | Method invocation |
| :------ | -------------------------------------------------------------- |
| Console | `debug.getAccessibleState(from, to rpc.BlockNumber)` |
| RPC | `{"method": "debug_getAccessibleState", "params": [from, to]}` |
## debug_getBadBlocks
Returns a list of the last 'bad blocks' that the client has seen on the network and returns them as a JSON list of block-hashes.
| Client | Method invocation |
| :------ | ------------------------------------------------ |
| Console | `debug.getBadBlocks()` |
| RPC | `{"method": "debug_getBadBlocks", "params": []}` |
## debug_getBlockRlp
Retrieves and returns the RLP encoded block by number.
| Client | Method invocation |
| :------ | ----------------------------------------------------- |
| Go | `debug.GetBlockRlp(number uint64) (string, error)` |
| Console | `debug.getBlockRlp(number, [options])` |
| RPC | `{"method": "debug_getBlockRlp", "params": [number]}` |
References: [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/#top)
## debug_getHeaderRlp
Returns an RLP-encoded header.
| Client | Method invocation |
| :------ | --------------------------------------------------- |
| Console | `debug.getHeaderRlp(blockNum)` |
| RPC | `{"method": "debug_getHeaderRlp", "params": [num]}` |
## debug_getModifiedAccountsByHash
Returns all accounts that have changed between the two blocks specified. A change is defined as a difference in nonce, balance, code hash, or storage hash. With one parameter, returns the list of accounts modified in the specified block.
| Client | Method invocation |
| :------ | ------------------------------------------------------------------------------- |
| Console | `debug.getModifiedAccountsByHash(startHash, endHash)` |
| RPC | `{"method": "debug_getModifiedAccountsByHash", "params": [startHash, endHash]}` |
## debug_getModifiedAccountsByNumber
Returns all accounts that have changed between the two blocks specified. A change is defined as a difference in nonce, balance, code hash or storage hash.
| Client | Method invocation |
| :------ | ------------------------------------------------------------------------------- |
| Console | `debug.getModifiedAccountsByNumber(startNum uint64, endNum uint64)` |
| RPC | `{"method": "debug_getModifiedAccountsByNumber", "params": [startNum, endNum]}` |
## debug_getRawReceipts
Returns the consensus-encoding of all receipts in a single block.
| Client | Method invocation |
| :------ | --------------------------------------------------------------- |
| Console | `debug.getRawReceipts(blockNrOrHash)` |
| RPC | `{"method": "debug_getRawReceipts", "params": [blockNrOrHash]}` |
## debug_goTrace
Turns on Go runtime tracing for the given duration and writes trace data to disk.
| Client | Method invocation |
| :------ | --------------------------------------------------------- |
| Console | `debug.goTrace(file, seconds)` |
| RPC | `{"method": "debug_goTrace", "params": [string, number]}` |
## debug_intermediateRoots
Executes a block (bad- or canon- or side-), and returns a list of intermediate roots: the stateroot after each transaction.
| Client | Method invocation |
| :------ | ------------------------------------------------------------------ |
| Console | `debug.intermediateRoots(blockHash, [options])` |
| RPC | `{"method": "debug_intermediateRoots", "params": [blockHash, {}]}` |
## debug_memStats
Returns detailed runtime memory statistics.
See https://golang.org/pkg/runtime/#MemStats for information about the fields of the returned object.
| Client | Method invocation |
| :------ | -------------------------------------------- |
| Console | `debug.memStats()` |
| RPC | `{"method": "debug_memStats", "params": []}` |
## debug_mutexProfile
Turns on mutex profiling for nsec seconds and writes profile data to file. It uses a profile rate of 1 for most accurate information. If a different rate is desired, set the rate and write the profile manually.
| Client | Method invocation |
| :------ | ---------------------------------------------------------- |
| Console | `debug.mutexProfile(file, nsec)` |
| RPC | `{"method": "debug_mutexProfile", "params": [file, nsec]}` |
## debug_preimage
Returns the preimage for a sha3 hash, if known.
| Client | Method invocation |
| :------ | ------------------------------------------------ |
| Console | `debug.preimage(hash)` |
| RPC | `{"method": "debug_preimage", "params": [hash]}` |
## debug_printBlock
Retrieves a block and returns its pretty printed form.
| Client | Method invocation |
| :------ | ---------------------------------------------------- |
| Console | `debug.printBlock(number uint64)` |
| RPC | `{"method": "debug_printBlock", "params": [number]}` |
## debug_seedHash
Fetches and retrieves the seed hash of the block by number
| Client | Method invocation |
| :------ | -------------------------------------------------- |
| Go | `debug.SeedHash(number uint64) (string, error)` |
| Console | `debug.seedHash(number, [options])` |
| RPC | `{"method": "debug_seedHash", "params": [number]}` |
## debug_setBlockProfileRate
Sets the rate (in samples/sec) of goroutine block profile data collection. A non-zero rate enables block profiling, setting it to zero stops the profile. Collected profile data can be written using `debug_writeBlockProfile`.
| Client | Method invocation |
| :------ | ------------------------------------------------------------- |
| Console | `debug.setBlockProfileRate(rate)` |
| RPC | `{"method": "debug_setBlockProfileRate", "params": [number]}` |
## debug_setGCPercent
Sets the garbage collection target percentage. A negative value disables garbage collection.
| Client | Method invocation |
| :------ | ------------------------------------------------- |
| Go | `debug.SetGCPercent(v int)` |
| Console | `debug.setGCPercent(v)` |
| RPC | `{"method": "debug_setGCPercent", "params": [v]}` |
## debug_setHead
Sets the current head of the local chain by block number. **Note**, this is a destructive action and may severely damage the chain. Use with _extreme_ caution.
| Client | Method invocation |
| :------ | ------------------------------------------------- |
| Go | `debug.SetHead(number uint64)` |
| Console | `debug.setHead(number)` |
| RPC | `{"method": "debug_setHead", "params": [number]}` |
References:
[Ethash](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/mining-algorithms/ethash)
## debug_setMutexProfileFraction
Sets the rate of mutex profiling.
| Client | Method invocation |
| :------ | --------------------------------------------------------------- |
| Console | `debug.setMutexProfileFraction(rate int)` |
| RPC | `{"method": "debug_setMutexProfileFraction", "params": [rate]}` |
## debug_stacks
Returns a printed representation of the stacks of all goroutines. Note that the web3 wrapper for this method takes care of the printing and does not return the string.
| Client | Method invocation |
| :------ | ------------------------------------------ |
| Console | `debug.stacks()` |
| RPC | `{"method": "debug_stacks", "params": []}` |
## debug_standardTraceBlockToFile
When JS-based tracing (see below) was first implemented, the intended usecase was to enable long-running tracers that could stream results back via a subscription channel. This method works a bit differently. (For full details, see [PR](https://github.com/ethereum/go-ethereum/pull/17914))
- It streams output to disk during the execution, to not blow up the memory usage on the node
- It uses `jsonl` as output format (to allow streaming)
- Uses a cross-client standardized output, so called 'standard json'
- Uses `op` for string-representation of opcode, instead of `op`/`opName` for numeric/string, and other simlar small differences.
- has `refund`
- Represents memory as a contiguous chunk of data, as opposed to a list of `32`-byte segments like `debug_traceTransaction`
This means that this method is only 'useful' for callers who control the node -- at least sufficiently to be able to read the artefacts from the filesystem after the fact.
The method can be used to dump a certain transaction out of a given block:
```sh
> debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {txHash:"0x4049f61ffbb0747bb88dc1c85dd6686ebf225a3c10c282c45a8e0c644739f7e9", disableMemory:true})
["/tmp/block_0x0bbe9f14-14-0x4049f61f-099048234"]
```
Or all txs from a block:
```sh
> debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {disableMemory:true})
["/tmp/block_0x0bbe9f14-0-0xb4502ea7-409046657", "/tmp/block_0x0bbe9f14-1-0xe839be8f-954614764", "/tmp/block_0x0bbe9f14-2-0xc6e2052f-542255195", "/tmp/block_0x0bbe9f14-3-0x01b7f3fe-209673214", "/tmp/block_0x0bbe9f14-4-0x0f290422-320999749", "/tmp/block_0x0bbe9f14-5-0x2dc0fb80-844117472", "/tmp/block_0x0bbe9f14-6-0x35542da1-256306111", "/tmp/block_0x0bbe9f14-7-0x3e199a08-086370834", "/tmp/block_0x0bbe9f14-8-0x87778b88-194603593", "/tmp/block_0x0bbe9f14-9-0xbcb081ba-629580052", "/tmp/block_0x0bbe9f14-10-0xc254381a-578605923", "/tmp/block_0x0bbe9f14-11-0xcc434d58-405931366", "/tmp/block_0x0bbe9f14-12-0xce61967d-874423181", "/tmp/block_0x0bbe9f14-13-0x05a20b35-267153288", "/tmp/block_0x0bbe9f14-14-0x4049f61f-606653767", "/tmp/block_0x0bbe9f14-15-0x46d473d2-614457338", "/tmp/block_0x0bbe9f14-16-0x35cf5500-411906321", "/tmp/block_0x0bbe9f14-17-0x79222961-278569788", "/tmp/block_0x0bbe9f14-18-0xad84e7b1-095032683", "/tmp/block_0x0bbe9f14-19-0x4bd48260-019097038", "/tmp/block_0x0bbe9f14-20-0x1517411d-292624085", "/tmp/block_0x0bbe9f14-21-0x6857e350-971385904", "/tmp/block_0x0bbe9f14-22-0xbe3ae2ca-236639695"]
```
Files are created in a temp-location, with the naming standard `block_<blockhash:4>-<txindex>-<txhash:4>-<random suffix>`. Each opcode immediately streams to file, with no in-geth buffering aside from whatever buffering the os normally does.
On the server side, it also adds some more info when regenerating historical state, namely, the reexec-number if `required historical state is not avaiable` is encountered, so a user can experiment with increasing that setting. It also prints out the remaining block until it reaches target:
```
INFO [10-15|13:48:25.263] Regenerating historical state block=2385959 target=2386012 remaining=53 elapsed=3m30.990537767s
INFO [10-15|13:48:33.342] Regenerating historical state block=2386012 target=2386012 remaining=0 elapsed=3m39.070073163s
INFO [10-15|13:48:33.343] Historical state regenerated block=2386012 elapsed=3m39.070454362s nodes=10.03mB preimages=652.08kB
INFO [10-15|13:48:33.352] Wrote trace file=/tmp/block_0x14490c57-0-0xfbbd6d91-715824834
INFO [10-15|13:48:33.352] Wrote trace file=/tmp/block_0x14490c57-1-0x71076194-187462969
INFO [10-15|13:48:34.421] Wrote trace file=/tmp/block_0x14490c57-2-0x3f4263fe-056924484
```
The `options` is as follows:
```sh
type StdTraceConfig struct {
*vm.LogConfig
Reexec *uint64
TxHash *common.Hash
}
```
## debug_standardTraceBadBlockToFile
This method is similar to `debug_standardTraceBlockToFile`, but can be used to obtain info about a block which has been _rejected_ as invalid (for some reason).
## debug_startCPUProfile
Turns on CPU profiling indefinitely, writing to the given file.
| Client | Method invocation |
| :------ | --------------------------------------------------------- |
| Console | `debug.startCPUProfile(file)` |
| RPC | `{"method": "debug_startCPUProfile", "params": [string]}` |
## debug_startGoTrace
Starts writing a Go runtime trace to the given file.
| Client | Method invocation |
| :------ | ------------------------------------------------------ |
| Console | `debug.startGoTrace(file)` |
| RPC | `{"method": "debug_startGoTrace", "params": [string]}` |
## debug_stopCPUProfile
Stops an ongoing CPU profile.
| Client | Method invocation |
| :------ | -------------------------------------------------- |
| Console | `debug.stopCPUProfile()` |
| RPC | `{"method": "debug_stopCPUProfile", "params": []}` |
## debug_stopGoTrace
Stops writing the Go runtime trace.
| Client | Method invocation |
| :------ | ----------------------------------------------- |
| Console | `debug.startGoTrace(file)` |
| RPC | `{"method": "debug_stopGoTrace", "params": []}` |
## debug_storageRangeAt
Returns the storage at the given block height and transaction index. The result can be paged by providing a `maxResult` to cap the number of storage slots returned as well as specifying the offset via `keyStart` (hash of storage key).
| Client | Method invocation |
| :------ | -------------------------------------------------------------------------------------------------------- |
| Console | `debug.storageRangeAt(blockHash, txIdx, contractAddress, keyStart, maxResult)` |
| RPC | `{"method": "debug_storageRangeAt", "params": [blockHash, txIdx, contractAddress, keyStart, maxResult]}` |
## debug_traceBadBlock
Returns the structured logs created during the execution of EVM against a block pulled from the pool of bad ones and returns them as a JSON object.
| Client | Method invocation |
| :------ | -------------------------------------------------------------- |
| Console | `debug.traceBadBlock(blockHash, [options])` |
| RPC | `{"method": "debug_traceBadBlock", "params": [blockHash, {}]}` |
## debug_traceBlock
The `traceBlock` method will return a full stack trace of all invoked opcodes of all transaction that were included in this block. **Note**, the parent of this block must be present or it will fail.
| Client | Method invocation |
| :------ | ------------------------------------------------------------------------ |
| Go | `debug.TraceBlock(blockRlp []byte, config. *vm.Config) BlockTraceResult` |
| Console | `debug.traceBlock(tblockRlp, [options])` |
| RPC | `{"method": "debug_traceBlock", "params": [blockRlp, {}]}` |
References:
[RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp)
### Example
```javascript
> debug.traceBlock("0xblock_rlp")
{
gas: 85301,
returnValue: "",
structLogs: [{
depth: 1,
error: "",
gas: 162106,
gasCost: 3,
memory: null,
op: "PUSH1",
pc: 0,
stack: [],
storage: {}
},
/* snip */
{
depth: 1,
error: "",
gas: 100000,
gasCost: 0,
memory: ["0000000000000000000000000000000000000000000000000000000000000006", "0000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000060"],
op: "STOP",
pc: 120,
stack: ["00000000000000000000000000000000000000000000000000000000d67cbec9"],
storage: {
0000000000000000000000000000000000000000000000000000000000000004: "8241fa522772837f0d05511f20caa6da1d5a3209000000000000000400000001",
0000000000000000000000000000000000000000000000000000000000000006: "0000000000000000000000000000000000000000000000000000000000000001",
f652222313e28459528d920b65115c16c04f3efc82aaedc97be59f3f377c0d3f: "00000000000000000000000002e816afc1b5c0f39852131959d946eb3b07b5ad"
}
}]
```
## debug_traceBlockByNumber
Similar to [debug_traceBlock](#debug_traceblock), `traceBlockByNumber` accepts a block number and will replay the block that is already present in the database.
| Client | Method invocation |
| :------ | ------------------------------------------------------------------------------ |
| Go | `debug.TraceBlockByNumber(number uint64, config. *vm.Config) BlockTraceResult` |
| Console | `debug.traceBlockByNumber(number, [options])` |
| RPC | `{"method": "debug_traceBlockByNumber", "params": [number, {}]}` |
References:
[RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp)
## debug_traceBlockByHash
Similar to [debug_traceBlock](#debug_traceblock), `traceBlockByHash` accepts a block hash and will replay the block that is already present in the database.
| Client | Method invocation |
| :------ | ------------------------------------------------------------------------------- |
| Go | `debug.TraceBlockByHash(hash common.Hash, config. *vm.Config) BlockTraceResult` |
| Console | `debug.traceBlockByHash(hash, [options])` |
| RPC | `{"method": "debug_traceBlockByHash", "params": [hash {}]}` |
References:
[RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp)
## debug_traceBlockFromFile
Similar to [debug_traceBlock](#debug_traceblock), `traceBlockFromFile` accepts a file containing the RLP of the block.
| Client | Method invocation |
| :------ | -------------------------------------------------------------------------------- |
| Go | `debug.TraceBlockFromFile(fileName string, config. *vm.Config) BlockTraceResult` |
| Console | `debug.traceBlockFromFile(fileName, [options])` |
| RPC | `{"method": "debug_traceBlockFromFile", "params": [fileName, {}]}` |
References:
[RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp)
## debug_traceCall
The `debug_traceCall` method enables running an `eth_call` within the context of the given block execution using the final state of parent block as the base. The first argument (just as in `eth_call`) is a [transaction object](/docs/rpc/objects#transaction-call-object). The block can be specified either by hash or by number as the second argument. A tracer can be specified as a third argument, similar to `debug_traceTransaction`. It returns the same output as `debug_traceTransaction`.
| Client | Method invocation |
| :-----: | --------------------------------------------------------------------------------------------------------------------------- |
| Go | `debug.TraceCall(args ethapi.CallArgs, blockNrOrHash rpc.BlockNumberOrHash, config *TraceConfig) (*ExecutionResult, error)` |
| Console | `debug.traceCall(object, blockNrOrHash, [options])` |
| RPC | `{"method": "debug_traceCall", "params": [object, blockNrOrHash, {}]}` |
### Example
No specific call options:
```sh
> debug.traceCall(null, "0x0")
{
failed: false,
gas: 53000,
returnValue: "",
structLogs: []
}
```
Tracing a call with a destination and specific sender, disabling the storage and memory output (less data returned over RPC)
```sh
debug.traceCall({
"from": "0xdeadbeef29292929192939494959594933929292",
"to": "0xde929f939d939d393f939393f93939f393929023",
"gas": "0x7a120",
"data": "0xf00d4b5d00000000000000000000000001291230982139282304923482304912923823920000000000000000000000001293123098123928310239129839291010293810"
},
"latest", {"disableStorage": true, "disableMemory": true})
```
It is possible to supply 'overrides' for both state-data (accounts/storage) and block data (number, timestamp etc). In the example below, a call which executes `NUMBER` is performed, and the overridden number is placed on the stack:
```sh
> debug.traceCall({
from: eth.accounts[0],
value:"0x1",
gasPrice: "0xffffffff",
gas: "0xffff",
input: "0x43"},
"latest",
{"blockoverrides":
{"number": "0x50"}
})
{
failed: false,
gas: 53018,
returnValue: "",
structLogs: [{
depth: 1,
gas: 12519,
gasCost: 2,
op: "NUMBER",
pc: 0,
stack: []
}, {
depth: 1,
gas: 12517,
gasCost: 0,
op: "STOP",
pc: 1,
stack: ["0x50"]
}]
}
```
Curl example:
```sh
> curl -H "Content-Type: application/json" -X POST localhost:8545 --data '{"jsonrpc":"2.0","method":"debug_traceCall","params":[null, "pending"],"id":1}'
{"jsonrpc":"2.0","id":1,"result":{"gas":53000,"failed":false,"returnValue":"","structLogs":[]}}
```
## debug_traceChain
Returns the structured logs created during the execution of EVM between two blocks (excluding start) as a JSON object. This endpoint must be invoked via `debug_subscribe` as follows:
`const res = provider.send('debug_subscribe', ['traceChain', '0x3f3a2a', '0x3f3a2b'])`
please refer to the [subscription page](/docs/rpc/pubsub) for more details.
## debug_traceTransaction
**OBS** In most scenarios, `debug.standardTraceBlockToFile` is better suited for tracing!
The `traceTransaction` debugging method will attempt to run the transaction in the exact same manner as it was executed on the network. It will replay any transaction that may have been executed prior to this one before it will finally attempt to execute the transaction that corresponds to the given
hash.
In addition to the hash of the transaction it can take a secondary _optional_ argument, which specifies the options for this specific call. The possible options are:
- `disableStorage`: `BOOL`. Setting this to true will disable storage capture (default = false).
- `disableStack`: `BOOL`. Setting this to true will disable stack capture (default = false).
- `enableMemory`: `BOOL`. Setting this to true will enable memory capture (default = false).
- `enableReturnData`: `BOOL`. Setting this to true will enable return data capture (default = false).
- `tracer`: `STRING`. Setting this will enable JavaScript-based transaction tracing, described below. If set, the previous four arguments will be ignored.
- `timeout`: `STRING`. Overrides the default timeout of 5 seconds for JavaScript-based tracing calls. Valid values are described [here](https://golang.org/pkg/time/#ParseDuration).
| Client | Method invocation |
| :------ | -------------------------------------------------------------------------------------------- |
| Go | `debug.TraceTransaction(txHash common.Hash, logger *vm.LogConfig) (*ExecutionResult, error)` |
| Console | `debug.traceTransaction(txHash, [options])` |
| RPC | `{"method": "debug_traceTransaction", "params": [txHash, {}]}` |
### Example
```javascript
> debug.traceTransaction("0x2059dd53ecac9827faad14d364f9e04b1d5fe5b506e3acc886eff7a6f88a696a")
{
gas: 85301,
returnValue: "",
structLogs: [{
depth: 1,
error: "",
gas: 162106,
gasCost: 3,
memory: null,
op: "PUSH1",
pc: 0,
stack: [],
storage: {}
},
/* snip */
{
depth: 1,
error: "",
gas: 100000,
gasCost: 0,
memory: ["0000000000000000000000000000000000000000000000000000000000000006", "0000000000000000000000000000000000000000000000000000000000000000", "0000000000000000000000000000000000000000000000000000000000000060"],
op: "STOP",
pc: 120,
stack: ["00000000000000000000000000000000000000000000000000000000d67cbec9"],
storage: {
0000000000000000000000000000000000000000000000000000000000000004: "8241fa522772837f0d05511f20caa6da1d5a3209000000000000000400000001",
0000000000000000000000000000000000000000000000000000000000000006: "0000000000000000000000000000000000000000000000000000000000000001",
f652222313e28459528d920b65115c16c04f3efc82aaedc97be59f3f377c0d3f: "00000000000000000000000002e816afc1b5c0f39852131959d946eb3b07b5ad"
}
}]
```
### JavaScript-based tracing
Specifying the `tracer` option in the second argument enables JavaScript-based tracing. In this mode, `tracer` is interpreted as a JavaScript expression that is expected to evaluate to an object which must expose the `result` and `fault` methods. There exist 3 additional methods, namely: `step`, `enter` and `exit`. One of either `step`, or `enter` AND `exit` must be provided(i.e. `enter` and `exit` must be exposed together). All three can be provided together.
#### Step
`step`is a function that takes two arguments, log and db, and is called for each step of the EVM, or when an error occurs, as the specified transaction is traced.
`log` has the following fields:
- `op`: Object, an OpCode object representing the current opcode
- `stack`: Object, a structure representing the EVM execution stack
- `memory`: Object, a structure representing the contract's memory space
- `contract`: Object, an object representing the account executing the current operation
and the following methods:
- `getPC()` - returns a Number with the current program counter
- `getGas()` - returns a Number with the amount of gas remaining
- `getCost()` - returns the cost of the opcode as a Number
- `getDepth()` - returns the execution depth as a Number
- `getRefund()` - returns the amount to be refunded as a Number
- `getError()` - returns information about the error if one occured, otherwise returns `undefined`
If error is non-empty, all other fields should be ignored.
For efficiency, the same `log` object is reused on each execution step, updated with current values; make sure to copy values that are needed beyond the current call. For instance, this step function will not work:
function(log) {
this.logs.append(log);
}
But this step function will:
function(log) {
this.logs.append({gas: log.getGas(), pc: log.getPC(), ...});
}
`log.op` has the following methods:
- `isPush()` - returns true iff the opcode is a PUSHn
- `toString()` - returns the string representation of the opcode
- `toNumber()` - returns the opcode's number
`log.memory` has the following methods:
- `slice(start, stop)` - returns the specified segment of memory as a byte slice
- `getUint(offset)` - returns the 32 bytes at the given offset
`log.stack` has the following methods:
- `peek(idx)` - returns the idx-th element from the top of the stack (0 is the topmost element) as a big.Int
- `length()` - returns the number of elements in the stack
`log.contract` has the following methods:
- `getCaller()` - returns the address of the caller
- `getAddress()` - returns the address of the current contract
- `getValue()` - returns the amount of value sent from caller to contract as a big.Int
- `getInput()` - returns the input data passed to the contract
`db` has the following methods:
- `getBalance(address)` - returns a `big.Int` with the specified account's balance
- `getNonce(address)` - returns a Number with the specified account's nonce
- `getCode(address)` - returns a byte slice with the code for the specified account
- `getState(address, hash)` - returns the state value for the specified account and the specified hash
- `exists(address)` - returns true if the specified address exists
If the step function throws an exception or executes an illegal operation at any point, it will not be called on any further VM steps, and the error will be returned to the caller.
#### Result
`result` is a function that takes two arguments `ctx` and `db`, and is expected to return a JSON-serializable value to return to the RPC caller.
`ctx` is the context in which the transaction is executing and has the following fields:
- `type` - String, one of the two values `CALL` and `CREATE`
- `from` - Address, sender of the transaction
- `to` - Address, target of the transaction
- `input` - Buffer, input transaction data
- `gas` - Number, gas budget of the transaction
- `value` - big.Int, amount to be transferred in wei
- `block` - Number, block number
- `output` - Buffer, value returned from EVM
- `gasUsed` - Number, amount of gas used in executing the transaction (excludes txdata costs)
- `time` - String, execution runtime
#### Fault
`fault` is a function that takes two arguments, `log` and `db`, just like `step` and is invoked when an error happens during the execution of an opcode which wasn't reported in `step`. The method `log.getError()` has information about the error.
#### Enter & Exit
`enter` and `exit` are respectively invoked on stepping in and out of an internal call. More specifically they are invoked on the `CALL` variants, `CREATE` variants and also for the transfer implied by a `SELFDESTRUCT`.
`enter` takes a `callFrame` object as argument which has the following methods:
- `getType()` - returns a string which has the type of the call frame
- `getFrom()` - returns the address of the call frame sender
- `getTo()` - returns the address of the call frame target
- `getInput()` - returns the input as a buffer
- `getGas()` - returns a Number which has the amount of gas provided for the frame
- `getValue()` - returns a `big.Int` with the amount to be transferred only if available, otherwise `undefined`
`exit` takes in a `frameResult` object which has the following methods:
- `getGasUsed()` - returns amount of gas used throughout the frame as a Number
- `getOutput()` - returns the output as a buffer
` -getError()` - returns an error if one occured during execution and `undefined` otherwise
#### Usage
Note that several values are Golang big.Int objects, not JavaScript numbers or JS bigints. As such, they have the same interface as described in the godocs. Their default serialization to JSON is as a Javascript number; to serialize large numbers accurately call `.String()` on them. For convenience, `big.NewInt(x)` is provided, and will convert a uint to a Go BigInt.
Usage example, returns the top element of the stack at each CALL opcode only:
```sh
debug.traceTransaction(txhash, {tracer: '{data: [], fault: function(log) {}, step: function(log) { if(log.op.toString() == "CALL") this.data.push(log.stack.peek(0)); }, result: function() { return this.data; }}'});
```
## debug_verbosity
Sets the logging verbosity ceiling. Log messages with level up to and including the given level will be printed.
The verbosity of individual packages and source files can be raised using `debug_vmodule`.
| Client | Method invocation |
| :------ | ------------------------------------------------- |
| Console | `debug.verbosity(level)` |
| RPC | `{"method": "debug_vmodule", "params": [number]}` |
## debug_vmodule
Sets the logging verbosity pattern.
| Client | Method invocation |
| :------ | ------------------------------------------------- |
| Console | `debug.vmodule(string)` |
| RPC | `{"method": "debug_vmodule", "params": [string]}` |
### Examples
To see messages from a particular Go package (directory) and all subdirectories, use:
```javascript
> debug.vmodule("eth/*=6")
```
To restrict messages to a particular package (e.g. p2p)
but exclude subdirectories, use:
```javascript
> debug.vmodule("p2p=6")
```
To see log messages from a particular source file, use
```javascript
> debug.vmodule("server.go=6")
```
To see all output from peer.go in a package below eth (eth/peer.go, eth/downloader/peer.go) as well as output from package p2p at level <= 5, use:
```javascript
debug.vmodule('eth/*/peer.go=6,p2p=5');
```
## debug_writeBlockProfile
Writes a goroutine blocking profile to the given file.
| Client | Method invocation |
| :------ | ----------------------------------------------------------- |
| Console | `debug.writeBlockProfile(file)` |
| RPC | `{"method": "debug_writeBlockProfile", "params": [string]}` |
## debug_writeMemProfile
Writes an allocation profile to the given file. Note that the profiling rate cannot be set through the API, it must be set on the command line using the `--pprof.memprofilerate` flag.
| Client | Method invocation |
| :------ | ----------------------------------------------------------- |
| Console | `debug.writeMemProfile(file string)` |
| RPC | `{"method": "debug_writeBlockProfile", "params": [string]}` |
## debug_writeMutexProfile
Writes a goroutine blocking profile to the given file.
| Client | Method invocation |
| :------ | --------------------------------------------------------- |
| Console | `debug.writeMutexProfile(file)` |
| RPC | `{"method": "debug_writeMutexProfile", "params": [file]}` |
This page gave an introduction to the concept of tracing and explained issues around state availability. More detailed information on Geth's built-in and custom tracers can be found on their dedicated pages.

3
docs/interacting-with-geth/rpc/ns-personal.md
View File

@ -3,6 +3,9 @@ title: personal Namespace
description: Documentation for the JSON-RPC API "personal" namespace
---
{% include note.html content="The personal namespace will be deprecated in the very near future. All the methods in the personal namespace have equivalents in Clef or Geth" %}
The personal API manages private keys in the key store.
## personal_deriveAccount