diff --git a/docs/Concepts/Transactions/Trace-Types.md b/docs/Concepts/Transactions/Trace-Types.md new file mode 100644 index 00000000000..3d23f8f9f90 --- /dev/null +++ b/docs/Concepts/Transactions/Trace-Types.md @@ -0,0 +1,146 @@ +description: Tracing transactions + + +# Transaction Trace Types + +When using [`trace_replayBlockTransactions`](../../Reference/API-Methods.md#trace_replayblocktransactions) +the trace options are [`trace`](#trace), [`vmTrace`](#vmtrace), and [`stateDiff`](#statediff). + +## trace + +Ordered list of calls to other contracts excluding precompiled contracts. + +```json tab="trace Example" +"trace":[ + { + "action":{ + "callType":"call", + "from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas":"0xffadea", + "input":"0x", + "to":"0x0100000000000000000000000000000000000000", + "value":"0x0" + }, + "result":{ + "gasUsed":"0x1e", + "output":"0x" + }, + "subtraces":0, + "traceAddress":[ + ], + "type":"call" + } +] +``` + +| Key | Value | +|----------------| --------------------------------------------------------------------------------------| +| `action` | Transaction details. +| `callType` | Indicates whether the transaction is `call` or `create`. +| `from` | Address from which transaction was sent. +| `gas` | Gas provided by sender. +| `input` | Transaction data. +| `to` | Target of the transaction. +| `value` | Value transferred in transaction. +| `result` | Transaction result. +| `gasUsed` | Gas used by the transaction. Includes any refunds of unused gas. +| `output` | Return value of contract call. Contains only the actual value sent by a `RETURN` operation. If a `RETURN` was not executed, the output is empty bytes. +| `subTraces` | Traces of contract calls made by the transaction. +| `traceAddress` | Tree list address of where the call occurred, address of the parents, and order of the current sub call. +| `type` | Indicates whether the transaction is a `CALL` or `CREATE` series operation. + +## vmTrace + +Ordered list of EVM actions when processing the transaction. + +Besu only reports actual data returned from a `RETURN` opcode. Besu does not +return the contents of the reserved output space for the call operations. As a result: + +* Besu reports null when a call operation ends because of a `STOP`, `HALT`, `REVERT`, running out of +instructions, or any exceptional halts. +* When a `RETURN` operation returns data of a different length to the space reserved by the call, only +the data passed to the `RETURN` operation is reported. Besu does not include pre-existing memory data +or trim the returned data. + +For out of gas operations, Besu reports the operation that caused the out of gas exception including +the calculated gas cost. No `ex` values are reported because the operation is not executed. + +```json tab="vmTrace Example" +"vmTrace":{ + "code":"0x7f3940be4289e4c3587d88c1856cc95352461992db0a584c281226faefe560b3016000527f14c4d2c102bdeb2354bfc3dc96a95e4512cf3a8461e0560e2272dbf884ef3905601052600851", + "ops":[ + { + "cost":3, + "ex":{ + "mem":null, + "push":[ + "0x8" + ], + "store":null, + "used":16756175 + }, + "pc":72, + "sub":null + }, + ... + ] +} +``` + +| Key | Value | +|-----------| --------------------------------------------------------------------------------------| +| `code` | Code executed by the EVM. +| `ops` | Sequence of EVM operations (opcodes) executed in the transaction. +| `cost` | Gas cost of the opcode. Includes memory expansion costs but not gas refunds. For precompiled contract calls, reports only the actual cost. +| `ex` | Executed operations. +| `mem` | Memory read or written by the operation. +| `push` | Adjusted stack items. For swap, includes all intermediate values and end result. Otherwise, is the value pushed onto stack. +| `store` | Account storage written by the operation. +| `used` | Remaining gas taking into account the all but 1/64th rule for calls. +| `pc` | Program counter. +| `sub` | Sub call operations. + +## stateDiff + +State changes in the requested block for each transaction represented as +a map of accounts to an object. The balance, code, nonce, and storage changes are enumerated +from immediately before the transaction to after the transaction. For the `key:value` pairs: + +* `+` indicates the field didn’t exist before and now has the specified value +* `-` indicates the value was deleted +* `*` has a from and a to value. + +An absent value is distinct from zero when accounts or storage are created or cleared. + +```json tab="stateDiff Example" +"stateDiff":{ + "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73":{ + "balance":{ + "*":{ + "from":"0xffffffffffffffffffffffffffffffffc3e12a20b", + "to":"0xffffffffffffffffffffffffffffffffc3dc5f091" + } + }, + "code":"=", + "nonce":{ + "*":{ + "from":"0x14", + "to":"0x15" + } + }, + "storage":{ + } + } +} +``` + +| Key | Value | +|----------- | --------------------------------------------------------------------------------------| +| `balance` | Change of balance event. +| `balance.from` | Balance before transaction. +| `balance.to` | Balance after transaction. +| `code` | Changes to code. None in this example. +| `nonce` | Change of nonce. +| `nonce.from` | Nonce before transaction. +| `nonce.to` | Nonce after transaction. +| `storage` | Changes to storage. None in this example. diff --git a/docs/HowTo/Troubleshoot/Trace-Transactions.md b/docs/HowTo/Troubleshoot/Trace-Transactions.md new file mode 100644 index 00000000000..b4bd3747827 --- /dev/null +++ b/docs/HowTo/Troubleshoot/Trace-Transactions.md @@ -0,0 +1,19 @@ +description: How to trace transactions + + +# Trace Transactions + +Use the [`TRACE` API](../../Reference/API-Methods.md#trace-methods) to get detailed information about +transaction processing. Enable the [`TRACE` API](../../Reference/API-Methods.md#trace-methods) 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. + +Use the [`trace_replayBlockTransactions`](../../Reference/API-Methods.md#trace_replayblocktransactions) +JSON RPC API method and specify the trace types required. Options are [`trace`, `vmTrace`, or `stateDiff`](../../Concepts/Transactions/Trace-Types.md). + +Your node must be an archive node (that is, synchronised without pruning or fast sync) +or the requested block must be within the last 1024 blocks. + +!!! important + The `TRACE` API is an early access feature in 1.4. The return values may change between v1.4 and + v1.5. \ No newline at end of file diff --git a/docs/Reference/API-Methods.md b/docs/Reference/API-Methods.md index be56f24736d..b2e7f0752b6 100644 --- a/docs/Reference/API-Methods.md +++ b/docs/Reference/API-Methods.md @@ -3103,6 +3103,8 @@ If the boolean value is `true`, the proposal is to add a signer. If `false`, the !!! note The `DEBUG` API methods are not enabled by default for JSON-RPC. Use the [`--rpc-http-api`](CLI/CLI-Syntax.md#rpc-http-api) or [`--rpc-ws-api`](CLI/CLI-Syntax.md#rpc-ws-api) options to enable the `DEBUG` API methods. + + The DEBUG API is an more verbose alternative to the [TRACE API](#trace-methods). ### debug_accountRange @@ -3825,7 +3827,6 @@ parameter to the latest block. } ``` - ## Permissioning Methods The permissioning API methods are used for [local](../HowTo/Limit-Access/Local-Permissioning.md) permissioning only. @@ -4142,6 +4143,116 @@ None } ``` +## Trace Methods + +!!! note + The `TRACE` API methods are not enabled by default for JSON-RPC. Use the [`--rpc-http-api`](CLI/CLI-Syntax.md#rpc-http-api) + or [`--rpc-ws-api`](CLI/CLI-Syntax.md#rpc-ws-api) options to enable the `TRACE` API methods. + + The TRACE API is an more concise alternative to the [DEBUG API](#debug-methods). + +### trace_replayBlockTransactions + +Provides transaction processing tracing. + +!!! important + Your node must be an archive node (that is, synchronised without pruning or fast sync) + or the requested block must be within the last 1024 blocks. + +**Parameters** + +`quantity|tag` - 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). + +`array of strings` - Tracing options are [`trace`, `vmTrace`, and `stateDiff`](../Concepts/Transactions/Trace-Types.md). +Specify any combination of the three options including none of them. + +**Returns** + +`result` - Array of [transaction trace objects](API-Objects.md#transaction-trace-object) containing one object +per transaction in the order the transactions were executed. + +!!! example + ```bash tab="curl HTTP request" + curl -X POST --data '{"jsonrpc": "2.0", "method": "trace_replayBlockTransactions","params": ["0x12",["trace","vmTrace","stateDiff"]],"id": 1}' http://127.0.0.1:8545 + ``` + + ```bash tab="wscat WS request" + {"jsonrpc": "2.0", "method": "trace_replayBlockTransactions","params": ["0x12",["trace","vmTrace","stateDiff"]],"id": 1} + ``` + + ```json tab="JSON result" + { + "jsonrpc": "2.0", + "id": 1, + "result":[ + { + "output":"0x", + "vmTrace":{ + "code":"0x7f3940be4289e4c3587d88c1856cc95352461992db0a584c281226faefe560b3016000527f14c4d2c102bdeb2354bfc3dc96a95e4512cf3a8461e0560e2272dbf884ef3905601052600851", + "ops":[ + { + "cost":3, + "ex":{ + "mem":null, + "push":[ + "0x8" + ], + "store":null, + "used":16756175 + }, + "pc":72, + "sub":null + }, + ... + ] + }, + "trace":[ + { + "action":{ + "callType":"call", + "from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas":"0xffadea", + "input":"0x", + "to":"0x0100000000000000000000000000000000000000", + "value":"0x0" + }, + "result":{ + "gasUsed":"0x1e", + "output":"0x" + }, + "subtraces":0, + "traceAddress":[ + ], + "type":"call" + } + ], + "stateDiff":{ + "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73":{ + "balance":{ + "*":{ + "from":"0xffffffffffffffffffffffffffffffffc3e12a20b", + "to":"0xffffffffffffffffffffffffffffffffc3dc5f091" + } + }, + "code":"=", + "nonce":{ + "*":{ + "from":"0x14", + "to":"0x15" + } + }, + "storage":{ + } + } + }, + "transactionHash":"0x2a5079cc535c429f668f13a7fb9a28bdba6831b5462bd04f781777b332a8fcbd", + }, + {...} + ] + } + ``` + ## EEA Methods !!! note diff --git a/docs/Reference/API-Objects.md b/docs/Reference/API-Objects.md index 34bd1ff208b..41740d048b9 100644 --- a/docs/Reference/API-Objects.md +++ b/docs/Reference/API-Objects.md @@ -7,7 +7,7 @@ The following objects are parameters for or returned by Besu API Methods. ## Block Object -Returned by [eth_getBlockByHash](API-Methods.md#eth_getblockbyhash) and [eth_getBlockByNumber](API-Methods.md#eth_getblockbynumber). +Returned by [`eth_getBlockByHash`](API-Methods.md#eth_getblockbyhash) and [`eth_getBlockByNumber`](API-Methods.md#eth_getblockbynumber). | Key | Type | Value | |----------------------|:---------------------:|----------------------------------------------------------------------------------------------------------------------------------| @@ -34,7 +34,7 @@ Returned by [eth_getBlockByHash](API-Methods.md#eth_getblockbyhash) and [eth_get ## Filter Options Object -Parameter for [eth_newFilter](API-Methods.md#eth_newfilter) and [eth_getLogs](API-Methods.md#eth_getlogs). Used to [filter logs](../HowTo/Interact/Filters/Accessing-Logs-Using-JSON-RPC.md). +Parameter for [`eth_newFilter`](API-Methods.md#eth_newfilter) and [`eth_getLogs`](API-Methods.md#eth_getlogs). Used to [`filter logs`](../HowTo/Interact/Filters/Accessing-Logs-Using-JSON-RPC.md). | Key | Type | Required/Optional | Value | |---------------|:---------------------------------:|:-----------------:|---------------------------------------------------------------------------------------------------------------------------------------------| @@ -43,7 +43,7 @@ Parameter for [eth_newFilter](API-Methods.md#eth_newfilter) and [eth_getLogs](AP | **address** | Data | Array | Optional | Contract address or array of addresses from which [logs](../Concepts/Events-and-Logs.md) originate. | | **topics** | Array of Data, 32 bytes each | Optional | Array of topics by which to [filter logs](../Concepts/Events-and-Logs.md#topic-filters). | -[eth_getLogs](API-Methods.md#eth_getlogs) has an additional key. +[`eth_getLogs`](API-Methods.md#eth_getlogs) has an additional key. | Key | Type | Required/Optional | Value | |------------|:-----------------:|:-----------------:|------| @@ -51,7 +51,7 @@ Parameter for [eth_newFilter](API-Methods.md#eth_newfilter) and [eth_getLogs](AP ## Log Object -Returned by [eth_getFilterChanges](API-Methods.md#eth_getfilterchanges) and [transaction receipt objects](#transaction-receipt-object) can contain an array of log objects. +Returned by [`eth_getFilterChanges`](API-Methods.md#eth_getfilterchanges) and [`transaction receipt objects`](#transaction-receipt-object) can contain an array of log objects. | Key | Type | Value | |----------------------|-:- :------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -67,7 +67,7 @@ Returned by [eth_getFilterChanges](API-Methods.md#eth_getfilterchanges) and [tra ## Private Transaction Object -Returned by [priv_getPrivateTransaction](API-Methods.md#priv_getprivatetransaction). +Returned by [`priv_getPrivateTransaction`](API-Methods.md#priv_getprivatetransaction). | Key | Type | Value | |----------------------|-:-:-------------------------------|---------------------------------------------------------------------------------| @@ -89,7 +89,7 @@ Returned by [priv_getPrivateTransaction](API-Methods.md#priv_getprivatetransacti ## Range Object -Returned by [debug_storageRangeAt](API-Methods.md#debug_storagerangeat). +Returned by [`debug_storageRangeAt`](API-Methods.md#debug_storagerangeat). | Key | Type | Value | |-----------------|:-------:|-------------------------------------------------------------------| @@ -115,8 +115,8 @@ Log information returned as part of the [Trace object](#trace-object). ## Trace Object -Returned by [debug_traceBlock](API-Methods.md#debug_traceblock), [debug_traceBlockByHash](API-Methods.md#debug_traceblockbyhash), -[debug_traceBlockByNumber](API-Methods.md#debug_traceblockbynumber), and [debug_traceTransaction](API-Methods.md#debug_tracetransaction). +Returned by [`debug_traceBlock`](API-Methods.md#debug_traceblock), [`debug_traceBlockByHash`](API-Methods.md#debug_traceblockbyhash), +[`debug_traceBlockByNumber`](API-Methods.md#debug_traceblockbynumber), and [`debug_traceTransaction`](API-Methods.md#debug_tracetransaction). | Key | Type | Value | |-----------------|:-------:|-------------------------------------------------------------------| @@ -127,7 +127,7 @@ Returned by [debug_traceBlock](API-Methods.md#debug_traceblock), [debug_traceBlo ## Transaction Object -Returned by [eth_getTransactionByHash](API-Methods.md#eth_gettransactionbyhash), [eth_getTransactionByBlockHashAndIndex](API-Methods.md#eth_gettransactionbyblockhashandindex), and [eth_getTransactionsByBlockNumberAndIndex](API-Methods.md#eth_gettransactionbyblocknumberandindex). +Returned by [`eth_getTransactionByHash`](API-Methods.md#eth_gettransactionbyhash), [`eth_getTransactionByBlockHashAndIndex`](API-Methods.md#eth_gettransactionbyblockhashandindex), and [`eth_getTransactionsByBlockNumberAndIndex`](API-Methods.md#eth_gettransactionbyblocknumberandindex). | Key | Type | Value | |----------------------|:-------------------:|----------------------------------------------------------------------------------------| @@ -148,10 +148,10 @@ Returned by [eth_getTransactionByHash](API-Methods.md#eth_gettransactionbyhash), ## Transaction Call Object -Parameter for [eth_call](API-Methods.md#eth_call) and [eth_estimateGas](API-Methods.md#eth_estimategas). +Parameter for [`eth_call`](API-Methods.md#eth_call) and [`eth_estimateGas`](API-Methods.md#eth_estimategas). !!!note - All parameters are optional for [eth_estimateGas](API-Methods.md#eth_estimategas) + All parameters are optional for [`eth_estimateGas`](API-Methods.md#eth_estimategas) | Key | Type | Required/Optional | Value | |--------------|:-------------------:|:-----------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -164,7 +164,7 @@ Parameter for [eth_call](API-Methods.md#eth_call) and [eth_estimateGas](API-Meth ## Transaction Receipt Object -Returned by [eth_getTransactionReceipt](API-Methods.md#eth_gettransactionreceipt). +Returned by [`eth_getTransactionReceipt`](API-Methods.md#eth_gettransactionreceipt). | Key | Type | Value | |-----------------------|:--------------------:|--------------------------------------------------------------------------------------| @@ -189,9 +189,22 @@ Returned by [eth_getTransactionReceipt](API-Methods.md#eth_gettransactionreceipt |-------|:-----------------:|---------| | **root** | Data, 32 bytes| Post-transaction stateroot| +## Transaction Trace Object + +Returned by [`trace_replayBlockTransactions`](API-Methods.md#trace_replayblocktransactions). + +| Key | Type | Value | +|----------------------- |:--------------------: |--------------------------------------------------------------------------------------| +| **output** | Boolean | Transaction result. 1 for success and 0 for failure. +| **stateDiff** | Object | [State changes in the requested block.](../Concepts/Transactions/Trace-Types.md#statediff) +| **trace** | Array | [Ordered list of calls to other contracts.](../Concepts/Transactions/Trace-Types.md#trace) +| **vmTrace** | Object | [Ordered list of EVM actions.](../Concepts/Transactions/Trace-Types.md#vmtrace) +| **transactionHash** | Data, 32 bytes | Hash of the replayed transaction. + + ## Private Transaction Receipt Object -Returned by [priv_getTransactionReceipt](API-Methods.md#priv_getTransactionReceipt). +Returned by [`priv_getTransactionReceipt`](API-Methods.md#priv_getTransactionReceipt). | Key | Type | Value | |----------------------- |:--------------------: |--------------------------------------------------------------------------------------| diff --git a/mkdocs.yml b/mkdocs.yml index 9ba33c527b8..42ea3e3f880 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -127,6 +127,7 @@ nav: - Use Truffle with Besu: HowTo/Develop-Dapps/Truffle.md - Use Web3.js to Sign Transactions: HowTo/Develop-Dapps/Use-web3js.md - Troubleshoot: + - Trace Transactions: HowTo/Troubleshoot/Trace-Transactions.md - Solve Common Problems: HowTo/Troubleshoot/Troubleshooting.md - Tutorials: - Examples: @@ -164,6 +165,7 @@ nav: - Transactions: - Transaction Pool: Concepts/Transactions/Transaction-Pool.md - Validating Transactions: Concepts/Transactions/Transaction-Validation.md + - Transaction Trace Types: Concepts/Transactions/Trace-Types.md - Monitoring: Concepts/Monitoring.md - Events and Logs: Concepts/Events-and-Logs.md - TLS Communication: Concepts/TLS.md