pop_fork/lib.rs
1// SPDX-License-Identifier: GPL-3.0
2
3//! Fork functionality for creating local forks of live Polkadot SDK chains.
4//!
5//! This crate provides the infrastructure for lazy-loading state from live chains,
6//! enabling instant local forks without full state sync.
7//!
8//! # Architecture
9//!
10//! ```text
11//! ┌─────────────────────────────────────────────────────────────────┐
12//! │ pop fork chain │
13//! │ CLI │
14//! └─────────────────────────────────────────────────────────────────┘
15//! │
16//! ▼
17//! ┌─────────────────────────────────────────────────────────────────┐
18//! │ RPC Server │
19//! │ (Polkadot SDK compatible JSON-RPC) │
20//! └─────────────────────────────────────────────────────────────────┘
21//! │
22//! ▼
23//! ┌─────────────────────────────────────────────────────────────────┐
24//! │ Layered Storage │
25//! │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
26//! │ │ Local Layer │─▶│ Cache Layer │─▶│ Remote Layer (Live RPC) │ │
27//! │ │(modifications)│ │ (SQLite) │ │ (lazy fetch) │ │
28//! │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
29//! └─────────────────────────────────────────────────────────────────┘
30//! ```
31//!
32//! # Main Types
33//!
34//! ## Blockchain Manager
35//!
36//! - [`Blockchain`] - Main entry point for creating and managing forked chains
37//! - [`ChainType`] - Identifies whether the chain is a relay chain or parachain
38//!
39//! ## Block and Block Building
40//!
41//! - [`Block`] - Represents a block in the forked chain with its storage state
42//! - [`BlockBuilder`] - Constructs new blocks by applying inherents and extrinsics
43//! - [`InherentProvider`] - Trait for generating inherent (timestamp, etc.)
44//!
45//! ## Storage Layers
46//!
47//! - [`LocalStorageLayer`] - Tracks local modifications to forked state
48//! - [`RemoteStorageLayer`] - Cache-through layer that lazily fetches from RPC
49//! - [`StorageCache`] - SQLite-based persistent cache for storage values
50//!
51//! ## Runtime Execution
52//!
53//! - [`RuntimeExecutor`] - Executes Polkadot SDK runtime calls against forked state
54//! - [`ForkRpcClient`] - RPC client for connecting to live chains
55//!
56//! ## Transaction Pool
57//!
58//! - [`TxPool`] - Minimal FIFO queue for pending extrinsics
59
60mod block;
61mod blockchain;
62mod builder;
63mod cache;
64pub mod dev;
65pub mod error;
66pub mod executor;
67pub mod inherent;
68mod local;
69mod models;
70mod remote;
71mod rpc;
72pub mod rpc_server;
73mod schema;
74mod strings;
75mod txpool;
76
77#[cfg(any(test, feature = "integration-tests"))]
78pub mod testing;
79
80pub use block::{Block, BlockForkPoint};
81pub use blockchain::{
82 Blockchain, BlockchainError, BlockchainEvent, BuildBlockResult, ChainType, FailedExtrinsic,
83 InvalidTransaction, TransactionValidity, TransactionValidityError, UnknownTransaction,
84 ValidTransaction,
85};
86pub use builder::{
87 ApplyExtrinsicResult, BlockBuilder, ConsensusEngineId, DigestItem, consensus_engine,
88 create_next_header, create_next_header_with_slot,
89};
90pub use cache::{PrefixScanProgress, StorageCache};
91pub use error::{
92 BlockBuilderError, BlockError, CacheError, ExecutorError, LocalStorageError,
93 RemoteStorageError, RpcClientError, TxPoolError,
94};
95pub use executor::{
96 ExecutorConfig, RuntimeCallResult, RuntimeExecutor, RuntimeLog, RuntimeVersion,
97 SignatureMockMode,
98};
99pub use inherent::{InherentProvider, ParachainInherent, TimestampInherent, default_providers};
100pub use local::LocalStorageLayer;
101pub use models::BlockRow;
102pub use remote::RemoteStorageLayer;
103pub use rpc::ForkRpcClient;
104pub use txpool::TxPool;