package tracing

import "github.com/ethereum/go-ethereum/core/tracing"

Package tracing defines hooks for 'live tracing' of block processing and transaction execution. Here we define the low-level Hooks object that carries hooks which are invoked by the go-ethereum core at various points in the state transition.

To create a tracer that can be invoked with Geth, you need to register it using github.com/ethereum/go-ethereum/eth/tracers.LiveDirectory.Register.

See https://geth.ethereum.org/docs/developers/evm-tracing/live-tracing for a tutorial.

Index

Types

type BalanceChangeHook 

type BalanceChangeHook = func(addr common.Address, prev, new *big.Int, reason BalanceChangeReason)

BalanceChangeHook is called when the balance of an account changes.

type BalanceChangeReason 

type BalanceChangeReason byte

BalanceChangeReason is used to indicate the reason for a balance change, useful for tracing and reporting. 

const (
	BalanceChangeUnspecified BalanceChangeReason = 0

	// Issuance
	// BalanceIncreaseRewardMineUncle is a reward for mining an uncle block.
	BalanceIncreaseRewardMineUncle BalanceChangeReason = 1
	// BalanceIncreaseRewardMineBlock is a reward for mining a block.
	BalanceIncreaseRewardMineBlock BalanceChangeReason = 2
	// BalanceIncreaseWithdrawal is ether withdrawn from the beacon chain.
	BalanceIncreaseWithdrawal BalanceChangeReason = 3
	// BalanceIncreaseGenesisBalance is ether allocated at the genesis block.
	BalanceIncreaseGenesisBalance BalanceChangeReason = 4

	// Transaction fees
	// BalanceIncreaseRewardTransactionFee is the transaction tip increasing block builder's balance.
	BalanceIncreaseRewardTransactionFee BalanceChangeReason = 5
	// BalanceDecreaseGasBuy is spent to purchase gas for execution a transaction.
	// Part of this gas will be burnt as per EIP-1559 rules.
	BalanceDecreaseGasBuy BalanceChangeReason = 6
	// BalanceIncreaseGasReturn is ether returned for unused gas at the end of execution.
	BalanceIncreaseGasReturn BalanceChangeReason = 7

	// DAO fork
	// BalanceIncreaseDaoContract is ether sent to the DAO refund contract.
	BalanceIncreaseDaoContract BalanceChangeReason = 8
	// BalanceDecreaseDaoAccount is ether taken from a DAO account to be moved to the refund contract.
	BalanceDecreaseDaoAccount BalanceChangeReason = 9

	// BalanceChangeTransfer is ether transferred via a call.
	// it is a decrease for the sender and an increase for the recipient.
	BalanceChangeTransfer BalanceChangeReason = 10
	// BalanceChangeTouchAccount is a transfer of zero value. It is only there to
	// touch-create an account.
	BalanceChangeTouchAccount BalanceChangeReason = 11

	// BalanceIncreaseSelfdestruct is added to the recipient as indicated by a selfdestructing account.
	BalanceIncreaseSelfdestruct BalanceChangeReason = 12
	// BalanceDecreaseSelfdestruct is deducted from a contract due to self-destruct.
	BalanceDecreaseSelfdestruct BalanceChangeReason = 13
	// BalanceDecreaseSelfdestructBurn is ether that is sent to an already self-destructed
	// account within the same tx (captured at end of tx).
	// Note it doesn't account for a self-destruct which appoints itself as recipient.
	BalanceDecreaseSelfdestructBurn BalanceChangeReason = 14

	// BalanceChangeRevert is emitted when the balance is reverted back to a previous value due to call failure.
	// It is only emitted when the tracer has opted in to use the journaling wrapper (WrapWithJournal).
	BalanceChangeRevert BalanceChangeReason = 15
)

func (BalanceChangeReason) String 

func (i BalanceChangeReason) String() string

type BlockEndHook 

type BlockEndHook = func(err error)

BlockEndHook is called after executing a block.

type BlockEvent 

type BlockEvent struct {
	Block     *types.Block
	Finalized *types.Header
	Safe      *types.Header
}

BlockEvent is emitted upon tracing an incoming block. It contains the block as well as consensus related information.

type BlockHashReadHook 

type BlockHashReadHook = func(blockNumber uint64, hash common.Hash)

BlockHashReadHook is called when EVM reads the blockhash of a block.

type BlockStartHook 

type BlockStartHook = func(event BlockEvent)

BlockStartHook is called before executing `block`. `td` is the total difficulty prior to `block`.

type BlockchainInitHook 

type BlockchainInitHook = func(chainConfig *params.ChainConfig)

BlockchainInitHook is called when the blockchain is initialized.

type CloseHook 

type CloseHook = func()

CloseHook is called when the blockchain closes.

type CodeChangeHook 

type CodeChangeHook = func(addr common.Address, prevCodeHash common.Hash, prevCode []byte, codeHash common.Hash, code []byte)

CodeChangeHook is called when the code of an account changes.

type EnterHook 

type EnterHook = func(depth int, typ byte, from common.Address, to common.Address, input []byte, gas uint64, value *big.Int)

EnterHook is invoked when the processing of a message starts.

Take note that EnterHook, when in the context of a live tracer, can be invoked outside of the `OnTxStart` and `OnTxEnd` hooks when dealing with system calls, see OnSystemCallStartHook and OnSystemCallEndHook for more information.

type ExitHook 

type ExitHook = func(depth int, output []byte, gasUsed uint64, err error, reverted bool)

ExitHook is invoked when the processing of a message ends. `revert` is true when there was an error during the execution. Exceptionally, before the homestead hardfork a contract creation that ran out of gas when attempting to persist the code to database did not count as a call failure and did not cause a revert of the call. This will be indicated by `reverted == false` and `err == ErrCodeStoreOutOfGas`.

Take note that ExitHook, when in the context of a live tracer, can be invoked outside of the `OnTxStart` and `OnTxEnd` hooks when dealing with system calls, see OnSystemCallStartHook and OnSystemCallEndHook for more information.

type FaultHook 

type FaultHook = func(pc uint64, op byte, gas, cost uint64, scope OpContext, depth int, err error)

FaultHook is invoked when an error occurs during the execution of an opcode.

type GasChangeHook 

type GasChangeHook = func(old, new uint64, reason GasChangeReason)

GasChangeHook is invoked when the gas changes.

type GasChangeReason 

type GasChangeReason byte

GasChangeReason is used to indicate the reason for a gas change, useful for tracing and reporting.

There is essentially two types of gas changes, those that can be emitted once per transaction and those that can be emitted on a call basis, so possibly multiple times per transaction.

They can be recognized easily by their name, those that start with `GasChangeTx` are emitted once per transaction, while those that start with `GasChangeCall` are emitted on a call basis. 

const (
	GasChangeUnspecified GasChangeReason = 0

	// GasChangeTxInitialBalance is the initial balance for the call which will be equal to the gasLimit of the call. There is only
	// one such gas change per transaction.
	GasChangeTxInitialBalance GasChangeReason = 1
	// GasChangeTxIntrinsicGas is the amount of gas that will be charged for the intrinsic cost of the transaction, there is
	// always exactly one of those per transaction.
	GasChangeTxIntrinsicGas GasChangeReason = 2
	// GasChangeTxRefunds is the sum of all refunds which happened during the tx execution (e.g. storage slot being cleared)
	// this generates an increase in gas. There is at most one of such gas change per transaction.
	GasChangeTxRefunds GasChangeReason = 3
	// GasChangeTxLeftOverReturned is the amount of gas left over at the end of transaction's execution that will be returned
	// to the chain. This change will always be a negative change as we "drain" left over gas towards 0. If there was no gas
	// left at the end of execution, no such even will be emitted. The returned gas's value in Wei is returned to caller.
	// There is at most one of such gas change per transaction.
	GasChangeTxLeftOverReturned GasChangeReason = 4

	// GasChangeCallInitialBalance is the initial balance for the call which will be equal to the gasLimit of the call. There is only
	// one such gas change per call.
	GasChangeCallInitialBalance GasChangeReason = 5
	// GasChangeCallLeftOverReturned is the amount of gas left over that will be returned to the caller, this change will always
	// be a negative change as we "drain" left over gas towards 0. If there was no gas left at the end of execution, no such even
	// will be emitted.
	GasChangeCallLeftOverReturned GasChangeReason = 6
	// GasChangeCallLeftOverRefunded is the amount of gas that will be refunded to the call after the child call execution it
	// executed completed. This value is always positive as we are giving gas back to the you, the left over gas of the child.
	// If there was no gas left to be refunded, no such even will be emitted.
	GasChangeCallLeftOverRefunded GasChangeReason = 7
	// GasChangeCallContractCreation is the amount of gas that will be burned for a CREATE.
	GasChangeCallContractCreation GasChangeReason = 8
	// GasChangeCallContractCreation2 is the amount of gas that will be burned for a CREATE2.
	GasChangeCallContractCreation2 GasChangeReason = 9
	// GasChangeCallCodeStorage is the amount of gas that will be charged for code storage.
	GasChangeCallCodeStorage GasChangeReason = 10
	// GasChangeCallOpCode is the amount of gas that will be charged for an opcode executed by the EVM, exact opcode that was
	// performed can be check by `OnOpcode` handling.
	GasChangeCallOpCode GasChangeReason = 11
	// GasChangeCallPrecompiledContract is the amount of gas that will be charged for a precompiled contract execution.
	GasChangeCallPrecompiledContract GasChangeReason = 12
	// GasChangeCallStorageColdAccess is the amount of gas that will be charged for a cold storage access as controlled by EIP2929 rules.
	GasChangeCallStorageColdAccess GasChangeReason = 13
	// GasChangeCallFailedExecution is the burning of the remaining gas when the execution failed without a revert.
	GasChangeCallFailedExecution GasChangeReason = 14
	// GasChangeWitnessContractInit flags the event of adding to the witness during the contract creation initialization step.
	GasChangeWitnessContractInit GasChangeReason = 15
	// GasChangeWitnessContractCreation flags the event of adding to the witness during the contract creation finalization step.
	GasChangeWitnessContractCreation GasChangeReason = 16
	// GasChangeWitnessCodeChunk flags the event of adding one or more contract code chunks to the witness.
	GasChangeWitnessCodeChunk GasChangeReason = 17
	// GasChangeWitnessContractCollisionCheck flags the event of adding to the witness when checking for contract address collision.
	GasChangeWitnessContractCollisionCheck GasChangeReason = 18
	// GasChangeTxDataFloor is the amount of extra gas the transaction has to pay to reach the minimum gas requirement for the
	// transaction data. This change will always be a negative change.
	GasChangeTxDataFloor GasChangeReason = 19

	// GasChangeIgnored is a special value that can be used to indicate that the gas change should be ignored as
	// it will be "manually" tracked by a direct emit of the gas change event.
	GasChangeIgnored GasChangeReason = 0xFF
)

func (GasChangeReason) String 

func (i GasChangeReason) String() string

type GenesisBlockHook 

type GenesisBlockHook = func(genesis *types.Block, alloc types.GenesisAlloc)

GenesisBlockHook is called when the genesis block is being processed.

type Hooks 

type Hooks struct {
	// VM events
	OnTxStart   TxStartHook
	OnTxEnd     TxEndHook
	OnEnter     EnterHook
	OnExit      ExitHook
	OnOpcode    OpcodeHook
	OnFault     FaultHook
	OnGasChange GasChangeHook
	// Chain events
	OnBlockchainInit    BlockchainInitHook
	OnClose             CloseHook
	OnBlockStart        BlockStartHook
	OnBlockEnd          BlockEndHook
	OnSkippedBlock      SkippedBlockHook
	OnGenesisBlock      GenesisBlockHook
	OnSystemCallStart   OnSystemCallStartHook
	OnSystemCallStartV2 OnSystemCallStartHookV2
	OnSystemCallEnd     OnSystemCallEndHook
	// State events
	OnBalanceChange BalanceChangeHook
	OnNonceChange   NonceChangeHook
	OnNonceChangeV2 NonceChangeHookV2
	OnCodeChange    CodeChangeHook
	OnStorageChange StorageChangeHook
	OnLog           LogHook
	// Block hash read
	OnBlockHashRead BlockHashReadHook
}

func WrapWithJournal 

func WrapWithJournal(hooks *Hooks) (*Hooks, error)

WrapWithJournal wraps the given tracer with a journaling layer.

type LogHook 

type LogHook = func(log *types.Log)

LogHook is called when a log is emitted.

type NonceChangeHook 

type NonceChangeHook = func(addr common.Address, prev, new uint64)

NonceChangeHook is called when the nonce of an account changes.

type NonceChangeHookV2 

type NonceChangeHookV2 = func(addr common.Address, prev, new uint64, reason NonceChangeReason)

NonceChangeHookV2 is called when the nonce of an account changes.

type NonceChangeReason 

type NonceChangeReason byte

NonceChangeReason is used to indicate the reason for a nonce change. 

const (
	NonceChangeUnspecified NonceChangeReason = 0

	// NonceChangeGenesis is the nonce allocated to accounts at genesis.
	NonceChangeGenesis NonceChangeReason = 1

	// NonceChangeEoACall is the nonce change due to an EoA call.
	NonceChangeEoACall NonceChangeReason = 2

	// NonceChangeContractCreator is the nonce change of an account creating a contract.
	NonceChangeContractCreator NonceChangeReason = 3

	// NonceChangeNewContract is the nonce change of a newly created contract.
	NonceChangeNewContract NonceChangeReason = 4

	// NonceChangeTransaction is the nonce change due to a EIP-7702 authorization.
	NonceChangeAuthorization NonceChangeReason = 5

	// NonceChangeRevert is emitted when the nonce is reverted back to a previous value due to call failure.
	// It is only emitted when the tracer has opted in to use the journaling wrapper (WrapWithJournal).
	NonceChangeRevert NonceChangeReason = 6
)

func (NonceChangeReason) String 

func (i NonceChangeReason) String() string

type OnSystemCallEndHook 

type OnSystemCallEndHook = func()

OnSystemCallEndHook is called when a system call has finished executing. Today, this hook is invoked when the EIP-4788 system call is about to be executed to set the beacon block root.

type OnSystemCallStartHook 

type OnSystemCallStartHook = func()

OnSystemCallStartHook is called when a system call is about to be executed. Today, this hook is invoked when the EIP-4788 system call is about to be executed to set the beacon block root.

After this hook, the EVM call tracing will happened as usual so you will receive a `OnEnter/OnExit` as well as state hooks between this hook and the `OnSystemCallEndHook`.

Note that system call happens outside normal transaction execution, so the `OnTxStart/OnTxEnd` hooks will not be invoked.

type OnSystemCallStartHookV2 

type OnSystemCallStartHookV2 = func(vm *VMContext)

OnSystemCallStartHookV2 is called when a system call is about to be executed. Refer to `OnSystemCallStartHook` for more information.

type OpContext 

type OpContext interface {
	MemoryData() []byte
	StackData() []uint256.Int
	Caller() common.Address
	Address() common.Address
	CallValue() *uint256.Int
	CallInput() []byte
	ContractCode() []byte
}

OpContext provides the context at which the opcode is being executed in, including the memory, stack and various contract-level information.

type OpcodeHook 

type OpcodeHook = func(pc uint64, op byte, gas, cost uint64, scope OpContext, rData []byte, depth int, err error)

OpcodeHook is invoked just prior to the execution of an opcode.

type SkippedBlockHook 

type SkippedBlockHook = func(event BlockEvent)

SkippedBlockHook indicates a block was skipped during processing due to it being known previously. This can happen e.g. when recovering from a crash.

type StateDB 

type StateDB interface {
	GetBalance(common.Address) *uint256.Int
	GetNonce(common.Address) uint64
	GetCode(common.Address) []byte
	GetCodeHash(common.Address) common.Hash
	GetState(common.Address, common.Hash) common.Hash
	GetTransientState(common.Address, common.Hash) common.Hash
	Exist(common.Address) bool
	GetRefund() uint64
}

StateDB gives tracers access to the whole state.

type StorageChangeHook 

type StorageChangeHook = func(addr common.Address, slot common.Hash, prev, new common.Hash)

StorageChangeHook is called when the storage of an account changes.

type TxEndHook 

type TxEndHook = func(receipt *types.Receipt, err error)

TxEndHook is called after the execution of a transaction ends.

type TxStartHook 

type TxStartHook = func(vm *VMContext, tx *types.Transaction, from common.Address)

TxStartHook is called before the execution of a transaction starts. Call simulations don't come with a valid signature. `from` field to be used for address of the caller.

type VMContext 

type VMContext struct {
	Coinbase    common.Address
	BlockNumber *big.Int
	Time        uint64
	Random      *common.Hash
	BaseFee     *big.Int
	StateDB     StateDB
}

VMContext provides the context for the EVM execution.

Source Files

gen_balance_change_reason_stringer.go gen_gas_change_reason_stringer.go gen_nonce_change_reason_stringer.go hooks.go journal.go

Version
v1.15.11 (latest)
Published
May 5, 2025
Platform
linux/amd64
Imports
7 packages
Last checked
1 day ago –

Tools for package owners.