Skip to main content

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
actionTransaction details.
callTypeWhether the transaction is call or create.
fromAddress of the transaction sender.
gasGas provided by sender.
inputTransaction data.
toTarget of the transaction.
valueValue transferred in the transaction.
resultTransaction result.
gasUsedGas used by the transaction. Includes any refunds of unused gas.
outputReturn 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.
subTracesTraces of contract calls made by the transaction.
traceAddressTree list address of where the call occurred, address of the parents, and order of the current sub call.
typeWhether 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
codeCode executed by the EVM.
opsSequence of EVM operations (opcodes) executed in the transaction.
costGas cost of the opcode. Includes memory expansion costs but not gas refunds. For precompiled contract calls, reports only the actual cost.
exExecuted operations.
memMemory read or written by the operation.
pushAdjusted stack items. For swap, includes all intermediate values and the result. Otherwise, is the value pushed onto the stack.
storeAccount storage written by the operation.
usedRemaining gas taking into account the all but 1/64th rule for calls.
pcProgram counter.
subSub 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
balanceChange of balance event.
balance.fromBalance before the transaction.
balance.toBalance after the transaction.
codeChanges to code. None in this example.
nonceChange of nonce.
nonce.fromNonce before the transaction.
nonce.toNonce after the transaction.
storageChanges 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: