Bug: Etherscan cache is constantly invalidated (#40)

Closes: foundry-rs/foundry#6792

Due to a small logical error and a missing smoke test the Etherscan
cache was constantly being invalidated.

On a large codebase with 197 tests, without this optimization:
foundry-rs/foundry#7606

Comparison:

1. Ran 17 test suites in 53.41s (64.87s CPU time): 197 tests passed, 0
failed, 0 skipped (197 total tests) (no cache)
2. Ran 17 test suites in 6.29s (49.10s CPU time): 197 tests passed, 0
failed, 0 skipped (197 total tests) (with cache)

src/lib.rs

@@ -388,16 +388,31 @@ impl ClientBuilder {
 }
 
 /// A wrapper around an Etherscan cache object with an expiry
+/// time for each item.
 #[derive(Clone, Debug, Deserialize, Serialize)]
 struct CacheEnvelope<T> {
+    // The expiry time is the time the cache item was created + the cache TTL.
+    // The cache item is considered expired if the current time is greater than the expiry time.
     expiry: u64,
+    // The cached data.
     data: T,
 }
 
-/// Simple cache for etherscan requests
+/// Simple cache for Etherscan requests.
+///
+/// The cache is stored at the defined `root` with the following structure:
+///
+/// - $root/abi/$address.json
+/// - $root/sources/$address.json
+///
+/// Each cache item is stored as a JSON file with the following structure:
+///
+/// - { "expiry": $expiry, "data": $data }
 #[derive(Clone, Debug)]
 struct Cache {
+    // Path to the cache directory root.
     root: PathBuf,
+    // Time to live for each cache item.
     ttl: Duration,
 }
 
@@ -444,18 +459,25 @@ impl Cache {
 
     fn get<T: DeserializeOwned>(&self, prefix: &str, address: Address) -> Option<T> {
         let path = self.root.join(prefix).join(format!("{address:?}.json"));
+
         let Ok(contents) = std::fs::read_to_string(path) else {
             return None;
         };
+
         let Ok(inner) = serde_json::from_str::<CacheEnvelope<T>>(&contents) else {
             return None;
         };
-        // If this does not return None then we have passed the expiry
+
+        // Check if the cache item is still valid.
         SystemTime::now()
             .duration_since(UNIX_EPOCH)
             .expect("system time is before unix epoch")
-            .checked_sub(Duration::from_secs(inner.expiry))
-            .map(|_| inner.data)
+            // Check if the current time is less than the expiry time
+            // to determine if the cache item is still valid.
+            .lt(&Duration::from_secs(inner.expiry))
+            // If the cache item is still valid, return the data.
+            // Otherwise, return None.
+            .then_some(inner.data)
     }
 }
 

test-data/cache/abi/0x00000000219ab540356cbb839cbe05303d7705fa.json

@@ -0,0 +1 @@
+{"expiry":1713286751,"data":[{"type":"constructor","inputs":[],"stateMutability":"nonpayable"},{"type":"function","name":"deposit","inputs":[{"name":"pubkey","type":"bytes","internalType":"bytes"},{"name":"withdrawal_credentials","type":"bytes","internalType":"bytes"},{"name":"signature","type":"bytes","internalType":"bytes"},{"name":"deposit_data_root","type":"bytes32","internalType":"bytes32"}],"outputs":[],"stateMutability":"payable"},{"type":"function","name":"get_deposit_count","inputs":[],"outputs":[{"name":"","type":"bytes","internalType":"bytes"}],"stateMutability":"view"},{"type":"function","name":"get_deposit_root","inputs":[],"outputs":[{"name":"","type":"bytes32","internalType":"bytes32"}],"stateMutability":"view"},{"type":"function","name":"supportsInterface","inputs":[{"name":"interfaceId","type":"bytes4","internalType":"bytes4"}],"outputs":[{"name":"","type":"bool","internalType":"bool"}],"stateMutability":"pure"},{"type":"event","name":"DepositEvent","inputs":[{"name":"pubkey","type":"bytes","indexed":false,"internalType":"bytes"},{"name":"withdrawal_credentials","type":"bytes","indexed":false,"internalType":"bytes"},{"name":"amount","type":"bytes","indexed":false,"internalType":"bytes"},{"name":"signature","type":"bytes","indexed":false,"internalType":"bytes"},{"name":"index","type":"bytes","indexed":false,"internalType":"bytes"}],"anonymous":false}]}

test-data/cache/sources/0x00000000219ab540356cbb839cbe05303d7705fa.json

@@ -0,0 +1 @@
+{"expiry":1713286754,"data":[{"SourceCode":"// ┏━━━┓━┏┓━┏┓━━┏━━━┓━━┏━━━┓━━━━┏━━━┓━━━━━━━━━━━━━━━━━━━┏┓━━━━━┏━━━┓━━━━━━━━━┏┓━━━━━━━━━━━━━━┏┓━\r\n// ┃┏━━┛┏┛┗┓┃┃━━┃┏━┓┃━━┃┏━┓┃━━━━┗┓┏┓┃━━━━━━━━━━━━━━━━━━┏┛┗┓━━━━┃┏━┓┃━━━━━━━━┏┛┗┓━━━━━━━━━━━━┏┛┗┓\r\n// ┃┗━━┓┗┓┏┛┃┗━┓┗┛┏┛┃━━┃┃━┃┃━━━━━┃┃┃┃┏━━┓┏━━┓┏━━┓┏━━┓┏┓┗┓┏┛━━━━┃┃━┗┛┏━━┓┏━┓━┗┓┏┛┏━┓┏━━┓━┏━━┓┗┓┏┛\r\n// ┃┏━━┛━┃┃━┃┏┓┃┏━┛┏┛━━┃┃━┃┃━━━━━┃┃┃┃┃┏┓┃┃┏┓┃┃┏┓┃┃━━┫┣┫━┃┃━━━━━┃┃━┏┓┃┏┓┃┃┏┓┓━┃┃━┃┏┛┗━┓┃━┃┏━┛━┃┃━\r\n// ┃┗━━┓━┃┗┓┃┃┃┃┃┃┗━┓┏┓┃┗━┛┃━━━━┏┛┗┛┃┃┃━┫┃┗┛┃┃┗┛┃┣━━┃┃┃━┃┗┓━━━━┃┗━┛┃┃┗┛┃┃┃┃┃━┃┗┓┃┃━┃┗┛┗┓┃┗━┓━┃┗┓\r\n// ┗━━━┛━┗━┛┗┛┗┛┗━━━┛┗┛┗━━━┛━━━━┗━━━┛┗━━┛┃┏━┛┗━━┛┗━━┛┗┛━┗━┛━━━━┗━━━┛┗━━┛┗┛┗┛━┗━┛┗┛━┗━━━┛┗━━┛━┗━┛\r\n// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┃┃━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\r\n// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┗┛━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\r\n\r\n// SPDX-License-Identifier: CC0-1.0\r\n\r\npragma solidity 0.6.11;\r\n\r\n// This interface is designed to be compatible with the Vyper version.\r\n/// @notice This is the Ethereum 2.0 deposit contract interface.\r\n/// For more information see the Phase 0 specification under https://github.com/ethereum/eth2.0-specs\r\ninterface IDepositContract {\r\n    /// @notice A processed deposit event.\r\n    event DepositEvent(\r\n        bytes pubkey,\r\n        bytes withdrawal_credentials,\r\n        bytes amount,\r\n        bytes signature,\r\n        bytes index\r\n    );\r\n\r\n    /// @notice Submit a Phase 0 DepositData object.\r\n    /// @param pubkey A BLS12-381 public key.\r\n    /// @param withdrawal_credentials Commitment to a public key for withdrawals.\r\n    /// @param signature A BLS12-381 signature.\r\n    /// @param deposit_data_root The SHA-256 hash of the SSZ-encoded DepositData object.\r\n    /// Used as a protection against malformed input.\r\n    function deposit(\r\n        bytes calldata pubkey,\r\n        bytes calldata withdrawal_credentials,\r\n        bytes calldata signature,\r\n        bytes32 deposit_data_root\r\n    ) external payable;\r\n\r\n    /// @notice Query the current deposit root hash.\r\n    /// @return The deposit root hash.\r\n    function get_deposit_root() external view returns (bytes32);\r\n\r\n    /// @notice Query the current deposit count.\r\n    /// @return The deposit count encoded as a little endian 64-bit number.\r\n    function get_deposit_count() external view returns (bytes memory);\r\n}\r\n\r\n// Based on official specification in https://eips.ethereum.org/EIPS/eip-165\r\ninterface ERC165 {\r\n    /// @notice Query if a contract implements an interface\r\n    /// @param interfaceId The interface identifier, as specified in ERC-165\r\n    /// @dev Interface identification is specified in ERC-165. This function\r\n    ///  uses less than 30,000 gas.\r\n    /// @return `true` if the contract implements `interfaceId` and\r\n    ///  `interfaceId` is not 0xffffffff, `false` otherwise\r\n    function supportsInterface(bytes4 interfaceId) external pure returns (bool);\r\n}\r\n\r\n// This is a rewrite of the Vyper Eth2.0 deposit contract in Solidity.\r\n// It tries to stay as close as possible to the original source code.\r\n/// @notice This is the Ethereum 2.0 deposit contract interface.\r\n/// For more information see the Phase 0 specification under https://github.com/ethereum/eth2.0-specs\r\ncontract DepositContract is IDepositContract, ERC165 {\r\n    uint constant DEPOSIT_CONTRACT_TREE_DEPTH = 32;\r\n    // NOTE: this also ensures `deposit_count` will fit into 64-bits\r\n    uint constant MAX_DEPOSIT_COUNT = 2**DEPOSIT_CONTRACT_TREE_DEPTH - 1;\r\n\r\n    bytes32[DEPOSIT_CONTRACT_TREE_DEPTH] branch;\r\n    uint256 deposit_count;\r\n\r\n    bytes32[DEPOSIT_CONTRACT_TREE_DEPTH] zero_hashes;\r\n\r\n    constructor() public {\r\n        // Compute hashes in empty sparse Merkle tree\r\n        for (uint height = 0; height < DEPOSIT_CONTRACT_TREE_DEPTH - 1; height++)\r\n            zero_hashes[height + 1] = sha256(abi.encodePacked(zero_hashes[height], zero_hashes[height]));\r\n    }\r\n\r\n    function get_deposit_root() override external view returns (bytes32) {\r\n        bytes32 node;\r\n        uint size = deposit_count;\r\n        for (uint height = 0; height < DEPOSIT_CONTRACT_TREE_DEPTH; height++) {\r\n            if ((size & 1) == 1)\r\n                node = sha256(abi.encodePacked(branch[height], node));\r\n            else\r\n                node = sha256(abi.encodePacked(node, zero_hashes[height]));\r\n            size /= 2;\r\n        }\r\n        return sha256(abi.encodePacked(\r\n            node,\r\n            to_little_endian_64(uint64(deposit_count)),\r\n            bytes24(0)\r\n        ));\r\n    }\r\n\r\n    function get_deposit_count() override external view returns (bytes memory) {\r\n        return to_little_endian_64(uint64(deposit_count));\r\n    }\r\n\r\n    function deposit(\r\n        bytes calldata pubkey,\r\n        bytes calldata withdrawal_credentials,\r\n        bytes calldata signature,\r\n        bytes32 deposit_data_root\r\n    ) override external payable {\r\n        // Extended ABI length checks since dynamic types are used.\r\n        require(pubkey.length == 48, \"DepositContract: invalid pubkey length\");\r\n        require(withdrawal_credentials.length == 32, \"DepositContract: invalid withdrawal_credentials length\");\r\n        require(signature.length == 96, \"DepositContract: invalid signature length\");\r\n\r\n        // Check deposit amount\r\n        require(msg.value >= 1 ether, \"DepositContract: deposit value too low\");\r\n        require(msg.value % 1 gwei == 0, \"DepositContract: deposit value not multiple of gwei\");\r\n        uint deposit_amount = msg.value / 1 gwei;\r\n        require(deposit_amount <= type(uint64).max, \"DepositContract: deposit value too high\");\r\n\r\n        // Emit `DepositEvent` log\r\n        bytes memory amount = to_little_endian_64(uint64(deposit_amount));\r\n        emit DepositEvent(\r\n            pubkey,\r\n            withdrawal_credentials,\r\n            amount,\r\n            signature,\r\n            to_little_endian_64(uint64(deposit_count))\r\n        );\r\n\r\n        // Compute deposit data root (`DepositData` hash tree root)\r\n        bytes32 pubkey_root = sha256(abi.encodePacked(pubkey, bytes16(0)));\r\n        bytes32 signature_root = sha256(abi.encodePacked(\r\n            sha256(abi.encodePacked(signature[:64])),\r\n            sha256(abi.encodePacked(signature[64:], bytes32(0)))\r\n        ));\r\n        bytes32 node = sha256(abi.encodePacked(\r\n            sha256(abi.encodePacked(pubkey_root, withdrawal_credentials)),\r\n            sha256(abi.encodePacked(amount, bytes24(0), signature_root))\r\n        ));\r\n\r\n        // Verify computed and expected deposit data roots match\r\n        require(node == deposit_data_root, \"DepositContract: reconstructed DepositData does not match supplied deposit_data_root\");\r\n\r\n        // Avoid overflowing the Merkle tree (and prevent edge case in computing `branch`)\r\n        require(deposit_count < MAX_DEPOSIT_COUNT, \"DepositContract: merkle tree full\");\r\n\r\n        // Add deposit data root to Merkle tree (update a single `branch` node)\r\n        deposit_count += 1;\r\n        uint size = deposit_count;\r\n        for (uint height = 0; height < DEPOSIT_CONTRACT_TREE_DEPTH; height++) {\r\n            if ((size & 1) == 1) {\r\n                branch[height] = node;\r\n                return;\r\n            }\r\n            node = sha256(abi.encodePacked(branch[height], node));\r\n            size /= 2;\r\n        }\r\n        // As the loop should always end prematurely with the `return` statement,\r\n        // this code should be unreachable. We assert `false` just to be safe.\r\n        assert(false);\r\n    }\r\n\r\n    function supportsInterface(bytes4 interfaceId) override external pure returns (bool) {\r\n        return interfaceId == type(ERC165).interfaceId || interfaceId == type(IDepositContract).interfaceId;\r\n    }\r\n\r\n    function to_little_endian_64(uint64 value) internal pure returns (bytes memory ret) {\r\n        ret = new bytes(8);\r\n        bytes8 bytesValue = bytes8(value);\r\n        // Byteswapping during copying to bytes.\r\n        ret[0] = bytesValue[7];\r\n        ret[1] = bytesValue[6];\r\n        ret[2] = bytesValue[5];\r\n        ret[3] = bytesValue[4];\r\n        ret[4] = bytesValue[3];\r\n        ret[5] = bytesValue[2];\r\n        ret[6] = bytesValue[1];\r\n        ret[7] = bytesValue[0];\r\n    }\r\n}","ABI":"[{\"inputs\":[],\"stateMutability\":\"nonpayable\",\"type\":\"constructor\"},{\"anonymous\":false,\"inputs\":[{\"indexed\":false,\"internalType\":\"bytes\",\"name\":\"pubkey\",\"type\":\"bytes\"},{\"indexed\":false,\"internalType\":\"bytes\",\"name\":\"withdrawal_credentials\",\"type\":\"bytes\"},{\"indexed\":false,\"internalType\":\"bytes\",\"name\":\"amount\",\"type\":\"bytes\"},{\"indexed\":false,\"internalType\":\"bytes\",\"name\":\"signature\",\"type\":\"bytes\"},{\"indexed\":false,\"internalType\":\"bytes\",\"name\":\"index\",\"type\":\"bytes\"}],\"name\":\"DepositEvent\",\"type\":\"event\"},{\"inputs\":[{\"internalType\":\"bytes\",\"name\":\"pubkey\",\"type\":\"bytes\"},{\"internalType\":\"bytes\",\"name\":\"withdrawal_credentials\",\"type\":\"bytes\"},{\"internalType\":\"bytes\",\"name\":\"signature\",\"type\":\"bytes\"},{\"internalType\":\"bytes32\",\"name\":\"deposit_data_root\",\"type\":\"bytes32\"}],\"name\":\"deposit\",\"outputs\":[],\"stateMutability\":\"payable\",\"type\":\"function\"},{\"inputs\":[],\"name\":\"get_deposit_count\",\"outputs\":[{\"internalType\":\"bytes\",\"name\":\"\",\"type\":\"bytes\"}],\"stateMutability\":\"view\",\"type\":\"function\"},{\"inputs\":[],\"name\":\"get_deposit_root\",\"outputs\":[{\"internalType\":\"bytes32\",\"name\":\"\",\"type\":\"bytes32\"}],\"stateMutability\":\"view\",\"type\":\"function\"},{\"inputs\":[{\"internalType\":\"bytes4\",\"name\":\"interfaceId\",\"type\":\"bytes4\"}],\"name\":\"supportsInterface\",\"outputs\":[{\"internalType\":\"bool\",\"name\":\"\",\"type\":\"bool\"}],\"stateMutability\":\"pure\",\"type\":\"function\"}]","ContractName":"DepositContract","CompilerVersion":"v0.6.11+commit.5ef660b1","OptimizationUsed":1,"Runs":5000000,"ConstructorArguments":"0x","EVMVersion":"Default","Library":"","LicenseType":"Unlicense","Proxy":0,"SwarmSource":"ipfs://dceca8706b29e917dacf25fceef95acac8d90d765ac926663ce4096195952b61"}]}

tests/it/contract.rs

@@ -1,4 +1,4 @@
-use crate::{init_tracing, run_with_client};
+use crate::{init_tracing, run_with_client, run_with_client_cached};
 use alloy_chains::{Chain, NamedChain};
 use foundry_block_explorers::{contract::SourceCodeMetadata, errors::EtherscanError, Client};
 use serial_test::serial;
@@ -31,6 +31,51 @@ async fn can_fetch_contract_abi() {
     .await;
 }
 
+#[tokio::test]
+#[serial]
+async fn can_fetch_and_cache_contract_abi() {
+    async fn fetch_abi(client: &Client, addr: &str) {
+        let abi = client.contract_abi(addr.parse().unwrap()).await.unwrap();
+        assert_eq!(abi, serde_json::from_str(DEPOSIT_CONTRACT_ABI).unwrap());
+    }
+
+    run_with_client_cached(Chain::mainnet(), |client| async move {
+        // Fetch the abi and cache it.
+        fetch_abi(&client, "0x00000000219ab540356cBB839Cbe05303d7705Fa").await;
+
+        // Repeated calls on the cached abi should not trigger a new request.
+        for _ in 0..10 {
+            fetch_abi(&client, "0x00000000219ab540356cBB839Cbe05303d7705Fa").await;
+        }
+    })
+    .await;
+}
+
+#[tokio::test]
+#[serial]
+async fn can_fetch_and_cache_contract_source_code() {
+    async fn fetch_source_code(client: &Client, addr: &str) {
+        let meta = client.contract_source_code(addr.parse().unwrap()).await.unwrap();
+        assert_eq!(meta.items.len(), 1);
+
+        let item = &meta.items[0];
+        assert!(matches!(item.source_code, SourceCodeMetadata::SourceCode(_)));
+        assert_eq!(item.source_code.sources().len(), 1);
+        assert_eq!(item.abi().unwrap(), serde_json::from_str(DEPOSIT_CONTRACT_ABI).unwrap());
+    }
+
+    run_with_client_cached(Chain::mainnet(), |client| async move {
+        // Fetch the source code and cache it.
+        fetch_source_code(&client, "0x00000000219ab540356cBB839Cbe05303d7705Fa").await;
+
+        // Repeated calls on the cached source code should not trigger a new request.
+        for _ in 0..10 {
+            fetch_source_code(&client, "0x00000000219ab540356cBB839Cbe05303d7705Fa").await;
+        }
+    })
+    .await;
+}
+
 #[tokio::test]
 #[serial]
 async fn can_fetch_deposit_contract_source_code_from_blockscout() {

tests/it/main.rs

@@ -6,6 +6,7 @@ use alloy_chains::{Chain, ChainKind, NamedChain};
 use foundry_block_explorers::{errors::EtherscanError, Client};
 use std::{
     future::Future,
+    path::PathBuf,
     time::{Duration, Instant},
 };
 
@@ -34,6 +35,28 @@ where
     run_at_least_duration(duration, f(client)).await
 }
 
+/// Calls the function with a new cached Etherscan Client.
+pub async fn run_with_client_cached<F, Fut, T>(chain: Chain, f: F) -> T
+where
+    F: FnOnce(Client) -> Fut,
+    Fut: Future<Output = T>,
+{
+    init_tracing();
+    let cache_path = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("test-data/cache");
+    let (client, duration) = match Client::builder()
+        .chain(chain)
+        .unwrap()
+        .with_cache(Some(cache_path), Duration::from_secs(24 * 60 * 60))
+        .build()
+    {
+        Ok(c) => (c, rate_limit(chain, true)),
+        Err(_) => {
+            (Client::builder().chain(chain).unwrap().build().unwrap(), rate_limit(chain, false))
+        }
+    };
+    run_at_least_duration(duration, f(client)).await
+}
+
 #[track_caller]
 fn rate_limit(chain: Chain, key: bool) -> Duration {
     match (chain.kind(), key) {