Cloning Mainnet Accounts
Seed solana-test-validator with real mainnet account data so local tests exercise production program layouts and oracle state.
Recipe
Quick-reference recipe card - copy-paste ready.
solana-test-validator --reset \
--url mainnet-beta \
--clone <ACCOUNT_PUBKEY> \
--clone <PROGRAM_ID>When to reach for this:
- Integrating with Raydium, Orca, Pyth, or other deployed programs.
- Testing CPI paths against real bytecode without mainnet fees.
- Reproducing a mainnet account layout bug locally.
- Validating parsers against live mint/metadata structures.
Working Example
# Example: clone SPL Token program and a USDC mint (verify current pubkeys in docs)
TOKEN_PROGRAM=TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
USDC_MINT=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
solana-test-validator --reset \
--url mainnet-beta \
--clone "$TOKEN_PROGRAM" \
--clone "$USDC_MINT"
solana config set --url http://127.0.0.1:8899
solana account "$USDC_MINT"What this demonstrates:
- Validator snapshots account data at startup from
--urlRPC. - Cloned programs execute real mainnet bytecode locally.
- Your transactions can CPI into cloned programs like on mainnet.
Deep Dive
How It Works
- At genesis, validator RPC-fetches each
--clonepubkey's lamports, owner, data, and executable flag. - Large accounts increase startup time and local ledger size.
- Cloned state is static until your local transactions mutate it.
- Some accounts depend on others - clone dependency graph thoughtfully.
Clone Planning
| Account type | Clone? | Notes |
|---|---|---|
| Program IDs | Often yes | Required for CPI |
| Pool/oracle state | Yes | Captures realistic reserves |
| User wallets | Rare | Use local keypairs instead |
| Sysvars | Auto | Clock, rent included by default |
bash Notes
# Clone many accounts from a file (one pubkey per line)
solana-test-validator --reset --url mainnet-beta \
$(awk '{print "--clone "$1}' accounts.txt)Gotchas
- Stale clone data - reserves differ from live mainnet minutes later. Fix: refresh clones for price-sensitive tests or use Surfpool fork.
- Missing dependent accounts - CPI fails with missing account. Fix: clone all accounts in the instruction's account list.
- Rate-limited mainnet RPC - clone fetch fails at startup. Fix: use provider RPC with API key in
--url. - Assuming clone updates live - local clone does not auto-sync mainnet. Fix: restart validator to re-fetch.
- Cloning entire token portfolios - unnecessary bloat. Fix: minimal set of mints/ATAs your program touches.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| Surfpool 0.12.0 | Continuous mainnet fork | Simple program-only tests |
| Hand-built fixtures | Tiny isolated unit tests | Complex DeFi integrations |
| devnet mirrors | Shared team staging | Mainnet-specific program versions |
| LiteSVM account injection | Fast Rust unit tests | Full RPC client paths |
FAQs
Does clone pull program bytecode?
Yes for executable accounts - the ELF is stored like a deploy.
Can I clone PDAs?
Yes if the PDA account exists on mainnet at fetch time - derive address and verify with solana account.
How do I find accounts to clone?
Inspect mainnet transactions in an explorer - copy all accounts your instruction touches.
Will CPI to uncloned programs work?
Only if the program is native builtin or you clone/deploy it locally.
Does clone cost mainnet fees?
No - read-only RPC fetch; you pay local rent only if transactions resize accounts.
Can I clone from devnet instead?
Yes - --url devnet for devnet-published programs.
How big can cloned data be?
Very large accounts slow startup - prefer Surfpool for heavy fork scenarios.
Do clones include token balances?
Yes - token account lamports and data copy exactly at fetch snapshot.
How do I debug clone failures?
Read validator startup logs for RPC errors; verify pubkey exists on source cluster.
Should CI clone mainnet?
Cache ledger directories or use minimal fixture sets to keep CI fast and reliable.
Related
- solana-test-validator - clone flags
- Surfpool - fork workflow
- Loading Programs & Fixtures - complementary seeding
- DeFi integrations - common CPI targets
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.