eth_portfolio.structs package

Submodules

eth_portfolio.structs.modified module

class eth_portfolio.structs.modified.CallTrace

Bases: Trace

It works just like a evmspec.trace.call.Trace but it encodes to a tuple instead of a dict to save space since keys are known.

__getitem__(attr)

Lookup an attribute value via dictionary-style access.

Parameters:

attr (str) – The name of the attribute to access.

Raises:

KeyError – If the provided key is not a member of the struct.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s['field1']
'value'
>>> s['field2']
Traceback (most recent call last):
    ...
KeyError: ('field2', MyStruct(field1='value'))

__iter__()

Iterate through the keys of the Struct.

Yields:

Struct key.

Return type:

Iterator[str]

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(iter(s))
['field1', 'field2']

get(key, default=None)

Get the value associated with a key, or a default value if the key is not present.

Parameters:

• key (str) – The key to look up.

• default (optional) – The value to return if the key is not present.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s.get('field1')
'value'
>>> s.get('field2', 'default')
'default'

items()

Returns an iterator over the struct’s field name and value pairs.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.items())
[('field1', 'value'), ('field2', 42)]

Return type:

Iterator[Tuple[str, Any]]

keys()

Returns an iterator over the field names of the struct.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.keys())
['field1', 'field2']

Return type:

Iterator[str]

values()

Returns an iterator over the struct’s field values.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.values())
['value', 42]

Return type:

Iterator[Any]

_action: Raw

The raw call action data, parity style.

property action: Action

The decoded call action, parity style.

property block: BlockNumber

A shorthand getter for ‘blockNumber’.

Examples

>>> trace = _FilterTraceBase(blockNumber=123456, ...)
>>> trace.block
123456

blockHash: BlockHash

The hash of the block where this action happened.

Examples

>>> trace = _FilterTraceBase(blockHash="0xabc...", ...)
>>> trace.blockHash
'0xabc...'

blockNumber: BlockNumber

The number of the block where this action happened.

Examples

>>> trace = _FilterTraceBase(blockNumber=123456, ...)
>>> trace.blockNumber
123456

error: str

The error message, if an error occurred.

result: Result | None

The result object, parity style.

None if the call errored. Error details will be included in the error field.

subtraces: uint

The number of traces of internal transactions that occurred during this transaction.

Examples

>>> trace = _FilterTraceBase(subtraces=2, ...)
>>> trace.subtraces
2

traceAddress: List[uint]

The trace addresses (array) representing the path of the call within the trace tree.

Examples

>>> trace = _FilterTraceBase(traceAddress=[0, 1], ...)
>>> trace.traceAddress
[0, 1]

transactionHash: TransactionHash

The hash of the transaction being traced.

Examples

>>> trace = _FilterTraceBase(transactionHash="0xdef...", ...)
>>> trace.transactionHash
'0xdef...'

transactionPosition: int

The position of the transaction in the block.

Examples

>>> trace = _FilterTraceBase(transactionPosition=1, ...)
>>> trace.transactionPosition
1

type: ClassVar[Literal['call']] = 'call'

A class variable indicating the trace type as “call”.

class eth_portfolio.structs.modified.CreateTrace

Bases: Trace

It works just like a evmspec.trace.create.Trace but it encodes to a tuple instead of a dict to save space since keys are known.

__getitem__(attr)

Lookup an attribute value via dictionary-style access.

Parameters:

attr (str) – The name of the attribute to access.

Raises:

KeyError – If the provided key is not a member of the struct.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s['field1']
'value'
>>> s['field2']
Traceback (most recent call last):
    ...
KeyError: ('field2', MyStruct(field1='value'))

__iter__()

Iterate through the keys of the Struct.

Yields:

Struct key.

Return type:

Iterator[str]

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(iter(s))
['field1', 'field2']

get(key, default=None)

Get the value associated with a key, or a default value if the key is not present.

Parameters:

• key (str) – The key to look up.

• default (optional) – The value to return if the key is not present.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s.get('field1')
'value'
>>> s.get('field2', 'default')
'default'

items()

Returns an iterator over the struct’s field name and value pairs.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.items())
[('field1', 'value'), ('field2', 42)]

Return type:

Iterator[Tuple[str, Any]]

keys()

Returns an iterator over the field names of the struct.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.keys())
['field1', 'field2']

Return type:

Iterator[str]

values()

Returns an iterator over the struct’s field values.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.values())
['value', 42]

Return type:

Iterator[Any]

_action: Raw

The raw create action data, following the parity format.

property action: Action

Decodes the raw action data into an Action object.

Utilizes the _action field for decoding, transforming it into a structured Action object that represents the specific details of the contract creation process.

Examples

>>> trace = Trace(_action=Raw(b'{"init":"0x6000600055"}'), result=Result(address=Address("0x1234567890abcdef1234567890abcdef12345678"), code=HexBytes("0x6000600055")))
>>> trace.action.init
HexBytes('0x6000600055')

property block: BlockNumber

A shorthand getter for ‘blockNumber’.

Examples

>>> trace = _FilterTraceBase(blockNumber=123456, ...)
>>> trace.block
123456

blockHash: BlockHash

The hash of the block where this action happened.

Examples

>>> trace = _FilterTraceBase(blockHash="0xabc...", ...)
>>> trace.blockHash
'0xabc...'

blockNumber: BlockNumber

The number of the block where this action happened.

Examples

>>> trace = _FilterTraceBase(blockNumber=123456, ...)
>>> trace.blockNumber
123456

error: str

An error message if an error occurred during the execution of the transaction. Defaults to UNSET.

Examples

>>> trace = _FilterTraceBase(error=UNSET, ...)
>>> trace.error
UNSET

result: Result

The result object, adhering to the parity format, containing deployment details.

subtraces: uint

The number of traces of internal transactions that occurred during this transaction.

Examples

>>> trace = _FilterTraceBase(subtraces=2, ...)
>>> trace.subtraces
2

traceAddress: List[uint]

The trace addresses (array) representing the path of the call within the trace tree.

Examples

>>> trace = _FilterTraceBase(traceAddress=[0, 1], ...)
>>> trace.traceAddress
[0, 1]

transactionHash: TransactionHash

The hash of the transaction being traced.

Examples

>>> trace = _FilterTraceBase(transactionHash="0xdef...", ...)
>>> trace.transactionHash
'0xdef...'

transactionPosition: int

The position of the transaction in the block.

Examples

>>> trace = _FilterTraceBase(transactionPosition=1, ...)
>>> trace.transactionPosition
1

type: ClassVar[Literal['create']] = 'create'

class eth_portfolio.structs.modified.RewardTrace

Bases: Trace

It works just like a evmspec.trace.reward.Trace but it encodes to a tuple instead of a dict to save space since keys are known.

__getitem__(attr)

Lookup an attribute value via dictionary-style access.

Parameters:

attr (str) – The name of the attribute to access.

Raises:

KeyError – If the provided key is not a member of the struct.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s['field1']
'value'
>>> s['field2']
Traceback (most recent call last):
    ...
KeyError: ('field2', MyStruct(field1='value'))

__iter__()

Iterate through the keys of the Struct.

Yields:

Struct key.

Return type:

Iterator[str]

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(iter(s))
['field1', 'field2']

get(key, default=None)

Get the value associated with a key, or a default value if the key is not present.

Parameters:

• key (str) – The key to look up.

• default (optional) – The value to return if the key is not present.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s.get('field1')
'value'
>>> s.get('field2', 'default')
'default'

items()

Returns an iterator over the struct’s field name and value pairs.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.items())
[('field1', 'value'), ('field2', 42)]

Return type:

Iterator[Tuple[str, Any]]

keys()

Returns an iterator over the field names of the struct.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.keys())
['field1', 'field2']

Return type:

Iterator[str]

values()

Returns an iterator over the struct’s field values.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.values())
['value', 42]

Return type:

Iterator[Any]

_action: Raw

Raw data of the reward action, requires decoding to be useful.

property action: Action

Decodes the raw reward action into an Action object, using parity style.

This method uses the msgspec.json.decode() function with a decoding hook to convert the raw action data into a structured Action object.

Returns:

The decoded action.

Example

>>> trace = Trace(blockNumber=123, blockHash=BlockHash("0xabc"), transactionHash=TransactionHash("0xdef"), transactionPosition=0, traceAddress=[], subtraces=0, _action=Raw(b'...'))
>>> action = trace.action
>>> print(action.author)
0x123

property block: BlockNumber

A shorthand getter for ‘blockNumber’.

Examples

>>> trace = _FilterTraceBase(blockNumber=123456, ...)
>>> trace.block
123456

blockHash: BlockHash

The hash of the block where this action happened.

Examples

>>> trace = _FilterTraceBase(blockHash="0xabc...", ...)
>>> trace.blockHash
'0xabc...'

blockNumber: BlockNumber

The number of the block where this action happened.

Examples

>>> trace = _FilterTraceBase(blockNumber=123456, ...)
>>> trace.blockNumber
123456

error: str

An error message if an error occurred during the execution of the transaction. Defaults to UNSET.

Examples

>>> trace = _FilterTraceBase(error=UNSET, ...)
>>> trace.error
UNSET

subtraces: uint

The number of traces of internal transactions that occurred during this transaction.

Examples

>>> trace = _FilterTraceBase(subtraces=2, ...)
>>> trace.subtraces
2

traceAddress: List[uint]

The trace addresses (array) representing the path of the call within the trace tree.

Examples

>>> trace = _FilterTraceBase(traceAddress=[0, 1], ...)
>>> trace.traceAddress
[0, 1]

transactionHash: TransactionHash

The hash of the transaction being traced.

Examples

>>> trace = _FilterTraceBase(transactionHash="0xdef...", ...)
>>> trace.transactionHash
'0xdef...'

transactionPosition: int

The position of the transaction in the block.

Examples

>>> trace = _FilterTraceBase(transactionPosition=1, ...)
>>> trace.transactionPosition
1

type: ClassVar[Literal['reward']] = 'reward'

class eth_portfolio.structs.modified.SuicideTrace

Bases: Trace

It works just like a evmspec.trace.suicide.Trace but it encodes to a tuple instead of a dict to save space since keys are known.

__getitem__(attr)

Lookup an attribute value via dictionary-style access.

Parameters:

attr (str) – The name of the attribute to access.

Raises:

KeyError – If the provided key is not a member of the struct.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s['field1']
'value'
>>> s['field2']
Traceback (most recent call last):
    ...
KeyError: ('field2', MyStruct(field1='value'))

__iter__()

Iterate through the keys of the Struct.

Yields:

Struct key.

Return type:

Iterator[str]

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(iter(s))
['field1', 'field2']

get(key, default=None)

Get the value associated with a key, or a default value if the key is not present.

Parameters:

• key (str) – The key to look up.

• default (optional) – The value to return if the key is not present.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s.get('field1')
'value'
>>> s.get('field2', 'default')
'default'

items()

Returns an iterator over the struct’s field name and value pairs.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.items())
[('field1', 'value'), ('field2', 42)]

Return type:

Iterator[Tuple[str, Any]]

keys()

Returns an iterator over the field names of the struct.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.keys())
['field1', 'field2']

Return type:

Iterator[str]

values()

Returns an iterator over the struct’s field values.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.values())
['value', 42]

Return type:

Iterator[Any]

action: Action

The suicide action, parity style.

property block: BlockNumber

A shorthand getter for ‘blockNumber’.

Examples

>>> trace = _FilterTraceBase(blockNumber=123456, ...)
>>> trace.block
123456

blockHash: BlockHash

The hash of the block where this action happened.

Examples

>>> trace = _FilterTraceBase(blockHash="0xabc...", ...)
>>> trace.blockHash
'0xabc...'

blockNumber: BlockNumber

The number of the block where this action happened.

Examples

>>> trace = _FilterTraceBase(blockNumber=123456, ...)
>>> trace.blockNumber
123456

error: str

An error message if an error occurred during the execution of the transaction. Defaults to UNSET.

Examples

>>> trace = _FilterTraceBase(error=UNSET, ...)
>>> trace.error
UNSET

result: Literal[None]

Explicitly set to None, indicating no meaningful result is expected from a contract self-destruct operation.

subtraces: uint

The number of traces of internal transactions that occurred during this transaction.

Examples

>>> trace = _FilterTraceBase(subtraces=2, ...)
>>> trace.subtraces
2

traceAddress: List[uint]

The trace addresses (array) representing the path of the call within the trace tree.

Examples

>>> trace = _FilterTraceBase(traceAddress=[0, 1], ...)
>>> trace.traceAddress
[0, 1]

transactionHash: TransactionHash

The hash of the transaction being traced.

Examples

>>> trace = _FilterTraceBase(transactionHash="0xdef...", ...)
>>> trace.transactionHash
'0xdef...'

transactionPosition: int

The position of the transaction in the block.

Examples

>>> trace = _FilterTraceBase(transactionPosition=1, ...)
>>> trace.transactionPosition
1

type: ClassVar[Literal['suicide']] = 'suicide'

The constant literal denoting the trace type as ‘suicide’.

eth_portfolio.structs.structs module

Defines the data classes used to represent the various types of value-transfer actions on the blockchain. These include transactions, internal transfers, and token transfers.

The classes are designed to provide a consistent and flexible interface for working with blockchain data. Instance attributes can be fetched with either dot notation or key lookup. Classes are compatible with the standard dictionary interface.

final class eth_portfolio.structs.structs.InternalTransfer

Bases: _LedgerEntryBase

The :class:`~structs.InternalTransfer`class represents an internal transfer or call within a blockchain transaction.

Captures operations that occur during transaction execution, such as contract-to-contract calls, contract creations, or self-destructs. These are not separate on-chain transactions but part of the execution of a single transaction.

Example

>>> internal_tx = InternalTransfer(trace=evmspec.FilterTrace(...), ...)
>>> internal_tx.type
'call'
>>> internal_tx.trace_address
'0.1'
>>> internal_tx.gas_used
21000

__getitem__(attr)

Lookup an attribute value via dictionary-style access.

Parameters:

attr (str) – The name of the attribute to access.

Raises:

KeyError – If the provided key is not a member of the struct.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s['field1']
'value'
>>> s['field2']
Traceback (most recent call last):
    ...
KeyError: ('field2', MyStruct(field1='value'))

__iter__()

Iterate through the keys of the Struct.

Yields:

Struct key.

Return type:

Iterator[str]

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(iter(s))
['field1', 'field2']

async static from_trace(trace, load_prices)

Asynchronously processes a raw internal transfer dictionary into an InternalTransfer object.

This function is the core of the internal transfer processing pipeline. It handles various types of transfers, including special cases like block and uncle rewards. It also filters out certain transfers (e.g., to Gnosis Safe Singleton) and verifies transaction success for non-reward transfers.

The function performs several data transformations: - Value and gas conversions - Optional USD price loading - Field standardization

Parameters:

• transfer – A dictionary containing the raw internal transfer data. Expected to have keys such as ‘type’, ‘transactionHash’, ‘blockNumber’, ‘from’, ‘to’, ‘value’, ‘gas’, ‘gasUsed’, ‘traceAddress’.

• load_prices (bool) – Flag to determine whether to load USD prices for the transfer value.

• trace (Trace | Trace | Trace | Trace)

Returns:

A processed InternalTransfer object.

Return type:

InternalTransfer

Example

>>> transfer = {"type": "call", "transactionHash": "0x123...", "blockNumber": 15537393, "from": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "to": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D", "value": "0x10", "gas": "0x5208", "gasUsed": "0x5208", "traceAddress": [0]}
>>> internal_tx = await load_internal_transfer(transfer=transfer, load_prices=True); print(internal_tx)

Note

• Transfers to the Gnosis Safe Singleton (0xd9Db270c1B5E3Bd161E8c8503c55cEABeE709552) are filtered out

as they typically don’t represent actual value transfers. - The traceAddress is converted to a string for consistent representation across different scenarios. - For block and uncle rewards, gas is set to 0 as these are not regular transactions. - When loading prices, the EEE_ADDRESS constant is used, which represents the native currency of the chain.

Integration with eth_portfolio ecosystem:

• Uses the InternalTransfer struct from eth_portfolio.structs for standardized output.

• Utilizes utility functions from eth_portfolio._loaders.utils and eth_portfolio._utils.

• Interacts with the global ‘chain’ object from the brownie library for chain ID.

get(key, default=None)

Get the value associated with a key, or a default value if the key is not present.

Parameters:

• key (str) – The key to look up.

• default (optional) – The value to return if the key is not present.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s.get('field1')
'value'
>>> s.get('field2', 'default')
'default'

items()

Returns an iterator over the struct’s field name and value pairs.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.items())
[('field1', 'value'), ('field2', 42)]

Return type:

Iterator[Tuple[str, Any]]

keys()

Returns an iterator over the field names of the struct.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.keys())
['field1', 'field2']

Return type:

Iterator[str]

values()

Returns an iterator over the struct’s field values.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.values())
['value', 42]

Return type:

Iterator[Any]

property _evm_object: CallTrace | CreateTrace | RewardTrace | SuicideTrace

The EVM object associated with {cls_name}, exactly as it was received from the RPC.

property block_hash: HexBytes

The hash of the block containing the transaction that includes this InternalTransfer.

property block_number: int | BlockNumber

The block number where the {cls_name} was included.

property call_type: str | None

The type of call made in this InternalTransfer (e.g., “call”, “delegatecall”, “staticcall”).

property chainid: Network

The network ID where the {cls_name} occurred.

entry_type: ClassVar[Literal['internal_transfer']] = 'internal_transfer'

Constant indicating this value transfer is an internal transfer or call entry.

property from_address: Address

The address from which the internal transfer was sent, if applicable.

property gas: int

The amount of gas allocated for this internal operation.

property gas_used: int

The amount of gas actually consumed by this internal operation, if known.

property hash: HexBytes | str

The unique hash of the transaction containing this internal transfer.

property input: HexBytes

The input data for this internal operation, if any.

property output: HexBytes

The output data from this internal operation, if any.

price: Decimal | None

The price of the cryptocurrency at the time of the {cls_name}, if known.

property reward_type: str | None

The type of the reward, for reward transactions.

property subtraces: int

The number of sub-operations spawned by this InternalTransfer.

property to_address: Address | None

The address to which the internal transfer was sent, if applicable.

trace: CallTrace | CreateTrace | RewardTrace | SuicideTrace

The raw trace object associated with this internal transfer.

property trace_address: List[int]

The path of sub-calls to reach this InternalTransfer within the transaction,

Example: - The following trace_address `python [0, 1, 2] ` represents the third sub-call of the second sub-call of the first top-level call.

property transaction_index: int | None

The index of the transaction within its block, if applicable.

property type: Literal['call', 'create', 'reward', 'suicide']

property value: Decimal

The value/amount of cryptocurrency transferred in the internal transfer, scaled to a human-readable decimal value.

value_usd: Decimal | None

The USD value of the cryptocurrency transferred in the {cls_name}, if price is known.

final class eth_portfolio.structs.structs.TokenTransfer

Bases: _LedgerEntryBase

The TokenTransfer class represents a token transfer event within a blockchain transaction.

Captures the movement of ERC20-like tokens between addresses. These are typically emitted as events by token contracts and are not separate transactions but part of the execution of a transaction interacting with the token contract.

Example

>>> token_transfer = TokenTransfer(
...     log=Log(...),
...     value=Decimal("1000000"),  # 1 USDC (assuming 6 decimals)
...     token="USDC",
... )
>>> token_transfer.token
'USDC'
>>> token_transfer.value
Decimal('1000000')
>>> token_transfer.log_index
3

__getitem__(attr)

Lookup an attribute value via dictionary-style access.

Parameters:

attr (str) – The name of the attribute to access.

Raises:

KeyError – If the provided key is not a member of the struct.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s['field1']
'value'
>>> s['field2']
Traceback (most recent call last):
    ...
KeyError: ('field2', MyStruct(field1='value'))

__iter__()

Iterate through the keys of the Struct.

Yields:

Struct key.

Return type:

Iterator[str]

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(iter(s))
['field1', 'field2']

get(key, default=None)

Get the value associated with a key, or a default value if the key is not present.

Parameters:

• key (str) – The key to look up.

• default (optional) – The value to return if the key is not present.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s.get('field1')
'value'
>>> s.get('field2', 'default')
'default'

items()

Returns an iterator over the struct’s field name and value pairs.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.items())
[('field1', 'value'), ('field2', 42)]

Return type:

Iterator[Tuple[str, Any]]

keys()

Returns an iterator over the field names of the struct.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.keys())
['field1', 'field2']

Return type:

Iterator[str]

values()

Returns an iterator over the struct’s field values.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.values())
['value', 42]

Return type:

Iterator[Any]

property _evm_object: Log

The EVM object associated with {cls_name}, exactly as it was received from the RPC.

property block_number: int | BlockNumber

The block number where the {cls_name} was included.

property chainid: Network

The network ID where the {cls_name} occurred.

entry_type: ClassVar[Literal['token_transfer']] = 'token_transfer'

Constant indicating this value transfer is a token transfer entry.

property from_address: Address

property hash: HexBytes

The unique hash of the transaction containing this token transfer.

log: Log

The log associated with this token transfer.

property log_index: int

The index of this transfer event within the transaction logs. Used to uniquely identify the Transfer event associated with this TokenTransfer within the transaction.

price: Decimal | None

The price of the cryptocurrency at the time of the {cls_name}, if known.

property to_address: Address

token: str | None

The symbol of the token being transferred, if known.

property token_address: Address

The contract address of the token being transferred.

transaction_index: int

value: Decimal

The amount of tokens transferred, scaled to a human-readable decimal value.

value_usd: Decimal | None

The USD value of the cryptocurrency transferred in the {cls_name}, if price is known.

final class eth_portfolio.structs.structs.Transaction

Bases: _TransactionBase

__getitem__(attr)

Lookup an attribute value via dictionary-style access.

Parameters:

attr (str) – The name of the attribute to access.

Raises:

KeyError – If the provided key is not a member of the struct.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s['field1']
'value'
>>> s['field2']
Traceback (most recent call last):
    ...
KeyError: ('field2', MyStruct(field1='value'))

__iter__()

Iterate through the keys of the Struct.

Yields:

Struct key.

Return type:

Iterator[str]

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(iter(s))
['field1', 'field2']

classmethod from_rpc_response(transaction, *, price=None, value_usd=None)

Parameters:

• transaction (TransactionLegacy | Transaction2930 | Transaction1559)

• price (Decimal | None)

• value_usd (Decimal | None)

Return type:

Transaction

get(key, default=None)

Get the value associated with a key, or a default value if the key is not present.

Parameters:

• key (str) – The key to look up.

• default (optional) – The value to return if the key is not present.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s.get('field1')
'value'
>>> s.get('field2', 'default')
'default'

items()

Returns an iterator over the struct’s field name and value pairs.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.items())
[('field1', 'value'), ('field2', 42)]

Return type:

Iterator[Tuple[str, Any]]

keys()

Returns an iterator over the field names of the struct.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.keys())
['field1', 'field2']

Return type:

Iterator[str]

values()

Returns an iterator over the struct’s field values.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.values())
['value', 42]

Return type:

Iterator[Any]

property _evm_object: TransactionLegacy | Transaction2930 | Transaction1559 | Trace | Trace | Trace | Trace | Log

The EVM object associated with {cls_name}, exactly as it was received from the RPC.

property access_list: Tuple[AccessListEntry, ...] | None

List of addresses and storage keys the transaction plans to access (for EIP-2930 and EIP-1559 transactions).

property block_hash: BlockHash

The hash of the block that includes this Transaction.

property block_number: int | BlockNumber

The block number where the {cls_name} was included.

property chainid: Network

The network ID where the {cls_name} occurred.

entry_type: ClassVar[Literal['transaction']] = 'transaction'

Constant indicating this value transfer is an on-chain transaction entry.

property from_address: Address | None

The address from which the transaction was sent, if applicable.

property gas: int

The maximum amount of gas the sender is willing to use for the Transaction.

property gas_price: int

The price per unit of gas the sender is willing to pay (for legacy and EIP-2930 transactions).

property hash: TransactionHash

The unique transaction hash.

property input: HexBytes

The data payload sent with the Transaction, often used for contract interactions.

property max_fee_per_gas: int | None

The maximum total fee per gas the sender is willing to pay (for EIP-1559 transactions only).

property max_priority_fee_per_gas: int | None

The maximum priority fee per gas the sender is willing to pay (for EIP-1559 transactions only).

property nonce: int

The sender’s transaction count at the time of this Transaction.

price: Decimal | None

The price of the cryptocurrency at the time of the {cls_name}, if known.

property r: HexBytes

The R component of the Transaction’s ECDSA signature.

property s: HexBytes

The S component of the Transaction’s ECDSA signature.

property to_address: Address | None

The address to which the transaction was sent, if applicable.

transaction: TransactionLegacy | Transaction2930 | Transaction1559

The transaction object received by calling eth_getTransactionByHash.

property transaction_index: int | None

The index of the transaction within its block, if applicable.

property type: int | None

The transaction type (e.g., 0 for legacy, 1 for EIP-2930, 2 for EIP-1559). None for chains that don’t specify transaction types.

property v: int

The V component of the Transaction’s ECDSA signature, used for replay protection.

property value: Decimal

The value/amount of cryptocurrency transferred in the transaction, scaled to a human-readable decimal value.

value_usd: Decimal | None

The USD value of the cryptocurrency transferred in the {cls_name}, if price is known.

property y_parity: int | None

The Y parity of the transaction signature, used in EIP-2718 typed transactions.

final class eth_portfolio.structs.structs.TransactionRLP

Bases: _TransactionBase

__getitem__(attr)

Lookup an attribute value via dictionary-style access.

Parameters:

attr (str) – The name of the attribute to access.

Raises:

KeyError – If the provided key is not a member of the struct.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s['field1']
'value'
>>> s['field2']
Traceback (most recent call last):
    ...
KeyError: ('field2', MyStruct(field1='value'))

__iter__()

Iterate through the keys of the Struct.

Yields:

Struct key.

Return type:

Iterator[str]

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(iter(s))
['field1', 'field2']

classmethod from_rpc_response(transaction, *, price=None, value_usd=None)

Parameters:

• transaction (TransactionLegacy | Transaction2930 | Transaction1559)

• price (Decimal | None)

• value_usd (Decimal | None)

Return type:

Transaction

get(key, default=None)

Get the value associated with a key, or a default value if the key is not present.

Parameters:

• key (str) – The key to look up.

• default (optional) – The value to return if the key is not present.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s.get('field1')
'value'
>>> s.get('field2', 'default')
'default'

items()

Returns an iterator over the struct’s field name and value pairs.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.items())
[('field1', 'value'), ('field2', 42)]

Return type:

Iterator[Tuple[str, Any]]

keys()

Returns an iterator over the field names of the struct.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.keys())
['field1', 'field2']

Return type:

Iterator[str]

values()

Returns an iterator over the struct’s field values.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.values())
['value', 42]

Return type:

Iterator[Any]

property _evm_object: TransactionLegacy | Transaction2930 | Transaction1559 | Trace | Trace | Trace | Trace | Log

The EVM object associated with {cls_name}, exactly as it was received from the RPC.

property access_list: Tuple[AccessListEntry, ...] | None

List of addresses and storage keys the transaction plans to access (for EIP-2930 and EIP-1559 transactions).

property block_hash: BlockHash

The hash of the block that includes this Transaction.

property block_number: int | BlockNumber

The block number where the {cls_name} was included.

property chainid: Network

The network ID where the {cls_name} occurred.

entry_type: ClassVar[Literal['transaction']] = 'transaction'

Constant indicating this value transfer is an on-chain transaction entry.

property from_address: Address | None

The address from which the transaction was sent, if applicable.

property gas: int

The maximum amount of gas the sender is willing to use for the Transaction.

property gas_price: int

The price per unit of gas the sender is willing to pay (for legacy and EIP-2930 transactions).

property hash: TransactionHash

The unique transaction hash.

property input: HexBytes

The data payload sent with the Transaction, often used for contract interactions.

property max_fee_per_gas: int | None

The maximum total fee per gas the sender is willing to pay (for EIP-1559 transactions only).

property max_priority_fee_per_gas: int | None

The maximum priority fee per gas the sender is willing to pay (for EIP-1559 transactions only).

property nonce: int

The sender’s transaction count at the time of this Transaction.

price: Decimal | None

The price of the cryptocurrency at the time of the {cls_name}, if known.

property r: HexBytes

The R component of the Transaction’s ECDSA signature.

property s: HexBytes

The S component of the Transaction’s ECDSA signature.

property to_address: Address | None

The address to which the transaction was sent, if applicable.

transaction: TransactionRLP

The transaction object received by calling eth_getTransactionByHash.

property transaction_index: int | None

The index of the transaction within its block, if applicable.

property type: int | None

The transaction type (e.g., 0 for legacy, 1 for EIP-2930, 2 for EIP-1559). None for chains that don’t specify transaction types.

property v: int

The V component of the Transaction’s ECDSA signature, used for replay protection.

property value: Decimal

The value/amount of cryptocurrency transferred in the transaction, scaled to a human-readable decimal value.

value_usd: Decimal | None

The USD value of the cryptocurrency transferred in the {cls_name}, if price is known.

property y_parity: int | None

The Y parity of the transaction signature, used in EIP-2718 typed transactions.

class eth_portfolio.structs.structs._LE

Type variable for generic operations on ledger entries. Can be Transaction, InternalTransfer, or TokenTransfer.

alias of TypeVar(‘_LE’, ~eth_portfolio.structs.structs.Transaction, ~eth_portfolio.structs.structs.InternalTransfer, ~eth_portfolio.structs.structs.TokenTransfer)

__init__(name, *constraints, bound=None, covariant=False, contravariant=False)

class eth_portfolio.structs.structs._LedgerEntryBase

Bases: DictStruct

The _LedgerEntryBase class is a base class for ledger entries representing on-chain actions in a blockchain.

Provides common attributes for transactions, internal transfers, and token transfers.

Extended by specific ledger entry types Transaction, InternalTransfer, and TokenTransfer.

__getitem__(attr)

Lookup an attribute value via dictionary-style access.

Parameters:

attr (str) – The name of the attribute to access.

Raises:

KeyError – If the provided key is not a member of the struct.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s['field1']
'value'
>>> s['field2']
Traceback (most recent call last):
    ...
KeyError: ('field2', MyStruct(field1='value'))

__iter__()

Iterate through the keys of the Struct.

Yields:

Struct key.

Return type:

Iterator[str]

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(iter(s))
['field1', 'field2']

get(key, default=None)

Get the value associated with a key, or a default value if the key is not present.

Parameters:

• key (str) – The key to look up.

• default (optional) – The value to return if the key is not present.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s.get('field1')
'value'
>>> s.get('field2', 'default')
'default'

items()

Returns an iterator over the struct’s field name and value pairs.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.items())
[('field1', 'value'), ('field2', 42)]

Return type:

Iterator[Tuple[str, Any]]

keys()

Returns an iterator over the field names of the struct.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.keys())
['field1', 'field2']

Return type:

Iterator[str]

values()

Returns an iterator over the struct’s field values.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.values())
['value', 42]

Return type:

Iterator[Any]

property _evm_object: TransactionLegacy | Transaction2930 | Transaction1559 | Trace | Trace | Trace | Trace | Log

The EVM object associated with {cls_name}, exactly as it was received from the RPC.

property block_number: int | BlockNumber

The block number where the {cls_name} was included.

property chainid: Network

The network ID where the {cls_name} occurred.

price: Decimal | None

The price of the cryptocurrency at the time of the {cls_name}, if known.

value_usd: Decimal | None

The USD value of the cryptocurrency transferred in the {cls_name}, if price is known.

class eth_portfolio.structs.structs._TransactionBase

Bases: _LedgerEntryBase

The Transaction class represents a complete on-chain blockchain transaction.

Contains detailed information about a single executed transaction on the blockchain, including gas parameters, signature components, and transaction-specific data.

Example

>>> tx = Transaction(tx=Transaction1559(...))
>>> tx.chainid
Network.Mainnet
>>> tx.type
2
>>> tx.max_fee_per_gas
30000000000

__getitem__(attr)

Lookup an attribute value via dictionary-style access.

Parameters:

attr (str) – The name of the attribute to access.

Raises:

KeyError – If the provided key is not a member of the struct.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s['field1']
'value'
>>> s['field2']
Traceback (most recent call last):
    ...
KeyError: ('field2', MyStruct(field1='value'))

__iter__()

Iterate through the keys of the Struct.

Yields:

Struct key.

Return type:

Iterator[str]

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(iter(s))
['field1', 'field2']

classmethod from_rpc_response(transaction, *, price=None, value_usd=None)

Parameters:

• transaction (TransactionLegacy | Transaction2930 | Transaction1559)

• price (Decimal | None)

• value_usd (Decimal | None)

Return type:

Transaction

get(key, default=None)

Get the value associated with a key, or a default value if the key is not present.

Parameters:

• key (str) – The key to look up.

• default (optional) – The value to return if the key is not present.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s.get('field1')
'value'
>>> s.get('field2', 'default')
'default'

items()

Returns an iterator over the struct’s field name and value pairs.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.items())
[('field1', 'value'), ('field2', 42)]

Return type:

Iterator[Tuple[str, Any]]

keys()

Returns an iterator over the field names of the struct.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.keys())
['field1', 'field2']

Return type:

Iterator[str]

values()

Returns an iterator over the struct’s field values.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.values())
['value', 42]

Return type:

Iterator[Any]

property _evm_object: TransactionLegacy | Transaction2930 | Transaction1559 | Trace | Trace | Trace | Trace | Log

The EVM object associated with {cls_name}, exactly as it was received from the RPC.

property access_list: Tuple[AccessListEntry, ...] | None

List of addresses and storage keys the transaction plans to access (for EIP-2930 and EIP-1559 transactions).

property block_hash: BlockHash

The hash of the block that includes this Transaction.

property block_number: int | BlockNumber

The block number where the {cls_name} was included.

property chainid: Network

The network ID where the {cls_name} occurred.

entry_type: ClassVar[Literal['transaction']] = 'transaction'

Constant indicating this value transfer is an on-chain transaction entry.

property from_address: Address | None

The address from which the transaction was sent, if applicable.

property gas: int

The maximum amount of gas the sender is willing to use for the Transaction.

property gas_price: int

The price per unit of gas the sender is willing to pay (for legacy and EIP-2930 transactions).

property hash: TransactionHash

The unique transaction hash.

property input: HexBytes

The data payload sent with the Transaction, often used for contract interactions.

property max_fee_per_gas: int | None

The maximum total fee per gas the sender is willing to pay (for EIP-1559 transactions only).

property max_priority_fee_per_gas: int | None

The maximum priority fee per gas the sender is willing to pay (for EIP-1559 transactions only).

property nonce: int

The sender’s transaction count at the time of this Transaction.

price: Decimal | None

The price of the cryptocurrency at the time of the {cls_name}, if known.

property r: HexBytes

The R component of the Transaction’s ECDSA signature.

property s: HexBytes

The S component of the Transaction’s ECDSA signature.

property to_address: Address | None

The address to which the transaction was sent, if applicable.

property transaction_index: int | None

The index of the transaction within its block, if applicable.

property type: int | None

The transaction type (e.g., 0 for legacy, 1 for EIP-2930, 2 for EIP-1559). None for chains that don’t specify transaction types.

property v: int

The V component of the Transaction’s ECDSA signature, used for replay protection.

property value: Decimal

The value/amount of cryptocurrency transferred in the transaction, scaled to a human-readable decimal value.

value_usd: Decimal | None

The USD value of the cryptocurrency transferred in the {cls_name}, if price is known.

property y_parity: int | None

The Y parity of the transaction signature, used in EIP-2718 typed transactions.

eth_portfolio.structs.structs._get_init_kwargs(original_struct)

Parameters:

original_struct (Struct)

Return type:

Dict[str, Any]

eth_portfolio.structs.structs.LedgerEntry

Type alias representing any type of ledger entry (Transaction, InternalTransfer, or TokenTransfer).

alias of Transaction | InternalTransfer | TokenTransfer

Module contents

final class eth_portfolio.structs.InternalTransfer

Bases: _LedgerEntryBase

The :class:`~structs.InternalTransfer`class represents an internal transfer or call within a blockchain transaction.

Captures operations that occur during transaction execution, such as contract-to-contract calls, contract creations, or self-destructs. These are not separate on-chain transactions but part of the execution of a single transaction.

Example

>>> internal_tx = InternalTransfer(trace=evmspec.FilterTrace(...), ...)
>>> internal_tx.type
'call'
>>> internal_tx.trace_address
'0.1'
>>> internal_tx.gas_used
21000

__getitem__(attr)

Lookup an attribute value via dictionary-style access.

Parameters:

attr (str) – The name of the attribute to access.

Raises:

KeyError – If the provided key is not a member of the struct.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s['field1']
'value'
>>> s['field2']
Traceback (most recent call last):
    ...
KeyError: ('field2', MyStruct(field1='value'))

__iter__()

Iterate through the keys of the Struct.

Yields:

Struct key.

Return type:

Iterator[str]

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(iter(s))
['field1', 'field2']

async static from_trace(trace, load_prices)

Asynchronously processes a raw internal transfer dictionary into an InternalTransfer object.

This function is the core of the internal transfer processing pipeline. It handles various types of transfers, including special cases like block and uncle rewards. It also filters out certain transfers (e.g., to Gnosis Safe Singleton) and verifies transaction success for non-reward transfers.

The function performs several data transformations: - Value and gas conversions - Optional USD price loading - Field standardization

Parameters:

• transfer – A dictionary containing the raw internal transfer data. Expected to have keys such as ‘type’, ‘transactionHash’, ‘blockNumber’, ‘from’, ‘to’, ‘value’, ‘gas’, ‘gasUsed’, ‘traceAddress’.

• load_prices (bool) – Flag to determine whether to load USD prices for the transfer value.

• trace (Trace | Trace | Trace | Trace)

Returns:

A processed InternalTransfer object.

Return type:

InternalTransfer

Example

>>> transfer = {"type": "call", "transactionHash": "0x123...", "blockNumber": 15537393, "from": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "to": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D", "value": "0x10", "gas": "0x5208", "gasUsed": "0x5208", "traceAddress": [0]}
>>> internal_tx = await load_internal_transfer(transfer=transfer, load_prices=True); print(internal_tx)

Note

• Transfers to the Gnosis Safe Singleton (0xd9Db270c1B5E3Bd161E8c8503c55cEABeE709552) are filtered out

as they typically don’t represent actual value transfers. - The traceAddress is converted to a string for consistent representation across different scenarios. - For block and uncle rewards, gas is set to 0 as these are not regular transactions. - When loading prices, the EEE_ADDRESS constant is used, which represents the native currency of the chain.

Integration with eth_portfolio ecosystem:

• Uses the InternalTransfer struct from eth_portfolio.structs for standardized output.

• Utilizes utility functions from eth_portfolio._loaders.utils and eth_portfolio._utils.

• Interacts with the global ‘chain’ object from the brownie library for chain ID.

get(key, default=None)

Get the value associated with a key, or a default value if the key is not present.

Parameters:

• key (str) – The key to look up.

• default (optional) – The value to return if the key is not present.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s.get('field1')
'value'
>>> s.get('field2', 'default')
'default'

items()

Returns an iterator over the struct’s field name and value pairs.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.items())
[('field1', 'value'), ('field2', 42)]

Return type:

Iterator[Tuple[str, Any]]

keys()

Returns an iterator over the field names of the struct.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.keys())
['field1', 'field2']

Return type:

Iterator[str]

values()

Returns an iterator over the struct’s field values.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.values())
['value', 42]

Return type:

Iterator[Any]

property _evm_object: CallTrace | CreateTrace | RewardTrace | SuicideTrace

The EVM object associated with {cls_name}, exactly as it was received from the RPC.

property block_hash: HexBytes

The hash of the block containing the transaction that includes this InternalTransfer.

property block_number: int | BlockNumber

The block number where the {cls_name} was included.

property call_type: str | None

The type of call made in this InternalTransfer (e.g., “call”, “delegatecall”, “staticcall”).

property chainid: Network

The network ID where the {cls_name} occurred.

entry_type: ClassVar[Literal['internal_transfer']] = 'internal_transfer'

Constant indicating this value transfer is an internal transfer or call entry.

property from_address: Address

The address from which the internal transfer was sent, if applicable.

property gas: int

The amount of gas allocated for this internal operation.

property gas_used: int

The amount of gas actually consumed by this internal operation, if known.

property hash: HexBytes | str

The unique hash of the transaction containing this internal transfer.

property input: HexBytes

The input data for this internal operation, if any.

property output: HexBytes

The output data from this internal operation, if any.

price: Decimal | None

The price of the cryptocurrency at the time of the {cls_name}, if known.

property reward_type: str | None

The type of the reward, for reward transactions.

property subtraces: int

The number of sub-operations spawned by this InternalTransfer.

property to_address: Address | None

The address to which the internal transfer was sent, if applicable.

trace: CallTrace | CreateTrace | RewardTrace | SuicideTrace

The raw trace object associated with this internal transfer.

property trace_address: List[int]

The path of sub-calls to reach this InternalTransfer within the transaction,

Example: - The following trace_address `python [0, 1, 2] ` represents the third sub-call of the second sub-call of the first top-level call.

property transaction_index: int | None

The index of the transaction within its block, if applicable.

property type: Literal['call', 'create', 'reward', 'suicide']

property value: Decimal

The value/amount of cryptocurrency transferred in the internal transfer, scaled to a human-readable decimal value.

value_usd: Decimal | None

The USD value of the cryptocurrency transferred in the {cls_name}, if price is known.

final class eth_portfolio.structs.TokenTransfer

Bases: _LedgerEntryBase

The TokenTransfer class represents a token transfer event within a blockchain transaction.

Captures the movement of ERC20-like tokens between addresses. These are typically emitted as events by token contracts and are not separate transactions but part of the execution of a transaction interacting with the token contract.

Example

>>> token_transfer = TokenTransfer(
...     log=Log(...),
...     value=Decimal("1000000"),  # 1 USDC (assuming 6 decimals)
...     token="USDC",
... )
>>> token_transfer.token
'USDC'
>>> token_transfer.value
Decimal('1000000')
>>> token_transfer.log_index
3

__getitem__(attr)

Lookup an attribute value via dictionary-style access.

Parameters:

attr (str) – The name of the attribute to access.

Raises:

KeyError – If the provided key is not a member of the struct.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s['field1']
'value'
>>> s['field2']
Traceback (most recent call last):
    ...
KeyError: ('field2', MyStruct(field1='value'))

__iter__()

Iterate through the keys of the Struct.

Yields:

Struct key.

Return type:

Iterator[str]

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(iter(s))
['field1', 'field2']

get(key, default=None)

Get the value associated with a key, or a default value if the key is not present.

Parameters:

• key (str) – The key to look up.

• default (optional) – The value to return if the key is not present.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s.get('field1')
'value'
>>> s.get('field2', 'default')
'default'

items()

Returns an iterator over the struct’s field name and value pairs.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.items())
[('field1', 'value'), ('field2', 42)]

Return type:

Iterator[Tuple[str, Any]]

keys()

Returns an iterator over the field names of the struct.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.keys())
['field1', 'field2']

Return type:

Iterator[str]

values()

Returns an iterator over the struct’s field values.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.values())
['value', 42]

Return type:

Iterator[Any]

property _evm_object: Log

The EVM object associated with {cls_name}, exactly as it was received from the RPC.

property block_number: int | BlockNumber

The block number where the {cls_name} was included.

property chainid: Network

The network ID where the {cls_name} occurred.

entry_type: ClassVar[Literal['token_transfer']] = 'token_transfer'

Constant indicating this value transfer is a token transfer entry.

property from_address: Address

property hash: HexBytes

The unique hash of the transaction containing this token transfer.

log: Log

The log associated with this token transfer.

property log_index: int

The index of this transfer event within the transaction logs. Used to uniquely identify the Transfer event associated with this TokenTransfer within the transaction.

price: Decimal | None

The price of the cryptocurrency at the time of the {cls_name}, if known.

property to_address: Address

token: str | None

The symbol of the token being transferred, if known.

property token_address: Address

The contract address of the token being transferred.

transaction_index: int

value: Decimal

The amount of tokens transferred, scaled to a human-readable decimal value.

value_usd: Decimal | None

The USD value of the cryptocurrency transferred in the {cls_name}, if price is known.

final class eth_portfolio.structs.Transaction

Bases: _TransactionBase

__getitem__(attr)

Lookup an attribute value via dictionary-style access.

Parameters:

attr (str) – The name of the attribute to access.

Raises:

KeyError – If the provided key is not a member of the struct.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s['field1']
'value'
>>> s['field2']
Traceback (most recent call last):
    ...
KeyError: ('field2', MyStruct(field1='value'))

__iter__()

Iterate through the keys of the Struct.

Yields:

Struct key.

Return type:

Iterator[str]

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(iter(s))
['field1', 'field2']

classmethod from_rpc_response(transaction, *, price=None, value_usd=None)

Parameters:

• transaction (TransactionLegacy | Transaction2930 | Transaction1559)

• price (Decimal | None)

• value_usd (Decimal | None)

Return type:

Transaction

get(key, default=None)

Get the value associated with a key, or a default value if the key is not present.

Parameters:

• key (str) – The key to look up.

• default (optional) – The value to return if the key is not present.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s.get('field1')
'value'
>>> s.get('field2', 'default')
'default'

items()

Returns an iterator over the struct’s field name and value pairs.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.items())
[('field1', 'value'), ('field2', 42)]

Return type:

Iterator[Tuple[str, Any]]

keys()

Returns an iterator over the field names of the struct.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.keys())
['field1', 'field2']

Return type:

Iterator[str]

values()

Returns an iterator over the struct’s field values.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.values())
['value', 42]

Return type:

Iterator[Any]

property _evm_object: TransactionLegacy | Transaction2930 | Transaction1559 | Trace | Trace | Trace | Trace | Log

The EVM object associated with {cls_name}, exactly as it was received from the RPC.

property access_list: Tuple[AccessListEntry, ...] | None

List of addresses and storage keys the transaction plans to access (for EIP-2930 and EIP-1559 transactions).

property block_hash: BlockHash

The hash of the block that includes this Transaction.

property block_number: int | BlockNumber

The block number where the {cls_name} was included.

property chainid: Network

The network ID where the {cls_name} occurred.

entry_type: ClassVar[Literal['transaction']] = 'transaction'

Constant indicating this value transfer is an on-chain transaction entry.

property from_address: Address | None

The address from which the transaction was sent, if applicable.

property gas: int

The maximum amount of gas the sender is willing to use for the Transaction.

property gas_price: int

The price per unit of gas the sender is willing to pay (for legacy and EIP-2930 transactions).

property hash: TransactionHash

The unique transaction hash.

property input: HexBytes

The data payload sent with the Transaction, often used for contract interactions.

property max_fee_per_gas: int | None

The maximum total fee per gas the sender is willing to pay (for EIP-1559 transactions only).

property max_priority_fee_per_gas: int | None

The maximum priority fee per gas the sender is willing to pay (for EIP-1559 transactions only).

property nonce: int

The sender’s transaction count at the time of this Transaction.

price: Decimal | None

The price of the cryptocurrency at the time of the {cls_name}, if known.

property r: HexBytes

The R component of the Transaction’s ECDSA signature.

property s: HexBytes

The S component of the Transaction’s ECDSA signature.

property to_address: Address | None

The address to which the transaction was sent, if applicable.

transaction: TransactionLegacy | Transaction2930 | Transaction1559

The transaction object received by calling eth_getTransactionByHash.

property transaction_index: int | None

The index of the transaction within its block, if applicable.

property type: int | None

The transaction type (e.g., 0 for legacy, 1 for EIP-2930, 2 for EIP-1559). None for chains that don’t specify transaction types.

property v: int

The V component of the Transaction’s ECDSA signature, used for replay protection.

property value: Decimal

The value/amount of cryptocurrency transferred in the transaction, scaled to a human-readable decimal value.

value_usd: Decimal | None

The USD value of the cryptocurrency transferred in the {cls_name}, if price is known.

property y_parity: int | None

The Y parity of the transaction signature, used in EIP-2718 typed transactions.

final class eth_portfolio.structs.TransactionRLP

Bases: _TransactionBase

__getitem__(attr)

Lookup an attribute value via dictionary-style access.

Parameters:

attr (str) – The name of the attribute to access.

Raises:

KeyError – If the provided key is not a member of the struct.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s['field1']
'value'
>>> s['field2']
Traceback (most recent call last):
    ...
KeyError: ('field2', MyStruct(field1='value'))

__iter__()

Iterate through the keys of the Struct.

Yields:

Struct key.

Return type:

Iterator[str]

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(iter(s))
['field1', 'field2']

classmethod from_rpc_response(transaction, *, price=None, value_usd=None)

Parameters:

• transaction (TransactionLegacy | Transaction2930 | Transaction1559)

• price (Decimal | None)

• value_usd (Decimal | None)

Return type:

Transaction

get(key, default=None)

Get the value associated with a key, or a default value if the key is not present.

Parameters:

• key (str) – The key to look up.

• default (optional) – The value to return if the key is not present.

Return type:

Any

Example

>>> class MyStruct(DictStruct):
...     field1: str
>>> s = MyStruct(field1="value")
>>> s.get('field1')
'value'
>>> s.get('field2', 'default')
'default'

items()

Returns an iterator over the struct’s field name and value pairs.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.items())
[('field1', 'value'), ('field2', 42)]

Return type:

Iterator[Tuple[str, Any]]

keys()

Returns an iterator over the field names of the struct.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.keys())
['field1', 'field2']

Return type:

Iterator[str]

values()

Returns an iterator over the struct’s field values.

Example

>>> class MyStruct(DictStruct):
...     field1: str
...     field2: int
>>> s = MyStruct(field1="value", field2=42)
>>> list(s.values())
['value', 42]

Return type:

Iterator[Any]

property _evm_object: TransactionLegacy | Transaction2930 | Transaction1559 | Trace | Trace | Trace | Trace | Log

The EVM object associated with {cls_name}, exactly as it was received from the RPC.

property access_list: Tuple[AccessListEntry, ...] | None

List of addresses and storage keys the transaction plans to access (for EIP-2930 and EIP-1559 transactions).

property block_hash: BlockHash

The hash of the block that includes this Transaction.

property block_number: int | BlockNumber

The block number where the {cls_name} was included.

property chainid: Network

The network ID where the {cls_name} occurred.

entry_type: ClassVar[Literal['transaction']] = 'transaction'

Constant indicating this value transfer is an on-chain transaction entry.

property from_address: Address | None

The address from which the transaction was sent, if applicable.

property gas: int

The maximum amount of gas the sender is willing to use for the Transaction.

property gas_price: int

The price per unit of gas the sender is willing to pay (for legacy and EIP-2930 transactions).

property hash: TransactionHash

The unique transaction hash.

property input: HexBytes

The data payload sent with the Transaction, often used for contract interactions.

property max_fee_per_gas: int | None

The maximum total fee per gas the sender is willing to pay (for EIP-1559 transactions only).

property max_priority_fee_per_gas: int | None

The maximum priority fee per gas the sender is willing to pay (for EIP-1559 transactions only).

property nonce: int

The sender’s transaction count at the time of this Transaction.

price: Decimal | None

The price of the cryptocurrency at the time of the {cls_name}, if known.

property r: HexBytes

The R component of the Transaction’s ECDSA signature.

property s: HexBytes

The S component of the Transaction’s ECDSA signature.

property to_address: Address | None

The address to which the transaction was sent, if applicable.

transaction: TransactionRLP

The transaction object received by calling eth_getTransactionByHash.

property transaction_index: int | None

The index of the transaction within its block, if applicable.

property type: int | None

The transaction type (e.g., 0 for legacy, 1 for EIP-2930, 2 for EIP-1559). None for chains that don’t specify transaction types.

property v: int

The V component of the Transaction’s ECDSA signature, used for replay protection.

property value: Decimal

The value/amount of cryptocurrency transferred in the transaction, scaled to a human-readable decimal value.

value_usd: Decimal | None

The USD value of the cryptocurrency transferred in the {cls_name}, if price is known.

property y_parity: int | None

The Y parity of the transaction signature, used in EIP-2718 typed transactions.