Struct BlockBuilder 

pub struct BlockBuilder { /* private fields */ }

Builder for constructing new blocks on a forked chain.

The BlockBuilder orchestrates the block production process by:

1. Initializing the block with Core_initialize_block
2. Applying inherent extrinsics from registered providers
3. Applying user extrinsics
4. Finalizing the block with BlockBuilder_finalize_block

Storage Handling

Storage changes are applied directly to the parent block’s storage layer. For failed extrinsics (dispatch errors), storage changes are NOT applied.

Thread Safety

BlockBuilder is not Sync by default. It should be used from a single async task.

Example

use pop_fork::{Block, BlockBuilder, RuntimeExecutor, create_next_header};

// Create header for the new block
let header = create_next_header(&parent_block, vec![]);

// Create builder with inherent providers
let mut builder = BlockBuilder::new(parent_block, executor, header, inherent_providers, None, false);

// Build the block
builder.initialize().await?;
builder.apply_inherents().await?;

// Apply user extrinsics
for extrinsic in user_extrinsics {
    match builder.apply_extrinsic(extrinsic).await? {
        ApplyExtrinsicResult::Success { storage_changes } => {
            println!("Applied with {} storage changes", storage_changes);
        }
        ApplyExtrinsicResult::DispatchFailed { error } => {
            println!("Dispatch failed: {}", error);
        }
    }
}

// Finalize and get the new block
let (new_block, _prototype) = builder.finalize().await?;

Implementations

impl BlockBuilder

pub fn new( parent: Block, executor: RuntimeExecutor, header: Vec<u8>, inherent_providers: Vec<Box<dyn InherentProvider>>, prototype: Option<HostVmPrototype>, skip_prefetch: bool, ) -> Self

Create a new block builder.

Arguments

• parent - The parent block to build upon
• executor - Runtime executor for calling runtime methods
• header - Encoded header for the new block
• inherent_providers - Providers for generating inherent extrinsics
• prototype - Optional warm VM prototype to reuse from a previous block build. Passing a compiled prototype avoids re-parsing and re-compiling the WASM runtime, which is significant for large runtimes (~2.5 MB for Asset Hub).
• skip_prefetch - When true, skip the storage prefetch during initialization. Set this after the first block build since all keys are already cached.

Returns

A new BlockBuilder ready for initialization.

pub fn extrinsics(&self) -> &[Vec<u8>]

Get the current list of successfully applied extrinsics.

This includes both inherent extrinsics and user extrinsics that were successfully applied.

pub fn phase(&self) -> BuilderPhase

Get the current phase of block building.

pub async fn initialize( &mut self, ) -> Result<RuntimeCallResult, BlockBuilderError>

Initialize the block by calling Core_initialize_block.

This must be called before applying any inherents or extrinsics. Can only be called once (in Created phase).

Returns

The runtime call result containing storage diff and logs.

Errors

Returns an error if:

• The block has already been initialized
• The runtime call fails

pub async fn apply_inherents( &mut self, ) -> Result<Vec<RuntimeCallResult>, BlockBuilderError>

Apply inherent extrinsics from all registered providers.

This calls each registered InherentProvider to generate inherent extrinsics, then applies them to the block. Can only be called once, after initialize() and before any apply_extrinsic() calls.

Returns

A vector of runtime call results, one for each applied inherent.

Errors

Returns an error if:

• The block has not been initialized
• Inherents have already been applied
• Any inherent provider fails
• Any inherent extrinsic fails to apply

pub async fn apply_extrinsic( &mut self, extrinsic: Vec<u8>, ) -> Result<ApplyExtrinsicResult, BlockBuilderError>

Apply a user extrinsic to the block.

This calls BlockBuilder_apply_extrinsic and checks the dispatch result. Storage changes are only applied if the extrinsic succeeds.

Arguments

• extrinsic - Encoded extrinsic to apply

Returns

• ApplyExtrinsicResult::Success if the extrinsic was applied
• ApplyExtrinsicResult::DispatchFailed if dispatch failed

Errors

Returns an error if:

• The block has not been initialized
• Inherents have not been applied yet
• The runtime call itself fails (not dispatch failure)

pub async fn finalize( self, ) -> Result<(Block, Option<HostVmPrototype>), BlockBuilderError>

Finalize the block by calling BlockBuilder_finalize_block.

This consumes the builder and returns the newly constructed block along with the warm VM prototype. The prototype can be passed to the next BlockBuilder::new call to avoid re-compiling the WASM runtime.

Returns

A tuple of (block, prototype) where prototype is the warm VM prototype that can be reused for the next block build.

Errors

Returns an error if:

• The block has not been initialized
• Inherents have not been applied
• The runtime call fails

pub fn runtime_upgraded(&self) -> bool

Check if a runtime upgrade occurred during this block’s execution.

Returns true if :code was modified in the current block, meaning the next block will need a fresh executor and prototype compiled from the new runtime code.