Skip to content

Commit f48e56f

Browse files
rolandtylermacfarla
rolandtyler
and
macfarla
authored
Document Trace APIs (#971)
* Document Trace APIs Signed-off-by: Roland Tyler <[email protected]> Co-authored-by: Sally MacFarlane <[email protected]>
1 parent 7ad2bbf commit f48e56f

File tree

3 files changed

+296
-25
lines changed

3 files changed

+296
-25
lines changed

‎docs/HowTo/Troubleshoot/Trace-Transactions.md‎

Lines changed: 32 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,25 +5,44 @@ description: How to trace transactions
55
# Trace transactions
66

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

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

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

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

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

26-
!!! important
25+
The ad-hoc tracing APIs are:
2726

28-
The `TRACE` API is an early access feature in v1.4. The return values might change between v1.4
29-
and v1.5.
27+
* [trace_call](../../Reference/API-Methods.md#trace_call)
28+
* [trace_callMany](../../Reference/API-Methods.md#trace_callmany)
29+
* [trace_rawTransaction](../../Reference/API-Methods.md#trace_rawtransaction)
30+
* [trace_replayBlockTransactions](../../Reference/API-Methods.md#trace_replayblocktransactions)
31+
32+
## Transaction-trace filtering APIs
33+
34+
These APIs allow you to filter and search by specific information such as the block, address, or transaction.
35+
These APIs only use the [`trace` type](../../Reference/Trace-Types.md#trace).
36+
37+
To use the transaction-trace filtering APIs, your node must be an archive node
38+
(that is, synchronized without pruning or fast sync) or the
39+
requested block or transaction must be within the
40+
[the number of pruning blocks retained](../../Reference/CLI/CLI-Syntax.md#pruning-blocks-retained)
41+
(by default, 1024).
42+
43+
The transaction-trace filtering APIs are:
44+
45+
* [trace_block](../../Reference/API-Methods.md#trace_block)
46+
* [trace_filter](../../Reference/API-Methods.md#trace_filter)
47+
* [trace_get](../../Reference/API-Methods.md#trace_get)
48+
* [trace_transaction](../../Reference/API-Methods.md#trace_transaction)

‎docs/Reference/API-Methods.md‎

Lines changed: 240 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7181,6 +7181,11 @@ the returned list items include the [revert reason](../HowTo/Send-Transactions/R
71817181

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

7184+
!!! important
7185+
7186+
The requested transaction must be contained in a block within [the number of pruning blocks retained](../CLI/CLI-Syntax#pruning-blocks-retained)
7187+
(by default, 1024).
7188+
71847189
#### Parameters
71857190

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

7251+
### `trace_callMany`
7252+
7253+
Performs multiple call traces on top of the same block. You can trace dependent transactions.
7254+
7255+
!!! important
7256+
7257+
The requested block must be within [the number of pruning blocks retained](../CLI/CLI-Syntax#pruning-blocks-retained)
7258+
(by default, 1024).
7259+
7260+
#### Parameters
7261+
7262+
* `options`: *array* of *strings* - list of tracing options; tracing options are
7263+
[`trace`, `vmTrace`, and `stateDiff`](Trace-Types.md). Specify any
7264+
combination of the three options including none of them.
7265+
7266+
* `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`,
7267+
`earliest`, or `pending`, as described in
7268+
[Block Parameter](../HowTo/Interact/APIs/Using-JSON-RPC-API.md#block-parameter)
7269+
7270+
#### Returns
7271+
7272+
`result`: *array* of *objects* - list of [calls to other contracts](Trace-Types.md#trace) containing
7273+
one object per call, in transaction execution order
7274+
7275+
!!! example
7276+
7277+
=== "curl HTTP request"
7278+
7279+
```bash
7280+
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
7281+
```
7282+
7283+
=== "wscat WS request"
7284+
7285+
```bash
7286+
{"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}
7287+
```
7288+
7289+
=== "JSON result"
7290+
7291+
```json
7292+
{
7293+
"jsonrpc": "2.0",
7294+
"result": [
7295+
{
7296+
"output" : "0x",
7297+
"stateDiff" : null,
7298+
"trace" : [ {
7299+
"action" : {
7300+
"callType" : "call",
7301+
"from" : "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
7302+
"gas" : "0x1dcd12f8",
7303+
"input" : "0x",
7304+
"to" : "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
7305+
"value" : "0x186a0"
7306+
},
7307+
"result" : {
7308+
"gasUsed" : "0x0",
7309+
"output" : "0x"
7310+
},
7311+
"subtraces" : 0,
7312+
"traceAddress" : [ ],
7313+
"type" : "call"
7314+
} ],
7315+
"vmTrace" : null
7316+
},
7317+
{
7318+
"output" : "0x",
7319+
"stateDiff" : null,
7320+
"trace" : [ {
7321+
"action" : {
7322+
"callType" : "call",
7323+
"from" : "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
7324+
"gas" : "0x1dcd12f8",
7325+
"input" : "0x",
7326+
"to" : "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
7327+
"value" : "0x186a0"
7328+
},
7329+
"result" : {
7330+
"gasUsed" : "0x0",
7331+
"output" : "0x"
7332+
},
7333+
"subtraces" : 0,
7334+
"traceAddress" : [ ],
7335+
"type" : "call"
7336+
} ],
7337+
"vmTrace" : null
7338+
},
7339+
],
7340+
"id" : 1
7341+
},
7342+
```
7343+
72467344
### `trace_filter`
72477345

72487346
Returns traces matching the specified filter.
72497347

7348+
!!! important
7349+
7350+
Your node must be an archive node (that is, synchronized without pruning or fast sync) or the
7351+
requested block must be within [the number of pruning blocks retained](../CLI/CLI-Syntax#pruning-blocks-retained)
7352+
(by default, 1024).
7353+
72507354
#### Parameters
72517355

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

7430+
### `trace_get`
7431+
7432+
Returns trace at given position.
7433+
7434+
!!! important
7435+
7436+
Your node must be an archive node (that is, synchronized without pruning or fast sync) or the
7437+
requested transaction must be contained in a block within
7438+
[the number of pruning blocks retained](../CLI/CLI-Syntax#pruning-blocks-retained) (by default, 1024).
7439+
7440+
#### Parameters
7441+
7442+
* `transaction`: *string* - transaction hash
7443+
7444+
* `indexPositions`: *array* - Index positions of the traces
7445+
7446+
#### Returns
7447+
7448+
`result`: *array* of *objects* - list of [calls to other contracts](Trace-Types.md#trace) containing
7449+
one object per call, in the order called by the transaction
7450+
7451+
!!! example
7452+
7453+
=== "curl HTTP request"
7454+
7455+
```bash
7456+
curl -X POST --data '{"jsonrpc":"2.0","method":"trace_get","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",["0x0"]],"id":1}' http://127.0.0.1:8545
7457+
```
7458+
7459+
=== "wscat WS request"
7460+
7461+
```bash
7462+
{"jsonrpc":"2.0","method":"trace_get","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",["0x0"]],"id":1}
7463+
```
7464+
7465+
=== "JSON result"
7466+
7467+
```json
7468+
{
7469+
"jsonrpc": "2.0",
7470+
"result": {
7471+
"action" : {
7472+
"callType" : "call",
7473+
"from" : "0x1c39ba39e4735cb65978d4db400ddd70a72dc750",
7474+
"gas" : "0x13e99",
7475+
"input" : "0x16c72721",
7476+
"to" : "0x2bd2326c993dfaef84f696526064ff22eba5b362",
7477+
"value" : "0x0"
7478+
},
7479+
"blockHash" : "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add"
7480+
"blockNumber": 3068185,
7481+
"result": {
7482+
"gasUsed": "0x183",
7483+
"output" : "0x0000000000000000000000000000000000000000000000000000000000000001"
7484+
},
7485+
"subtraces" : 0,
7486+
"traceAddress" : [
7487+
0
7488+
],
7489+
"transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
7490+
"transactionPosition": 2,
7491+
"type" : "call"
7492+
},
7493+
"id" : 1
7494+
},
7495+
```
7496+
7497+
### `trace_rawTransaction`
7498+
7499+
Traces a call to `eth_sendRawTransaction` without making the call, returning the traces.
7500+
7501+
!!! important
7502+
7503+
The requested transaction must be contained in a block within
7504+
[the number of pruning blocks retained](../CLI/CLI-Syntax#pruning-blocks-retained) (by default, 1024).
7505+
7506+
#### Parameters
7507+
7508+
* `data` - *string* - Raw transaction data
7509+
7510+
* `options`: *array* of *strings* - list of tracing options; tracing options are
7511+
[`trace`, `vmTrace`, and `stateDiff`](Trace-Types.md). Specify any
7512+
combination of the three options including none of them.
7513+
7514+
#### Returns
7515+
7516+
`result`: *array* of *objects* - list of [calls to other contracts](Trace-Types.md#trace) containing
7517+
one object per call, in the order called by the transaction
7518+
7519+
!!! example
7520+
7521+
=== "curl HTTP request"
7522+
7523+
```bash
7524+
curl -X POST --data '{"jsonrpc":"2.0","method":"trace_get","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",["0x0"]],"id":1}' http://127.0.0.1:8545
7525+
```
7526+
7527+
=== "wscat WS request"
7528+
7529+
```bash
7530+
{"jsonrpc":"2.0","method":"trace_get","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",["0x0"]],"id":1}
7531+
```
7532+
7533+
=== "JSON result"
7534+
7535+
```json
7536+
{
7537+
"jsonrpc": "2.0",
7538+
"result": {
7539+
"action" : {
7540+
"callType" : "call",
7541+
"from" : "0x1c39ba39e4735cb65978d4db400ddd70a72dc750",
7542+
"gas" : "0x13e99",
7543+
"input" : "0x16c72721",
7544+
"to" : "0x2bd2326c993dfaef84f696526064ff22eba5b362",
7545+
"value" : "0x0"
7546+
},
7547+
"blockHash" : "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add"
7548+
"blockNumber": 3068185,
7549+
"result": {
7550+
"gasUsed": "0x183",
7551+
"output" : "0x0000000000000000000000000000000000000000000000000000000000000001"
7552+
},
7553+
"subtraces" : 0,
7554+
"traceAddress" : [
7555+
0
7556+
],
7557+
"transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
7558+
"transactionPosition": 2,
7559+
"type" : "call"
7560+
},
7561+
"id" : 1
7562+
},
7563+
```
7564+
73267565
### `trace_replayBlockTransactions`
73277566

73287567
Provides transaction processing tracing per block.
73297568

73307569
!!! important
73317570

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

73367574
#### Parameters

‎docs/Reference/Trace-Types.md‎

Lines changed: 24 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,17 @@
11
---
2-
description: Tracing transactions
2+
description: Transaction trace types
33
---
44

55
# Transaction trace types
66

7-
When using
8-
[`trace_replayBlockTransactions`](API-Methods.md#trace_replayblocktransactions) the
9-
trace options are [`trace`](#trace), [`vmTrace`](#vmtrace), and [`stateDiff`](#statediff).
10-
11-
[`trace_block`](API-Methods.md#trace_block) and [`trace_transaction`](API-Methods.md#trace_transaction)
12-
retrieve only the [`trace`](#trace) option.
7+
When [tracing transactions](../HowTo/Troubleshoot/Trace-Transactions.md), the trace type options are
8+
[`trace`](#trace), [`vmTrace`](#vmtrace), and [`stateDiff`](#statediff).
139

1410
## trace
1511

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

18-
!!!example "trace Example"
14+
!!!example "`trace` example"
1915

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

76-
!!!example "vmTrace Example"
72+
!!!example "`vmTrace` example"
7773

7874
```json
7975
"vmTrace":{
@@ -122,7 +118,7 @@ transaction to after the transaction. For the `key:value` pairs:
122118

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

125-
!!!example "stateDiff Example"
121+
!!!example "`stateDiff` example"
126122

127123
```json
128124
"stateDiff":{
@@ -156,3 +152,21 @@ An absent value is distinct from zero when creating accounts or clearing storage
156152
| `nonce.from` | Nonce before the transaction.
157153
| `nonce.to` | Nonce after the transaction.
158154
| `storage` | Changes to storage. None in this example.
155+
156+
## Applicable API methods
157+
158+
The trace options `trace`, `vmTrace`, and `stateDiff` are available for the following
159+
[ad-hoc tracing API methods](../HowTo/Troubleshoot/Trace-Transactions.md#ad-hoc-tracing-apis):
160+
161+
* [`trace_call`](API-Methods.md#trace_call)
162+
* [`trace_callMany`](API-Methods.md#trace_callmany)
163+
* [`trace_rawTransaction`](API-Methods.md#trace_rawtransaction)
164+
* [`trace_replayBlockTransactions`](API-Methods.md#trace_replayblocktransactions)
165+
166+
Only the `trace` option is available for the following
167+
[transaction-trace filtering API methods](../HowTo/Troubleshoot/Trace-Transactions.md#transaction-trace-filtering-apis):
168+
169+
* [`trace_block`](API-Methods.md#trace_block)
170+
* [`trace_filter`](API-Methods.md#trace_filter)
171+
* [`trace_get`](API-Methods.md#trace_get)
172+
* [`trace_transaction`](API-Methods.md#trace_transaction)

0 commit comments

Comments
 (0)