# Fork a chain Use `pop fork` (alias: `pop f`) to fork a live chain locally and start an RPC server. This command requires a Pop CLI build with the `chain` feature enabled. ## Usage ```bash pop fork [ | -e ] [options] ``` ### JSON mode Use global `--json` for structured detached-fork output: ```bash pop --json fork paseo --detach ``` JSON mode requirements: * `--detach` is required. * You must pass either `` or `--endpoint`. ## Flags and arguments | Flag or argument | Required | Description | | --------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | No | Well-known chain to fork (for example: `paseo`, `polkadot`, `kusama`, `westend`, `asset-hub`, `asset-hub-polkadot`). | | `-e, --endpoint ` | No | RPC endpoint URL to fork. Parsed as a URL. If omitted, Pop starts an interactive chain/endpoint selection flow. | | `-c, --cache ` | No | Path to a SQLite cache file. If omitted, Pop uses an in-memory cache. | | `-p, --port ` | No | Port for the local RPC server. If omitted, Pop auto-selects an available port starting from `9944`. | | `--mock-all-signatures` | No | Accept all signatures as valid for dev/testing. Default is to accept only magic signatures (`0xdeadbeef`). Do not use for production or security-sensitive scenarios. | | `--dev` | No | Fund well-known dev accounts (Alice, Bob, Charlie, Dave, Eve, Ferdie) and set Alice as sudo when supported by the chain. | | `--at ` | No | Fork at a specific block number. If omitted, Pop forks at the latest finalized block. | | `-d, --detach` | No | Run the fork in the background. Pop waits until the fork is ready, then prints endpoint info, PID, and log file path. | ## Behavior notes * If you do not pass `` or `--endpoint`, Pop prompts you to pick a chain RPC endpoint. * When you pass a well-known ``, Pop tries its known RPC endpoints and falls back to the next endpoint if one fails. * Pop waits for Ctrl+C. On shutdown, it stops all servers, clears local storage, and warns if cleanup fails. * When you use `--detach`, Pop starts a background process and waits until the fork is ready before returning. To stop it, run `pop clean node --pid ` or `kill -9 `. * If you do not specify a fork point, Pop uses the latest finalized block from the remote RPC as the fork point. * Storage is fetched lazily from the live chain and cached in SQLite. With `--cache`, the cache is persisted on disk. Without it, Pop uses an in-memory cache. * After forking, Pop prints explorer links for Polkadot.js Apps and PAPI for the local endpoint. * Use `RUST_LOG` to control logging (for example: `RUST_LOG=info,pop_fork=debug pop fork paseo`). ## Interactive flow Use interactive mode when you don't want to pass source flags up front: 1. Run `pop fork`. 2. Select a chain source (for example Local, a known chain, or Custom URL). 3. If needed, provide a custom RPC endpoint URL. 4. Pop starts the fork and prints the local WebSocket RPC URL you can connect to. ## Examples ```bash # Fork a live chain (uses latest finalized block) pop fork paseo ``` ```bash # Fork from a specific RPC endpoint pop fork -e wss://rpc.polkadot.io ``` ```bash # Fork at a specific block pop fork polkadot --at 1234 ``` ```bash # Fork with persistent cache for fast restarts pop fork -e wss://rpc.polkadot.io --cache ./polkadot-fork.db ``` ```bash # Fork with signature mocking (accept any signature) pop fork -e wss://rpc.polkadot.io --mock-all-signatures ``` ```bash # Fork and fund dev accounts pop fork paseo --dev ``` ```bash # Fork in the background and return once ready pop fork kusama --detach ``` ```bash # Fork Asset Hub (Polkadot) pop fork asset-hub-polkadot --detach ``` ## Example workflow 1. Start the fork. ```bash pop fork westend --port 9944 ``` 2. Connect a client to the local RPC endpoint in Polkadot.js Apps. ``` ws://127.0.0.1:9944 ``` 3. Submit transactions and query state against the local RPC endpoint. ## Supported RPC methods Use `rpc_methods` to list every supported method at runtime. The fork RPC server exposes these namespaces and methods: | Namespace | Methods | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chain` | `chain_getBlockHash`, `chain_getHeader`, `chain_getBlock`, `chain_getFinalizedHead`, `chain_subscribeNewHeads`, `chain_unsubscribeNewHeads`, `chain_subscribeFinalizedHeads`, `chain_unsubscribeFinalizedHeads`, `chain_subscribeAllHeads`, `chain_unsubscribeAllHeads` | | `state` | `state_getStorage`, `state_getMetadata`, `state_getRuntimeVersion`, `state_getKeysPaged`, `state_call`, `state_queryStorageAt`, `state_subscribeRuntimeVersion`, `state_unsubscribeRuntimeVersion`, `state_subscribeStorage`, `state_unsubscribeStorage` | | `system` | `system_chain`, `system_name`, `system_version`, `system_health`, `system_properties`, `system_localPeerId`, `system_nodeRoles`, `system_localListenAddresses`, `system_chainType`, `system_syncState`, `system_accountNextIndex` | | `author` | `author_submitExtrinsic`, `author_pendingExtrinsics` | | `dev` | `dev_newBlock` | Additional namespaces are available, including `archive`, `chainHead`, `chainSpec`, `payment`, and `transaction`. Use `rpc_methods` to see the full list. Polkadot.js compatibility aliases are also registered for `chain_subscribeNewHead` and `chain_unsubscribeNewHead`. ``` ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://learn.onpop.io/chains/guides/fork-a-chain.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.