feat(cold): add get_receipt_with_context composite query (#19)

* feat(cold): add get_receipt_with_context composite query

Add a single-roundtrip method to ColdStorage that returns everything
needed to build an RPC receipt response: the header, transaction,
receipt, confirmation metadata, and prior cumulative gas.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor(cold-mdbx): use single MDBX transaction per read method

Rewrite get_header, get_headers, get_transaction, get_receipt, and
get_receipt_with_context to each open a single read transaction with
inline cursor lookups instead of delegating to helpers that each open
their own transaction. Removes 9 now-unused private helpers.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor(cold): simplify ReceiptContext with Confirmed<Receipt>

Use Confirmed<Receipt> instead of separate receipt + meta fields,
add default trait impl for get_receipt_with_context, and eliminate
MDBX get_receipt_inner duplication by delegating to the composite method.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor(cold): remove tag-based block lookups

BlockTag and HeaderSpecifier::Tag were dead code — the only real
consumer of "latest block" uses the dedicated get_latest_block() method,
and Finalized/Safe were never written. Removing them simplifies the
trait contract and reduces implementation burden for backends.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: prestwich

crates/cold-mdbx/src/backend.rs

@@ -10,8 +10,8 @@ use crate::{
 };
 use alloy::{consensus::Header, primitives::BlockNumber};
 use signet_cold::{
-    BlockData, BlockTag, ColdResult, ColdStorage, Confirmed, HeaderSpecifier, ReceiptSpecifier,
-    SignetEventsSpecifier, TransactionSpecifier, ZenithHeaderSpecifier,
+    BlockData, ColdResult, ColdStorage, Confirmed, HeaderSpecifier, ReceiptContext,
+    ReceiptSpecifier, SignetEventsSpecifier, TransactionSpecifier, ZenithHeaderSpecifier,
 };
 use signet_hot::{
     KeySer, MAX_KEY_SIZE, ValSer,
@@ -124,116 +124,111 @@ impl MdbxColdBackend {
         Ok(())
     }
 
-    fn resolve_tag(&self, tag: BlockTag) -> Result<Option<BlockNumber>, MdbxColdError> {
-        let key = match tag {
-            BlockTag::Latest => MetadataKey::LatestBlock,
-            BlockTag::Finalized => MetadataKey::FinalizedBlock,
-            BlockTag::Safe => MetadataKey::SafeBlock,
-            BlockTag::Earliest => MetadataKey::EarliestBlock,
-        };
-        self.get_metadata(key)
-    }
-
     fn get_metadata(&self, key: MetadataKey) -> Result<Option<BlockNumber>, MdbxColdError> {
         let tx = self.env.tx()?;
         Ok(TableTraverse::<ColdMetadata, _>::exact(&mut tx.new_cursor::<ColdMetadata>()?, &key)?)
     }
 
-    fn get_block_by_hash(
-        &self,
-        hash: alloy::primitives::B256,
-    ) -> Result<Option<BlockNumber>, MdbxColdError> {
+    fn get_header_inner(&self, spec: HeaderSpecifier) -> Result<Option<Header>, MdbxColdError> {
         let tx = self.env.tx()?;
-        Ok(TableTraverse::<ColdBlockHashIndex, _>::exact(
-            &mut tx.new_cursor::<ColdBlockHashIndex>()?,
-            &hash,
+        let block_num = match spec {
+            HeaderSpecifier::Number(n) => n,
+            HeaderSpecifier::Hash(h) => {
+                let Some(n) = TableTraverse::<ColdBlockHashIndex, _>::exact(
+                    &mut tx.new_cursor::<ColdBlockHashIndex>()?,
+                    &h,
+                )?
+                else {
+                    return Ok(None);
+                };
+                n
+            }
+        };
+        Ok(TableTraverse::<ColdHeaders, _>::exact(
+            &mut tx.new_cursor::<ColdHeaders>()?,
+            &block_num,
         )?)
     }
 
-    fn get_tx_location(
+    fn get_headers_inner(
         &self,
-        hash: alloy::primitives::B256,
-    ) -> Result<Option<TxLocation>, MdbxColdError> {
+        specs: Vec<HeaderSpecifier>,
+    ) -> Result<Vec<Option<Header>>, MdbxColdError> {
         let tx = self.env.tx()?;
-        Ok(TableTraverse::<ColdTxHashIndex, _>::exact(
-            &mut tx.new_cursor::<ColdTxHashIndex>()?,
-            &hash,
-        )?)
-    }
-
-    fn resolve_header_spec(
-        &self,
-        spec: HeaderSpecifier,
-    ) -> Result<Option<BlockNumber>, MdbxColdError> {
-        match spec {
-            HeaderSpecifier::Number(n) => Ok(Some(n)),
-            HeaderSpecifier::Hash(h) => self.get_block_by_hash(h),
-            HeaderSpecifier::Tag(tag) => self.resolve_tag(tag),
-        }
+        specs
+            .into_iter()
+            .map(|spec| {
+                let block_num = match spec {
+                    HeaderSpecifier::Number(n) => Some(n),
+                    HeaderSpecifier::Hash(h) => TableTraverse::<ColdBlockHashIndex, _>::exact(
+                        &mut tx.new_cursor::<ColdBlockHashIndex>()?,
+                        &h,
+                    )?,
+                };
+                block_num
+                    .map(|n| {
+                        TableTraverse::<ColdHeaders, _>::exact(
+                            &mut tx.new_cursor::<ColdHeaders>()?,
+                            &n,
+                        )
+                    })
+                    .transpose()
+                    .map(Option::flatten)
+            })
+            .collect::<Result<_, _>>()
+            .map_err(Into::into)
     }
 
-    fn resolve_tx_spec(
+    fn get_transaction_inner(
         &self,
         spec: TransactionSpecifier,
-    ) -> Result<Option<(BlockNumber, u64)>, MdbxColdError> {
-        match spec {
+    ) -> Result<Option<Confirmed<TransactionSigned>>, MdbxColdError> {
+        let tx = self.env.tx()?;
+        let (block, index) = match spec {
             TransactionSpecifier::Hash(h) => {
-                self.get_tx_location(h).map(|opt| opt.map(|loc| (loc.block, loc.index)))
+                let Some(loc) = TableTraverse::<ColdTxHashIndex, _>::exact(
+                    &mut tx.new_cursor::<ColdTxHashIndex>()?,
+                    &h,
+                )?
+                else {
+                    return Ok(None);
+                };
+                (loc.block, loc.index)
             }
-            TransactionSpecifier::BlockAndIndex { block, index } => Ok(Some((block, index))),
+            TransactionSpecifier::BlockAndIndex { block, index } => (block, index),
             TransactionSpecifier::BlockHashAndIndex { block_hash, index } => {
-                self.get_block_by_hash(block_hash).map(|opt| opt.map(|b| (b, index)))
+                let Some(block) = TableTraverse::<ColdBlockHashIndex, _>::exact(
+                    &mut tx.new_cursor::<ColdBlockHashIndex>()?,
+                    &block_hash,
+                )?
+                else {
+                    return Ok(None);
+                };
+                (block, index)
             }
-        }
-    }
-
-    fn resolve_receipt_spec(
-        &self,
-        spec: ReceiptSpecifier,
-    ) -> Result<Option<(BlockNumber, u64)>, MdbxColdError> {
-        match spec {
-            ReceiptSpecifier::TxHash(h) => {
-                self.get_tx_location(h).map(|opt| opt.map(|loc| (loc.block, loc.index)))
-            }
-            ReceiptSpecifier::BlockAndIndex { block, index } => Ok(Some((block, index))),
-        }
-    }
-
-    fn get_header_by_number(
-        &self,
-        block_num: BlockNumber,
-    ) -> Result<Option<Header>, MdbxColdError> {
-        let tx = self.env.tx()?;
-        Ok(TableTraverse::<ColdHeaders, _>::exact(
-            &mut tx.new_cursor::<ColdHeaders>()?,
-            &block_num,
-        )?)
-    }
-
-    fn get_transaction_by_location(
-        &self,
-        block: BlockNumber,
-        index: u64,
-    ) -> Result<Option<TransactionSigned>, MdbxColdError> {
-        let tx = self.env.tx()?;
-        Ok(DualTableTraverse::<ColdTransactions, _>::exact_dual(
+        };
+        let Some(signed_tx) = DualTableTraverse::<ColdTransactions, _>::exact_dual(
             &mut tx.new_cursor::<ColdTransactions>()?,
             &block,
             &index,
-        )?)
+        )?
+        else {
+            return Ok(None);
+        };
+        let Some(header) =
+            TableTraverse::<ColdHeaders, _>::exact(&mut tx.new_cursor::<ColdHeaders>()?, &block)?
+        else {
+            return Ok(None);
+        };
+        let meta = ConfirmationMeta::new(block, header.hash_slow(), index);
+        Ok(Some(Confirmed::new(signed_tx, meta)))
     }
 
-    fn get_receipt_by_location(
+    fn get_receipt_inner(
         &self,
-        block: BlockNumber,
-        index: u64,
-    ) -> Result<Option<Receipt>, MdbxColdError> {
-        let tx = self.env.tx()?;
-        Ok(DualTableTraverse::<ColdReceipts, _>::exact_dual(
-            &mut tx.new_cursor::<ColdReceipts>()?,
-            &block,
-            &index,
-        )?)
+        spec: ReceiptSpecifier,
+    ) -> Result<Option<Confirmed<Receipt>>, MdbxColdError> {
+        Ok(self.get_receipt_with_context_inner(spec)?.map(|ctx| ctx.receipt))
     }
 
     fn get_zenith_header_by_number(
@@ -374,15 +369,6 @@ impl MdbxColdBackend {
             &current_latest.map_or(block, |prev| prev.max(block)),
         )?;
 
-        let current_earliest: Option<BlockNumber> = TableTraverse::<ColdMetadata, _>::exact(
-            &mut tx.new_cursor::<ColdMetadata>()?,
-            &MetadataKey::EarliestBlock,
-        )?;
-        tx.queue_put::<ColdMetadata>(
-            &MetadataKey::EarliestBlock,
-            &current_earliest.map_or(block, |prev| prev.min(block)),
-        )?;
-
         tx.raw_commit()?;
         Ok(())
     }
@@ -453,44 +439,81 @@ impl MdbxColdBackend {
         tx.raw_commit()?;
         Ok(())
     }
+
+    fn get_receipt_with_context_inner(
+        &self,
+        spec: ReceiptSpecifier,
+    ) -> Result<Option<ReceiptContext>, MdbxColdError> {
+        let tx = self.env.tx()?;
+        let (block, index) = match spec {
+            ReceiptSpecifier::TxHash(h) => {
+                let Some(loc) = TableTraverse::<ColdTxHashIndex, _>::exact(
+                    &mut tx.new_cursor::<ColdTxHashIndex>()?,
+                    &h,
+                )?
+                else {
+                    return Ok(None);
+                };
+                (loc.block, loc.index)
+            }
+            ReceiptSpecifier::BlockAndIndex { block, index } => (block, index),
+        };
+        let Some(header) =
+            TableTraverse::<ColdHeaders, _>::exact(&mut tx.new_cursor::<ColdHeaders>()?, &block)?
+        else {
+            return Ok(None);
+        };
+        let Some(receipt) = DualTableTraverse::<ColdReceipts, _>::exact_dual(
+            &mut tx.new_cursor::<ColdReceipts>()?,
+            &block,
+            &index,
+        )?
+        else {
+            return Ok(None);
+        };
+        let Some(transaction) = DualTableTraverse::<ColdTransactions, _>::exact_dual(
+            &mut tx.new_cursor::<ColdTransactions>()?,
+            &block,
+            &index,
+        )?
+        else {
+            return Ok(None);
+        };
+
+        let prior_cumulative_gas = index
+            .checked_sub(1)
+            .map(|prev| {
+                DualTableTraverse::<ColdReceipts, _>::exact_dual(
+                    &mut tx.new_cursor::<ColdReceipts>()?,
+                    &block,
+                    &prev,
+                )
+            })
+            .transpose()?
+            .flatten()
+            .map(|r: Receipt| r.inner.cumulative_gas_used)
+            .unwrap_or(0);
+
+        let meta = ConfirmationMeta::new(block, header.hash_slow(), index);
+        let confirmed_receipt = Confirmed::new(receipt, meta);
+        Ok(Some(ReceiptContext::new(header, transaction, confirmed_receipt, prior_cumulative_gas)))
+    }
 }
 
 impl ColdStorage for MdbxColdBackend {
     async fn get_header(&self, spec: HeaderSpecifier) -> ColdResult<Option<Header>> {
-        let Some(block_num) = self.resolve_header_spec(spec)? else {
-            return Ok(None);
-        };
-        Ok(self.get_header_by_number(block_num)?)
+        Ok(self.get_header_inner(spec)?)
     }
 
     async fn get_headers(&self, specs: Vec<HeaderSpecifier>) -> ColdResult<Vec<Option<Header>>> {
-        specs
-            .into_iter()
-            .map(|spec| {
-                self.resolve_header_spec(spec)?
-                    .map(|n| self.get_header_by_number(n))
-                    .transpose()
-                    .map(Option::flatten)
-            })
-            .collect::<Result<_, MdbxColdError>>()
-            .map_err(Into::into)
+        Ok(self.get_headers_inner(specs)?)
     }
 
     async fn get_transaction(
         &self,
         spec: TransactionSpecifier,
     ) -> ColdResult<Option<Confirmed<TransactionSigned>>> {
-        let Some((block, index)) = self.resolve_tx_spec(spec)? else {
-            return Ok(None);
-        };
-        let Some(tx) = self.get_transaction_by_location(block, index)? else {
-            return Ok(None);
-        };
-        let Some(header) = self.get_header_by_number(block)? else {
-            return Ok(None);
-        };
-        let meta = ConfirmationMeta::new(block, header.hash_slow(), index);
-        Ok(Some(Confirmed::new(tx, meta)))
+        Ok(self.get_transaction_inner(spec)?)
     }
 
     async fn get_transactions_in_block(
@@ -505,17 +528,7 @@ impl ColdStorage for MdbxColdBackend {
     }
 
     async fn get_receipt(&self, spec: ReceiptSpecifier) -> ColdResult<Option<Confirmed<Receipt>>> {
-        let Some((block, index)) = self.resolve_receipt_spec(spec)? else {
-            return Ok(None);
-        };
-        let Some(receipt) = self.get_receipt_by_location(block, index)? else {
-            return Ok(None);
-        };
-        let Some(header) = self.get_header_by_number(block)? else {
-            return Ok(None);
-        };
-        let meta = ConfirmationMeta::new(block, header.hash_slow(), index);
-        Ok(Some(Confirmed::new(receipt, meta)))
+        Ok(self.get_receipt_inner(spec)?)
     }
 
     async fn get_receipts_in_block(&self, block: BlockNumber) -> ColdResult<Vec<Receipt>> {
@@ -565,6 +578,13 @@ impl ColdStorage for MdbxColdBackend {
         Ok(self.get_metadata(MetadataKey::LatestBlock)?)
     }
 
+    async fn get_receipt_with_context(
+        &self,
+        spec: ReceiptSpecifier,
+    ) -> ColdResult<Option<ReceiptContext>> {
+        Ok(self.get_receipt_with_context_inner(spec)?)
+    }
+
     async fn append_block(&self, data: BlockData) -> ColdResult<()> {
         Ok(self.append_block_inner(data)?)
     }