feat: add F3 proofs cache #1457

karlem · 2025-10-09T16:41:21Z

Note

Introduce an F3 proof generation and caching service (with RocksDB, metrics, and verifier), wire it into Fendermint and add CLI tools to inspect/manage the cache; also sync contract event/signature markers and minor CI/test tweaks.

Fendermint VM (new service):
- Add fendermint/vm/topdown/proof-service crate for F3 certificate validation, proof bundle assembly, two-level cache (in-memory + RocksDB), persistence, metrics, and verification (assembler.rs, cache.rs, persistence.rs, service.rs, verifier.rs).
- Provide launch_service(...) API and a dev binary proof-cache-test.
App Integration:
- Add dependency on fendermint_vm_topdown_proof_service and include it in workspace.
- New CLI subcommands fendermint proof-cache {inspect|stats|get|clear} for cache management.
Contracts:
- Annotate event signatures and storage slot offsets in LibGateway.sol, LibGatewayActorStorage.sol, LibPowerChangeLog.sol, and Subnet.sol to stay in sync with proof-service.
IPLD Resolver:
- Reduce membership publish intervals in tests; clean up unused log import.
CI:
- Switch Aderyn installation to npm install -g @cyfrin/aderyn.
Deps/Workspace:
- Add parking_lot, humantime-serde; bump bls-signatures to 0.15; update Cargo.toml members.

^{Written by Cursor Bugbot for commit b0213ec. This will update automatically on new commits. Configure here.}

fendermint/actors/f3-light-client/src/state.rs

fendermint/actors/f3-light-client/src/types.rs

fendermint/vm/topdown/proof-service/src/f3_client.rs

fendermint/vm/topdown/proof-service/src/assembler.rs

fendermint/vm/topdown/proof-service/src/types.rs

fendermint/vm/topdown/proof-service/src/service.rs

fendermint/vm/topdown/proof-service/src/f3_client.rs

sergefdrv · 2025-11-10T20:12:27Z

fendermint/vm/topdown/proof-service/README.md

Was this AI-generated? In many places it mentions exact identifiers and full data structures from the current code base. Do we really want to keep such detailed readme in sync with future code changes?

It is AI generated, so updating is quite easy (as we could also have it re-generated on CI?). But I can remove some of the details from it.

It's up to you, I just shared my opinion

It's already out of sync with the actual source code 🙃

Because there was no need to re-generate it give that there was no final implementation approved.

fendermint/vm/topdown/proof-service/src/assembler.rs

sergefdrv

I did my first round of review and left some comments/questions. I would do another round after getting your answers.

One general suggestion: maybe we should consider removing the persistent storage functionality from this PR and make it simpler and easier to review? We can add it later, in a separate PR. WDYT?

fendermint/vm/topdown/proof-service/src/assembler.rs

fendermint/vm/topdown/proof-service/src/verifier.rs

fendermint/vm/topdown/proof-service/Cargo.toml

fendermint/vm/topdown/proof-service/src/assembler.rs

karlem · 2025-11-18T18:52:20Z

One general suggestion: maybe we should consider removing the persistent storage functionality from this PR and make it simpler and easier to review? We can add it later, in a separate PR. WDYT?

I honestly think that the storage is NOT a big part of the PR so it should be fine with it.

sergefdrv · 2025-11-19T19:29:57Z

One general suggestion: maybe we should consider removing the persistent storage functionality from this PR and make it simpler and easier to review? We can add it later, in a separate PR. WDYT?

I honestly think that the storage is NOT a big part of the PR so it should be fine with it.

Then I should review the interplay between the in-memory cache, the persistent storage, and the on-chain state more closely.

fendermint/vm/topdown/proof-service/src/cache.rs

fendermint/app/src/cmd/proof_cache.rs

fendermint/app/options/src/proof_cache.rs

fendermint/vm/topdown/proof-service/Cargo.toml

fendermint/vm/topdown/proof-service/src/assembler.rs

fendermint/vm/topdown/proof-service/src/verifier.rs

fendermint/vm/topdown/proof-service/src/assembler.rs

cursor · 2025-12-04T19:58:53Z

fendermint/vm/topdown/proof-service/src/assembler.rs

+            StorageProofSpec {
+                actor_id: self.gateway_actor_id,
+                slot: calculate_storage_slot("", NEXT_CONFIG_NUMBER_STORAGE_SLOT),
+            },


Bug: Storage slot calculation uses empty string for global config

The second StorageProofSpec for NEXT_CONFIG_NUMBER_STORAGE_SLOT uses an empty string "" for calculate_storage_slot, while the first spec uses self.subnet_id. If nextConfigurationNumber is a global field (not per-subnet), passing an empty string may be intentional, but if it's per-subnet like the first spec, this would generate an incorrect storage slot. The inconsistency between the two specs suggests a potential copy-paste error or misunderstanding of the storage layout.

fendermint/vm/topdown/proof-service/src/cache.rs

fendermint/vm/topdown/proof-service/src/types.rs

fendermint/vm/topdown/proof-service/src/cache.rs

fendermint/vm/topdown/proof-service/src/service.rs

fendermint/vm/topdown/proof-service/src/types.rs

fendermint/vm/topdown/proof-service/src/service.rs

fendermint/vm/topdown/proof-service/src/verifier.rs

fendermint/vm/topdown/proof-service/src/service.rs

cursor · 2025-12-08T20:40:12Z

fendermint/vm/topdown/proof-service/src/bin/proof-cache-test.rs

+        "calibrationnet",
+        initial_instance,
+    )
+    .await?;


Bug: Hardcoded F3 network name in development testing tool

The development tool accepts arbitrary RPC URLs via --rpc-url but hardcodes "calibrationnet" as the F3 network name. The F3 light client uses this network name as part of the BLS signing domain, so if a user points the tool at a mainnet or other network RPC endpoint, certificate validation will silently fail with cryptographic errors rather than a clear message about the network mismatch. The network name parameter is missing from the CLI arguments despite the tool being designed to work with arbitrary RPC endpoints.

sergefdrv

Nice job! Now this PR looks good. I don't have any serious concern, just some small minor suggestions. Feel free to merge at your discretion.

fendermint/vm/topdown/proof-service/src/service.rs

fendermint/vm/topdown/proof-service/src/types.rs

fendermint/vm/topdown/proof-service/README.md

sergefdrv · 2025-12-09T10:42:40Z

fendermint/vm/topdown/proof-service/README.md

It's already out of sync with the actual source code 🙃

fendermint/vm/topdown/proof-service/src/lib.rs

fendermint/vm/topdown/proof-service/src/service.rs

cursor · 2025-12-09T18:35:11Z

fendermint/vm/topdown/proof-service/src/bin/proof-cache-test.rs

+        "calibrationnet",
+        initial_instance,
+    )
+    .await?;


Bug: Hardcoded network name prevents multi-network usage

The F3 network name is hardcoded to "calibrationnet" when creating the F3Client, but the binary accepts --rpc-url as a user-configurable parameter implying multi-network support. If a user provides a mainnet or other network RPC URL, the F3 client would be initialized with the wrong network name, causing certificate validation failures or incorrect behavior. The network name parameter is missing from the CLI arguments.

cursor · 2025-12-15T17:20:09Z

fendermint/app/src/cmd/proof_cache.rs

+    } else {
+        println!("No proof found for instance {}", instance_id);
+        println!();
+        println!("Available instances: {:?}", entries.len());


Bug: Misleading CLI output shows count instead of instance IDs

In the get_proof function, when a proof is not found, the error message displays "Available instances: X" where X is entries.len() (the count of entries). This is misleading because the label "Available instances" suggests the user will see a list of instance IDs they can query, but instead they only see a number. Compare this to show_stats which correctly labels the count as "Count" and shows actual instance IDs separately. Users who see "Available instances: 5" would reasonably expect to see something like [100, 101, 102, 103, 104] so they know which specific instances to query.

cursor · 2025-12-17T15:04:29Z

fendermint/vm/topdown/proof-service/src/assembler.rs

+/// This captures validator power changes that need to be reflected in the subnet
+pub const NEW_POWER_CHANGE_REQUEST_SIGNATURE: &str =
+    "NewPowerChangeRequest(PowerOperation,address,bytes,uint64)";
+


Bug: Event signatures use non-canonical Solidity types

NEW_TOPDOWN_MESSAGE_SIGNATURE and NEW_POWER_CHANGE_REQUEST_SIGNATURE use IpcEnvelope and PowerOperation type names, but Ethereum event topics are derived from canonical ABI types (structs as tuples, enums as uint8). This likely makes EventProofSpec.event_signature hash to the wrong topic0, so event proofs won’t match logs and generated bundles can be incomplete/invalid.

cursor · 2025-12-17T16:42:58Z

fendermint/vm/topdown/proof-service/src/assembler.rs

+/// This captures validator power changes that need to be reflected in the subnet
+pub const NEW_POWER_CHANGE_REQUEST_SIGNATURE: &str =
+    "NewPowerChangeRequest(PowerOperation,address,bytes,uint64)";
+


Bug: Incorrect Solidity event signatures in proofs

NEW_TOPDOWN_MESSAGE_SIGNATURE and NEW_POWER_CHANGE_REQUEST_SIGNATURE use custom type names (IpcEnvelope, PowerOperation) instead of ABI canonical types (tuple(...) for structs and uint8 for enums). Any filtering/proof generation keyed off these signatures will not match actual event topics, leading to missing/invalid event proofs.

cursor · 2025-12-17T19:06:10Z

fendermint/vm/topdown/proof-service/src/assembler.rs

+/// Bindings: contract_bindings::lib_power_change_log::NewPowerChangeRequestFilter
+/// This captures validator power changes that need to be reflected in the subnet
+pub const NEW_POWER_CHANGE_REQUEST_SIGNATURE: &str =
+    "NewPowerChangeRequest(PowerOperation,address,bytes,uint64)";


Bug: Incorrect event signature strings for proofs

The constants NEW_TOPDOWN_MESSAGE_SIGNATURE and NEW_POWER_CHANGE_REQUEST_SIGNATURE use non-canonical Solidity types (IpcEnvelope, PowerOperation) instead of ABI-canonical types (tuples/underlying integer). This likely produces mismatched topic hashes during proof generation, causing event proofs to miss real NewTopDownMessage/NewPowerChangeRequest logs.

cursor · 2025-12-17T19:06:10Z

fendermint/vm/topdown/proof-service/src/assembler.rs

+                slot: calculate_storage_slot("", NEXT_CONFIG_NUMBER_STORAGE_SLOT),
+            },
+        ]
+    }


Bug: Wrong storage slot computation for config number

build_storage_specs computes the nextConfigurationNumber slot via calculate_storage_slot(\"\", NEXT_CONFIG_NUMBER_STORAGE_SLOT). If nextConfigurationNumber is a plain storage slot (not a mapping keyed by a string), hashing with an empty key will target a different slot and generate invalid storage proofs.

cursor · 2025-12-18T13:58:19Z

fendermint/vm/topdown/proof-service/src/assembler.rs

+            },
+            StorageProofSpec {
+                actor_id: self.gateway_actor_id,
+                slot: calculate_storage_slot("", NEXT_CONFIG_NUMBER_STORAGE_SLOT),


Bug: Incorrect storage slot calculation for nextConfigurationNumber

The NEXT_CONFIG_NUMBER_STORAGE_SLOT constant is set to 20, but according to the contract storage layout JSON files, PowerChangeLog (containing nextConfigurationNumber) is stored at slot 9 within ParentValidatorsTracker. The comment claims "nextConfigurationNumber is at slot 20" but this doesn't match the actual storage layout. Additionally, calculate_storage_slot("", NEXT_CONFIG_NUMBER_STORAGE_SLOT) passes an empty string for the key, which may produce incorrect results if the function expects a mapping key for slot calculation. This could cause storage proofs to reference the wrong slot, leading to proof verification failures.

karlem changed the base branch from main to f3-add-actor October 9, 2025 16:41

karlem force-pushed the f3-add-actor branch 2 times, most recently from 6f22fee to 023528d Compare October 20, 2025 18:15

karlem force-pushed the f3-proofs-cache branch from 818edfb to ce61c1d Compare October 20, 2025 19:10

karlem marked this pull request as ready for review October 27, 2025 18:58

karlem requested a review from a team as a code owner October 27, 2025 18:58

karlem changed the title ~~F3 proofs cache~~ feat: F3 proofs cache Oct 27, 2025

This comment was marked as outdated.

Sign in to view

karlem changed the title ~~feat: F3 proofs cache~~ feat: add F3 proofs cache Oct 27, 2025

This comment was marked as outdated.

Sign in to view

karlem force-pushed the f3-proofs-cache branch from fbaa095 to b34142d Compare October 29, 2025 18:26

Base automatically changed from f3-add-actor to main October 31, 2025 15:10

karlem force-pushed the f3-proofs-cache branch from b34142d to 31feb85 Compare November 4, 2025 15:47

This comment was marked as outdated.

Sign in to view

LePremierHomme reviewed Nov 5, 2025

View reviewed changes

karlem requested a review from a team November 5, 2025 13:50

karlem force-pushed the f3-proofs-cache branch from 39e59d6 to bfdc6f7 Compare November 5, 2025 22:26

karlem requested a review from LePremierHomme November 6, 2025 12:14

sergefdrv reviewed Nov 10, 2025

View reviewed changes

fendermint/vm/topdown/proof-service/src/assembler.rs Outdated Show resolved Hide resolved

sergefdrv reviewed Nov 12, 2025

View reviewed changes

karlem added 6 commits November 28, 2025 20:49

feat: add f3 cert actor

95ee4d3

feat: add fetching from parent

fbe0db6

feat: add extra checks and tests

4c6bf4e

feat: multiple epochs in certificate

5f3eb8a

fix: clippy

fbee757

feat: fix comments

8a5533e

karlem force-pushed the f3-proofs-cache branch from 93a1066 to 1747f78 Compare November 28, 2025 19:49

cursor bot reviewed Nov 28, 2025

View reviewed changes

fendermint/vm/topdown/proof-service/src/cache.rs Outdated Show resolved Hide resolved

sergefdrv reviewed Dec 2, 2025

View reviewed changes

karlem mentioned this pull request Dec 2, 2025

Store gateway_eth_address on subnet chain #1487

Open

karlem added 3 commits December 2, 2025 21:35

feat: fix most of comments

be9c28e

feat: re-work cache, generates proofs for epoch, certify child tipssets

0e9612e

feat: cleanup code, optimize logic

ab2ba27

cursor bot reviewed Dec 4, 2025

View reviewed changes

karlem requested a review from sergefdrv December 4, 2025 20:00

sergefdrv reviewed Dec 8, 2025

View reviewed changes

feat: simplify proofs generation and simplify cache

d40e5f4

karlem requested a review from sergefdrv December 8, 2025 20:35

cursor bot reviewed Dec 8, 2025

View reviewed changes

sergefdrv approved these changes Dec 9, 2025

View reviewed changes

feat: fix minor comments

7192140

cursor bot reviewed Dec 9, 2025

View reviewed changes

fix: CI

7aef2f2

cursor bot reviewed Dec 15, 2025

View reviewed changes

karlem added 2 commits December 17, 2025 15:18

fix: clippy

93f317d

fix: fmt

3cc0376

cursor bot reviewed Dec 17, 2025

View reviewed changes

fix: clippy

6914245

cursor bot reviewed Dec 17, 2025

View reviewed changes

fix: clippy

9be81e8

cursor bot reviewed Dec 17, 2025

View reviewed changes

fix: failing unit test

4e168f0

cursor bot reviewed Dec 18, 2025

View reviewed changes

fix: test

b0213ec

karlem merged commit 00b3d7f into main Dec 18, 2025
18 checks passed

karlem deleted the f3-proofs-cache branch December 18, 2025 16:15

feat: add F3 proofs cache #1457

feat: add F3 proofs cache #1457

Uh oh!

Conversation

karlem commented Oct 9, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sergefdrv Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

karlem Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sergefdrv Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

sergefdrv Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

karlem Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sergefdrv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

karlem commented Nov 18, 2025

Uh oh!

sergefdrv commented Nov 19, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot Dec 4, 2025

Choose a reason for hiding this comment

Bug: Storage slot calculation uses empty string for global config

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

karlem commented Oct 9, 2025 •

edited by cursor bot

Loading

karlem Nov 18, 2025 •

edited

Loading