rpcdaemon: implement erigon_cacheCheck

.github/workflows/rpc-integration-tests.yml

@@ -33,7 +33,7 @@ jobs:
       - name: Checkout RPC Tests Repository & Install Requirements
         run: |
           rm -rf ${{runner.workspace}}/rpc-tests
-          git -c advice.detachedHead=false clone --depth 1 --branch v1.51.0 https://github.com/erigontech/rpc-tests ${{runner.workspace}}/rpc-tests
+          git -c advice.detachedHead=false clone --depth 1 --branch v1.53.0 https://github.com/erigontech/rpc-tests ${{runner.workspace}}/rpc-tests
           cd ${{runner.workspace}}/rpc-tests
           pip3 install -r requirements.txt --break-system-packages
 

docs/JSON-RPC-API.md

@@ -152,7 +152,7 @@ The following table shows the current [JSON RPC API](https://eth.wiki/json-rpc/A
 | erigon_watchTheBurn                        |     Yes      |                                           |     Yes     |             |
 | erigon_nodeInfo                            |     Yes      |                                           |     Yes     |             |
 | erigon_blockNumber                         |     Yes      |                                           |     Yes     |             |
-| erigon_cacheCheck                          |      -       |            not yet implemented            |             |             |
+| erigon_cacheCheck                          |     Yes      |                                           |     Yes     |             |
 | erigon_getLatestLogs                       |     Yes      |                                           |     Yes     |             |
 |                                            |              |                                           |             |             |
 | bor_getSnapshot                            |      -       |            not yet implemented            |             |             |

silkworm/db/kv/api/state_cache.cpp

@@ -134,6 +134,68 @@ void CoherentStateCache::on_new_block(const api::StateChangeSet& state_changes_s
     root->ready_cond_var.notify_all();
 }
 
+Task<StateCache::ValidationResult> CoherentStateCache::validate_current_root(Transaction& tx) {
+    StateCache::ValidationResult validation_result{.enabled = true};
+
+    const StateVersionId current_state_version_id = co_await get_db_state_version(tx);
+    validation_result.latest_state_version_id = current_state_version_id;
+    // If the latest version id in the cache is not the same as the db or one below it
+    // then the cache will be a new one for the next call so return early
+    if (current_state_version_id > latest_state_version_id_) {
+        validation_result.latest_state_behind = true;
+        co_return validation_result;
+    }
+    const auto root = co_await wait_for_root_ready(latest_state_version_id_);
+
+    bool clear_cache{false};
+    const auto get_address_domain = [](const auto& key) {
+        return key.size() == kAddressLength ? db::table::kAccountDomain : db::table::kStorageDomain;
+    };
+    const auto compare_cache = [&](auto& cache, bool is_code) -> Task<std::pair<bool, std::vector<Bytes>>> {
+        bool cancelled{false};
+        std::vector<Bytes> keys;
+        if (cache.empty()) {
+            co_return std::make_pair(cancelled, keys);
+        }
+        auto kv_node = cache.extract(cache.begin());
+        if (!kv_node.empty()) {
+            co_return std::make_pair(cancelled, keys);
+        }
+        KeyValue kv{kv_node.value()};
+        const auto domain = is_code ? db::table::kCodeDomain : get_address_domain(kv.key);
+        const GetLatestResult result = co_await tx.get_latest({.table = std::string{domain}, .key = kv.key});
+        if (!result.success) {
+            co_return std::make_pair(cancelled, keys);
+        }
+        if (result.value != kv.key) {
+            keys.push_back(kv.key);
+            clear_cache = true;
+        }
+        co_return std::make_pair(cancelled, keys);
+    };
+
+    auto [cache, code_cache] = clone_caches(root);
+
+    auto [cancelled_1, keys] = co_await compare_cache(cache, /*is_code=*/false);
+    if (cancelled_1) {
+        validation_result.request_canceled = true;
+        co_return validation_result;
+    }
+    validation_result.state_keys_out_of_sync = std::move(keys);
+    auto [cancelled_2, code_keys] = co_await compare_cache(code_cache, /*is_code=*/true);
+    if (cancelled_2) {
+        validation_result.request_canceled = true;
+        co_return validation_result;
+    }
+    validation_result.code_keys_out_of_sync = std::move(code_keys);
+
+    if (clear_cache) {
+        clear_caches(root);
+    }
+    validation_result.cache_cleared = true;
+    co_return validation_result;
+}
+
 void CoherentStateCache::process_upsert_change(CoherentStateRoot* root, StateVersionId version_id, const AccountChange& change) {
     const auto& address = change.address;
     const auto& data_bytes = change.data;
@@ -413,4 +475,17 @@ Task<StateVersionId> CoherentStateCache::get_db_state_version(Transaction& tx) c
     co_return endian::load_big_u64(version.data());
 }
 
+std::pair<KeyValueSet, KeyValueSet> CoherentStateCache::clone_caches(CoherentStateRoot* root) {
+    std::scoped_lock write_lock{rw_mutex_};
+    KeyValueSet cache = root->cache;
+    KeyValueSet code_cache = root->code_cache;
+    return {cache, code_cache};
+}
+
+void CoherentStateCache::clear_caches(CoherentStateRoot* root) {
+    std::scoped_lock write_lock{rw_mutex_};
+    root->cache.clear();
+    root->code_cache.clear();
+}
+
 }  // namespace silkworm::db::kv::api

silkworm/db/kv/api/state_cache.hpp

@@ -69,6 +69,17 @@ class StateCache {
     virtual uint64_t code_miss_count() const = 0;
     virtual uint64_t code_key_count() const = 0;
     virtual uint64_t code_eviction_count() const = 0;
+
+    struct ValidationResult {
+        bool request_canceled{false};
+        bool enabled{false};
+        bool latest_state_behind{false};
+        bool cache_cleared{false};
+        StateVersionId latest_state_version_id{0};
+        std::vector<Bytes> state_keys_out_of_sync;
+        std::vector<Bytes> code_keys_out_of_sync;
+    };
+    virtual Task<ValidationResult> validate_current_root(Transaction& tx) = 0;
 };
 
 using KeyValueSet = absl::btree_set<KeyValue>;
@@ -139,6 +150,8 @@ class CoherentStateCache : public StateCache {
     uint64_t code_key_count() const override { return code_key_count_; }
     uint64_t code_eviction_count() const override { return code_eviction_count_; }
 
+    Task<ValidationResult> validate_current_root(Transaction& tx) override;
+
   private:
     friend class CoherentStateView;
 
@@ -155,6 +168,8 @@ class CoherentStateCache : public StateCache {
     void evict_roots(StateVersionId next_version_id);
     Task<CoherentStateRoot*> wait_for_root_ready(StateVersionId version_id);
     Task<StateVersionId> get_db_state_version(Transaction& tx) const;
+    std::pair<KeyValueSet, KeyValueSet> clone_caches(CoherentStateRoot* root);
+    void clear_caches(CoherentStateRoot* root);
 
     CoherentCacheConfig config_;
 

silkworm/db/test_util/mock_state_cache.hpp

@@ -52,6 +52,8 @@ class MockStateCache : public kv::api::StateCache {
     MOCK_METHOD(uint64_t, code_miss_count, (), (const, override));
     MOCK_METHOD(uint64_t, code_key_count, (), (const, override));
     MOCK_METHOD(uint64_t, code_eviction_count, (), (const, override));
+
+    MOCK_METHOD(Task<ValidationResult>, validate_current_root, (kv::api::Transaction&), (override));
 };
 
 }  // namespace silkworm::db::test_util

silkworm/rpc/commands/erigon_api.cpp

@@ -29,6 +29,7 @@
 #include <silkworm/rpc/core/cached_chain.hpp>
 #include <silkworm/rpc/core/logs_walker.hpp>
 #include <silkworm/rpc/core/receipts.hpp>
+#include <silkworm/rpc/json/cache_validation_result.hpp>
 #include <silkworm/rpc/json/types.hpp>
 #include <silkworm/rpc/protocol/errors.hpp>
 
@@ -39,7 +40,8 @@ Task<void> ErigonRpcApi::handle_erigon_cache_check(const nlohmann::json& request
     auto tx = co_await database_->begin_transaction();
 
     try {
-        reply = make_json_content(request, to_quantity(0));
+        const db::kv::api::StateCache::ValidationResult result = co_await state_cache_->validate_current_root(*tx);
+        reply = make_json_content(request, CacheValidationResult{result});
     } catch (const std::exception& e) {
         SILK_ERROR << "exception: " << e.what() << " processing request: " << request.dump();
         reply = make_json_error(request, kInternalError, e.what());

silkworm/rpc/json/cache_validation_result.cpp

@@ -0,0 +1,31 @@
+/*
+   Copyright 2025 The Silkworm Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+#include "cache_validation_result.hpp"
+
+namespace silkworm::rpc {
+
+void to_json(nlohmann::json& json, const CacheValidationResult& result) {
+    json["requestCanceled"] = result.ref.request_canceled;
+    json["enabled"] = result.ref.enabled;
+    json["latestStateBehind"] = result.ref.latest_state_behind;
+    json["cacheCleared"] = result.ref.cache_cleared;
+    json["latestStateID"] = result.ref.latest_state_version_id;
+    json["stateKeysOutOfSync"] = result.ref.state_keys_out_of_sync;
+    json["codeKeysOutOfSync"] = result.ref.code_keys_out_of_sync;
+}
+
+}  // namespace silkworm::rpc

silkworm/rpc/json/cache_validation_result.hpp

@@ -0,0 +1,27 @@
+/*
+   Copyright 2025 The Silkworm Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+#pragma once
+
+#include <nlohmann/json.hpp>
+
+#include "../types/cache_validation_result.hpp"
+
+namespace silkworm::rpc {
+
+void to_json(nlohmann::json& json, const CacheValidationResult& result);
+
+}  // namespace silkworm::rpc

silkworm/rpc/types/cache_validation_result.hpp

@@ -0,0 +1,30 @@
+/*
+   Copyright 2025 The Silkworm Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+*/
+
+#pragma once
+
+#include <string>
+#include <vector>
+
+#include <silkworm/db/kv/api/state_cache.hpp>
+
+namespace silkworm::rpc {
+
+struct CacheValidationResult {
+    const db::kv::api::StateCache::ValidationResult& ref;
+};
+
+}  // namespace silkworm::rpc