provider.multi_provider

Documentation for eth_defi.provider.multi_provider Python module.

Configuring and managing multiple JSON-RPC provider connections.

See MEV protection and multiple JSON-RPCs configuration tutorial for details.

Module Attributes

`DEFAULT_RETRIES`	Retry count used for ordinary remote JSON-RPC providers.
`DEFAULT_ANVIL_RETRIES`	A registered local Anvil already performs upstream failover.

Functions

create_multi_provider_web3(configuration_line)

Create a Web3 instance with multi-provider support.

Classes

`MultiProviderWeb3`	A web3 instance that knows about multiple RPC endpoints it is using.
`MultiProviderWeb3Factory`	Needed to pass RPC URL as `Web3Factory`

Exceptions

MultiProviderConfigurationError

Could not parse URL soup for configuring web3

DEFAULT_RETRIES: int = 6: Retry count used for ordinary remote JSON-RPC providers.

DEFAULT_ANVIL_RETRIES: int = 0: A registered local Anvil already performs upstream failover. Retrying the localhost request can only multiply a wedged fork’s timeout.

exception MultiProviderConfigurationError

Bases: Exception

Could not parse URL soup for configuring web3

__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.

class MultiProviderWeb3

Bases: web3.main.Web3

A web3 instance that knows about multiple RPC endpoints it is using.

Can use eth_defi.provider.mev_blocker.MEVBlockerProvider for making transactions to prevent frontrunning
There might be several call (read) providers for reading on-chain data with fallbacks using eth_defi.provider.fallback.FallbackProvider

See

get_active_transact_provider()

Get active transact provider.

Can be a call provider if not configured.

Return type: Union[eth_defi.provider.named.BaseNamedProvider, web3.providers.rpc.rpc.HTTPProvider]

get_configured_transact_provider()

Get configured transact provider.

Return type: Optional[eth_defi.provider.mev_blocker.MEVBlockerProvider]

get_active_call_provider()

Get active call provider.

Return type: Union[eth_defi.provider.named.BaseNamedProvider, web3.providers.rpc.rpc.HTTPProvider]

get_fallback_provider()

Get the fallback provider multiplexer.

Return type: eth_defi.provider.fallback.FallbackProvider

switch_to_next_call_provider(): Recycles to the next call provider (if available).

get_api_call_counts()

How many times different APIs where called.

Returns: RPC endpoint name, call count dict
Return type: Dict[str, int]

set_rpc_request_stats(stats)

Attach request accounting to the fallback call provider.

Parameters: stats (Optional[eth_defi.provider.rpcdb.RPCRequestStats]) – Phase or subprocess-task accumulator, or None to detach it.
Return type: None

__init__(provider=None, middleware=None, modules=None, external_modules=None, ens=<web3._utils.empty.Empty object>)

Parameters

provider (Optional[web3.providers.base.BaseProvider]) –
middleware (Optional[Sequence[Any]]) –
modules (Optional[Dict[str, Union[Type[web3.module.Module], Sequence[Any]]]]) –
external_modules (Optional[Dict[str, Union[Type[web3.module.Module], Sequence[Any]]]]) –
ens (Union[ens.ens.ENS, ForwardRef('Empty')]) –

Return type

None

attach_modules(modules)

Attach modules to the Web3 instance.

Parameters: modules (Dict[str, Union[Type[web3.module.Module], Sequence[Any]]]) –
Return type: None

static from_wei(number, unit)

Takes a number of wei and converts it to any other ether unit.

Parameters

number (int) –
unit (str) –

Return type

Union[int, decimal.Decimal]

static is_address(value)

Is the given string an address in any of the known formats?

Parameters: value (Any) –
Return type: bool

solidity_keccak(abi_types, values)

Executes keccak256 exactly as Solidity does. Takes list of abi_types as inputs – [uint24, int8[], bool] and list of corresponding values – [20, [-1, 5, 0], True]

Parameters

abi_types (List[str]) –
values (List[Any]) –

Return type

bytes

static to_checksum_address(value)

Makes a checksum address given a supported format.

Parameters: value (Union[eth_typing.evm.AnyAddress, str, bytes]) –
Return type: eth_typing.evm.ChecksumAddress

static to_hex(primitive=None, hexstr=None, text=None)

Auto converts any supported value into its hex representation. Trims leading zeros, as defined in: https://github.com/ethereum/wiki/wiki/JSON-RPC#hex-value-encoding

Parameters

primitive (Optional[Union[bytes, int, bool, bytearray, memoryview]]) –
hexstr (Optional[eth_typing.encoding.HexStr]) –
text (Optional[str]) –

Return type

eth_typing.encoding.HexStr

static to_int(primitive=None, hexstr=None, text=None)

Converts value to its integer representation. Values are converted this way:

primitive:

bytes, bytearray, memoryview: big-endian integer

bool: True => 1, False => 0

int: unchanged

hexstr: interpret hex as integer

text: interpret as string of digits, like ‘12’ => 12

Parameters

primitive (Optional[Union[bytes, int, bool, bytearray, memoryview]]) –
hexstr (Optional[eth_typing.encoding.HexStr]) –
text (Optional[str]) –

Return type

int

static to_json(obj)

Convert a complex object (like a transaction object) to a JSON string

Parameters: obj (Dict[Any, Any]) –
Return type: str

static to_wei(number, unit)

Takes a number of a unit and converts it to wei.

Parameters

number (Union[int, float, str, decimal.Decimal]) –
unit (str) –

Return type

int

create_multi_provider_web3(configuration_line, fallback_sleep=5.0, fallback_backoff=1.25, request_kwargs=None, session=None, switchover_noisiness=30, default_http_timeout=(3.0, 60.0), retries=None, hint='', unit_test=False, add_signing_middleware=None, skip_verification=False, expected_chain_id=None, rpc_request_stats=None)

Create a Web3 instance with multi-provider support.

Create a complex Web3 connection manager that

Supports fail-overs to different providers
Can have a special execution endpoint for MEV protection
HTTP providers are monkey-patched for faster uJSON reading
HTTP providers have middleware cleared and chain middleware installed

The configuration line is a whitespace separated list of URLs (spaces, newlines, etc.) using mini configuration language.

If any of the protocols have mev+ prefix like mev+https then this endpoint is used for the execution.

Example:

config = "mev+https://rpc.mevblocker.io https://polygon-rpc.com https://bsc-dataseed2.bnbchain.org"
web3 = create_multi_provider_web3(config)
assert get_provider_name(web3.get_fallback_provider()) == "polygon-rpc.com"
assert len(web3.get_fallback_provider().providers) == 2
assert get_provider_name(web3.get_active_transact_provider()) == "rpc.mevblocker.io"

See

MEV protection and multiple JSON-RPCs configuration for details

Parameters

configuration_line (str) – Configuration line from an environment variable, config file or similar.
fallback_sleep – Seconds between JSON-RPC call retries.
fallback_backoff – Sleep increase multiplier.
request_kwargs (Optional[Any]) –
Passed to HTTPProvider, arguments for requests library when doing HTTP requests.

See web3.HTTPProvider for details.

Example: request_kwargs={"timeout": 10.0}
default_http_timeout –
Use this timeout value for HTTP requests library if request_kwargs not given.

Tuple (connect timeout, read timeout)
session (Optional[Any]) –
Use specific HTTP 1.1 session with requests.

If not given create a default session manager with retry logic.
switchover_noisiness – Log level for messages when one RPC provider fails and we try other one.
retries (Optional[int]) –
How many retry count we do calling JSON-RPC API if the API response fails.

When omitted, ordinary remote providers use six retries and a local Anvil URL registered by eth_defi.provider.anvil.launch_anvil() uses none. Anvil’s upstream proxy already performs provider failover, so retrying a wedged localhost request only multiplies the timeout.
hint (Optional[str]) – A hint for error logs if something goes wrong.
unit_test –
Run in unit test mode.

Have special hooks and environment variable based timeouts for unit tests.
add_signing_middleware (Optional[eth_account.signers.local.LocalAccount]) –
If set, install signing middleware for this account.

This allows contract.functions.foo().transact({"from": account.address}) to automatically sign transactions with the given private key.

Pass an eth_account.signers.local.LocalAccount instance, e.g. from Account.from_key(private_key).
skip_verification (bool) –
Skip the startup eth_chainId cross-check of all providers (FallbackProvider.verify_providers()).

That cross-check probes every configured provider with eth_chainId. When fanning out to multiprocessing worker pools (e.g. MultiprocessMulticallReader), each worker rebuilds its own Web3 via MultiProviderWeb3Factory, so this probe runs once per worker and multiplies eth_chainId load on the primary provider — which can itself trip rate limits (HTTP 429). The parent process has already verified the chain ID before fan-out, so pass True for subprocess factories together with expected_chain_id.
expected_chain_id (Optional[int]) –
Pre-seed FallbackProvider.expected_chain_id without probing.

Required when skip_verification is set (asserted). The parent process passes the chain ID it already verified so that runtime provider switchover in the worker still rejects an endpoint that mis-routes to the wrong chain. Without it, a verification-skipped worker would have no chain-id baseline and could silently accept a wrong-chain provider on failover, so the combination is rejected rather than silently downgraded.
rpc_request_stats (Optional[eth_defi.provider.rpcdb.RPCRequestStats]) –

Returns

Configured Web3 instance with multiple providers

Return type

eth_defi.provider.multi_provider.MultiProviderWeb3

class MultiProviderWeb3Factory

Bases: object

Needed to pass RPC URL as Web3Factory

Allows creating web3 connections from a config line in multiprocessing worker pools

__init__(rpc_url, retries=None, hint='', skip_verification=False, expected_chain_id=None, rpc_request_stats=None)

Parameters

rpc_url (str) –
retries (Optional[int]) –
hint (Optional[str]) –
skip_verification (bool) –
expected_chain_id (Optional[int]) –
rpc_request_stats (Optional[eth_defi.provider.rpcdb.RPCRequestStats]) –

skip_verification

Skip the per-worker eth_chainId provider cross-check.

Defaults to False so a stand-alone factory behaves like create_multi_provider_web3(). Set to True when this factory is handed to a multiprocessing worker pool: the parent process has already verified the chain ID, and re-verifying in every worker multiplies eth_chainId load on the primary provider and can itself trigger HTTP 429 rate limiting.

expected_chain_id: Parent-verified chain ID to seed into each worker when skip_verification is set, preserving the runtime switchover chain-id safety check.

rpc_request_stats: Optional accumulator shared by parent-process worker threads.