Struct TransactionTrace

pub struct TransactionTrace {

    pub to: Vec<u8>,
    pub nonce: u64,
    pub gas_price: Option<BigInt>,
    pub gas_limit: u64,
    pub value: Option<BigInt>,
    pub input: Vec<u8>,
    pub v: Vec<u8>,
    pub r: Vec<u8>,
    pub s: Vec<u8>,
    pub gas_used: u64,
    pub type: i32,
    pub access_list: Vec<AccessTuple>,
    pub max_fee_per_gas: Option<BigInt>,
    pub max_priority_fee_per_gas: Option<BigInt>,
    pub index: u32,
    pub hash: Vec<u8>,
    pub from: Vec<u8>,
    pub return_data: Vec<u8>,
    pub public_key: Vec<u8>,
    pub begin_ordinal: u64,
    pub end_ordinal: u64,
    pub status: i32,
    pub receipt: Option<TransactionReceipt>,
    pub calls: Vec<Call>,
    pub blob_gas: Option<u64>,
    pub blob_gas_fee_cap: Option<BigInt>,
    pub blob_hashes: Vec<Vec<u8>>,
    pub set_code_authorizations: Vec<SetCodeAuthorization>,
}

TransactionTrace is full trace of execution of the transaction when the it actually executed on chain.

It contains all the transaction details like from, to, gas, etc. as well as all the internal calls that were made during the transaction.

The calls vector contains Call objects which have balance changes, events storage changes, etc.

If ordering is important between elements, almost each message like Log, Call, StorageChange, etc. have an ordinal field that is represents “execution” order of the said element against all other elements in this block.

Due to how the call tree works doing “naively”, looping through all calls then through a Call’s element like logs while not yielding the elements in the order they were executed on chain. A log in call could have been done before or after another in another call depending on the actual call tree.

The calls are ordered by creation order and the call tree can be re-computing using fields found in Call object (parent/child relationship).

Another important thing to note is that even if a transaction succeed, some calls within it could have been reverted internally, if this is important to you, you must check the field state_reverted on the Call to determine if it was fully committed to the chain or not.

Fields

to: Vec<u8>

consensus

nonce: u64

gas_price: Option<BigInt>

GasPrice represents the effective price that has been paid for each gas unit of this transaction. Over time, the Ethereum rules changes regarding GasPrice field here. Before London fork, the GasPrice was always set to the fixed gas price. After London fork, this value has different meaning depending on the transaction type (see Type field).

In cases where TransactionTrace.Type == TRX_TYPE_LEGACY || TRX_TYPE_ACCESS_LIST, then GasPrice has the same meaning as before the London fork.

In cases where TransactionTrace.Type == TRX_TYPE_DYNAMIC_FEE, then GasPrice is the effective gas price paid for the transaction which is equals to BlockHeader.BaseFeePerGas + TransactionTrace.

gas_limit: u64

GasLimit is the maximum of gas unit the sender of the transaction is willing to consume when perform the EVM execution of the whole transaction

value: Option<BigInt>

Value is the amount of Ether transferred as part of this transaction.

input: Vec<u8>

Input data the transaction will receive for execution of EVM.

v: Vec<u8>

V is the recovery ID value for the signature Y point.

r: Vec<u8>

R is the signature’s X point on the elliptic curve (32 bytes).

s: Vec<u8>

S is the signature’s Y point on the elliptic curve (32 bytes).

gas_used: u64

GasUsed is the total amount of gas unit used for the whole execution of the transaction.

type: i32

Type represents the Ethereum transaction type, available only since EIP-2718 & EIP-2930 activation which happened on Berlin fork. The value is always set even for transaction before Berlin fork because those before the fork are still legacy transactions.

access_list: Vec<AccessTuple>

AccessList represents the storage access this transaction has agreed to do in which case those storage access cost less gas unit per access.

This will is populated only if TransactionTrace.Type == TRX_TYPE_ACCESS_LIST || TRX_TYPE_DYNAMIC_FEE which is possible only if Berlin (TRX_TYPE_ACCESS_LIST) nor London (TRX_TYPE_DYNAMIC_FEE) fork are active on the chain.

max_fee_per_gas: Option<BigInt>

MaxFeePerGas is the maximum fee per gas the user is willing to pay for the transaction gas used.

This will is populated only if TransactionTrace.Type == TRX_TYPE_DYNAMIC_FEE which is possible only if London fork is active on the chain.

Only available in DetailLevel: EXTENDED

max_priority_fee_per_gas: Option<BigInt>

MaxPriorityFeePerGas is priority fee per gas the user to pay in extra to the miner on top of the block’s base fee.

This will is populated only if TransactionTrace.Type == TRX_TYPE_DYNAMIC_FEE which is possible only if London fork is active on the chain.

Only available in DetailLevel: EXTENDED

index: u32

meta

hash: Vec<u8>

from: Vec<u8>

return_data: Vec<u8>

Only available in DetailLevel: EXTENDED Known Issues

• Version 3: Field not populated. It will be empty.

  Fixed in Version 4, see https://docs.substreams.dev/reference-material/chains-and-endpoints/ethereum-data-model for information about block versions.

public_key: Vec<u8>

Only available in DetailLevel: EXTENDED

begin_ordinal: u64

The block’s global ordinal when the transaction started executing, refer to [Block] documentation for further information about ordinals and total ordering.

end_ordinal: u64

The block’s global ordinal when the transaction finished executing, refer to [Block] documentation for further information about ordinals and total ordering.

status: i32

TransactionTraceStatus is the status of the transaction execution and will let you know if the transaction was successful or not.

Explanation relevant only for blocks with DetailLevel: EXTENDED

A successful transaction has been recorded to the blockchain’s state for calls in it that were successful. This means it’s possible only a subset of the calls were properly recorded, refer to [calls[].state_reverted] field to determine which calls were reverted.

A quirks of the Ethereum protocol is that a transaction FAILED or REVERTED still affects the blockchain’s state for some of the state changes. Indeed, in those cases, the transactions fees are still paid to the miner which means there is a balance change for the transaction’s emitter (e.g. from) to pay the gas fees, an optional balance change for gas refunded to the transaction’s emitter (e.g. from) and a balance change for the miner who received the transaction fees. There is also a nonce change for the transaction’s emitter (e.g. from).

This means that to properly record the state changes for a transaction, you need to conditionally procees the transaction’s status.

For a SUCCEEDED transaction, you iterate over the calls array and record the state changes for each call for which state_reverted == false (if a transaction succeeded, the call at #0 will always state_reverted == false because it aligns with the transaction).

For a FAILED or REVERTED transaction, you iterate over the root call (e.g. at #0, will always exist) for balance changes you process those where reason is either REASON_GAS_BUY, REASON_GAS_REFUND or REASON_REWARD_TRANSACTION_FEE and for nonce change, still on the root call, you pick the nonce change which the smallest ordinal (if more than one).

receipt: Option<TransactionReceipt>

calls: Vec<Call>

Only available in DetailLevel: EXTENDED

blob_gas: Option<u64>

BlobGas is the amount of gas the transaction is going to pay for the blobs, this is a computed value equivalent to self.blob_gas_fee_cap * len(self.blob_hashes) and provided in the model for convenience.

This is specified by https://eips.ethereum.org/EIPS/eip-4844

This will is populated only if TransactionTrace.Type == TRX_TYPE_BLOB which is possible only if Cancun fork is active on the chain.

blob_gas_fee_cap: Option<BigInt>

BlobGasFeeCap is the maximum fee per data gas the user is willing to pay for the data gas used.

This is specified by https://eips.ethereum.org/EIPS/eip-4844

This will is populated only if TransactionTrace.Type == TRX_TYPE_BLOB which is possible only if Cancun fork is active on the chain.

blob_hashes: Vec<Vec<u8>>

BlobHashes field represents a list of hash outputs from ‘kzg_to_versioned_hash’ which essentially is a version byte + the sha256 hash of the blob commitment (e.g. BLOB_COMMITMENT_VERSION_KZG + sha256(commitment)\[1:\].

This is specified by https://eips.ethereum.org/EIPS/eip-4844

This will is populated only if TransactionTrace.Type == TRX_TYPE_BLOB which is possible only if Cancun fork is active on the chain.

set_code_authorizations: Vec<SetCodeAuthorization>

SetCodeAuthorizations represents the authorizations of a transaction to set code to an EOA (Externally Owned Accounts) as defined in EIP-7702. The list will contain all the authorizations as they were specified in the transaction itself regardless of their validity. If you need to determined if a given authorization was correctly applied on chain’s state, refer to [SetCodeAuthorization.discarded] field that records if the authorization was discarded or not by the chain due to invalidity.

This is specified by https://eips.ethereum.org/EIPS/eip-7702

This will is populated only if TransactionTrace.Type == TRX_TYPE_SET_CODE which is possible only if Prague fork is active on the chain.

Implementations

impl TransactionTrace

pub fn type(&self) -> Type

Returns the enum value of type, or the default if the field is set to an invalid enum value.

pub fn set_type(&mut self, value: Type)

Sets type to the provided enum value.

pub fn status(&self) -> TransactionTraceStatus

Returns the enum value of status, or the default if the field is set to an invalid enum value.

pub fn set_status(&mut self, value: TransactionTraceStatus)

Sets status to the provided enum value.

pub fn blob_gas(&self) -> u64

Returns the value of blob_gas, or the default value if blob_gas is unset.

impl TransactionTrace

pub fn calls(&self) -> impl Iterator<Item = CallView<'_>>

pub fn receipt(&self) -> ReceiptView<'_>

pub fn logs_with_calls(&self) -> impl Iterator<Item = (&Log, CallView<'_>)>

Iterates over all logs in the transaction, excluding those from calls that were not recorded to the chain’s state.

The logs are sorted by their ordinal and returned as pairs of (log, call) where call is the call that produced the log.

Trait Implementations

impl Clone for TransactionTrace

fn clone(&self) -> TransactionTrace

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TransactionTrace

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for TransactionTrace

fn default() -> TransactionTrace

Returns the “default value” for a type.

impl Message for TransactionTrace

fn encoded_len(&self) -> usize

Returns the encoded length of the message without a length delimiter.

fn clear(&mut self)

Clears the message, resetting all fields to their default.

fn encode(&self, buf: &mut impl BufMut) -> Result<(), EncodeError>

where Self: Sized,

Encodes the message to a buffer.

fn encode_to_vec(&self) -> Vec<u8>

where Self: Sized,

Encodes the message to a newly allocated buffer.

fn encode_length_delimited( &self, buf: &mut impl BufMut, ) -> Result<(), EncodeError>

where Self: Sized,

Encodes the message with a length-delimiter to a buffer.

fn encode_length_delimited_to_vec(&self) -> Vec<u8>

where Self: Sized,

Encodes the message with a length-delimiter to a newly allocated buffer.

fn decode(buf: impl Buf) -> Result<Self, DecodeError>

where Self: Default,

Decodes an instance of the message from a buffer.

fn decode_length_delimited(buf: impl Buf) -> Result<Self, DecodeError>

where Self: Default,

Decodes a length-delimited instance of the message from the buffer.

fn merge(&mut self, buf: impl Buf) -> Result<(), DecodeError>

where Self: Sized,

Decodes an instance of the message from a buffer, and merges it into self.

fn merge_length_delimited(&mut self, buf: impl Buf) -> Result<(), DecodeError>

where Self: Sized,

Decodes a length-delimited instance of the message from buffer, and merges it into self.

impl PartialEq for TransactionTrace

fn eq(&self, other: &TransactionTrace) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for TransactionTrace