Crate pop_fork 

Fork functionality for creating local forks of live Polkadot SDK chains.

This crate provides the infrastructure for lazy-loading state from live chains, enabling instant local forks without full state sync.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         pop fork chain                          │
│                              CLI                                 │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                         RPC Server                               │
│           (Polkadot SDK compatible JSON-RPC)                     │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Layered Storage                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │ Local Layer │─▶│ Cache Layer │─▶│ Remote Layer (Live RPC) │  │
│  │(modifications)│ │  (SQLite)   │  │    (lazy fetch)         │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Main Types

Blockchain Manager

• Blockchain - Main entry point for creating and managing forked chains
• ChainType - Identifies whether the chain is a relay chain or parachain

Block and Block Building

• Block - Represents a block in the forked chain with its storage state
• BlockBuilder - Constructs new blocks by applying inherents and extrinsics
• InherentProvider - Trait for generating inherent (timestamp, etc.)

Storage Layers

• LocalStorageLayer - Tracks local modifications to forked state
• RemoteStorageLayer - Cache-through layer that lazily fetches from RPC
• StorageCache - SQLite-based persistent cache for storage values

Runtime Execution

• RuntimeExecutor - Executes Polkadot SDK runtime calls against forked state
• ForkRpcClient - RPC client for connecting to live chains

Transaction Pool

• TxPool - Minimal FIFO queue for pending extrinsics

Re-exports

pub use error::BlockBuilderError;

pub use error::BlockError;

pub use error::CacheError;

pub use error::ExecutorError;

pub use error::LocalStorageError;

pub use error::RemoteStorageError;

pub use error::RpcClientError;

pub use error::TxPoolError;

pub use executor::ExecutorConfig;

pub use executor::RuntimeCallResult;

pub use executor::RuntimeExecutor;

pub use executor::RuntimeLog;

pub use executor::RuntimeVersion;

pub use executor::SignatureMockMode;

pub use inherent::InherentProvider;

pub use inherent::ParachainInherent;

pub use inherent::TimestampInherent;

pub use inherent::default_providers;

Modules

consensus_engine

Well-known consensus engine identifiers.

dev

Dev account utilities for forked chains.

error

Error types for fork operations.

executor

Runtime executor using smoldot to execute Substrate runtime calls.

inherent

Inherent extrinsic providers for block building.

rpc_server

JSON-RPC server for forked blockchain.

Structs

Block

A block in a forked blockchain.

BlockBuilder

Builder for constructing new blocks on a forked chain.

BlockRow

Block row for query results (uses owned data).

Blockchain

The blockchain manager for a forked chain.

BuildBlockResult

Result of building a block, including information about extrinsic processing.

FailedExtrinsic

An extrinsic that failed during block building.

ForkRpcClient

RPC client wrapper for fork operations.

LocalStorageLayer

Local storage layer that tracks modifications on top of a remote layer.

PrefixScanProgress

Progress information for a prefix scan operation.

RemoteStorageLayer

Remote storage layer that lazily fetches state from a live chain.

StorageCache

SQLite-backed persistent cache for storage values.

TxPool

A minimal transaction pool that stores pending extrinsics.

ValidTransaction

Information about a valid transaction.

Enums

ApplyExtrinsicResult

Result of applying an extrinsic to the block.

BlockForkPoint

Handy type to allow specifying both number and hash as the fork point.

BlockchainError

Errors that can occur when working with the blockchain manager.

BlockchainEvent

Events emitted by the blockchain when state changes.

ChainType

Type of chain being forked.

DigestItem

Digest item for block headers.

InvalidTransaction

Reasons a transaction is invalid.

TransactionValidity

Result of transaction validation.

TransactionValidityError

Error when transaction validation fails.

UnknownTransaction

Reasons transaction validity is unknown.

Functions

create_next_header

Create a header for the next block.

create_next_header_with_slot

Create a header for the next block with automatic slot digest injection.

Type Aliases

ConsensusEngineId

Consensus engine identifier (4-byte ASCII).