Struct CoinsViewCache

pub struct CoinsViewCache<Block: BlockT, Client> { /* private fields */ }

In-memory UTXO cache with Substrate runtime backend.

Uses a dual-layer design to handle both blockchain UTXOs and mempool-created coins:

• base_cache: LRU cache of UTXOs from the blockchain (cleared on block import)
• mempool_overlay: Coins created by pending transactions (preserved across blocks)
• mempool_spends: Outputs spent by pending transactions

Implementations

impl<Block, Client> CoinsViewCache<Block, Client>

where Block: BlockT, Client: ProvideRuntimeApi<Block> + HeaderBackend<Block> + Send + Sync, Client::Api: SubcoinApi<Block>,

pub fn new(client: Arc<Client>, cache_size: u32) -> Self

Create a new coins view cache.

Arguments

• client - Substrate client for runtime API access
• cache_size - Maximum number of base layer entries to cache

pub fn get_coin( &mut self, outpoint: &COutPoint, ) -> Result<Option<PoolCoin>, MempoolError>

Get coin with overlay priority.

Query order:

1. Check if spent by mempool
2. Check mempool overlay (created by pending txs)
3. Check base cache
4. Query runtime and cache result

pub fn ensure_coins( &mut self, outpoints: &[COutPoint], ) -> Result<(), MempoolError>

Batch-prefetch coins (called at start of validation).

This is critical for performance: queries all needed coins in a single runtime call rather than making individual calls per input.

Should be called with all transaction inputs before validation begins.

pub fn add_mempool_coins(&mut self, tx: &Transaction)

Add coins from mempool transaction to overlay.

These coins are marked with MEMPOOL_HEIGHT and are preserved across block imports until the transaction is removed from the mempool.

pub fn spend_coin(&mut self, outpoint: &COutPoint)

Mark coin as spent by mempool transaction.

This creates an overlay that makes the coin appear spent even though it exists in the blockchain UTXO set.

pub fn remove_mempool_tx(&mut self, tx: &Transaction)

Remove mempool transaction’s coins (on eviction/confirmation).

Cleans up both the coins created by this transaction and the spends it made from the overlay.

pub fn on_block_connected(&mut self, block_hash: Block::Hash)

Update to new block tip.

CRITICAL: Only clears the base cache, preserving the mempool overlay. Mempool coins remain valid until their transactions are removed.

pub fn have_coin(&self, outpoint: &COutPoint) -> bool

Check if coin exists (for quick lookups without fetching).

pub fn best_block(&self) -> Block::Hash

Get the current best block hash.

pub fn client(&self) -> &Arc<Client>

Get reference to the client.

pub fn cache_stats(&self) -> CacheStats

Get statistics about the cache.