How to fork or import network state
Learn how to fork public state into a simulator or copy account state into a localnet
Fork a simulator from a public-network block, or copy selected accounts into a localnet. Both execute locally without changing the source network or tracking its later state.
Importing into an existing localnet pauses it for a hardfork and replaces accounts at the selected addresses. Save a snapshot first to recover overwritten state.
Prerequisites
- Acton 1.2 or later installed.
- An Acton project containing
Acton.toml. - A source remote procedure call (RPC) provider and any required API key. Historical forks require access to the selected block.
- For localnet, a running Docker engine with Compose v2, as specified in the localnet requirements.
- For Studio imports, the target accounts' addresses.
Select the source state
For a simulator:
- Open Create environment and select Simulator.
- Set Initial state to Fork testnet or Fork mainnet.
- Optionally enter a masterchain sequence number in Fork block.
- Select startup accounts and create the environment.
For localnet:
- Add account imports during creation or open Import accounts on an existing network.
- Select a source environment and enter each active account address. Optionally name the contract.
- Submit the imports to copy code, data, and balances.
Pin testnet state at a masterchain block served by the provider. Replace <BLOCK_SEQNO> with that block's sequence number:
acton simulator start --port 5411 --fork-net testnet --fork-block-number '<BLOCK_SEQNO>'Omit --fork-block-number to resolve the latest block once during startup. Use --fork-net mainnet for mainnet, or custom:<NAME> for a network entry in Acton.toml, replacing <NAME> with its name. Use a fresh database when changing the fork origin.
Acton loads matching provider keys from .env: TONCENTER_TESTNET_API_KEY, TONCENTER_MAINNET_API_KEY, or <NORMALIZED_NAME>_API_KEY for custom networks. Custom names are uppercased and non-alphanumeric characters become underscores.
A historical fork uses the selected block's configuration and Unix time. A latest fork uses the pinned block's configuration and starts its clock from system time. Masterchain state is cached under build/cache/masterchain-snapshots/ for 24 hours; a latest fork still resolves the latest block on startup. Pass the global --clear-cache flag to discard cached snapshots.
Prepare accounts.json as an array of hexadecimal bags of cells (BoCs) containing ShardAccount values. Each entry must contain a complete active basechain account with a distinct address. Plain addresses, base64 strings, and contract data cells alone are not valid imports.
acton localnet start imported --accounts-file accounts.json --detachThe --accounts-file applies only when creating a network. To replace accounts in an existing network, use Studio's import dialog or the administrative API.
Imported dependencies must be included explicitly — localnet does not fetch missing accounts lazily.
Verify the imported state
- In a simulator, inspect the fork block on Home and open a source account in Explorer.
- In localnet, inspect imported code, storage, and balance. Source transactions do not appear as local history. Save a snapshot before modifying the copied state.
Last updated on