BlockchainTransaction#

API documentation for tradeexecutor.state.blockhain_transaction.BlockchainTransaction Python class in Trading Strategy framework.

class BlockchainTransaction[source]#

Bases: object

A stateful blockchain transaction.

The state tracks a transaction over its life cycle
Transactions are part of a larger logical operation (a trade)
Transactions can be resolved either to success or failed
Transaction information is easily exported to the frontend

Transaction has (rough) four phases

Preparation
Signing
Broadcast
Confirmation

Note

In the future, during the broadcasting phase, transactions can be re-signed. If the gas parameters are too low, a new transaction is generated with gas parameters changed and signed again.

Note

A lot information is data structure is redundant and can be streamlined in the future.

__init__(type=BlockchainTransactionType.hot_wallet, chain_id=None, from_address=None, contract_address=None, function_selector=None, transaction_args=None, wrapped_target=None, wrapped_function_selector=None, wrapped_args=None, tx_hash=None, nonce=None, details=None, signed_bytes=None, signed_tx_object=None, broadcasted_at=None, included_at=None, block_number=None, block_hash=None, status=None, realised_gas_units_consumed=None, realised_gas_price=None, revert_reason=None, stack_trace=None, asset_deltas=<factory>, args=None, other=<factory>, notes='')#

Parameters:

type (BlockchainTransactionType) –
chain_id (Optional[int]) –
from_address (Optional[str]) –
contract_address (Optional[str]) –
function_selector (Optional[str]) –
transaction_args (Optional[Tuple[Any]]) –
wrapped_target (Optional[str]) –
wrapped_function_selector (Optional[str]) –
wrapped_args (Optional[Tuple[Any]]) –
tx_hash (Optional[str]) –
nonce (Optional[int]) –
details (Optional[Dict]) –
signed_bytes (Optional[str]) –
signed_tx_object (Optional[str]) –
broadcasted_at (Optional[datetime]) –
included_at (Optional[datetime]) –
block_number (Optional[int]) –
block_hash (Optional[str]) –
status (Optional[bool]) –
realised_gas_units_consumed (Optional[int]) –
realised_gas_price (Optional[int]) –
revert_reason (Optional[str]) –
stack_trace (Optional[str]) –
asset_deltas (List[JSONAssetDelta]) –
args (Optional[Tuple[Any]]) –
other (dict) –
notes (str) –

Return type:

None

Methods

`__init__`([type, chain_id, from_address, ...])
`from_dict`(kvs, *[, infer_missing])
`from_json`(s, *[, parse_float, parse_int, ...])
`get_actual_function_input_args`()	Get the Solidity function input args this transaction was calling.
`get_gas_limit`()	Get the gas limit of the transaction.
`get_planned_gas_price`()	How much wei per gas unit we planned to spend on this transactions.
`get_prepared_raw_transaction`()	Get the bytes we can pass to web_ethSendRawTransction
`get_transaction`()	Return the transaction object as it would be in web3.py.
`get_tx_object`()	Get the raw transaction object.
`is_reverted`()	Transaction reverted.
`is_success`()	Transaction is success if it's succeed flag has been set.
`schema`(*[, infer_missing, only, exclude, ...])
`set_broadcast_information`(nonce, tx_hash, ...)	Update the information we are going to use to broadcast the transaction.
`set_confirmation_information`(ts, ...[, ...])	Update the information we are going to use to broadcast the transaction.
`set_target_information`(chain_id, ...)	Update the information on which transaction we are going to perform.
`to_dict`([encode_json])
`to_json`(*[, skipkeys, ensure_ascii, ...])

Attributes

`type`	What kidn of internal type of this transaction is
`chain_id`	Chain id from https://github.com/ethereum-lists/chains
`from_address`	TODO: Part of signed bytes.
`contract_address`	Contract we called.
`function_selector`	Function name we called
`transaction_args`	Arguments we passed to the smart contract entry function.
`wrapped_target`	If this is a wrapped call, the underlying target of the wrapped call payload.
`wrapped_function_selector`	Function name the vault calls.
`wrapped_args`	Arguments that execute the actual trade.
`tx_hash`	Blockchain bookkeeping
`nonce`	Blockchain bookkeeping
`details`	Raw Ethereum transaction dict.
`signed_bytes`	Raw bytes of the signed transaction
`signed_tx_object`	Pickled SignedTransactionWithNonce.
`broadcasted_at`	When this transaction was broadcasted
`included_at`	Block timestamp when this tranasction was included in a block
`block_number`	Block number when this transaction was included in a block
`block_hash`	Block has of the transaction where the executor saw the inclusion
`status`	status from the tx receipt.
`realised_gas_units_consumed`	Gas consumed by the tx
`realised_gas_price`	Gas price for the tx in gwei
`revert_reason`	The transaction revert reason if we manage to extract it
`stack_trace`	Solidity stack trace of reverted transactions.
`asset_deltas`	List of assets this transaction touches
`args`	Legacy compatibility field.
`other`	Any other metadata associated with this transaction.
`notes`	Human readable notes on this transaction.

type: BlockchainTransactionType#: What kidn of internal type of this transaction is

chain_id: Optional[int]#: Chain id from https://github.com/ethereum-lists/chains

from_address: Optional[str]#: TODO: Part of signed bytes. Create an accessor.

contract_address: Optional[str]#: Contract we called. Usually the Uniswap v2 router address.

function_selector: Optional[str]#

Function name we called

This is Solidity function entry point from the transaction data payload

Human-readable function name for debugging purposes.

transaction_args: Optional[Tuple[Any]]#

Arguments we passed to the smart contract entry function.

This is not JSON serialisable because individual arguments may contain values that are token amounts and thus outside the maximum int of JavaScript.

wrapped_target: Optional[str]#: If this is a wrapped call, the underlying target of the wrapped call payload.

wrapped_function_selector: Optional[str]#

Function name the vault calls.

This is Solidity function entry point from the transaction data payload

Human-readable function name for debugging purposes.

wrapped_args: Optional[Tuple[Any]]#

Arguments that execute the actual trade.

In the case of Enzyme’s vaults, we need to store the underlying smart contract function call, so that we can analyse the slippage later on, because we need the swap function input args for the slippage analysis.

tx_hash: Optional[str]#

Blockchain bookkeeping

Hex string, starts with 0x.

nonce: Optional[int]#: Blockchain bookkeeping

details: Optional[Dict]#

Raw Ethereum transaction dict. Output from web3 buildTransaction()

Example:

{‘value’: 0, ‘maxFeePerGas’: 1844540158, ‘maxPriorityFeePerGas’: 1000000000, ‘chainId’: 61, ‘from’: ‘0x6B49598B34B9c7FbF7C57306d0b0578676D55ffA’, ‘gas’: 100000, ‘to’: ‘0xF2E246BB76DF876Cef8b38ae84130F4F55De395b’, ‘data’: ‘0x095ea7b30000000000000000000000006d411e0a54382ed43f02410ce1c7a7c122afa6e1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff’, ‘nonce’: 0}

signed_bytes: Optional[str]#

Raw bytes of the signed transaction

Legacy. Use signed_tx_object instead.

signed_tx_object: Optional[str]#

Pickled SignedTransactionWithNonce.

This is a pickled binary of SignedTransactionWithNonce object, as hex. It is the latest signed tx object we broadcasted over the wire.

This object may change if we have a broadcast failure (timeout) due to gas spike and we need to sign the tx again with different paramenters.

See eth_defi.hotwallet.SignedTransactionWithNonce

broadcasted_at: Optional[datetime]#: When this transaction was broadcasted

included_at: Optional[datetime]#: Block timestamp when this tranasction was included in a block

block_number: Optional[int]#: Block number when this transaction was included in a block

block_hash: Optional[str]#: Block has of the transaction where the executor saw the inclusion

status: Optional[bool]#: status from the tx receipt. True is success, false is revert.

realised_gas_units_consumed: Optional[int]#: Gas consumed by the tx

realised_gas_price: Optional[int]#: Gas price for the tx in gwei

revert_reason: Optional[str]#: The transaction revert reason if we manage to extract it

stack_trace: Optional[str]#

Solidity stack trace of reverted transactions.

Used in the unit testing environment with Anvil.

See eth_defi.trace.

asset_deltas: List[JSONAssetDelta]#

List of assets this transaction touches

Set in tradeexecutor.tx.TransactionBuilder

args: Optional[Tuple[Any]]#

Legacy compatibility field.

“Somewhat” human-readable encoded Solidity args to be displayed in the frontend. Arguments cannot be decoded for programmatic use.

Use transaction_args and get_actual_function_input_args() instead.

other: dict#

Any other metadata associated with this transaction.

Currently used for vault_slippage_tolerance.

notes: str#

Human readable notes on this transaction.

Used for diagnostics
E.g. the text line of the controlling trade that is causing this transaction, with information about expected tokens, slippage, etc.
Newline separated

get_transaction()[source]#

Return the transaction object as it would be in web3.py.

Needed for analyse_trade_by_receipt(). This will reconstruct TypedTransaction instance from the raw signed transaction bytes. The object will have a dict containing “data” field which we can then use for the trade analysis.

Return type:: eth_defi.hotwallet.SignedTransactionWithNonce | dict

is_success()[source]#

Transaction is success if it’s succeed flag has been set.

Return type:: bool

is_reverted()[source]#

Transaction reverted.

Return type:: bool

set_target_information(chain_id, contract_address, function_selector, args, details)[source]#

Update the information on which transaction we are going to perform.

Parameters:

chain_id (int) –
contract_address (str) –
function_selector (str) –
args (list) –
details (dict) –

set_broadcast_information(nonce, tx_hash, signed_bytes)[source]#

Update the information we are going to use to broadcast the transaction.

Parameters:

nonce (int) –
tx_hash (str) –
signed_bytes (str) –

set_confirmation_information(ts, block_number, block_hash, realised_gas_units_consumed, realised_gas_price, status, revert_reason=None, stack_trace=None)[source]#

Update the information we are going to use to broadcast the transaction.

Parameters:

ts (datetime) –
block_number (int) –
block_hash (str) –
realised_gas_units_consumed (int) –
realised_gas_price (int) –
status (bool) –
revert_reason (Optional[str]) –
stack_trace (Optional[str]) –

get_planned_gas_price()[source]#

How much wei per gas unit we planned to spend on this transactions.

Gets maxFeePerGas for EVM transction.

Returns:: 0 if unknown
Return type:: int

get_gas_limit()[source]#

Get the gas limit of the transaction.

Gets gas for EVM transction.

Returns:: 0 if unknown
Return type:: int

get_actual_function_input_args()[source]#

Get the Solidity function input args this transaction was calling.

For any wrapped vault transaction this returns the real function that was called, instead of the proxy function.
Otherwise return the args in the transaction payload.

Return type:: tuple

get_tx_object()[source]#

Get the raw transaction object.

Returns:: Something that web3.py send_raw_transaction can accept
Return type:: eth_defi.hotwallet.SignedTransactionWithNonce | None

get_prepared_raw_transaction()[source]#

Get the bytes we can pass to web_ethSendRawTransction

Return type:: bytes

Parameters:

type (BlockchainTransactionType) –
chain_id (Optional[int]) –
from_address (Optional[str]) –
contract_address (Optional[str]) –
function_selector (Optional[str]) –
transaction_args (Optional[Tuple[Any]]) –
wrapped_target (Optional[str]) –
wrapped_function_selector (Optional[str]) –
wrapped_args (Optional[Tuple[Any]]) –
tx_hash (Optional[str]) –
nonce (Optional[int]) –
details (Optional[Dict]) –
signed_bytes (Optional[str]) –
signed_tx_object (Optional[str]) –
broadcasted_at (Optional[datetime]) –
included_at (Optional[datetime]) –
block_number (Optional[int]) –
block_hash (Optional[str]) –
status (Optional[bool]) –
realised_gas_units_consumed (Optional[int]) –
realised_gas_price (Optional[int]) –
revert_reason (Optional[str]) –
stack_trace (Optional[str]) –
asset_deltas (List[JSONAssetDelta]) –
args (Optional[Tuple[Any]]) –
other (dict) –
notes (str) –

Return type:

None