confirmation

Documentation for eth_defi.confirmation Python module.

Transaction broadcasting, block confirmation and completion monitoring.

  • Wait for multiple transactions to be confirmed and read back the results from the blockchain

  • The safest way to get transactions out is to use wait_and_broadcast_multiple_nodes()

Some notes

Functions

broadcast_and_wait_transactions_to_complete(...)

Broadcast and wait a bunch of signed transactions to confirm.

broadcast_transactions(web3, txs[, ...])

Broadcast and wait a bunch of signed transactions to confirm.

check_nonce_mismatch(web3, txs)

Check for nonce re-use issues.

is_invalid_sender(eth_rpc_error_messag)

from address missing in the tx payload

is_out_of_gas(eth_rpc_error_messag)

wait_and_broadcast_multiple_nodes(web3, txs)

Try to broadcast transactions through multiple nodes.

wait_and_broadcast_multiple_nodes_mev_blocker(...)

Broadcast transactions through a MEV blocker enabled endpoint.

wait_transactions_to_complete(web3, txs[, ...])

Watch multiple transactions executed at parallel.

Exceptions

BadChainId

Out of gas funds for an executor.

BroadcastFailure

Could not broadcast a transaction for some reason.

ConfirmationTimedOut

We exceeded the transaction confirmation timeout.

NonRetryableBroadcastException

Don't try to rebroadcast these.

NonceMismatch

Chain has a different nonce than we expect.

NonceTooLow

Out of gas funds for an executor.

OutOfGasFunds

Out of gas funds for an executor.

Reverted

Transaction reverted on-chain.
exception BroadcastFailure

Bases: Exception

Could not broadcast a transaction for some reason.

__init__(*args, **kwargs)
__new__(**kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception ConfirmationTimedOut

Bases: Exception

We exceeded the transaction confirmation timeout.

__init__(*args, **kwargs)
__new__(**kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception NonRetryableBroadcastException

Bases: Exception

Don’t try to rebroadcast these.

__init__(*args, **kwargs)
__new__(**kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception NonceMismatch

Bases: Exception

Chain has a different nonce than we expect.

__init__(*args, **kwargs)
__new__(**kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception OutOfGasFunds

Bases: eth_defi.confirmation.NonRetryableBroadcastException

Out of gas funds for an executor.

__init__(*args, **kwargs)
__new__(**kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception NonceTooLow

Bases: eth_defi.confirmation.NonRetryableBroadcastException

Out of gas funds for an executor.

__init__(*args, **kwargs)
__new__(**kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception BadChainId

Bases: eth_defi.confirmation.NonRetryableBroadcastException

Out of gas funds for an executor.

__init__(*args, **kwargs)
__new__(**kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception Reverted

Bases: Exception

Transaction reverted on-chain.

__init__(*args, **kwargs)
__new__(**kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

is_invalid_sender(eth_rpc_error_messag)

from address missing in the tx payload

Parameters

eth_rpc_error_messag (str) –

Return type

bool

wait_transactions_to_complete(web3, txs, confirmation_block_count=0, max_timeout=datetime.timedelta(seconds=300), poll_delay=datetime.timedelta(seconds=1), node_switch_timeout=datetime.timedelta(seconds=60))

Watch multiple transactions executed at parallel.

Use simple poll loop to wait all transactions to complete.

If web3 is configured to use eth_defi.provider.fallback.FallbackProvider, try to switch between alternative node providers when confirming the transactions, because sometimes low quality nodes (Ankr, LlamaNodes) do not see transactions for several minutes.

Example:

raw_bytes1 = get_tx_broadcast_data(signed1)
tx_hash1 = web3.eth.send_raw_transaction(raw_bytes)

raw_bytes2 = get_tx_broadcast_data(signed2)
tx_hash2 = web3.eth.send_raw_transaction(raw_bytes2)

complete = wait_transactions_to_complete(web3, [tx_hash1, tx_hash2])

# Check both transaction succeeded
for receipt in complete.values():
    assert receipt.status == 1  # tx success
Parameters

  • txs (List[Union[hexbytes.main.HexBytes, str]]) – List of transaction hashes

  • confirmation_block_count (int) – How many blocks wait for the transaction receipt to settle. Set to zero to return as soon as we see the first transaction receipt.

  • node_switch_timeout –

    Switch to alternative fallback node provider every time we reach this limit.

    Sometimes our node is malfunctioning (LlamaNodes, Ankr) and does not report transactions timely. Try with another node.

    See eth_defi.provider.fallback.FallbackProvider for details.

  • web3 (web3.main.Web3) –

Returns

Map of transaction hashes -> receipt

Return type

Dict[hexbytes.main.HexBytes, dict]

broadcast_transactions(web3, txs, confirmation_block_count=0, work_around_bad_nodes=True, bad_node_sleep=0.5)

Broadcast and wait a bunch of signed transactions to confirm.

Multiple transactions can be broadcasted and confirmed in a single go, to ensure fast confirmation batches.

Parameters

  • web3 (web3.main.Web3) – Web3

  • txs (List[eth_account.datastructures.SignedTransaction]) – List of Signed transactions

  • work_around_bad_nodes – If true try to work around issues with low quality JSON-RPC APIs like Ganache by checking if the transaction broadcast succeeded

  • confirmation_block_count – How many blocks wait for the transaction receipt to settle. Set to zero to return as soon as we see the first transaction receipt or when using insta-mining tester RPC.

Returns

List of tx hashes

Raises

BroadcastFailure –

If the JSON-RPC node rejects the transaction.

  • Anvil will reject some transactions immediately: if there is not enough gas money

  • Ethereum Tester reject some transactions immediately on any error in automining mode

Return type

List[hexbytes.main.HexBytes]

broadcast_and_wait_transactions_to_complete(web3, txs, confirm_ok=True, work_around_bad_nodes=True, confirmation_block_count=0, max_timeout=datetime.timedelta(seconds=300), poll_delay=datetime.timedelta(seconds=1))

Broadcast and wait a bunch of signed transactions to confirm.

Multiple transactions can be broadcasted and confirmed in a single go, to ensure fast confirmation batches.

Parameters

  • web3 (web3.main.Web3) – Web3

  • txs (List[eth_account.datastructures.SignedTransaction]) – List of Signed transactions

  • confirm_ok – Raise an error if any of the transaction reverts

  • max_timeout – How long we wait until we give up waiting transactions to complete

  • poll_delay – Poll timeout between the tx check loops

  • work_around_bad_nodes – If true try to work around issues with low quality JSON-RPC APIs like Ganache by checking if the transaction broadcast succeeded

  • confirmation_block_count (int) – How many blocks wait for the transaction receipt to settle. Set to zero to return as soon as we see the first transaction receipt.

Returns

Map transaction hash -> receipt

Raises

Reverted – If the transaction did not go through and confirm_ok is set.

Return type

Dict[hexbytes.main.HexBytes, dict]

wait_and_broadcast_multiple_nodes(web3, txs, confirmation_block_count=0, max_timeout=datetime.timedelta(seconds=300), poll_delay=datetime.timedelta(seconds=1), node_switch_timeout=datetime.timedelta(seconds=180), check_nonce_validity=True, mine_blocks=False, inter_node_delay=datetime.timedelta(seconds=60))

Try to broadcast transactions through multiple nodes.

  • Broadcast transaction through all nodes

  • Wait to confirm

  • If node_switch_timeout is reached, try to confirm using an alternative node

Parameters
Returns

Map of transaction hashes -> receipt

Raises

  • ConfirmationTimedOut – If we cannot get transactions out

  • NonceMismatch –

    Starting nonce does not match what we see on chain.

    When check_nonce_validity is set.

  • Exception –

    If all nodes fail to broadcast the transaction, then raise an exception.

    It’s likely that there is a problem with a transaction.

    The exception is raised after we try multiple nodes multiple times, based on node_switch_timeout and other arguments.

    A reverted transaction is not an exception, but will be returned in the receipts.

    In the case of multiple exceptions, the last one is raised. The exception is whatever lower stack is giving us.

  • OutOfGasFunds – The hot wallet account does not have enough native token to cover the tx fees.

Return type

Dict[hexbytes.main.HexBytes, dict]

check_nonce_mismatch(web3, txs)

Check for nonce re-use issues.

Compare pre-signed transactions with on-chain addresses’ nonce states.

Raises

NonceMismatch – If your transaction broadcast is going to fail because nonce too low.

Parameters
wait_and_broadcast_multiple_nodes_mev_blocker(provider, txs, max_timeout=datetime.timedelta(seconds=600), poll_delay=datetime.timedelta(seconds=10), broadcast_and_read_delay=datetime.timedelta(seconds=6), try_other_provider_delay=datetime.timedelta(seconds=45))

Broadcast transactions through a MEV blocker enabled endpoint.

  • Cannot transact multiple transactions simultaneously, need to broadacst and confirm one by one

For all transactions

  • Broadcast transaction

  • Wait until it is confirmed

    • To avoid nonce errors

Parameters
Returns

Map of transaction hashes -> receipt

Raises

  • ConfirmationTimedOut – If we cannot get transactions out

  • NonceMismatch –

    Starting nonce does not match what we see on chain.

    When check_nonce_validity is set.

  • Exception –

    If all nodes fail to broadcast the transaction, then raise an exception.

    It’s likely that there is a problem with a transaction.

    The exception is raised after we try multiple nodes multiple times, based on node_switch_timeout and other arguments.

    A reverted transaction is not an exception, but will be returned in the receipts.

    In the case of multiple exceptions, the last one is raised. The exception is whatever lower stack is giving us.

  • OutOfGasFunds – The hot wallet account does not have enough native token to cover the tx fees.

Return type

Dict[hexbytes.main.HexBytes, dict]