Struct Blockchain 

pub struct Blockchain { /* private fields */ }

The blockchain manager for a forked chain.

Blockchain is the main entry point for creating local forks of live Polkadot SDK chains. It manages the fork lifecycle, block building, and provides APIs for querying state and executing runtime calls.

Creating a Fork

Use Blockchain::fork to create a new fork from a live chain:

let blockchain = Blockchain::fork(&endpoint, None).await?;

Block Building

Build blocks using build_block or build_empty_block:

// Build a block with user extrinsics
let block = blockchain.build_block(vec![signed_extrinsic]).await?;

// Build an empty block (just inherents)
let block = blockchain.build_empty_block().await?;

Querying State

Query storage at the current head or at a specific block:

// At head
let value = blockchain.storage(&key).await?;

// At a specific block
let value = blockchain.storage_at(block_hash, &key).await?;

Thread Safety

Blockchain is Send + Sync and can be safely shared across async tasks. Internal state is protected by RwLock.

Implementations

impl Blockchain

pub async fn fork( endpoint: &Url, cache_path: Option<&Path>, ) -> Result<Arc<Self>, BlockchainError>

Create a new blockchain forked from a live chain.

This connects to the live chain, fetches the fork point block, initializes the runtime executor, and detects the chain type.

Arguments

• endpoint - RPC endpoint URL of the live chain
• cache_path - Optional path for persistent SQLite cache. If None, an in-memory cache is used.

Returns

A new Blockchain instance ready for block building.

Example

use pop_fork::Blockchain;
use std::path::Path;
use url::Url;

let endpoint: Url = "wss://rpc.polkadot.io".parse()?;

// With in-memory cache
let blockchain = Blockchain::fork(&endpoint, None).await?;

// With persistent cache
let blockchain = Blockchain::fork(&endpoint, Some(Path::new("./cache.sqlite"))).await?;

pub async fn fork_at( endpoint: &Url, cache_path: Option<&Path>, fork_point: Option<BlockForkPoint>, ) -> Result<Arc<Self>, BlockchainError>

Create a new blockchain forked from a live chain at a specific block.

Similar to fork, but allows specifying the exact block to fork from.

Arguments

• endpoint - RPC endpoint URL of the live chain
• cache_path - Optional path for persistent SQLite cache
• fork_point - Block number or hash to fork from. If None, uses the latest finalized block.

Example

// Fork at a specific block number
let blockchain = Blockchain::fork_at(&endpoint, None, Some(12345678.into())).await?;

// Fork at a specific block hash
let blockchain = Blockchain::fork_at(&endpoint, None, Some(block_hash.into())).await?;

pub async fn fork_with_config( endpoint: &Url, cache_path: Option<&Path>, fork_point: Option<BlockForkPoint>, executor_config: ExecutorConfig, ) -> Result<Arc<Self>, BlockchainError>

Create a new blockchain forked from a live chain with custom executor configuration.

This is the most flexible fork method, allowing customization of both the fork point and the executor configuration.

Arguments

• endpoint - RPC endpoint URL of the live chain
• cache_path - Optional path for persistent SQLite cache
• fork_point - Block number or hash to fork from. If None, uses the latest finalized block.
• executor_config - Configuration for the runtime executor

Example

use pop_fork::{Blockchain, ExecutorConfig, SignatureMockMode};

// Fork with signature mocking enabled (useful for testing)
let config = ExecutorConfig {
    signature_mock: SignatureMockMode::AlwaysValid,
    ..Default::default()
};
let blockchain = Blockchain::fork_with_config(&endpoint, None, None, config).await?;

pub async fn warmup(self: &Arc<Self>)

Run background warmup to pre-cache expensive resources.

This method is designed to be spawned as a background task immediately after forking. It pre-populates caches that would otherwise cause a cold-start penalty on the first block build:

1. WASM prototype compilation (~2-5s for large runtimes like Asset Hub). The compiled prototype is stored in warm_prototype for reuse by the first build_block() call.

2. Storage prefetch (~1-2s). Batch-fetches all StorageValue keys and the first page of each pallet’s storage map, populating the remote cache.

3. Inherent provider warmup. Calls warmup() on each registered provider (e.g. TimestampInherent caches the slot duration to avoid a separate WASM execution during block building).

If a block is built before warmup finishes, the builder falls back to its normal (non-cached) path. The Mutex/OnceCell guards ensure no races.

pub fn chain_name(&self) -> &str

Get the chain name.

pub fn chain_type(&self) -> &ChainType

Get the chain type.

pub fn fork_point(&self) -> H256

Get the fork point block hash.

pub fn fork_point_number(&self) -> u32

Get the fork point block number.

pub fn endpoint(&self) -> &Url

Get the RPC endpoint URL.

pub async fn genesis_hash(&self) -> Result<String, BlockchainError>

Get the genesis hash, formatted as a hex string with “0x” prefix.

This method lazily fetches and caches the genesis hash on first call. The cache is per-instance, so each forked chain maintains its own value even when multiple forks run in the same process.

Returns

The genesis hash as “0x” prefixed hex string, or an error if fetching fails.

pub async fn chain_properties(&self) -> Option<Value>

Get the chain properties.

This method lazily fetches and caches the chain properties on first call. The cache is per-instance, so each forked chain maintains its own value even when multiple forks run in the same process.

Returns

The chain properties as JSON, or None if not available.

pub fn subscribe_events(&self) -> Receiver<BlockchainEvent>

Subscribe to blockchain events.

Returns a receiver that will get events when blocks are built. Use this for implementing reactive RPC subscriptions.

Example

let mut receiver = blockchain.subscribe_events();
tokio::spawn(async move {
    while let Ok(event) = receiver.recv().await {
        match event {
            BlockchainEvent::NewBlock { hash, number, .. } => {
                println!("New block #{} ({:?})", number, hash);
            }
        }
    }
});

pub async fn head(&self) -> Block

Get the current head block.

pub async fn head_number(&self) -> u32

Get the current head block number.

pub async fn head_hash(&self) -> H256

Get the current head block hash.

pub async fn block_body( &self, hash: H256, ) -> Result<Option<Vec<Vec<u8>>>, BlockchainError>

Get block body (extrinsics) by hash.

This method searches for the block in three places:

1. The current head block
2. Locally-built blocks (traversing the parent chain)
3. The remote chain (for blocks at or before the fork point)

Arguments

• hash - The block hash to query

Returns

The block’s extrinsics as raw bytes, or None if the block is not found.

pub async fn block_header( &self, hash: H256, ) -> Result<Option<Vec<u8>>, BlockchainError>

Get block header by hash.

This method searches for the block in three places:

1. Locally-built blocks (traversing the parent chain)
2. The fork point block
3. The remote chain (for blocks at or before the fork point)

Arguments

• hash - The block hash to query

Returns

The SCALE-encoded block header, or None if the block is not found.

pub async fn block_hash_at( &self, block_number: u32, ) -> Result<Option<H256>, BlockchainError>

Get block hash by block number.

This method searches for the block in three places:

1. Locally-built blocks (traversing the parent chain from head)
2. The fork point block
3. The remote chain (for blocks before the fork point)

Arguments

• block_number - The block number to query

Returns

The block hash, or None if the block number doesn’t exist.

pub async fn block_number_by_hash( &self, hash: H256, ) -> Result<Option<u32>, BlockchainError>

Get block number by block hash.

This method searches for the block in two places:

1. Locally-built blocks (traversing the parent chain from head)
2. The remote chain (for blocks at or before the fork point)

Arguments

• hash - The block hash to query

Returns

The block number, or None if the block hash doesn’t exist.

pub async fn block_parent_hash( &self, hash: H256, ) -> Result<Option<H256>, BlockchainError>

Get parent hash of a block by its hash.

This method searches for the block in two places:

1. Locally-built blocks (traversing the parent chain from head)
2. The remote chain (for blocks at or before the fork point)

Arguments

• hash - The block hash to query

Returns

The parent block hash, or None if the block hash doesn’t exist.

pub async fn build_block( &self, extrinsics: Vec<Vec<u8>>, ) -> Result<BuildBlockResult, BlockchainError>

Build a new block with the given extrinsics.

This creates a new block on top of the current head, applying:

1. Inherent extrinsics (timestamp, parachain validation data, etc.)
2. User-provided extrinsics

The new block becomes the new head.

Arguments

• extrinsics - User extrinsics to include in the block

Returns

A BuildBlockResult containing the newly created block and information about which extrinsics were successfully included vs which failed.

Example

let extrinsic = /* create signed extrinsic */;
let result = blockchain.build_block(vec![extrinsic]).await?;
println!("New block: #{} ({:?})", result.block.number, result.block.hash);
println!("Included: {}, Failed: {}", result.included.len(), result.failed.len());

pub async fn build_empty_block(&self) -> Result<Block, BlockchainError>

Build an empty block (just inherents, no user extrinsics).

This is useful for advancing the chain state without any user transactions.

Returns

The newly created block.

pub async fn call( &self, method: &str, args: &[u8], ) -> Result<Vec<u8>, BlockchainError>

Execute a runtime call at the current head.

Arguments

• method - Runtime API method name (e.g., “Core_version”)
• args - SCALE-encoded arguments

Returns

The SCALE-encoded result from the runtime.

pub async fn storage( &self, key: &[u8], ) -> Result<Option<Vec<u8>>, BlockchainError>

Get storage value at the current head.

Arguments

• key - Storage key

Returns

The storage value, or None if the key doesn’t exist.

pub async fn storage_at( &self, block_number: u32, key: &[u8], ) -> Result<Option<Vec<u8>>, BlockchainError>

Get storage value at a specific block number.

Arguments

• block_number - Block number to query at
• key - Storage key

Returns

The storage value, or None if the key doesn’t exist.

pub async fn storage_keys_paged( &self, prefix: &[u8], count: u32, start_key: Option<&[u8]>, at: Option<H256>, ) -> Result<Vec<Vec<u8>>, BlockchainError>

Get paginated storage keys matching a prefix at a given block.

If at is None, defaults to the current head block hash so that newly created keys are visible to callers such as polkadot.js.

For fork-local blocks, the full key set is obtained by merging remote keys (at the fork point) with local modifications, then applying pagination. For pre-fork blocks, delegates to the upstream RPC.

pub async fn storage_keys_by_prefix( &self, prefix: &[u8], at: H256, ) -> Result<Vec<Vec<u8>>, BlockchainError>

Get all storage keys matching a prefix, with prefetching. Enumerate all storage keys matching a prefix at a given block.

For pre-fork blocks, delegates to the remote RPC’s get_keys method. For fork-local blocks, merges remote keys (at the fork point) with local modifications so that keys added or deleted after the fork are visible.

at is the block hash whose state should be scanned for keys.

pub async fn call_at_block( &self, hash: H256, method: &str, args: &[u8], ) -> Result<Option<Vec<u8>>, BlockchainError>

Execute a runtime call at a specific block hash.

Arguments

• hash - The block hash to execute at
• method - Runtime API method name (e.g., “Core_version”)
• args - SCALE-encoded arguments

Returns

• Ok(Some(result)) - Call succeeded at the specified block
• Ok(None) - Block hash not found
• Err(_) - Call failed (runtime error, storage error, etc.)

pub async fn storage_batch( &self, at: H256, keys: &[&[u8]], ) -> Result<Vec<Option<Vec<u8>>>, BlockchainError>

Batch-fetch storage values from the upstream at a given block.

Uses the remote storage layer’s batch fetch, which checks the cache first and fetches only uncached keys in a single upstream RPC call. This is significantly faster than fetching each key individually.

Automatically reconnects to the upstream if the connection has dropped.

pub async fn proxy_state_call( &self, method: &str, args: &[u8], at: H256, ) -> Result<Vec<u8>, BlockchainError>

Proxy a runtime API call to the upstream RPC endpoint.

This forwards the call to the upstream node at the given block, which has a JIT-compiled runtime and handles computationally expensive calls (like metadata generation) much faster than the local WASM interpreter.

Automatically reconnects if the upstream connection has dropped.

pub async fn validate_extrinsic( &self, extrinsic: &[u8], ) -> Result<ValidTransaction, TransactionValidityError>

Validate an extrinsic before pool submission.

Calls TaggedTransactionQueue_validate_transaction runtime API to check if the extrinsic is valid for inclusion in a future block.

Arguments

• extrinsic - The encoded extrinsic to validate

Returns

• Ok(ValidTransaction) - Transaction is valid with priority/dependency info
• Err(TransactionValidityError) - Transaction is invalid or unknown

Example

match blockchain.validate_extrinsic(&extrinsic_bytes).await {
    Ok(valid) => println!("Valid with priority {}", valid.priority),
    Err(TransactionValidityError::Invalid(inv)) => {
        println!("Invalid: {:?}", inv);
    }
    Err(TransactionValidityError::Unknown(unk)) => {
        println!("Unknown validity: {:?}", unk);
    }
}

pub async fn initialize_dev_accounts(&self) -> Result<(), BlockchainError>

Fund well-known dev accounts and optionally set sudo.

Detects the chain type from the isEthereum chain property:

• Ethereum chains: funds both Substrate (Alice, Bob, …) and Ethereum (Alith, Baltathar, …) dev accounts for compatibility.
• Substrate chains: funds Substrate dev accounts only.

For each account:

• If it already exists on-chain, patches its free balance
• If it does not exist, creates a fresh AccountInfo

If the chain has a Sudo pallet, sets sudo to a dev account matching the runtime’s account-id width (20-byte or 32-byte), with first-account fallback.

pub async fn clear_local_storage(&self) -> Result<(), CacheError>

Clear all locally tracked storage data from the cache.

This removes all key-value pairs that were created during block building (stored in the local_keys and local_values tables). Remote chain data that was fetched and cached remains intact.

Call this during shutdown to clean up local storage state.

Returns

Ok(()) on success, or a cache error if the operation fails.