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. If the chain ID does not match or cannot be fetched, the provider index is rolled back to the previous value and the exception is raised.

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

ChainIdMismatch – If the new provider reports a different chain ID than expected, or its eth_chainId cannot be fetched. The active provider is rolled back to the previous one before raising.

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.

Raises

ChainIdMismatch – If any provider returns a different chain ID, or if a provider cannot be reached at all.