FallbackProvider

Documentation for eth_defi.provider.fallback.FallbackProvider Python class.

class FallbackProvider

Bases: eth_defi.provider.named.BaseNamedProvider

Fault-tolerance for JSON-RPC requests with multiple providers.

Fall back to the next provider on the list if a JSON-RPC request fails. Contains build-in retry logic in round-robin manner. We will also recover from situations when we suspect the node does not have the block data we are asking yet (but should have shorty).

See also

  • eth_defi.middlware.exception_retry_middleware()

  • eth_defi.middlware.ProbablyNodeHasNoBlock()

Note

FallbackProvider does not call any middlewares installed on the providers themselves.

Parameters

  • providers – List of provider we cycle through.

  • strategy –

    What is the strategy to deal with errors.

    Currently on cycling supported.

  • retryable_exceptions – List of exceptions we can retry.

  • retryable_status_codes – List of HTTP status codes we can retry.

  • retryable_rpc_error_codes – List of GoEthereum error codes we can retry.

  • sleep – Seconds between retries.

  • backoff – Multiplier to increase sleep.

  • retries – How many retries we attempt before giving up.

  • switchover_noisiness – How loud we are about switchover issues.

  • state_missing_switch_over_delay –

    If we encounter state missing condition at node, what is the minimum time (seconds) we wait before trying to switch to next node.

    See code comments for details.

Attributes summary

call_endpoint_uri

Return the active node URI where call JSON-RPCs go.

ccip_read_max_redirects

endpoint_uri

Return the active node URI endpoint.

global_ccip_read_enabled

has_persistent_connection

is_async

logger

Methods summary

__init__(providers[, strategy, ...])

param providers

batch_request_func(w3, middleware_onion)

decode_rpc_response(raw_response)

encode_batch_rpc_request(requests)

encode_rpc_request(method, params)

get_active_provider()

Get currently active provider.

get_provider_context_for_log(provider)

Get provider diagnostics suitable for warning logs.

get_total_api_call_counts()

Get API call coubst across all providers

has_multiple_providers()

Have we configured multiple providers

is_connected([show_traceback])

make_batch_request(requests)

make_request(method, params)

Make a request.

request_func(w3, middleware_onion)

@param w3 is the web3 instance @param middleware_onion is an iterable of middleware, ordered by first to execute @returns a function that calls all the middleware and eventually self.make_request()

reset_switch()

Reset the provider switch to the first provider.

switch_provider([log_level, randomise, cause])

Switch to next available provider.

switch_to_provider_index(new_index[, ...])

Switch to a specific provider by index, with the same verification as switch_provider().

verify_providers()

Check that all providers return the same chain ID.
__init__(providers, strategy=FallbackStrategy.cycle_on_error, retryable_exceptions=(<class 'requests.exceptions.ConnectionError'>, <class 'requests.exceptions.HTTPError'>, <class 'requests.exceptions.Timeout'>, <class 'requests.exceptions.TooManyRedirects'>, <class 'web3.exceptions.BlockNotFound'>, <class 'requests.exceptions.ChunkedEncodingError'>, <class 'http.client.RemoteDisconnected'>, <class 'eth_defi.middleware.SomeCrappyRPCProviderException'>, <class 'requests.exceptions.ContentDecodingError'>), retryable_status_codes=(429, 500, 502, 503, 504, 525, 520, 410, 403, 400, 401), retryable_rpc_error_codes=(-32003, -32043, -32005, -32701, 42903, -32002, -32603, -32052, -32601), sleep=5.0, backoff=1.6, retries=6, state_missing_switch_over_delay=12.0, switchover_noisiness=30)
Parameters

  • providers (list[eth_defi.provider.named.BaseNamedProvider | web3.providers.rpc.rpc.HTTPProvider]) – List of provider we cycle through.

  • strategy –

    What is the strategy to deal with errors.

    Currently on cycling supported.

  • retryable_exceptions – List of exceptions we can retry.

  • retryable_status_codes – List of HTTP status codes we can retry.

  • retryable_rpc_error_codes – List of GoEthereum error codes we can retry.

  • sleep (float) – Seconds between retries.

  • backoff (float) – Multiplier to increase sleep.

  • retries (int) – How many retries we attempt before giving up.

  • switchover_noisiness – How loud we are about switchover issues.

  • state_missing_switch_over_delay (float) –

    If we encounter state missing condition at node, what is the minimum time (seconds) we wait before trying to switch to next node.

    See code comments for details.

property call_endpoint_uri: str

Return the active node URI where call JSON-RPCs go.

Warning

Endpoint URIs often contain API keys. They should be never publicly displayed as is.

property endpoint_uri

Return the active node URI endpoint.

For HTTPProvider compatibility.

get_active_provider()

Get currently active provider.

If this provider fails, we are automatically recycled to the next one.

Return type

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

get_provider_context_for_log(provider)

Get provider diagnostics suitable for warning logs.

The context includes Anvil launch metadata when the local Anvil provider has metadata copied by create_multi_provider_web3(). The metadata is registered by eth_defi.provider.anvil.launch_anvil(). Upstream RPC URLs are reduced to domains to avoid leaking API keys.

Parameters

provider (Union[eth_defi.provider.named.BaseNamedProvider, web3.providers.rpc.rpc.HTTPProvider]) – Provider that handled the failing JSON-RPC request.

Returns

Dictionary safe to include in logs.

Return type

dict[str, Any]

get_total_api_call_counts()

Get API call coubst across all providers

Return type

dict[str, int]

has_multiple_providers()

Have we configured multiple providers

Return type

bool

make_request(method, params)

Make a request.

  • By default use the current active provider

  • If there are errors try cycle through providers and sleep between cycles until one provider works

  • Use a special “ignore_error” parameter to skip retries, if given in eth_call payload.

Parameters

  • method (web3.types.RPCEndpoint) –

  • params (Any) –

Return type

web3.types.RPCResponse

request_func(w3, middleware_onion)

@param w3 is the web3 instance @param middleware_onion is an iterable of middleware,

ordered by first to execute

@returns a function that calls all the middleware and

eventually self.make_request()

Parameters

  • w3 (Web3) –

  • middleware_onion (web3.datastructures.NamedElementOnion[str, Type[web3.middleware.base.Web3Middleware]]) –

Return type

Callable[[…], web3.types.RPCResponse]

reset_switch()

Reset the provider switch to the first provider.

  • Assume we have main provider and more expensive backup providers

  • Try to switch back to the main provider if we have switched away due to a temporary error

  • Used in batch scan tasks

switch_provider(log_level=None, randomise=False, cause='<not specified>')

Switch to next available provider.

After switching, verifies that the new provider returns the same eth_chainId as the previously observed value. Providers that cannot answer the verification call are skipped when other alternatives are available. Providers that answer with a different chain ID are rejected.

Parameters

  • log_level (int) – Logging level to be verbose about the switch over

  • randomise – If set switch to a random provider instead of cycling.

  • cause (str) –

switch_to_provider_index(new_index, log_level=None, cause='<not specified>')

Switch to a specific provider by index, with the same verification as switch_provider().

Use this when you need to deterministically select one upstream (e.g. to fail a chain over to a known-good single node) rather than cycling or randomising. Like switch_provider(), after switching it verifies the new provider returns the expected eth_chainId and rolls back to the previous provider (raising ChainIdMismatch) if it does not, so a misconfigured or mis-routing endpoint cannot be silently selected.

Parameters

  • new_index (int) – Index into providers to switch to.

  • log_level (int) – Logging level to be verbose about the switch over.

  • cause (str) – Human-readable reason for the switch, logged for diagnostics.

Raises
verify_providers()

Check that all providers return the same chain ID.

Call this at startup to detect misconfigured RPC endpoints before any trading logic runs. Providers that do not answer during startup are left in the fallback rotation, because their availability can be transient and runtime switching verifies chain ID before selecting them.

Raises

ChainIdMismatch – If responding providers return different chain IDs, or if no provider can be reached at all.