Fork Off Substrate
A script to bootstrap a new Substrate chain with the current state of a live chain for development and testing.
What is Fork Off Substrate?
Fork off Substrate is a Node.js script that allows developers to create a fork of any Substrate-based blockchain by bootstrapping a new chain with the current state of a live network. It solves the problem of needing an isolated, stateful environment for testing smart contracts, runtime upgrades, or other blockchain modifications without interacting with the mainnet. The tool generates a genesis file that can be used to launch a local development chain.
Substrate and Polkadot ecosystem developers who need to test their parachains, pallets, or runtime logic in an environment that mirrors a live network's state.
Developers choose Fork off Substrate because it provides a straightforward, configurable way to fork live chains without complex setup, supports Docker for reproducibility, and is specifically tailored for the Substrate framework, unlike generic blockchain tools.
Overview
This script allows bootstrapping a new substrate chain with the current state of a live chain
Use Cases
Best For
- Testing smart contracts or pallets against a real network state
- Simulating runtime upgrades in a safe, isolated environment
- Creating development instances of Polkadot or Kusama for experimentation
- Debugging chain-specific issues without deploying to testnets
- Educational purposes to study live chain data and behavior
- Preparing for network migrations or hard forks
Not Ideal For
- Projects on non-Substrate blockchains like Ethereum or Cosmos
- Teams requiring fully automated CI/CD pipelines without manual file handling
- Developers needing to fork only specific parts of the state, not the entire chain
Pros & Cons
Pros
Captures the exact state of a live Substrate chain at any block, enabling precise testing environments as per the README's usage instructions.
Uses environment variables like HTTP_RPC_ENDPOINT and FORK_CHUNKS_LEVEL to customize the forking process, as detailed in the configuration table.
Provides a Docker image for containerized execution, ensuring portability and ease of use across different systems, mentioned in the Using Docker section.
Offers QUICK_MODE to parallelize data retrieval from RPC endpoints, speeding up the forking for large chains.
Allows replacing the chain's sudo account with //Alice for easier control in development, as specified with the ALICE environment variable.
Cons
Requires users to manually copy the chain binary and runtime WASM blob into a data folder, which can be cumbersome and error-prone.
The tool fails if the specified RPC endpoint is unavailable or slow, impacting reliability.
Only supports Substrate-based blockchains, so it's not applicable for other blockchain frameworks.
Downloading full state from large chains can be time-consuming and require significant bandwidth, even with optimization.
Frequently Asked Questions
Related Projects
Polkadot-JS ExtensionSimple browser extension for managing Polkadot and Substrate network accounts in a browser. Allows the signing of extrinsics using these accounts. Also provides a simple interface for compliant extensions for dapps.
polkadot-launchSimple CLI tool to launch a local Polkadot test network
SidecarREST service that makes it easy to interact with blockchain nodes built using Substrate's FRAME framework.
ArchiveBlockchain Indexing Engine
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.