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

docs: update tracer docs (#26140) 

Co-authored-by: Sina Mahmoodi <1591639+s1na@users.noreply.github.com>
This commit is contained in:
Joseph Cook 2022-11-08 15:19:22 +00:00 committed by GitHub
parent f5c7a5321d
commit 1f9c494d07
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 370 additions and 156 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
docs/_evm-tracing/basic-traces.md Normal file
View File

@ -0,0 +1,132 @@
---
title: Basic traces
sort_key: B
---
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.

56
docs/_evm-tracing/builtin-tracers.md
View File

@ -1,6 +1,6 @@
---
title: Built-in tracers
sort_key: B
sort_key: C
---
Geth comes bundled with a choice of tracers that can be invoked via the
@ -152,18 +152,19 @@ The result will be a nested list of call frames, resembling how EVM works. They
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:
@ -206,10 +207,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
@ -284,25 +289,6 @@ 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.

26
docs/_evm-tracing/custom-tracer.md
View File

@ -1,6 +1,6 @@
---
title: Custom EVM tracer
sort_key: C
title: Custom tracers
sort_key: D
---
In addition to the default opcode tracer and the built-in tracers, Geth offers the
@ -20,7 +20,7 @@ transaction execution, which can be a very large amount of data. Often, users ar
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](/content/docs/developers/interacting-with-geth/rpc/ns-debug#debug_tracetransaction).
[reference documentation](/docs/rpc/ns-debug#debug_tracetransaction).
### A simple filter
@ -397,7 +397,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)}
}
@ -455,13 +455,17 @@ 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' })

108
docs/_evm-tracing/index.md
View File

@ -1,49 +1,117 @@
---
title: EVM Tracing
title: Introduction to 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.
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.
Also see this [Devcon 2022 talk](https://www.youtube.com/watch?v=b8RdmGsilfU) on
tracing in Geth.
## State availability
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:
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:
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.
- 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](/static/images/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*
More detailed information about syncing is available on the [sync modes page](/pages/docs/fundamentals/sync-modes.md).
More detailed information about syncing is available on the [sync modes page](/docs/interface/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`.
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
@ -58,7 +126,7 @@ different data from the method. Under the hood, these tracers are Go or Javascri
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](/pages/docs/developers/dapp-developer/evm-tracing/built-in-tracers.md)
[built-in tracers](/docs/evm-tracing/builtin-tracers)
page.
@ -73,7 +141,7 @@ Geth source code. This means developers only have to gather the data they actual
need, and do any processing at the source.
More information about custom tracers is available on the
[custom tracers](/pages/docs/developers/dapp-developer/evm-tracing/custom-tracers.md)
[custom tracers](/docs/evm-tracing/custom-tracer)
page.

204
docs/_rpc/ns-debug.md
View File

@ -16,7 +16,7 @@ Enumerates all accounts at a given block with paging capability. `maxResults` ar
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.
| Client | Method invocation |
|:--------|------------------------------------------------------------------------------------------------------------------|
| :------ | ---------------------------------------------------------------------------------------------------------------- |
| Console | `debug.accountRange(blockNrOrHash, start, maxResults, nocode, nostorage, incompletes)` |
| RPC | `{"method": "debug_getHeaderRlp", "params": [blockNrOrHash, start, maxResults, nocode, nostorage, incompletes]}` |
@ -29,7 +29,7 @@ of the goroutine executing the log statement will be printed to stderr.
The location is specified as `<filename>:<line>`.
| Client | Method invocation |
|:--------|-------------------------------------------------------|
| :------ | ----------------------------------------------------- |
| Console | `debug.backtraceAt(string)` |
| RPC | `{"method": "debug_backtraceAt", "params": [string]}` |
@ -48,7 +48,7 @@ the rate and write the profile manually using
`debug_writeBlockProfile`.
| Client | Method invocation |
|:--------|----------------------------------------------------------------|
| :------ | -------------------------------------------------------------- |
| Console | `debug.blockProfile(file, seconds)` |
| RPC | `{"method": "debug_blockProfile", "params": [string, number]}` |
@ -58,7 +58,7 @@ the rate and write the profile manually using
Flattens the entire key-value database into a single level, removing all unused slots and merging all keys.
| Client | Method invocation |
|:--------|----------------------------------------------------|
| :------ | -------------------------------------------------- |
| Console | `debug.chaindbCompact()` |
| RPC | `{"method": "debug_chaindbCompact", "params": []}` |
@ -67,10 +67,10 @@ Flattens the entire key-value database into a single level, removing all unused
Returns leveldb properties of the key-value database.
| Client | Method invocation |
|:--------|----------------------------------------------------------------|
| Console | `debug.chaindbProperty(property string)` |
| RPC | `{"method": "debug_chaindbProperty", "params": [property]}` |
| Client | Method invocation |
| :------ | ----------------------------------------------------------- |
| Console | `debug.chaindbProperty(property string)` |
| RPC | `{"method": "debug_chaindbProperty", "params": [property]}` |
### debug_cpuProfile
@ -79,7 +79,7 @@ Turns on CPU profiling for the given duration and writes
profile data to disk.
| Client | Method invocation |
|:--------|--------------------------------------------------------------|
| :------ | ------------------------------------------------------------ |
| Console | `debug.cpuProfile(file, seconds)` |
| RPC | `{"method": "debug_cpuProfile", "params": [string, number]}` |
@ -96,7 +96,7 @@ The first argument `kind` specifies which table to look up data from. The list o
- `diffs`: total difficulty table (block number -> td)
| Client | Method invocation |
|:--------|-------------------------------------------------------------|
| :------ | ----------------------------------------------------------- |
| Console | `debug.dbAncient(kind string, number uint64)` |
| RPC | `{"method": "debug_dbAncient", "params": [string, number]}` |
@ -105,7 +105,7 @@ The first argument `kind` specifies which table to look up data from. The list o
Returns the number of ancient items in the ancient store.
| Client | Method invocation |
|:--------|----------------------------------|
| :------ | -------------------------------- |
| Console | `debug.dbAncients()` |
| RPC | `{"method": "debug_dbAncients"}` |
@ -113,10 +113,10 @@ Returns the number of ancient items in the ancient store.
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]}` |
| Client | Method invocation |
| :------ | -------------------------------------------- |
| Console | `debug.dbGet(key string)` |
| RPC | `{"method": "debug_dbGet", "params": [key]}` |
@ -126,7 +126,7 @@ Retrieves the state that corresponds to the block number and returns a list of a
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]}` |
@ -161,11 +161,11 @@ storage and code).
Forces garbage collection
| Client | Method invocation |
|:--------|---------------------------------------------------|
| Go | `debug.FreeOSMemory()` |
| Console | `debug.freeOSMemory()` |
| RPC | `{"method": "debug_freeOSMemory", "params": []}` |
| Client | Method invocation |
| :------ | ------------------------------------------------ |
| Go | `debug.FreeOSMemory()` |
| Console | `debug.freeOSMemory()` |
| RPC | `{"method": "debug_freeOSMemory", "params": []}` |
@ -175,7 +175,7 @@ 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]}` |
@ -188,10 +188,10 @@ 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": []}` |
| Client | Method invocation |
| :------ | ------------------------------------------- |
| Console | `debug.gcStats()` |
| RPC | `{"method": "debug_gcStats", "params": []}` |
### debug_getAccessibleState
@ -203,10 +203,10 @@ to search, which can go either forwards or backwards.
Note: to get the last state pass in the range of blocks in reverse, i.e. (last, first).
| Client | Method invocation |
|:--------|-----------------------------------------------------------------------|
| Console | `debug.getAccessibleState(from, to rpc.BlockNumber)` |
| RPC | `{"method": "debug_getAccessibleState", "params": [from, to]}` |
| Client | Method invocation |
| :------ | -------------------------------------------------------------- |
| Console | `debug.getAccessibleState(from, to rpc.BlockNumber)` |
| RPC | `{"method": "debug_getAccessibleState", "params": [from, to]}` |
### debug_getBadBlocks
@ -214,10 +214,10 @@ Note: to get the last state pass in the range of blocks in reverse, i.e. (last,
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": []}` |
| Client | Method invocation |
| :------ | ------------------------------------------------ |
| Console | `debug.getBadBlocks()` |
| RPC | `{"method": "debug_getBadBlocks", "params": []}` |
### debug_getBlockRlp
@ -225,7 +225,7 @@ the network and returns them as a JSON list of block-hashes.
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]}` |
@ -237,7 +237,7 @@ References: [RLP](https://github.com/ethereum/wiki/wiki/RLP)
Returns an RLP-encoded header.
| Client | Method invocation |
|:--------|-----------------------------------------------------|
| :------ | --------------------------------------------------- |
| Console | `debug.getHeaderRlp(blockNum)` |
| RPC | `{"method": "debug_getHeaderRlp", "params": [num]}` |
@ -246,7 +246,7 @@ Returns an RLP-encoded header.
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]}` |
@ -257,7 +257,7 @@ 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]}` |
@ -266,7 +266,7 @@ storage hash.
Returns the consensus-encoding of all receipts in a single block.
| Client | Method invocation |
|:--------|-----------------------------------------------------------------|
| :------ | --------------------------------------------------------------- |
| Console | `debug.getRawReceipts(blockNrOrHash)` |
| RPC | `{"method": "debug_getRawReceipts", "params": [blockNrOrHash]}` |
@ -276,7 +276,7 @@ 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]}` |
@ -285,7 +285,7 @@ trace data to disk.
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, {}]}` |
@ -296,17 +296,17 @@ 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": []}` |
| 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]}` |
@ -315,7 +315,7 @@ Turns on mutex profiling for nsec seconds and writes profile data to file. It us
Returns the preimage for a sha3 hash, if known.
| Client | Method invocation |
|:--------|--------------------------------------------------|
| :------ | ------------------------------------------------ |
| Console | `debug.preimage(hash)` |
| RPC | `{"method": "debug_preimage", "params": [hash]}` |
@ -324,10 +324,10 @@ Returns the preimage for a sha3 hash, if known.
Retrieves a block and returns its pretty printed form.
| Client | Method invocation |
|:--------|---------------------------------------------------|
| Console | `debug.printBlock(number uint64)` |
| RPC | `{"method": "debug_printBlock", "params": [number]}` |
| Client | Method invocation |
| :------ | ---------------------------------------------------- |
| Console | `debug.printBlock(number uint64)` |
| RPC | `{"method": "debug_printBlock", "params": [number]}` |
### debug_seedHash
@ -335,7 +335,7 @@ Retrieves a block and returns its pretty printed form.
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]}` |
@ -348,7 +348,7 @@ 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]}` |
@ -358,8 +358,8 @@ Sets the garbage collection target percentage. A negative value disables garbage
collection.
| Client | Method invocation |
|:--------|---------------------------------------------------|
| Go | `debug.SetGCPercent(v int)` |
| :------ | ------------------------------------------------- |
| Go | `debug.SetGCPercent(v int)` |
| Console | `debug.setGCPercent(v)` |
| RPC | `{"method": "debug_setGCPercent", "params": [v]}` |
@ -370,7 +370,7 @@ Sets the current head of the local chain by block number. **Note**, this is a
destructive action and may severely damage your chain. Use with *extreme* caution.
| Client | Method invocation |
|:--------|---------------------------------------------------|
| :------ | ------------------------------------------------- |
| Go | `debug.SetHead(number uint64)` |
| Console | `debug.setHead(number)` |
| RPC | `{"method": "debug_setHead", "params": [number]}` |
@ -383,7 +383,7 @@ References:
Sets the rate of mutex profiling.
| Client | Method invocation |
|:--------|-----------------------------------------------------------------|
| :------ | --------------------------------------------------------------- |
| Console | `debug.setMutexProfileFraction(rate int)` |
| RPC | `{"method": "debug_setMutexProfileFraction", "params": [rate]}` |
@ -393,10 +393,10 @@ 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": []}` |
| Client | Method invocation |
| :------ | ------------------------------------------ |
| Console | `debug.stacks()` |
| RPC | `{"method": "debug_stacks", "params": []}` |
### debug_standardTraceBlockToFile
@ -456,7 +456,7 @@ This method is similar to `debug_standardTraceBlockToFile`, but can be used to o
Turns on CPU profiling indefinitely, writing to the given file.
| Client | Method invocation |
|:--------|-----------------------------------------------------------|
| :------ | --------------------------------------------------------- |
| Console | `debug.startCPUProfile(file)` |
| RPC | `{"method": "debug_startCPUProfile", "params": [string]}` |
@ -465,7 +465,7 @@ Turns on CPU profiling indefinitely, writing to the given file.
Starts writing a Go runtime trace to the given file.
| Client | Method invocation |
|:--------|--------------------------------------------------------|
| :------ | ------------------------------------------------------ |
| Console | `debug.startGoTrace(file)` |
| RPC | `{"method": "debug_startGoTrace", "params": [string]}` |
@ -474,7 +474,7 @@ Starts writing a Go runtime trace to the given file.
Stops an ongoing CPU profile.
| Client | Method invocation |
|:--------|----------------------------------------------------|
| :------ | -------------------------------------------------- |
| Console | `debug.stopCPUProfile()` |
| RPC | `{"method": "debug_stopCPUProfile", "params": []}` |
@ -482,17 +482,17 @@ Stops an ongoing CPU profile.
Stops writing the Go runtime trace.
| Client | Method invocation |
|:--------|---------------------------------------------------|
| Console | `debug.startGoTrace(file)` |
| RPC | `{"method": "debug_stopGoTrace", "params": []}` |
| 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]}` |
@ -501,7 +501,7 @@ Returns the storage at the given block height and transaction index. The result
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, {}]}` |
@ -512,7 +512,7 @@ that were included in this block. **Note**, the parent of this block must be pre
fail.
| Client | Method invocation |
|:--------|--------------------------------------------------------------------------|
| :------ | ------------------------------------------------------------------------ |
| Go | `debug.TraceBlock(blockRlp []byte, config. *vm.Config) BlockTraceResult` |
| Console | `debug.traceBlock(tblockRlp, [options])` |
| RPC | `{"method": "debug_traceBlock", "params": [blockRlp, {}]}` |
@ -562,7 +562,7 @@ Similar to [debug_traceBlock](#debug_traceblock), `traceBlockByNumber` accepts a
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, {}]}` |
@ -576,7 +576,7 @@ Similar to [debug_traceBlock](#debug_traceblock), `traceBlockByHash` accepts a b
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 {}]}` |
@ -590,7 +590,7 @@ References:
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, {}]}` |
@ -602,11 +602,11 @@ References:
The `debug_traceCall` method lets you run 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, {}]}` |
| 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
@ -698,11 +698,13 @@ specifies the options for this specific call. The possible options are:
* `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).
* `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, {}]}` |
@ -746,15 +748,37 @@ specifies the options for this specific call. The possible options are:
#### 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 4 additional methods, namely: `setup`, `step`, `enter`, and `exit`. `enter` and `exit` must be present or omitted together.
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
4 additional methods, namely: `setup`, `step`, `enter`, and `exit`. `enter` and `exit`
must be present or omitted together.
##### Setup
`setup` is invoked once, in the beginning when the tracer is being constructed by Geth for a given transaction. It takes in one argument `config`. `config` allows users to pass in options to the tracer. `config` is to be JSON-decoded for usage and its default value is `"{}"`.
`setup` is invoked once, in the beginning when the tracer is being constructed by Geth
for a given transaction. It takes in one argument `config`. `config` is tracer-specific and
allows users to pass in options to the tracer. `config` is to be JSON-decoded for usage and
its default value is `"{}"`.
The `config` in the following example is the `onlyTopCall` option available in the
`callTracer`:
```js
debug.traceTransaction('<txhash>, { tracer: 'callTracer', tracerConfig: { onlyTopCall: true } })
```
The config in the following example is the `diffMode` option available
in the `prestateTracer`:
```js
debug.traceTransaction('<txhash>, { tracer: 'prestateTracer': tracerConfig: { diffMode: true } })
```
##### 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.
`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:
@ -886,7 +910,7 @@ 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]}` |
@ -895,7 +919,7 @@ can be raised using `debug_vmodule`.
Sets the logging verbosity pattern.
| Client | Method invocation |
|:--------|---------------------------------------------------|
| :------ | ------------------------------------------------- |
| Console | `debug.vmodule(string)` |
| RPC | `{"method": "debug_vmodule", "params": [string]}` |
@ -936,7 +960,7 @@ debug.vmodule("eth/*/peer.go=6,p2p=5")
Writes a goroutine blocking profile to the given file.
| Client | Method invocation |
|:--------|-------------------------------------------------------------|
| :------ | ----------------------------------------------------------- |
| Console | `debug.writeBlockProfile(file)` |
| RPC | `{"method": "debug_writeBlockProfile", "params": [string]}` |
@ -948,7 +972,7 @@ 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]}` |
@ -957,6 +981,6 @@ flag.
Writes a goroutine blocking profile to the given file.
| Client | Method invocation |
|:--------|-----------------------------------------------------------|
| :------ | --------------------------------------------------------- |
| Console | `debug.writeMutexProfile(file)` |
| RPC | `{"method": "debug_writeMutexProfile", "params": [file]}` |