Update request caching documentation

docs/internals.rst

@@ -119,48 +119,100 @@ Provider Configurations
 Request Caching
 ```````````````
 
+.. important::
+    Familiarize yourself with the validation logic for request caching before
+    enabling it. Since this feature often requires making additional requests under the
+    hood to try to guarantee the validity of the data, it may create unnecessary
+    overhead for your use case. Validation can be turned off by setting the
+    ``request_cache_validation_threshold`` option to ``None``, caching all allowed
+    requests, or configured for adjusting performance to your needs.
+
+
 Request caching can be configured at the provider level via the following configuration
 options on the provider instance:
 
 - ``cache_allowed_requests: bool = False``
-- ``cacheable_requests: Set[RPCEndpoint] = CACHEABLE_REQUESTS``
-- ``request_cache_validation_threshold: RequestCacheValidationThreshold = RequestCacheValidationThreshold.FINALIZED``
+- ``cacheable_requests: Optional[Set[RPCEndpoint]]``
+- ``request_cache_validation_threshold: Optional[Union[RequestCacheValidationThreshold, int]]``
 
 For requests that don't rely on block data (e.g., ``eth_chainId``), enabling request
 caching by setting the ``cache_allowed_requests`` option to ``True`` will cache all
 responses. This is safe to do.
 
 However, for requests that rely on block data (e.g., ``eth_getBlockByNumber``), it is
 not safe to always cache their responses because block data can change - during a
-chain reorganization, for example. The ``request_cache_validation_threshold`` option
-allows configuring a safe threshold for caching responses that depend on block data. By
-default, the ``finalized`` block number is used as the validation threshold, meaning
-that a request's response will be cached if the block number it relies on is less than
-or equal to the ``finalized`` block number. If the block number exceeds the
-``finalized`` block number, the response won't be cached.
+chain reorganization or while finality has not been reached, for example. The
+``request_cache_validation_threshold`` option allows configuring a safe threshold for
+caching responses that depend on block data. By default, this option is configured
+to internal values deemed "safe" for the chain id you are connected to. If you are
+connected to mainnet Ethereum, this value is set to the ``finalized`` block number.
+If you are connected to another chain, this value is set to a time internal in seconds,
+from the current time, that is deemed "safe" for that chain's finality mechanism.
+
+**It's important to understand that, in order to perform these validations, extra
+requests are sometimes made to the node to get the appropriate information. For a
+transaction request, for example, it is necessary to get the block information to
+validate the transaction is beyond the safe threshold. This can create overhead,
+especially for high-frequency requests. For this reason, it is important to understand
+when to turn on caching and how to configure the validation appropriately for your
+use case in order to avoid unnecessary overhead.**
+
+We keep a list of some reasonable values for bigger chains and
+use the time interval of 1 hour for everything else. Below is a list of the default
+values for internally configured chains:
+
+    - ETH: RequestCacheValidationThreshold.FINALIZED ("finalized" block)
+    - ARB1: 7 days
+    - ZKSYNC: 1 hour
+    - OETH: 3 minutes
+    - MATIC: 30 minutes
+    - ZKEVM: 1 hour
+    - BASE: 7 days
+    - SCR: 1 hour
+    - GNO: 5 minutes
+    - AVAX: 2 minutes
+    - BNB: 2 minutes
+    - FTM: 1 minute
+
+For Ethereum mainnet, for example, this means that a request's response will be cached
+if the block number the request relies on is less than or equal to the ``finalized``
+block number. If the block number exceeds the ``finalized`` block number, the response
+won't be cached. For all others, the response will be cached if the block timestamp
+related to the data that is being requested is older than or equal to the time interval
+configured for that chain. For any chain not on this list, the default value is set to
+1 hour (this includes all testnets).
 
 This behavior can be modified by setting the ``request_cache_validation_threshold``
 option to ``RequestCacheValidationThreshold.SAFE``, which uses the ``safe`` block as
-the threshold, or to ``None``, which disables cache validation and caches all
-requests (this is not recommended). The ``RequestCacheValidationThreshold`` enum is
-imported from the ``web3.utils`` module.
-
-The current list of requests that are validated by this configuration before being
-cached is:
-
-    - RPC.eth_getBlockByNumber
-    - RPC.eth_getRawTransactionByBlockNumberAndIndex
-    - RPC.eth_getBlockTransactionCountByNumber
-    - RPC.eth_getUncleByBlockNumberAndIndex
-    - RPC.eth_getUncleCountByBlockNumber
-    - RPC.eth_getBlockByHash
-    - RPC.eth_getTransactionByHash
-    - RPC.eth_getTransactionByBlockNumberAndIndex
-    - RPC.eth_getTransactionByBlockHashAndIndex
-    - RPC.eth_getBlockTransactionCountByHash
-    - RPC.eth_getRawTransactionByBlockHashAndIndex
-    - RPC.eth_getUncleByBlockHashAndIndex
-    - RPC.eth_getUncleCountByBlockHash
+the threshold (Ethereum mainnet only), to your own time interval in seconds (for any
+chain, including mainnet Ethereum), or to ``None``, which disables any validation and
+caches all requests (this is not recommended for non testnet chains). The
+``RequestCacheValidationThreshold`` enum, for mainnet ``finalized`` and ``safe`` values,
+is imported from the ``web3.utils`` module.
+
+Note that the ``cacheable_requests`` option can be used to specify a set of RPC
+endpoints that are allowed to be cached. By default, this option is set to an internal
+list of deemed-safe-to-cache endpoints, excluding endpoints such as ``eth_call``, whose
+responses can vary and are not safe to cache. The default list of cacheable requests is
+below, with requests validated by the ``request_cache_validation_threshold`` option in
+bold:
+
+    - eth_chainId
+    - web3_clientVersion
+    - net_version
+    - **eth_getBlockByNumber**
+    - **eth_getRawTransactionByBlockNumberAndIndex**
+    - **eth_getBlockTransactionCountByNumber**
+    - **eth_getUncleByBlockNumberAndIndex**
+    - **eth_getUncleCountByBlockNumber**
+    - **eth_getBlockByHash**
+    - **eth_getTransactionByHash**
+    - **eth_getTransactionByBlockNumberAndIndex**
+    - **eth_getTransactionByBlockHashAndIndex**
+    - **eth_getBlockTransactionCountByHash**
+    - **eth_getRawTransactionByBlockHashAndIndex**
+    - **eth_getUncleByBlockHashAndIndex**
+    - **eth_getUncleCountByBlockHash**
 
 .. code-block:: python
 
@@ -173,13 +225,12 @@ cached is:
         # optional flag to turn on cached requests, defaults to ``False``
         cache_allowed_requests=True,
 
-        # optional, defaults to an internal list of deemed-safe-to-cache endpoints
+        # optional, defaults to an internal list of deemed-safe-to-cache endpoints (see above)
         cacheable_requests={"eth_chainId", "eth_getBlockByNumber"},
 
-        # optional, defaults to ``RequestCacheValidationThreshold.FINALIZED``
-        # can be set to ``RequestCacheValidationThreshold.SAFE`` or turned off
-        # by setting to ``None``.
-        request_cache_validation_threshold=RequestCacheValidationThreshold.SAFE,
+        # optional, defaults to a value that is based on the chain id (see above)
+        request_cache_validation_threshold=60 * 60,  # 1 hour
+        # request_cache_validation_threshold=RequestCacheValidationThreshold.SAFE,  # Ethereum mainnet only
     ))
 
 .. _http_retry_requests:

newsfragments/3508.bugfix.rst

@@ -0,0 +1 @@
+Fix a bug where non-mainnet chains could not cache requests based on missing ``finalized`` block number.

newsfragments/3508.docs.rst

@@ -0,0 +1 @@
+Update the request caching documentation to clarify on when to reach for request caching and how to configure the request validation threshold for certain endpoints.

newsfragments/3508.feature.rst

@@ -0,0 +1 @@
+Allow a time interval, in seconds, to be used as the ``request_cache_validation_threshold`` for request caching. Keep a list of internal default values based on the chain id for some of the bigger chains.