github.com/amazechain/amc@v0.1.3/docs/jsonrpc/trace.md (about)

     1  # `trace` Namespace
     2  
     3  <!-- TODO: We should probably document the format of the traces themselves, OE does not do that !-->
     4  
     5  The `trace` API provides several methods to inspect the Ethereum state, including Parity-style traces.
     6  
     7  A similar module exists (with other debug functions) with Geth-style traces ([`debug`](./debug.md)).
     8  
     9  The `trace` API gives deeper insight into transaction processing.
    10  
    11  There are two types of methods in this API:
    12  
    13  - **Ad-hoc tracing APIs** for performing diagnostics on calls or transactions (historical or hypothetical).
    14  - **Transaction-trace filtering APIs** for getting full externality traces on any transaction executed by reth.
    15  
    16  ## Ad-hoc tracing APIs
    17  
    18  Ad-hoc tracing APIs allow you to perform diagnostics on calls or transactions (historical or hypothetical), including:
    19  
    20  - Transaction traces (`trace`)
    21  - VM traces (`vmTrace`)
    22  - State difference traces (`stateDiff`)
    23  
    24  The ad-hoc tracing APIs are:
    25  
    26  - [`trace_call`](#trace_call)
    27  - [`trace_callMany`](#trace_callmany)
    28  - [`trace_rawTransaction`](#trace_rawtransaction)
    29  - [`trace_replayBlockTransactions`](#trace_replayblocktransactions)
    30  - [`trace_replayTransaction`](#trace_replaytransaction)
    31  
    32  ## Transaction-trace filtering APIs
    33  
    34  Transaction trace filtering APIs are similar to log filtering APIs in the `eth` namespace, except these allow you to search and filter based only upon address information.
    35  
    36  Information returned includes the execution of all contract creations, destructions, and calls, together with their input data, output data, gas usage, transfer amounts and success statuses.
    37  
    38  The transaction trace filtering APIs are:
    39  
    40  - [`trace_block`](#trace_block)
    41  - [`trace_filter`](#trace_filter)
    42  - [`trace_get`](#trace_get)
    43  - [`trace_transaction`](#trace_transaction)
    44  
    45  ## `trace_call`
    46  
    47  Executes the given call and returns a number of possible traces for it.
    48  
    49  The first parameter is a transaction object where the `from` field is optional and the `nonce` field is ommitted.
    50  
    51  The second parameter is an array of one or more trace types (`vmTrace`, `trace`, `stateDiff`).
    52  
    53  The third and optional parameter is a block number, block hash, or a block tag (`latest`, `finalized`, `safe`, `earliest`, `pending`).
    54  
    55  | Client | Method invocation                                         |
    56  |--------|-----------------------------------------------------------|
    57  | RPC    | `{"method": "trace_call", "params": [tx, type[], block]}` |
    58  
    59  ### Example
    60  
    61  ```js
    62  // > {"jsonrpc":"2.0","id":1,"method":"trace_call","params":[{},["trace"]}
    63  {
    64      "id": 1,
    65      "jsonrpc": "2.0",
    66      "result": {
    67          "output": "0x",
    68          "stateDiff": null,
    69          "trace": [{
    70              "action": { ... },
    71              "result": {
    72                  "gasUsed": "0x0",
    73                  "output": "0x"
    74              },
    75              "subtraces": 0,
    76              "traceAddress": [],
    77              "type": "call"
    78          }],
    79          "vmTrace": null
    80      }
    81  }
    82  ```
    83  
    84  ## `trace_callMany`
    85  
    86  Performs multiple call traces on top of the same block, that is, transaction `n` will be executed on top of a pending block with all `n - 1` transaction applied (and traced) first.
    87  
    88  The first parameter is a list of call traces, where each call trace is of the form `[tx, type[]]` (see [`trace_call`](#trace_call)).
    89  
    90  The second and optional parameter is a block number, block hash, or a block tag (`latest`, `finalized`, `safe`, `earliest`, `pending`).
    91  
    92  | Client | Method invocation                                      |
    93  |--------|--------------------------------------------------------|
    94  | RPC    | `{"method": "trace_call", "params": [trace[], block]}` |
    95  
    96  ### Example
    97  
    98  ```js
    99  // > {"jsonrpc":"2.0","id":1,"method":"trace_callMany","params":[[[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]],[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]]],"latest"]}
   100  {
   101      "id": 1,
   102      "jsonrpc": "2.0",
   103      "result": [
   104          {
   105              "output": "0x",
   106              "stateDiff": null,
   107              "trace": [{
   108                  "action": {
   109                      "callType": "call",
   110                      "from": "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
   111                      "gas": "0x1dcd12f8",
   112                      "input": "0x",
   113                      "to": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
   114                      "value": "0x186a0"
   115                  },
   116                  "result": {
   117                      "gasUsed": "0x0",
   118                      "output": "0x"
   119                  },
   120                  "subtraces": 0,
   121                  "traceAddress": [],
   122                  "type": "call"
   123              }],
   124              "vmTrace": null
   125          },
   126          {
   127              "output": "0x",
   128              "stateDiff": null,
   129              "trace": [{
   130                  "action": {
   131                      "callType": "call",
   132                      "from": "0x407d73d8a49eeb85d32cf465507dd71d507100c1",
   133                      "gas": "0x1dcd12f8",
   134                      "input": "0x",
   135                      "to": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
   136                      "value": "0x186a0"
   137                  },
   138                  "result": {
   139                      "gasUsed": "0x0",
   140                      "output": "0x"
   141                  },
   142                  "subtraces": 0,
   143                  "traceAddress": [],
   144                  "type": "call"
   145              }],
   146              "vmTrace": null
   147          }
   148      ]
   149  }
   150  ```
   151  
   152  ## `trace_rawTransaction`
   153  
   154  Traces a call to `eth_sendRawTransaction` without making the call, returning the traces.
   155  
   156  | Client | Method invocation                                      |
   157  |--------|--------------------------------------------------------|
   158  | RPC    | `{"method": "trace_call", "params": [raw_tx, type[]]}` |
   159  
   160  ### Example
   161  
   162  ```js
   163  // > {"jsonrpc":"2.0","id":1,"method":"trace_rawTransaction","params":["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675",["trace"]]}
   164  {
   165      "id": 1,
   166      "jsonrpc": "2.0",
   167      "result": {
   168          "output": "0x",
   169              "stateDiff": null,
   170              "trace": [{
   171              "action": { ... },
   172              "result": {
   173                  "gasUsed": "0x0",
   174                  "output": "0x"
   175              },
   176              "subtraces": 0,
   177              "traceAddress": [],
   178              "type": "call"
   179          }],
   180              "vmTrace": null
   181      }
   182  }
   183  ```
   184  
   185  ## `trace_replayBlockTransactions`
   186  
   187  Replays all transactions in a block returning the requested traces for each transaction.
   188  
   189  | Client | Method invocation                                                        |
   190  |--------|--------------------------------------------------------------------------|
   191  | RPC    | `{"method": "trace_replayBlockTransactions", "params": [block, type[]]}` |
   192  
   193  ### Example
   194  
   195  ```js
   196  // > {"jsonrpc":"2.0","id":1,"method":"trace_replayBlockTransactions","params":["0x2ed119",["trace"]]}
   197  {
   198      "id": 1,
   199      "jsonrpc": "2.0",
   200      "result": [
   201          {
   202              "output": "0x",
   203              "stateDiff": null,
   204              "trace": [{
   205                  "action": { ... },
   206                  "result": {
   207                      "gasUsed": "0x0",
   208                      "output": "0x"
   209                  },
   210                  "subtraces": 0,
   211                  "traceAddress": [],
   212                  "type": "call"
   213              }],
   214              "transactionHash": "0x...",
   215              "vmTrace": null
   216          },
   217          { ... }
   218      ]
   219  }
   220  ```
   221  
   222  ## `trace_replayTransaction`
   223  
   224  Replays a transaction, returning the traces.
   225  
   226  | Client | Method invocation                                                    |
   227  |--------|----------------------------------------------------------------------|
   228  | RPC    | `{"method": "trace_replayTransaction", "params": [tx_hash, type[]]}` |
   229  
   230  ### Example
   231  
   232  ```js
   233  // > {"jsonrpc":"2.0","id":1,"method":"trace_replayTransaction","params":["0x02d4a872e096445e80d05276ee756cefef7f3b376bcec14246469c0cd97dad8f",["trace"]]}
   234  {
   235      "id": 1,
   236      "jsonrpc": "2.0",
   237      "result": {
   238          "output": "0x",
   239          "stateDiff": null,
   240          "trace": [{
   241              "action": { ... },
   242              "result": {
   243                  "gasUsed": "0x0",
   244                  "output": "0x"
   245              },
   246              "subtraces": 0,
   247              "traceAddress": [],
   248              "type": "call"
   249          }],
   250          "vmTrace": null
   251      }
   252  }
   253  ```
   254  
   255  ## `trace_block`
   256  
   257  Returns traces created at given block.
   258  
   259  | Client | Method invocation                              |
   260  |--------|------------------------------------------------|
   261  | RPC    | `{"method": "trace_block", "params": [block]}` |
   262  
   263  ### Example
   264  
   265  ```js
   266  // > {"jsonrpc":"2.0","id":1,"method":"trace_block","params":["0x2ed119"]}
   267  {
   268      "id": 1,
   269      "jsonrpc": "2.0",
   270      "result": [
   271          {
   272              "action": {
   273                  "callType": "call",
   274                  "from": "0xaa7b131dc60b80d3cf5e59b5a21a666aa039c951",
   275                  "gas": "0x0",
   276                  "input": "0x",
   277                  "to": "0xd40aba8166a212d6892125f079c33e6f5ca19814",
   278                  "value": "0x4768d7effc3fbe"
   279              },
   280              "blockHash": "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add",
   281              "blockNumber": 3068185,
   282              "result": {
   283                  "gasUsed": "0x0",
   284                  "output": "0x"
   285              },
   286              "subtraces": 0,
   287              "traceAddress": [],
   288              "transactionHash": "0x07da28d752aba3b9dd7060005e554719c6205c8a3aea358599fc9b245c52f1f6",
   289              "transactionPosition": 0,
   290              "type": "call"
   291          },
   292          ...
   293      ]
   294  }
   295  ```
   296  
   297  ## `trace_filter`
   298  
   299  Returns traces matching given filter.
   300  
   301  Filters are objects with the following properties:
   302  
   303  - `fromBlock`: Returns traces from the given block (a number, hash, or a tag like `latest`).
   304  - `toBlock`: Returns traces to the given block.
   305  - `fromAddress`: Sent from these addresses
   306  - `toAddress`: Sent to these addresses
   307  - `after`: The offset trace number
   308  - `count`: The number of traces to display in a batch
   309  
   310  All properties are optional.
   311  
   312  | Client | Method invocation                                |
   313  |--------|--------------------------------------------------|
   314  | RPC    | `{"method": "trace_filter", "params": [filter]}` |
   315  
   316  ### Example
   317  
   318  ```js
   319  // > {"jsonrpc":"2.0","id":1,"method":"trace_filter","params":[{"fromBlock":"0x2ed0c4","toBlock":"0x2ed128","toAddress":["0x8bbB73BCB5d553B5A556358d27625323Fd781D37"],"after":1000,"count":100}]}
   320  {
   321      "id": 1,
   322      "jsonrpc": "2.0",
   323      "result": [
   324          {
   325              "action": {
   326                  "callType": "call",
   327                  "from": "0x32be343b94f860124dc4fee278fdcbd38c102d88",
   328                  "gas": "0x4c40d",
   329                  "input": "0x",
   330                  "to": "0x8bbb73bcb5d553b5a556358d27625323fd781d37",
   331                  "value": "0x3f0650ec47fd240000"
   332              },
   333              "blockHash": "0x86df301bcdd8248d982dbf039f09faf792684e1aeee99d5b58b77d620008b80f",
   334              "blockNumber": 3068183,
   335              "result": {
   336                  "gasUsed": "0x0",
   337                  "output": "0x"
   338              },
   339              "subtraces": 0,
   340              "traceAddress": [],
   341              "transactionHash": "0x3321a7708b1083130bd78da0d62ead9f6683033231617c9d268e2c7e3fa6c104",
   342              "transactionPosition": 3,
   343              "type": "call"
   344          },
   345          ...
   346      ]
   347  }
   348  ```
   349  
   350  ## `trace_get`
   351  
   352  Returns trace at given position.
   353  
   354  | Client | Method invocation                                        |
   355  |--------|----------------------------------------------------------|
   356  | RPC    | `{"method": "trace_get", "params": [tx_hash,indices[]]}` |
   357  
   358  ### Example
   359  
   360  ```js
   361  // > {"jsonrpc":"2.0","id":1,"method":"trace_get","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",["0x0"]]}
   362  {
   363      "id": 1,
   364      "jsonrpc": "2.0",
   365      "result": {
   366          "action": {
   367              "callType": "call",
   368              "from": "0x1c39ba39e4735cb65978d4db400ddd70a72dc750",
   369              "gas": "0x13e99",
   370              "input": "0x16c72721",
   371              "to": "0x2bd2326c993dfaef84f696526064ff22eba5b362",
   372              "value": "0x0"
   373          },
   374          "blockHash": "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add",
   375              "blockNumber": 3068185,
   376              "result": {
   377              "gasUsed": "0x183",
   378              "output": "0x0000000000000000000000000000000000000000000000000000000000000001"
   379          },
   380          "subtraces": 0,
   381              "traceAddress": [
   382              0
   383          ],
   384          "transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
   385          "transactionPosition": 2,
   386          "type": "call"
   387      }
   388  }
   389  ```
   390  
   391  ## `trace_transaction`
   392  
   393  Returns all traces of given transaction
   394  
   395  | Client | Method invocation                                      |
   396  |--------|--------------------------------------------------------|
   397  | RPC    | `{"method": "trace_transaction", "params": [tx_hash]}` |
   398  
   399  ### Example
   400  
   401  ```js
   402  // > {"jsonrpc":"2.0","id":1,"method":"trace_transaction","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3"]}
   403  {
   404      "id": 1,
   405      "jsonrpc": "2.0",
   406      "result": [
   407          {
   408              "action": {
   409                  "callType": "call",
   410                  "from": "0x1c39ba39e4735cb65978d4db400ddd70a72dc750",
   411                  "gas": "0x13e99",
   412                  "input": "0x16c72721",
   413                  "to": "0x2bd2326c993dfaef84f696526064ff22eba5b362",
   414                  "value": "0x0"
   415              },
   416              "blockHash": "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add",
   417              "blockNumber": 3068185,
   418              "result": {
   419                  "gasUsed": "0x183",
   420                  "output": "0x0000000000000000000000000000000000000000000000000000000000000001"
   421              },
   422              "subtraces": 0,
   423              "traceAddress": [
   424                  0
   425              ],
   426              "transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
   427              "transactionPosition": 2,
   428              "type": "call"
   429          },
   430          ...
   431      ]
   432  }
   433  ```