feat: forc-node local contract state forking

[zees-dev]

Description

Addresses #7448

This pull request introduces state forking support to the local node in forc-node, allowing developers to run a local node that mirrors the contract state from a remote node at latest block height (currently only latest is supported).

The contract bytecode and state is fetched dynamically (at runtime - from specified forked url) as the state is requested.

State Forking Feature

• Added fork_url and fork_block_number to forc-node local, enabling users to specify a remote node and block height for state forking (it must support historical execution).
• Refactored local/mod.rs to support state forking by integrating a new fork module, which handles fetching state from the remote node and merging it with local storage. The node now conditionally initializes with forking logic based on user input.

Dependency and Build Updates

• Updated Cargo.toml and forc-node/Cargo.toml to use patched versions of fuel-core crates from a specific branch
  • This was required as we need to override the datasource in the combined database; the datasource attributes are private; the fuel-core v0.46.0 patch simply updates the visibility of the relevant attributes so that they can be overriden to provide fork functionality
• Made the block_on_any_runtime function in forc-pkg/src/source/reg/mod.rs public, allowing it to be used outside its original module
  • This is necessary for async operations in the new forking logic since the overriden trait function impls are not async

Testing and Examples

• Added new test contracts and supporting files (fork and fork-caller) to demonstrate and validate the state forking capability.
  • These include contract sources, ABI files, and storage slot definitions. [1] [2] [3] [4] [5] [6] [7] [8]

These updates collectively enable local development nodes to fork contract state from a remote node, greatly enhancing testing flexibility and realism for smart contract developers.

Related PR: FuelLabs/fuel-core#3134

Checklist

• I have linked to any relevant issues.
• I have commented my code, particularly in hard-to-understand areas.
• I have updated the documentation where relevant (API docs, the reference, and the Sway book).
  • If my change requires substantial documentation changes, I have requested support from the DevRel team
• I have added tests that prove my fix is effective or that my feature works.
• I have added (or requested a maintainer to add) the necessary Breaking* or New Feature labels where relevant.
• I have done my best to ensure that my PR adheres to the Fuel Labs Code Review Standards.
• I have requested a review from the relevant team or maintainers.

---

Note

Adds state forking to forc-node local via --fork-url/--fork-block-number, fetching contract bytecode/state on demand and persisting locally, with tests, docs, and dependency updates.

• forc-node:
  • Local forking: New flags --fork-url and --fork-block-number enable mirroring contract state from a remote node; lazily fetches contract bytecode/storage and caches in local DB.
  • Storage plumbing: Introduces ForkingOnChainStorage/ForkClient and reconstructs CombinedDatabase to overlay remote state; supports non-interactive mode for config updates.
• Chain config & utils:
  • check_and_update_chain_config supports non-interactive flows; block_on_any_runtime made public for blocking async calls from sync contexts.
• Tests:
  • Adds integration tests and example contracts (fork, fork-caller) validating bytecode/state forking and transitive calls; updates EVM tests to newer revm API.
• Docs:
  • New "Testing with Forc Node" guide and SUMMARY entry; spelling list updated (e.g., AMM, RocksDB).
• Dependencies:
  • Patches fuel-core* crates to git master; bumps revm and enables features; aligns Cargo.toml/dev-deps accordingly.

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

[codspeed-hq]

CodSpeed Performance Report

Merging #7478 will not alter performance

_{Comparing feat/forc-node-local-state-forking (f23981d) with master (ec51769)}

Summary

✅ 25 untouched

[JoshuaBatty]

seem to be using outdated version of forc

[JoshuaBatty]

Nice, this is looking really promising. It'd be great to also write up some documentation to include with this PR, stepping through an example use case of when and how to use this feature. Maybe in the same sort of vein as what we have written up for forc debug.

[kayagokalp]

Very excited for this! We also might want to make sure we depend on std via path instead of registry in the test. That way std will keep up-to-date with the repo for the tests.

[cursor]

This PR is being reviewed by Cursor Bugbot

Details

Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[cursor]

Bug: Inconsistent Key Slicing Causes Panics

The exists method for Column::ContractsRawCode attempts to slice key[..32] without first checking if key.len() >= 32. This causes a panic when the key is shorter than 32 bytes. The other methods (size_of_value, get, read) have the same issue. In contrast, Column::ContractsState correctly checks key.len() == 64 before slicing, preventing out-of-bounds access.

 

[cursor]

PR Summary

Adds state forking to forc-node local, lazily fetching contract bytecode/state from a remote node and persisting locally, with flags to configure the fork and comprehensive tests/docs.

• forc-node (local):
  • Add state forking via --fork-url and --fork-block-number; persist to RocksDB; supports --historical-execution.
  • Implement ForkClient and ForkingOnChainStorage to lazily fetch contract bytecode/state from a remote GraphQL endpoint and cache locally; integrate by rebuilding CombinedDatabase with forked on-chain storage.
  • Add --non-interactive to local/testnet/ignition paths and auto chain-config updates; refactor check_and_update_chain_config to accept non-interactive mode.
• Core utilities:
  • Expose forc-pkg::source::reg::block_on_any_runtime for blocking async calls inside storage wrappers.
• Dependencies:
  • Patch fuel-core crates to git master and update revm usage in tests.
• Tests:
  • Add fork demo contracts (fork, fork-caller) and E2E tests validating bytecode/state hydration, state isolation, and transitive calls; update health check test.
• Docs:
  • New guide: "Testing with Forc Node" including fork workflow; update SUMMARY and spellcheck list.

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

[cursor]

Bug: Temporary directory deleted immediately after path extraction

The run_node function creates a temporary directory with tempfile::tempdir(), extracts its path, but immediately drops the TempDir handle. When TempDir is dropped, it automatically deletes the directory. The resulting db_path therefore points to a non-existent directory when passed to LocalCmd for RocksDB storage. The TempDir handle needs to be kept alive for the duration the directory is needed, or into_path() can be used to take ownership of the path without auto-deletion.