Skip to content
You are reading Hyperledger Besu development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.
Date of last update: September 20, 2022

Transaction trace types

When tracing transactions, the trace type options are trace, vmTrace, and stateDiff.


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

trace example

Key Value
action Transaction details.
callType Whether the transaction is call or create.
from Address of the transaction sender.
gas Gas provided by sender.
input Transaction data.
to Target of the transaction.
value Value transferred in the transaction.
result Transaction result.
gasUsed Gas used by the transaction. Includes any refunds of unused gas.
output Return value of the 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 Whether the transaction is a CALL or CREATE series operation.


An ordered list of EVM actions when processing the transaction.

vmTrace only reports actual data returned from a RETURN opcode and does not return the contents of the reserved output space for the call operations. As a result:

  • vmTrace 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, vmTrace reports only the data passed to the RETURN operation and does not include pre-existing memory data or trim the returned data.

For out of gas operations, vmTrace reports the operation that caused the out of gas exception, including the calculated gas cost. vmTrace does not report ex values because the operation is not executed.

vmTrace example

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 the result. Otherwise, is the value pushed onto the 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.


State changes in the requested block for each transaction represented as a map of accounts to an object. Besu lists the balance, code, nonce, and storage changes 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 a deleted value
  • * has a from and a to value.

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

stateDiff example

Key Value
balance Change of balance event.
balance.from Balance before the transaction. Balance after the transaction.
code Changes to code. None in this example.
nonce Change of nonce.
nonce.from Nonce before the transaction. 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:

Only the trace option is available for the following transaction-trace filtering API methods: