Struct RpcBlockchainProvider 

pub struct RpcBlockchainProvider<P, Node, N = AnyNetwork>
where
    Node: NodeTypes,
{ /* private fields */ }

An RPC-based blockchain provider that fetches blockchain data via remote RPC calls.

This is the RPC equivalent of BlockchainProvider, implementing the same StateProviderFactory and related traits but fetching data from a remote node instead of local storage.

This provider is useful for:

• Testing without requiring a full local database
• Accessing blockchain state from remote nodes
• Building light clients or tools that don’t need full node storage

The provider type is generic over the network type N (defaulting to AnyNetwork), but the current implementation is specialized for alloy_network::AnyNetwork as it needs to access block header fields directly.

Implementations

impl<P, Node: NodeTypes, N> RpcBlockchainProvider<P, Node, N>

pub fn new(provider: P) -> Self

where Node::ChainSpec: Default,

Creates a new RpcBlockchainProvider with default configuration

pub fn new_with_config(provider: P, config: RpcBlockchainProviderConfig) -> Self

where Node::ChainSpec: Default,

Creates a new RpcBlockchainProvider with custom configuration

pub fn with_chain_spec(self, chain_spec: Arc<Node::ChainSpec>) -> Self

Use a custom chain spec for the provider

pub const fn canon_state_notification( &self, ) -> &Sender<CanonStateNotification<PrimitivesTy<Node>>>

Get a reference to the canon state notification sender

Trait Implementations

impl<P, Node, N> BlockBodyIndicesProvider for RpcBlockchainProvider<P, Node, N>

where P: Provider<N> + Clone + 'static, N: Network, Node: NodeTypes,

fn block_body_indices( &self, _num: u64, ) -> ProviderResult<Option<StoredBlockBodyIndices>>

Returns the block body indices with matching number from database.

fn block_body_indices_range( &self, _range: RangeInclusive<BlockNumber>, ) -> ProviderResult<Vec<StoredBlockBodyIndices>>

Returns the block body indices within the requested range matching number from storage.

impl<P, Node, N> BlockHashReader for RpcBlockchainProvider<P, Node, N>

where P: Provider<N> + Clone + 'static, N: Network, Node: NodeTypes,

fn block_hash(&self, number: BlockNumber) -> Result<Option<B256>, ProviderError>

Get the hash of the block with the given number. Returns None if no block with this number exists.

fn canonical_hashes_range( &self, _start: BlockNumber, _end: BlockNumber, ) -> Result<Vec<B256>, ProviderError>

Get headers in range of block hashes or numbers

fn convert_block_hash( &self, hash_or_number: HashOrNumber, ) -> Result<Option<FixedBytes<32>>, ProviderError>

Get the hash of the block with the given number. Returns None if no block with this number exists.

impl<P, Node, N> BlockIdReader for RpcBlockchainProvider<P, Node, N>

where P: Provider<N> + Clone + 'static, N: Network, Node: NodeTypes,

fn block_number_for_id( &self, block_id: BlockId, ) -> Result<Option<BlockNumber>, ProviderError>

Get the number of the block by matching the given id.

fn pending_block_num_hash(&self) -> Result<Option<BlockNumHash>, ProviderError>

Get the current pending block number and hash.

fn safe_block_num_hash(&self) -> Result<Option<BlockNumHash>, ProviderError>

Get the current safe block number and hash.

fn finalized_block_num_hash( &self, ) -> Result<Option<BlockNumHash>, ProviderError>

Get the current finalized block number and hash.

fn convert_block_number( &self, num: BlockNumberOrTag, ) -> Result<Option<u64>, ProviderError>

Converts the BlockNumberOrTag variants to a block number.

fn block_hash_for_id( &self, block_id: BlockId, ) -> Result<Option<FixedBytes<32>>, ProviderError>

Get the hash of the block by matching the given id.

fn safe_block_number(&self) -> Result<Option<u64>, ProviderError>

Get the safe block number.

fn finalized_block_number(&self) -> Result<Option<u64>, ProviderError>

Get the finalized block number.

fn safe_block_hash(&self) -> Result<Option<FixedBytes<32>>, ProviderError>

Get the safe block hash.

fn finalized_block_hash(&self) -> Result<Option<FixedBytes<32>>, ProviderError>

Get the finalized block hash.

impl<P, Node, N> BlockNumReader for RpcBlockchainProvider<P, Node, N>

where P: Provider<N> + Clone + 'static, N: Network, Node: NodeTypes,

fn chain_info(&self) -> Result<ChainInfo, ProviderError>

Returns the current info for the chain.

fn best_block_number(&self) -> Result<BlockNumber, ProviderError>

Returns the best block number in the chain.

fn last_block_number(&self) -> Result<BlockNumber, ProviderError>

Returns the last block number associated with the last canonical header in the database.

fn block_number(&self, hash: B256) -> Result<Option<BlockNumber>, ProviderError>

Gets the BlockNumber for the given hash. Returns None if no block with this hash exists.

fn earliest_block_number(&self) -> Result<u64, ProviderError>

Returns earliest block number to keep track of the expired block range.

fn convert_hash_or_number( &self, id: HashOrNumber, ) -> Result<Option<u64>, ProviderError>

Gets the block number for the given BlockHashOrNumber. Returns None if no block with this hash exists. If the BlockHashOrNumber is a Number, it is returned as is.

fn convert_number( &self, id: HashOrNumber, ) -> Result<Option<FixedBytes<32>>, ProviderError>

Gets the block hash for the given BlockHashOrNumber. Returns None if no block with this number exists. If the BlockHashOrNumber is a Hash, it is returned as is.

impl<P, Node, N> BlockReader for RpcBlockchainProvider<P, Node, N>

where P: Provider<N> + Clone + 'static, N: Network, Node: NodeTypes, BlockTy<Node>: TryFromBlockResponse<N>, TxTy<Node>: TryFromTransactionResponse<N>, ReceiptTy<Node>: TryFromReceiptResponse<N>,

type Block = <<Node as NodeTypes>::Primitives as NodePrimitives>::Block

The block type this provider reads.

fn find_block_by_hash( &self, _hash: B256, _source: BlockSource, ) -> ProviderResult<Option<Self::Block>>

Tries to find in the given block source.

fn block(&self, id: BlockHashOrNumber) -> ProviderResult<Option<Self::Block>>

Returns the block with given id from the database.

fn pending_block(&self) -> ProviderResult<Option<RecoveredBlock<Self::Block>>>

Returns the pending block if available

fn pending_block_and_receipts( &self, ) -> ProviderResult<Option<(RecoveredBlock<Self::Block>, Vec<Self::Receipt>)>>

Returns the pending block and receipts if available.

fn recovered_block( &self, _id: BlockHashOrNumber, _transaction_kind: TransactionVariant, ) -> ProviderResult<Option<RecoveredBlock<Self::Block>>>

Returns the block with senders with matching number or hash from database.

fn sealed_block_with_senders( &self, _id: BlockHashOrNumber, _transaction_kind: TransactionVariant, ) -> ProviderResult<Option<RecoveredBlock<Self::Block>>>

Returns the sealed block with senders with matching number or hash from database.

fn block_range( &self, _range: RangeInclusive<BlockNumber>, ) -> ProviderResult<Vec<Self::Block>>

Returns all blocks in the given inclusive range.

fn block_with_senders_range( &self, _range: RangeInclusive<BlockNumber>, ) -> ProviderResult<Vec<RecoveredBlock<Self::Block>>>

Returns a range of blocks from the database, along with the senders of each transaction in the blocks.

fn recovered_block_range( &self, _range: RangeInclusive<BlockNumber>, ) -> ProviderResult<Vec<RecoveredBlock<Self::Block>>>

Returns a range of sealed blocks from the database, along with the senders of each transaction in the blocks.

fn block_by_hash( &self, hash: FixedBytes<32>, ) -> Result<Option<Self::Block>, ProviderError>

Returns the block with matching hash from the database.

fn block_by_number( &self, num: u64, ) -> Result<Option<Self::Block>, ProviderError>

Returns the block with matching number from database.

impl<P, Node, N> BlockReaderIdExt for RpcBlockchainProvider<P, Node, N>

where P: Provider<N> + Clone + 'static, N: Network, Node: NodeTypes, BlockTy<Node>: TryFromBlockResponse<N>, TxTy<Node>: TryFromTransactionResponse<N>, ReceiptTy<Node>: TryFromReceiptResponse<N>,

fn block_by_id(&self, id: BlockId) -> ProviderResult<Option<Self::Block>>

Returns the block with the matching [BlockId] from the database.

fn sealed_header_by_id( &self, id: BlockId, ) -> ProviderResult<Option<SealedHeader<Self::Header>>>

Returns the sealed header with the matching BlockId from the database.

fn header_by_id(&self, id: BlockId) -> ProviderResult<Option<Self::Header>>

Returns the header with the matching BlockId from the database.

fn block_by_number_or_tag( &self, id: BlockNumberOrTag, ) -> Result<Option<Self::Block>, ProviderError>

Returns the block with matching tag from the database

fn pending_header( &self, ) -> Result<Option<SealedHeader<Self::Header>>, ProviderError>

Returns the pending block header if available

fn latest_header( &self, ) -> Result<Option<SealedHeader<Self::Header>>, ProviderError>

Returns the latest block header if available

fn safe_header( &self, ) -> Result<Option<SealedHeader<Self::Header>>, ProviderError>

Returns the safe block header if available

fn finalized_header( &self, ) -> Result<Option<SealedHeader<Self::Header>>, ProviderError>

Returns the finalized block header if available

fn block_with_senders_by_id( &self, id: BlockId, transaction_kind: TransactionVariant, ) -> Result<Option<RecoveredBlock<Self::Block>>, ProviderError>

Returns the block with senders with matching [BlockId].

fn header_by_number_or_tag( &self, id: BlockNumberOrTag, ) -> Result<Option<Self::Header>, ProviderError>

Returns the header with matching tag from the database

fn sealed_header_by_number_or_tag( &self, id: BlockNumberOrTag, ) -> Result<Option<SealedHeader<Self::Header>>, ProviderError>

Returns the header with matching tag from the database

impl<P, Node, N> CanonChainTracker for RpcBlockchainProvider<P, Node, N>

where P: Provider<N> + Clone + 'static, N: Network, Node: NodeTypes,

type Header = Header

The header type.

fn on_forkchoice_update_received(&self, _update: &ForkchoiceState)

Notify the tracker about a received fork choice update.

fn last_received_update_timestamp(&self) -> Option<Instant>

Returns the last time a fork choice update was received from the CL ([CanonChainTracker::on_forkchoice_update_received])

fn set_canonical_head(&self, _header: SealedHeader<Self::Header>)

Sets the canonical head of the chain.

fn set_safe(&self, _header: SealedHeader<Self::Header>)

Sets the safe block of the chain.

fn set_finalized(&self, _header: SealedHeader<Self::Header>)

Sets the finalized block of the chain.

impl<P, Node, N> CanonStateSubscriptions for RpcBlockchainProvider<P, Node, N>

where P: Provider<N> + Clone + 'static, N: Network, Node: NodeTypes,

fn subscribe_to_canonical_state( &self, ) -> CanonStateNotifications<PrimitivesTy<Node>>

Get notified when a new canonical chain was imported.

fn canonical_state_stream( &self, ) -> CanonStateNotificationStream<Self::Primitives>

Convenience method to get a stream of [CanonStateNotification].

impl<P, Node, N> ChainSpecProvider for RpcBlockchainProvider<P, Node, N>

where P: Send + Sync, N: Send + Sync, Node: NodeTypes, Node::ChainSpec: Default,

type ChainSpec = <Node as NodeTypes>::ChainSpec

The chain spec type.

fn chain_spec(&self) -> Arc<Self::ChainSpec>

Get an Arc to the chainspec.

impl<P: Clone, Node, N: Clone> Clone for RpcBlockchainProvider<P, Node, N>

where Node: NodeTypes + Clone, Node::ChainSpec: Clone,

fn clone(&self) -> RpcBlockchainProvider<P, Node, N>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<P, Node, N> DatabaseProviderFactory for RpcBlockchainProvider<P, Node, N>

where P: Provider<N> + Clone + 'static, N: Network, Node: NodeTypes,

type DB = DatabaseMock

Database this factory produces providers for.

type ProviderRW = RpcBlockchainStateProvider<P, Node, N>

Read-write provider type returned by the factory.

type Provider = RpcBlockchainStateProvider<P, Node, N>

Provider type returned by the factory.

fn database_provider_ro(&self) -> Result<Self::Provider, ProviderError>

Create new read-only database provider.

fn database_provider_rw(&self) -> Result<Self::ProviderRW, ProviderError>

Create new read-write database provider.

impl<P, Node: NodeTypes, N> Debug for RpcBlockchainProvider<P, Node, N>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<P, Node, N> HeaderProvider for RpcBlockchainProvider<P, Node, N>

where P: Provider<N> + Clone + 'static, N: Network, Node: NodeTypes, BlockTy<Node>: TryFromBlockResponse<N>,

type Header = <<Node as NodeTypes>::Primitives as NodePrimitives>::BlockHeader

The header type this provider supports.

fn header(&self, block_hash: &BlockHash) -> ProviderResult<Option<Self::Header>>

Get header by block hash

fn header_by_number(&self, num: u64) -> ProviderResult<Option<Self::Header>>

Get header by block number

fn header_td(&self, hash: &BlockHash) -> ProviderResult<Option<U256>>

Get total difficulty by block hash.

fn header_td_by_number( &self, number: BlockNumber, ) -> ProviderResult<Option<U256>>

Get total difficulty by block number.

fn headers_range( &self, _range: impl RangeBounds<BlockNumber>, ) -> ProviderResult<Vec<Self::Header>>

Get headers in range of block numbers

fn sealed_header( &self, number: BlockNumber, ) -> ProviderResult<Option<SealedHeader<Self::Header>>>

Get a single sealed header by block number.

fn sealed_headers_while( &self, _range: impl RangeBounds<BlockNumber>, _predicate: impl FnMut(&SealedHeader<Self::Header>) -> bool, ) -> ProviderResult<Vec<SealedHeader<Self::Header>>>

Get sealed headers while predicate returns true or the range is exhausted.

fn is_known(&self, block_hash: &FixedBytes<32>) -> Result<bool, ProviderError>

Check if block is known

fn sealed_header_by_hash( &self, block_hash: FixedBytes<32>, ) -> Result<Option<SealedHeader<Self::Header>>, ProviderError>

Retrieves the header sealed by the given block hash.

fn header_by_hash_or_number( &self, hash_or_num: HashOrNumber, ) -> Result<Option<Self::Header>, ProviderError>

Get header by block number or hash

fn sealed_headers_range( &self, range: impl RangeBounds<u64>, ) -> Result<Vec<SealedHeader<Self::Header>>, ProviderError>

Get headers in range of block numbers.

impl<P, Node, N> NodePrimitivesProvider for RpcBlockchainProvider<P, Node, N>

where P: Send + Sync, N: Send + Sync, Node: NodeTypes,

type Primitives = <Node as NodeTypes>::Primitives

The node primitive types.

impl<P, Node, N> ReceiptProvider for RpcBlockchainProvider<P, Node, N>

where P: Provider<N> + Clone + 'static, N: Network, Node: NodeTypes, ReceiptTy<Node>: TryFromReceiptResponse<N>,

type Receipt = <<Node as NodeTypes>::Primitives as NodePrimitives>::Receipt

The receipt type.

fn receipt(&self, _id: TxNumber) -> ProviderResult<Option<Self::Receipt>>

Get receipt by transaction number

fn receipt_by_hash(&self, hash: TxHash) -> ProviderResult<Option<Self::Receipt>>

Get receipt by transaction hash.

fn receipts_by_block( &self, block: BlockHashOrNumber, ) -> ProviderResult<Option<Vec<Self::Receipt>>>

Get receipts by block num or hash.

fn receipts_by_tx_range( &self, _range: impl RangeBounds<TxNumber>, ) -> ProviderResult<Vec<Self::Receipt>>

Get receipts by tx range.

fn receipts_by_block_range( &self, _block_range: RangeInclusive<BlockNumber>, ) -> ProviderResult<Vec<Vec<Self::Receipt>>>

Get receipts by block range.

impl<P, Node, N> ReceiptProviderIdExt for RpcBlockchainProvider<P, Node, N>

where P: Provider<N> + Clone + 'static, N: Network, Node: NodeTypes, ReceiptTy<Node>: TryFromReceiptResponse<N>,

fn receipts_by_block_id( &self, block: BlockId, ) -> Result<Option<Vec<Self::Receipt>>, ProviderError>

Get receipt by block id

fn receipts_by_number_or_tag( &self, number_or_tag: BlockNumberOrTag, ) -> Result<Option<Vec<Self::Receipt>>, ProviderError>

Returns the block with the matching BlockId from the database.

impl<P, Node, N> StateProviderFactory for RpcBlockchainProvider<P, Node, N>

where P: Provider<N> + Clone + 'static, N: Network, Node: NodeTypes,

fn latest(&self) -> Result<StateProviderBox, ProviderError>

Storage provider for latest block.

fn state_by_block_id( &self, block_id: BlockId, ) -> Result<StateProviderBox, ProviderError>

Returns a [StateProvider] indexed by the given [BlockId].

fn state_by_block_number_or_tag( &self, number_or_tag: BlockNumberOrTag, ) -> Result<StateProviderBox, ProviderError>

Returns a [StateProvider] indexed by the given block number or tag.

fn history_by_block_number( &self, block_number: BlockNumber, ) -> Result<StateProviderBox, ProviderError>

Returns a historical [StateProvider] indexed by the given historic block number.

fn history_by_block_hash( &self, block_hash: BlockHash, ) -> Result<StateProviderBox, ProviderError>

Returns a historical [StateProvider] indexed by the given block hash.

fn state_by_block_hash( &self, block_hash: BlockHash, ) -> Result<StateProviderBox, ProviderError>

Returns any [StateProvider] with matching block hash.

fn pending(&self) -> Result<StateProviderBox, ProviderError>

Storage provider for pending state.

fn pending_state_by_hash( &self, _block_hash: B256, ) -> Result<Option<StateProviderBox>, ProviderError>

Storage provider for pending state for the given block hash.

impl<P, Node, N> TransactionsProvider for RpcBlockchainProvider<P, Node, N>

where P: Provider<N> + Clone + 'static, N: Network, Node: NodeTypes, BlockTy<Node>: TryFromBlockResponse<N>, TxTy<Node>: TryFromTransactionResponse<N>,

type Transaction = <<Node as NodeTypes>::Primitives as NodePrimitives>::SignedTx

The transaction type this provider reads.

fn transaction_id(&self, _tx_hash: TxHash) -> ProviderResult<Option<TxNumber>>

Get internal transaction identifier by transaction hash.

fn transaction_by_id( &self, _id: TxNumber, ) -> ProviderResult<Option<Self::Transaction>>

Get transaction by id, computes hash every time so more expensive.

fn transaction_by_id_unhashed( &self, _id: TxNumber, ) -> ProviderResult<Option<Self::Transaction>>

Get transaction by id without computing the hash.

fn transaction_by_hash( &self, hash: TxHash, ) -> ProviderResult<Option<Self::Transaction>>

Get transaction by transaction hash.

fn transaction_by_hash_with_meta( &self, _hash: TxHash, ) -> ProviderResult<Option<(Self::Transaction, TransactionMeta)>>

Get transaction by transaction hash and additional metadata of the block the transaction was mined in

fn transaction_block( &self, _id: TxNumber, ) -> ProviderResult<Option<BlockNumber>>

Get transaction block number

fn transactions_by_block( &self, block: BlockHashOrNumber, ) -> ProviderResult<Option<Vec<Self::Transaction>>>

Get transactions by block id.

fn transactions_by_block_range( &self, _range: impl RangeBounds<BlockNumber>, ) -> ProviderResult<Vec<Vec<Self::Transaction>>>

Get transactions by block range.

fn transactions_by_tx_range( &self, _range: impl RangeBounds<TxNumber>, ) -> ProviderResult<Vec<Self::Transaction>>

Get transactions by tx range.

fn senders_by_tx_range( &self, _range: impl RangeBounds<TxNumber>, ) -> ProviderResult<Vec<Address>>

Get Senders from a tx range.

fn transaction_sender(&self, _id: TxNumber) -> ProviderResult<Option<Address>>

Get transaction sender.

Layout

Note: Unable to compute type layout, possibly due to this type having generic parameters. Layout can only be computed for concrete, fully-instantiated types.