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 (d6c6bd9) with master (fb10b2f)}

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.