tracing

package
v1.15.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 17, 2025 License: GPL-3.0 Imports: 7 Imported by: 158

Documentation

Overview

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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 added in v1.14.4 

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 added in v1.15.0 

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
)

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 added in v1.15.0 

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 added in v1.15.0 

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

NonceChangeHookV2 is called when the nonce of an account changes.

type NonceChangeReason added in v1.15.0 

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
)

type OnSystemCallEndHook added in v1.14.2 

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 added in v1.14.2 

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 added in v1.15.0 

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

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.