graph: Add CachedBlock enum and typed block cache

Author: incrypto32

chain/ethereum/src/chain.rs

@@ -65,8 +65,6 @@ use graph::blockchain::block_stream::{
     BlockStream, BlockStreamBuilder, BlockStreamError, BlockStreamMapper, FirehoseCursor,
     TriggersAdapterWrapper,
 };
-use graph::components::ethereum::EthereumJsonBlock;
-
 /// Celo Mainnet: 42220, Testnet Alfajores: 44787, Testnet Baklava: 62320
 const CELO_CHAIN_IDS: [u64; 3] = [42220, 44787, 62320];
 
@@ -1076,52 +1074,25 @@ impl TriggersAdapterTrait<Chain> for TriggersAdapter {
             .ancestor_block(ptr.clone(), offset, root.clone())
             .await?;
 
-        // First check if we have the ancestor in cache and can deserialize it.
-        // The cached JSON can be in one of three formats:
-        // 1. Full RPC format: {"block": {...}, "transaction_receipts": [...]}
-        // 2. Shallow/header-only: {"timestamp": "...", "data": null} - only timestamp, no block data
-        // 3. Legacy direct: block fields at root level {hash, number, transactions, ...}
-        // We need full format with receipts for ancestor_block (used for trigger processing).
+        // Use full blocks (with receipts) directly from cache.
+        // Light blocks (no receipts) need to be fetched from Firehose/RPC.
         let block_ptr = match cached {
-            Some((json, ptr)) => {
-                let json_block = EthereumJsonBlock::new(json);
-                if json_block.is_shallow() {
-                    trace!(
-                        self.logger,
-                        "Cached block #{} {} is shallow (header-only). Falling back to Firehose/RPC.",
-                        ptr.number,
-                        ptr.hash_hex(),
-                    );
-                    ptr
-                } else if json_block.is_legacy_format() {
-                    trace!(
-                        self.logger,
-                        "Cached block #{} {} is legacy light format. Falling back to Firehose/RPC.",
-                        ptr.number,
-                        ptr.hash_hex(),
-                    );
-                    ptr
-                } else {
-                    match json_block.into_full_block() {
-                        Ok(block) => {
-                            return Ok(Some(BlockFinality::NonFinal(EthereumBlockWithCalls {
-                                ethereum_block: block,
-                                calls: None,
-                            })));
-                        }
-                        Err(e) => {
-                            warn!(
-                                self.logger,
-                                "Failed to deserialize cached ancestor block #{} {} (offset {} from #{}): {}. \
-                                 Falling back to Firehose/RPC.",
-                                ptr.number,
-                                ptr.hash_hex(),
-                                offset,
-                                ptr_for_log.number,
-                                e
-                            );
-                            ptr
-                        }
+            Some((cached_block, ptr)) => {
+                match cached_block.into_full_block() {
+                    Some(block) => {
+                        return Ok(Some(BlockFinality::NonFinal(EthereumBlockWithCalls {
+                            ethereum_block: block,
+                            calls: None,
+                        })));
+                    }
+                    None => {
+                        trace!(
+                            self.logger,
+                            "Cached block #{} {} is light (no receipts). Falling back to Firehose/RPC.",
+                            ptr.number,
+                            ptr.hash_hex(),
+                        );
+                        ptr
                     }
                 }
             }
@@ -1179,35 +1150,10 @@ impl TriggersAdapterTrait<Chain> for TriggersAdapter {
         let block = match self.chain_client.as_ref() {
             ChainClient::Firehose(endpoints) => {
                 let chain_store = self.chain_store.cheap_clone();
-                // First try to get the block from the store
-                // See ancestor_block() for documentation of the 3 cached JSON formats.
+                // First try to get the block from the store (typed cache)
                 if let Ok(blocks) = chain_store.blocks(vec![block.hash.clone()]).await {
-                    if let Some(cached_json) = blocks.into_iter().next() {
-                        let json_block = EthereumJsonBlock::new(cached_json);
-                        if json_block.is_shallow() {
-                            trace!(
-                                self.logger,
-                                "Cached block #{} {} is shallow. Falling back to Firehose.",
-                                block.number,
-                                block.hash_hex(),
-                            );
-                        } else {
-                            match json_block.into_light_block() {
-                                Ok(light_block) => {
-                                    return Ok(light_block.parent_ptr());
-                                }
-                                Err(e) => {
-                                    warn!(
-                                        self.logger,
-                                        "Failed to deserialize cached block #{} {}: {}. \
-                                         Falling back to Firehose.",
-                                        block.number,
-                                        block.hash_hex(),
-                                        e
-                                    );
-                                }
-                            }
-                        }
+                    if let Some(cached_block) = blocks.into_iter().next() {
+                        return Ok(cached_block.light_block().parent_ptr());
                     }
                 }
 

chain/ethereum/src/ethereum_adapter.rs

@@ -79,7 +79,6 @@ use crate::{
     trigger::{EthereumBlockTriggerType, EthereumTrigger},
     ENV_VARS,
 };
-use graph::components::ethereum::EthereumJsonBlock;
 
 type AlloyProvider = FillProvider<
     JoinFill<
@@ -1641,23 +1640,7 @@ impl EthereumAdapterTrait for EthereumAdapter {
             .map_err(|e| error!(&logger, "Error accessing block cache {}", e))
             .unwrap_or_default()
             .into_iter()
-            .filter_map(|value| {
-                let json_block = EthereumJsonBlock::new(value);
-                if json_block.is_shallow() {
-                    return None;
-                }
-                json_block
-                    .into_light_block()
-                    .map_err(|e| {
-                        warn!(
-                            &logger,
-                            "Failed to deserialize cached block: {}. Block will be re-fetched from RPC.",
-                            e
-                        );
-                    })
-                    .ok()
-            })
-            .map(Arc::new)
+            .map(|cached| Arc::new(cached.into_light_block()))
             .collect();
 
         let missing_blocks = Vec::from_iter(

graph/src/blockchain/mock.rs

@@ -1,6 +1,7 @@
 use crate::{
     bail,
     components::{
+        ethereum::CachedBlock,
         link_resolver::LinkResolver,
         network_provider::ChainName,
         store::{
@@ -527,15 +528,18 @@ impl ChainStore for MockChainStore {
     ) -> Result<Option<B256>, Error> {
         unimplemented!()
     }
-    async fn blocks(self: Arc<Self>, _hashes: Vec<BlockHash>) -> Result<Vec<Value>, Error> {
+    async fn blocks(self: Arc<Self>, _hashes: Vec<BlockHash>) -> Result<Vec<CachedBlock>, Error> {
+        unimplemented!()
+    }
+    async fn blocks_as_json(self: Arc<Self>, _hashes: Vec<BlockHash>) -> Result<Vec<Value>, Error> {
         unimplemented!()
     }
     async fn ancestor_block(
         self: Arc<Self>,
         _block_ptr: BlockPtr,
         _offset: BlockNumber,
         _root: Option<BlockHash>,
-    ) -> Result<Option<(Value, BlockPtr)>, Error> {
+    ) -> Result<Option<(CachedBlock, BlockPtr)>, Error> {
         unimplemented!()
     }
     async fn cleanup_cached_blocks(

graph/src/components/ethereum/json_block.rs

@@ -1,7 +1,7 @@
 use serde_json::{self as json, Value};
 
 use super::json_patch;
-use super::types::{EthereumBlock, LightEthereumBlock};
+use super::types::{CachedBlock, EthereumBlock, LightEthereumBlock};
 
 #[derive(Debug)]
 pub struct EthereumJsonBlock(Value);
@@ -49,4 +49,18 @@ impl EthereumJsonBlock {
         json_patch::patch_block_transactions(&mut inner);
         json::from_value(inner)
     }
+
+    /// Tries to deserialize into a `CachedBlock`. Uses `transaction_receipts`
+    /// presence to decide between full and light block, avoiding a JSON clone.
+    pub fn try_into_cached_block(self) -> Option<CachedBlock> {
+        let has_receipts = self
+            .0
+            .get("transaction_receipts")
+            .is_some_and(|v| !v.is_null());
+        if has_receipts {
+            self.into_full_block().ok().map(CachedBlock::Full)
+        } else {
+            self.into_light_block().ok().map(CachedBlock::Light)
+        }
+    }
 }

graph/src/components/ethereum/mod.rs

@@ -6,8 +6,8 @@ mod types;
 pub use self::json_block::EthereumJsonBlock;
 pub use self::network::AnyNetworkBare;
 pub use self::types::{
-    AnyBlock, AnyTransaction, AnyTransactionReceiptBare, EthereumBlock, EthereumBlockWithCalls,
-    EthereumCall, LightEthereumBlock, LightEthereumBlockExt,
+    AnyBlock, AnyTransaction, AnyTransactionReceiptBare, CachedBlock, EthereumBlock,
+    EthereumBlockWithCalls, EthereumCall, LightEthereumBlock, LightEthereumBlockExt,
 };
 
 // Re-export Alloy network types for convenience

graph/src/components/ethereum/types.rs

@@ -17,14 +17,16 @@ use crate::{
     prelude::BlockNumber,
 };
 
+use super::json_block::EthereumJsonBlock;
+
 pub type AnyTransaction = Transaction<AnyTxEnvelope>;
 pub type AnyBlock = Block<AnyTransaction, Header<AnyHeader>>;
 /// Like alloy's `AnyTransactionReceipt` but without the `WithOtherFields` wrapper,
 /// avoiding `#[serde(flatten)]` overhead during deserialization.
 pub type AnyTransactionReceiptBare = TransactionReceipt<AnyReceiptEnvelope<Log>>;
 
 #[allow(dead_code)]
-#[derive(Debug, Deserialize, Serialize)]
+#[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct LightEthereumBlock(AnyBlock);
 
 impl Default for LightEthereumBlock {
@@ -259,3 +261,55 @@ impl<'a> From<&'a EthereumCall> for BlockPtr {
         BlockPtr::from((call.block_hash, call.block_number))
     }
 }
+
+/// Typed cached block for Ethereum. Stores the deserialized block so that
+/// repeated reads from the in-memory cache avoid `serde_json::from_value()`.
+#[derive(Clone, Debug)]
+#[allow(clippy::large_enum_variant)]
+pub enum CachedBlock {
+    Full(EthereumBlock),
+    Light(LightEthereumBlock),
+}
+
+impl CachedBlock {
+    pub fn light_block(&self) -> &LightEthereumBlock {
+        match self {
+            CachedBlock::Full(block) => &block.block,
+            CachedBlock::Light(block) => block,
+        }
+    }
+
+    pub fn into_light_block(self) -> LightEthereumBlock {
+        match self {
+            CachedBlock::Full(block) => block.block.as_ref().clone(),
+            CachedBlock::Light(block) => block,
+        }
+    }
+
+    pub fn into_full_block(self) -> Option<EthereumBlock> {
+        match self {
+            CachedBlock::Full(block) => Some(block),
+            CachedBlock::Light(_) => None,
+        }
+    }
+
+    pub fn from_json(value: serde_json::Value) -> Option<Self> {
+        let json_block = EthereumJsonBlock::new(value);
+        if json_block.is_shallow() {
+            return None;
+        }
+        json_block.try_into_cached_block()
+    }
+
+    pub fn timestamp(&self) -> Option<u64> {
+        Some(self.light_block().timestamp_u64())
+    }
+
+    pub fn parent_ptr(&self) -> Option<BlockPtr> {
+        self.light_block().parent_ptr()
+    }
+
+    pub fn ptr(&self) -> BlockPtr {
+        self.light_block().block_ptr()
+    }
+}

graph/src/components/store/traits.rs

@@ -7,6 +7,7 @@ use async_trait::async_trait;
 use super::*;
 use crate::blockchain::block_stream::{EntitySourceOperation, FirehoseCursor};
 use crate::blockchain::{BlockTime, ChainIdentifier, ExtendedBlockPtr};
+use crate::components::ethereum::CachedBlock;
 use crate::components::metrics::stopwatch::StopwatchMetrics;
 use crate::components::network_provider::ChainName;
 use crate::components::server::index_node::VersionInfo;
@@ -553,8 +554,12 @@ pub trait ChainStore: ChainHeadStore {
         ancestor_count: BlockNumber,
     ) -> Result<Option<B256>, Error>;
 
-    /// Returns the blocks present in the store.
-    async fn blocks(
+    /// Returns the blocks present in the store as typed cached blocks.
+    async fn blocks(self: Arc<Self>, hashes: Vec<BlockHash>) -> Result<Vec<CachedBlock>, Error>;
+
+    /// Returns blocks as raw JSON. Used by callers that need the original
+    /// JSON representation (e.g., GraphQL block queries, CLI tools).
+    async fn blocks_as_json(
         self: Arc<Self>,
         hashes: Vec<BlockHash>,
     ) -> Result<Vec<serde_json::Value>, Error>;
@@ -584,7 +589,7 @@ pub trait ChainStore: ChainHeadStore {
         block_ptr: BlockPtr,
         offset: BlockNumber,
         root: Option<BlockHash>,
-    ) -> Result<Option<(serde_json::Value, BlockPtr)>, Error>;
+    ) -> Result<Option<(CachedBlock, BlockPtr)>, Error>;
 
     /// Remove old blocks from the cache we maintain in the database and
     /// return a pair containing the number of the oldest block retained

node/src/manager/commands/check_blocks.rs

@@ -187,7 +187,7 @@ mod steps {
         block_hash: B256,
         chain_store: Arc<ChainStore>,
     ) -> anyhow::Result<Value> {
-        let blocks = chain_store.blocks(vec![block_hash.into()]).await?;
+        let blocks = chain_store.blocks_as_json(vec![block_hash.into()]).await?;
         match blocks.len() {
             0 => bail!("Failed to locate block with hash {} in store", block_hash),
             1 => {}

server/index-node/src/resolver.rs

@@ -222,7 +222,9 @@ where
             return Ok(r::Value::Null);
         };
 
-        let blocks_res = chain_store.blocks(vec![block_hash.cheap_clone()]).await;
+        let blocks_res = chain_store
+            .blocks_as_json(vec![block_hash.cheap_clone()])
+            .await;
         Ok(match blocks_res {
             Ok(blocks) if blocks.is_empty() => {
                 error!(