Skip to content

Commit

Permalink
Document Trace APIs (#971)
Browse files Browse the repository at this point in the history 
* Document Trace APIs

Signed-off-by: Roland Tyler <roland.tyler@consensys.net>

Co-authored-by: Sally MacFarlane <sally.macfarlane@consensys.net>
  • Loading branch information
@rolandtyler @macfarla
rolandtyler and macfarla committed Mar 16, 2022
1 parent 7ad2bbf commit f48e56f
Show file tree
Hide file tree
Showing 3 changed files with 296 additions and 25 deletions.
45 changes: 32 additions & 13 deletions docs/HowTo/Troubleshoot/Trace-Transactions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,25 +5,44 @@ description: How to trace transactions
# Trace transactions

To get detailed information about transaction processing, use the
[`TRACE` API](../../Reference/API-Methods.md#trace-methods). Enable the
[`TRACE` API](../../Reference/API-Methods.md#trace-methods) using the
[`TRACE` API](../../Reference/API-Methods.md#trace-methods).
Enable the `TRACE` API using the
[`--rpc-http-api`](../../Reference/CLI/CLI-Syntax.md#rpc-http-api) or
[`--rpc-ws-api`](../../Reference/CLI/CLI-Syntax.md#rpc-ws-api) command line options.

To specify the trace types required and retrieve the transaction traces for a block, use
[`trace_replayBlockTransactions`](../../Reference/API-Methods.md#trace_replayblocktransactions). Options are
[`trace`, `vmTrace`, or `stateDiff`](../../Reference/Trace-Types.md).
The `TRACE` API has two sets of trace calls, [ad-hoc tracing APIs](#ad-hoc-tracing-apis) and
[transaction-trace filtering APIs](#transaction-trace-filtering-apis).

To retrieve the [`trace` type](../../Reference/Trace-Types.md#trace) for a specific:
## Ad-hoc tracing APIs

* Block, use [`trace_block`](../../Reference/API-Methods.md#trace_block).
* Transaction, use [`trace_transaction`](../../Reference/API-Methods.md#trace_transaction).
These APIs allow different diagnostic options when tracing calls or transactions.
The options are [`trace`, `vmTrace`, or `stateDiff`](../../Reference/Trace-Types.md).

Your node must be an archive node (that is, synchronized without pruning or fast sync) or the
requested block or transaction must be within the [the number of pruning blocks retained](../../Reference/CLI/CLI-Syntax.md#pruning-blocks-retained)
To use the ad-hoc tracing APIs, your node must be within the
[the number of pruning blocks retained](../../Reference/CLI/CLI-Syntax.md#pruning-blocks-retained)
(by default, 1024).

!!! important
The ad-hoc tracing APIs are:

The `TRACE` API is an early access feature in v1.4. The return values might change between v1.4
and v1.5.
* [trace_call](../../Reference/API-Methods.md#trace_call)
* [trace_callMany](../../Reference/API-Methods.md#trace_callmany)
* [trace_rawTransaction](../../Reference/API-Methods.md#trace_rawtransaction)
* [trace_replayBlockTransactions](../../Reference/API-Methods.md#trace_replayblocktransactions)

## Transaction-trace filtering APIs

These APIs allow you to filter and search by specific information such as the block, address, or transaction.
These APIs only use the [`trace` type](../../Reference/Trace-Types.md#trace).

To use the transaction-trace filtering APIs, your node must be an archive node
(that is, synchronized without pruning or fast sync) or the
requested block or transaction must be within the
[the number of pruning blocks retained](../../Reference/CLI/CLI-Syntax.md#pruning-blocks-retained)
(by default, 1024).

The transaction-trace filtering APIs are:

* [trace_block](../../Reference/API-Methods.md#trace_block)
* [trace_filter](../../Reference/API-Methods.md#trace_filter)
* [trace_get](../../Reference/API-Methods.md#trace_get)
* [trace_transaction](../../Reference/API-Methods.md#trace_transaction)
242 changes: 240 additions & 2 deletions docs/Reference/API-Methods.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7181,6 +7181,11 @@ the returned list items include the [revert reason](../HowTo/Send-Transactions/R

Executes the given call and returns a number of possible traces for it.

!!! important

The requested transaction must be contained in a block within [the number of pruning blocks retained](../CLI/CLI-Syntax#pruning-blocks-retained)
(by default, 1024).

#### Parameters

* `call`: *object* - [transaction call object](API-Objects.md#transaction-call-object)
Expand Down Expand Up @@ -7243,10 +7248,109 @@ one object per call, in transaction execution order
},
```

### `trace_callMany`

Performs multiple call traces on top of the same block. You can trace dependent transactions.

!!! important

The requested block must be within [the number of pruning blocks retained](../CLI/CLI-Syntax#pruning-blocks-retained)
(by default, 1024).

#### Parameters

* `options`: *array* of *strings* - list of tracing options; tracing options are
[`trace`, `vmTrace`, and `stateDiff`](Trace-Types.md). Specify any
combination of the three options including none of them.

* `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`,
`earliest`, or `pending`, as described in
[Block Parameter](../HowTo/Interact/APIs/Using-JSON-RPC-API.md#block-parameter)

#### Returns

`result`: *array* of *objects* - list of [calls to other contracts](Trace-Types.md#trace) containing
one object per call, in transaction execution order

!!! example

=== "curl HTTP request"

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"trace_callMany","params":[[[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]],[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]]],"latest"],"id":1}' http://127.0.0.1:8545
```

=== "wscat WS request"

```bash
{"jsonrpc":"2.0","method":"trace_callMany","params":[[[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]],[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]]],"latest"],"latest"],"id":1}
```

=== "JSON result"

```json
{
"jsonrpc": "2.0",
"result": [
{
"output" : "0x",
"stateDiff" : null,
"trace" : [ {
"action" : {
"callType" : "call",
"from" : "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
"gas" : "0x1dcd12f8",
"input" : "0x",
"to" : "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
"value" : "0x186a0"
},
"result" : {
"gasUsed" : "0x0",
"output" : "0x"
},
"subtraces" : 0,
"traceAddress" : [ ],
"type" : "call"
} ],
"vmTrace" : null
},
{
"output" : "0x",
"stateDiff" : null,
"trace" : [ {
"action" : {
"callType" : "call",
"from" : "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
"gas" : "0x1dcd12f8",
"input" : "0x",
"to" : "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
"value" : "0x186a0"
},
"result" : {
"gasUsed" : "0x0",
"output" : "0x"
},
"subtraces" : 0,
"traceAddress" : [ ],
"type" : "call"
} ],
"vmTrace" : null
},
],
"id" : 1
},
```

### `trace_filter`

Returns traces matching the specified filter.

!!! important

Your node must be an archive node (that is, synchronized without pruning or fast sync) or the
requested block must be within [the number of pruning blocks retained](../CLI/CLI-Syntax#pruning-blocks-retained)
(by default, 1024).

#### Parameters

`traceFilterOptions`: *object* - [trace filter options object](API-Objects.md#trace-filter-options-object)
Expand Down Expand Up @@ -7323,14 +7427,148 @@ one object per call, in transaction execution order
}
```

### `trace_get`

Returns trace at given position.

!!! important

Your node must be an archive node (that is, synchronized without pruning or fast sync) or the
requested transaction must be contained in a block within
[the number of pruning blocks retained](../CLI/CLI-Syntax#pruning-blocks-retained) (by default, 1024).

#### Parameters

* `transaction`: *string* - transaction hash

* `indexPositions`: *array* - Index positions of the traces

#### Returns

`result`: *array* of *objects* - list of [calls to other contracts](Trace-Types.md#trace) containing
one object per call, in the order called by the transaction

!!! example

=== "curl HTTP request"

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"trace_get","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",["0x0"]],"id":1}' http://127.0.0.1:8545
```

=== "wscat WS request"

```bash
{"jsonrpc":"2.0","method":"trace_get","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",["0x0"]],"id":1}
```

=== "JSON result"

```json
{
"jsonrpc": "2.0",
"result": {
"action" : {
"callType" : "call",
"from" : "0x1c39ba39e4735cb65978d4db400ddd70a72dc750",
"gas" : "0x13e99",
"input" : "0x16c72721",
"to" : "0x2bd2326c993dfaef84f696526064ff22eba5b362",
"value" : "0x0"
},
"blockHash" : "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add"
"blockNumber": 3068185,
"result": {
"gasUsed": "0x183",
"output" : "0x0000000000000000000000000000000000000000000000000000000000000001"
},
"subtraces" : 0,
"traceAddress" : [
0
],
"transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
"transactionPosition": 2,
"type" : "call"
},
"id" : 1
},
```

### `trace_rawTransaction`

Traces a call to `eth_sendRawTransaction` without making the call, returning the traces.

!!! important

The requested transaction must be contained in a block within
[the number of pruning blocks retained](../CLI/CLI-Syntax#pruning-blocks-retained) (by default, 1024).

#### Parameters

* `data` - *string* - Raw transaction data

* `options`: *array* of *strings* - list of tracing options; tracing options are
[`trace`, `vmTrace`, and `stateDiff`](Trace-Types.md). Specify any
combination of the three options including none of them.

#### Returns

`result`: *array* of *objects* - list of [calls to other contracts](Trace-Types.md#trace) containing
one object per call, in the order called by the transaction

!!! example

=== "curl HTTP request"

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"trace_get","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",["0x0"]],"id":1}' http://127.0.0.1:8545
```

=== "wscat WS request"

```bash
{"jsonrpc":"2.0","method":"trace_get","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",["0x0"]],"id":1}
```

=== "JSON result"

```json
{
"jsonrpc": "2.0",
"result": {
"action" : {
"callType" : "call",
"from" : "0x1c39ba39e4735cb65978d4db400ddd70a72dc750",
"gas" : "0x13e99",
"input" : "0x16c72721",
"to" : "0x2bd2326c993dfaef84f696526064ff22eba5b362",
"value" : "0x0"
},
"blockHash" : "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add"
"blockNumber": 3068185,
"result": {
"gasUsed": "0x183",
"output" : "0x0000000000000000000000000000000000000000000000000000000000000001"
},
"subtraces" : 0,
"traceAddress" : [
0
],
"transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
"transactionPosition": 2,
"type" : "call"
},
"id" : 1
},
```

### `trace_replayBlockTransactions`

Provides transaction processing tracing per block.

!!! important

Your node must be an archive node (that is, synchronized without pruning or fast sync) or the
requested block must be within [the number of pruning blocks retained](../CLI/CLI-Syntax#pruning-blocks-retained)
The requested block must be within [the number of pruning blocks retained](../CLI/CLI-Syntax#pruning-blocks-retained)
(by default, 1024).

#### Parameters
Expand Down
34 changes: 24 additions & 10 deletions docs/Reference/Trace-Types.md
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,17 @@
---
description: Tracing transactions
description: Transaction trace types
---

# Transaction trace types

When using
[`trace_replayBlockTransactions`](API-Methods.md#trace_replayblocktransactions) the
trace options are [`trace`](#trace), [`vmTrace`](#vmtrace), and [`stateDiff`](#statediff).

[`trace_block`](API-Methods.md#trace_block) and [`trace_transaction`](API-Methods.md#trace_transaction)
retrieve only the [`trace`](#trace) option.
When [tracing transactions](../HowTo/Troubleshoot/Trace-Transactions.md), the trace type options are
[`trace`](#trace), [`vmTrace`](#vmtrace), and [`stateDiff`](#statediff).

## trace

An ordered list of calls to other contracts, excluding precompiled contracts.

!!!example "trace Example"
!!!example "`trace` example"

```json
"trace":[
Expand Down Expand Up @@ -73,7 +69,7 @@ For out of gas operations, `vmTrace` reports the operation that caused the out o
including the calculated gas cost. `vmTrace` does not report `ex` values because the operation is
not executed.

!!!example "vmTrace Example"
!!!example "`vmTrace` example"

```json
"vmTrace":{
Expand Down Expand Up @@ -122,7 +118,7 @@ transaction to after the transaction. For the `key:value` pairs:

An absent value is distinct from zero when creating accounts or clearing storage.

!!!example "stateDiff Example"
!!!example "`stateDiff` example"

```json
"stateDiff":{
Expand Down Expand Up @@ -156,3 +152,21 @@ An absent value is distinct from zero when creating accounts or clearing storage
| `nonce.from` | Nonce before the transaction.
| `nonce.to` | Nonce after the transaction.
| `storage` | Changes to storage. None in this example.

## Applicable API methods

The trace options `trace`, `vmTrace`, and `stateDiff` are available for the following
[ad-hoc tracing API methods](../HowTo/Troubleshoot/Trace-Transactions.md#ad-hoc-tracing-apis):

* [`trace_call`](API-Methods.md#trace_call)
* [`trace_callMany`](API-Methods.md#trace_callmany)
* [`trace_rawTransaction`](API-Methods.md#trace_rawtransaction)
* [`trace_replayBlockTransactions`](API-Methods.md#trace_replayblocktransactions)

Only the `trace` option is available for the following
[transaction-trace filtering API methods](../HowTo/Troubleshoot/Trace-Transactions.md#transaction-trace-filtering-apis):

* [`trace_block`](API-Methods.md#trace_block)
* [`trace_filter`](API-Methods.md#trace_filter)
* [`trace_get`](API-Methods.md#trace_get)
* [`trace_transaction`](API-Methods.md#trace_transaction)

0 comments on commit f48e56f

Please sign in to comment.