provider.receipt

Documentation for eth_defi.provider.receipt Python module.

Transaction receipt visibility helpers for multi-provider Web3 setups.

Functions

get_read_providers(web3)

Get JSON-RPC providers used for read calls.

wait_for_transaction_receipt_robust(web3, ...)

Wait until a transaction receipt is visible through all read RPC providers.

Exceptions

ReceiptVisibilityMismatch

Read providers returned conflicting receipt data for the same transaction.

ReceiptVisibilityTimedOut

Timed out before all read providers could see a transaction receipt.
exception ReceiptVisibilityMismatch

Bases: RuntimeError

Read providers returned conflicting receipt data for the same transaction.

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

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

exception ReceiptVisibilityTimedOut

Bases: TimeoutError

Timed out before all read providers could see a transaction receipt.

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

Add a note to the exception

errno

POSIX exception code

filename

exception filename

filename2

second exception filename

strerror

exception strerror

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

get_read_providers(web3)

Get JSON-RPC providers used for read calls.

MEV/sequencer transaction providers are intentionally excluded because some sequencers are write-only and do not support receipt or state reads.

Parameters

web3 (web3.main.Web3) –

Return type

list[web3.providers.base.BaseProvider]

wait_for_transaction_receipt_robust(web3, tx_hash, timeout=120.0, poll_delay=1.0, max_poll_delay=5.0, confirmation_block_count=None, confirmation_block_time=None, extra_sleep=0.0)

Wait until a transaction receipt is visible through all read RPC providers.

This is stricter than web3.eth.wait_for_transaction_receipt() for live multi-RPC setups. Receipt values fetched directly from providers are raw JSON-RPC objects, so comparisons use raw hex strings. For Anvil we use the normal Web3 receipt wait path because Anvil has one coherent local state view. This helper is safe to call after the transaction is already confirmed through the primary provider; it checks read-provider visibility separately.

Parameters

  • web3 (web3.main.Web3) – Web3 instance, optionally backed by FallbackProvider or MEVBlockerProvider.

  • tx_hash (Union[hexbytes.main.HexBytes, str]) – Transaction hash to wait for.

  • timeout (float) – Maximum seconds to wait.

  • poll_delay (float) – Initial delay between polling rounds.

  • max_poll_delay (float) – Maximum adaptive delay between polling rounds.

  • confirmation_block_count (Optional[int]) –

    How many confirmations each read provider should see. This is best-effort because provider block numbers are fetched sequentially.

    Defaults to None, which resolves to DEFAULT_CONFIRMATION_BLOCK_COUNT (2) on live chains and is ignored on Anvil (Anvil has a single coherent state view).

    Why 2 by default: requiring confirmations makes it very likely a state-read eth_call issued immediately after this wait hits a backend whose state trie already reflects the transaction, rather than merely a backend that has the receipt visible. This prevents read-after-write races on MultiProvider setups — for example reading an allowance() of 0 right after a confirmed approve() when the read provider trails the sequencer.

    Pass confirmation_block_count=0 explicitly to opt back into pure receipt-visibility behaviour without waiting for confirmations. This also disables the default time-based wait below, unless an explicit confirmation_block_time is passed alongside.

  • confirmation_block_time (Optional[float]) –

    Wall-clock confirmation time in seconds, converted to a per-chain block count using eth_defi.chain.get_evm_block_time().

    The effective confirmation requirement is max(ceil(confirmation_block_time / chain_block_time), confirmation_block_count).

    This makes the wait meaningful on fast chains: a fixed block count of 2 is ~24 s on Ethereum mainnet but only ~0.5 s on Arbitrum, which is not enough for all backends behind a load-balanced RPC endpoint to catch up before a follow-up state read. See DEFAULT_CONFIRMATION_BLOCK_TIME.

    Defaults to None, which resolves to DEFAULT_CONFIRMATION_BLOCK_TIME (25 seconds) — except when confirmation_block_count=0 was explicitly passed, the documented pure receipt-visibility opt-out, in which case no time-based wait is applied either.

    Pass 0 to disable and use only confirmation_block_count. Ignored on Anvil and on chains with no known block time.

  • extra_sleep (float) – Extra seconds to sleep once after all read providers have seen the matching receipt and enough confirmations.

Returns

Typed receipt from the original Web3 instance, preserving middleware behaviour.

Return type

web3.types.TxReceipt