refactor(cold): remove metadata table and consolidate SQL queries (#22)

The metadata table only tracked latest_block, which is trivially
derivable from the headers table. Remove it from all three backends
(in-memory, MDBX, SQL) and derive get_latest_block from headers
directly.

Additionally consolidate SQL queries in the cold-sql backend:
- get_transaction: use JOINs to fetch tx + block_hash in one query
- get_receipt: use JOINs to fetch receipt + block_hash in one query
- get_receipts_in_block: fix N+1 by batch-fetching all logs for a
  block instead of per-receipt
- Remove 5 dead helper methods made redundant by the consolidation

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

Author: prestwich

crates/cold-mdbx/src/backend.rs

@@ -5,8 +5,8 @@
 //! database environment from `signet-hot-mdbx`.
 
 use crate::{
-    ColdBlockHashIndex, ColdHeaders, ColdMetadata, ColdReceipts, ColdSignetEvents,
-    ColdTransactions, ColdTxHashIndex, ColdZenithHeaders, MdbxColdError, MetadataKey,
+    ColdBlockHashIndex, ColdHeaders, ColdReceipts, ColdSignetEvents, ColdTransactions,
+    ColdTxHashIndex, ColdZenithHeaders, MdbxColdError,
 };
 use alloy::{consensus::Header, primitives::BlockNumber};
 use signet_cold::{
@@ -92,12 +92,6 @@ impl MdbxColdBackend {
                 ColdTxHashIndex::FIXED_VAL_SIZE,
                 ColdTxHashIndex::INT_KEY,
             ),
-            (
-                ColdMetadata::NAME,
-                ColdMetadata::DUAL_KEY_SIZE,
-                ColdMetadata::FIXED_VAL_SIZE,
-                ColdMetadata::INT_KEY,
-            ),
             (
                 ColdTransactions::NAME,
                 ColdTransactions::DUAL_KEY_SIZE,
@@ -124,11 +118,6 @@ impl MdbxColdBackend {
         Ok(())
     }
 
-    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_header_inner(&self, spec: HeaderSpecifier) -> Result<Option<Header>, MdbxColdError> {
         let tx = self.env.tx()?;
         let block_num = match spec {
@@ -359,16 +348,6 @@ impl MdbxColdBackend {
             tx.queue_put::<ColdZenithHeaders>(&block, zh)?;
         }
 
-        // Update block bounds
-        let current_latest: Option<BlockNumber> = TableTraverse::<ColdMetadata, _>::exact(
-            &mut tx.new_cursor::<ColdMetadata>()?,
-            &MetadataKey::LatestBlock,
-        )?;
-        tx.queue_put::<ColdMetadata>(
-            &MetadataKey::LatestBlock,
-            &current_latest.map_or(block, |prev| prev.max(block)),
-        )?;
-
         tx.raw_commit()?;
         Ok(())
     }
@@ -420,22 +399,6 @@ impl MdbxColdBackend {
             tx.queue_delete::<ColdZenithHeaders>(block_num)?;
         }
 
-        // Update latest block
-        {
-            let mut cursor = tx.new_cursor::<ColdHeaders>()?;
-            match KvTraverse::<_>::last(&mut cursor)? {
-                Some((key, _)) => {
-                    tx.queue_put::<ColdMetadata>(
-                        &MetadataKey::LatestBlock,
-                        &BlockNumber::decode_key(&key)?,
-                    )?;
-                }
-                None => {
-                    tx.queue_delete::<ColdMetadata>(&MetadataKey::LatestBlock)?;
-                }
-            }
-        }
-
         tx.raw_commit()?;
         Ok(())
     }
@@ -575,7 +538,14 @@ impl ColdStorage for MdbxColdBackend {
     }
 
     async fn get_latest_block(&self) -> ColdResult<Option<BlockNumber>> {
-        Ok(self.get_metadata(MetadataKey::LatestBlock)?)
+        let tx = self.env.tx().map_err(MdbxColdError::from)?;
+        let mut cursor = tx.new_cursor::<ColdHeaders>().map_err(MdbxColdError::from)?;
+        let latest = KvTraverse::<_>::last(&mut cursor)
+            .map_err(MdbxColdError::from)?
+            .map(|(key, _)| BlockNumber::decode_key(&key))
+            .transpose()
+            .map_err(MdbxColdError::from)?;
+        Ok(latest)
     }
 
     async fn get_receipt_with_context(

crates/cold-mdbx/src/lib.rs

@@ -16,10 +16,6 @@
 //! - [`ColdBlockHashIndex`]: Maps block hash to block number.
 //! - [`ColdTxHashIndex`]: Maps transaction hash to (block number, tx index).
 //!
-//! ## Metadata Tables
-//!
-//! - [`ColdMetadata`]: Storage metadata (latest block, finalized, safe, earliest).
-//!
 //! # Feature Flags
 //!
 //! - **`test-utils`**: Propagates `signet-cold/test-utils` for conformance
@@ -42,8 +38,8 @@ pub use error::MdbxColdError;
 
 mod tables;
 pub use tables::{
-    ColdBlockHashIndex, ColdHeaders, ColdMetadata, ColdReceipts, ColdSignetEvents,
-    ColdTransactions, ColdTxHashIndex, ColdZenithHeaders, MetadataKey,
+    ColdBlockHashIndex, ColdHeaders, ColdReceipts, ColdSignetEvents, ColdTransactions,
+    ColdTxHashIndex, ColdZenithHeaders,
 };
 
 mod backend;

crates/cold-mdbx/src/tables.rs

@@ -4,52 +4,10 @@
 //! the [`Table`], [`SingleKey`], and [`DualKey`] traits.
 
 use alloy::{consensus::Header, primitives::B256, primitives::BlockNumber};
-use signet_hot::ser::{DeserError, KeySer, MAX_KEY_SIZE};
+use signet_hot::ser::KeySer;
 use signet_hot::tables::{DualKey, SingleKey, Table};
 use signet_storage_types::{DbSignetEvent, DbZenithHeader, Receipt, TransactionSigned, TxLocation};
 
-// ============================================================================
-// Metadata Key Enum
-// ============================================================================
-
-/// Keys for the cold storage metadata table.
-///
-/// These are used to store semantic block references like "latest" or
-/// "finalized" that need to be resolved to actual block numbers.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
-#[repr(u8)]
-pub enum MetadataKey {
-    /// The latest (most recent) block number stored.
-    LatestBlock = 0,
-}
-
-impl TryFrom<u8> for MetadataKey {
-    type Error = DeserError;
-
-    fn try_from(value: u8) -> Result<Self, Self::Error> {
-        match value {
-            0 => Ok(Self::LatestBlock),
-            _ => Err(DeserError::String(format!("Invalid MetadataKey value: {}", value))),
-        }
-    }
-}
-
-impl KeySer for MetadataKey {
-    const SIZE: usize = 1;
-
-    fn encode_key<'a: 'c, 'b: 'c, 'c>(&'a self, buf: &'b mut [u8; MAX_KEY_SIZE]) -> &'c [u8] {
-        buf[0] = *self as u8;
-        &buf[..1]
-    }
-
-    fn decode_key(data: &[u8]) -> Result<Self, DeserError> {
-        if data.is_empty() {
-            return Err(DeserError::InsufficientData { needed: 1, available: 0 });
-        }
-        MetadataKey::try_from(data[0])
-    }
-}
-
 // ============================================================================
 // Primary Data Tables
 // ============================================================================
@@ -189,24 +147,6 @@ impl Table for ColdTxHashIndex {
 
 impl SingleKey for ColdTxHashIndex {}
 
-// ============================================================================
-// Metadata Table
-// ============================================================================
-
-/// Cold storage metadata.
-///
-/// Keys: `LatestBlock(0)`
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
-pub struct ColdMetadata;
-
-impl Table for ColdMetadata {
-    const NAME: &'static str = "ColdMetadata";
-    type Key = MetadataKey;
-    type Value = BlockNumber;
-}
-
-impl SingleKey for ColdMetadata {}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -220,7 +160,6 @@ mod tests {
         assert_eq!(ColdZenithHeaders::NAME, "ColdZenithHeaders");
         assert_eq!(ColdBlockHashIndex::NAME, "ColdBlockHashIndex");
         assert_eq!(ColdTxHashIndex::NAME, "ColdTxHashIndex");
-        assert_eq!(ColdMetadata::NAME, "ColdMetadata");
     }
 
     #[test]
@@ -232,7 +171,6 @@ mod tests {
         assert_single_key::<ColdZenithHeaders>();
         assert_single_key::<ColdBlockHashIndex>();
         assert_single_key::<ColdTxHashIndex>();
-        assert_single_key::<ColdMetadata>();
     }
 
     #[test]
@@ -257,7 +195,6 @@ mod tests {
         // Non-int_key tables should have INT_KEY = false
         const { assert!(!ColdBlockHashIndex::INT_KEY) };
         const { assert!(!ColdTxHashIndex::INT_KEY) };
-        const { assert!(!ColdMetadata::INT_KEY) };
     }
 
     #[test]
@@ -268,28 +205,8 @@ mod tests {
         // ColdBlockHashIndex has BlockNumber (u64) = 8 bytes
         assert_eq!(ColdBlockHashIndex::FIXED_VAL_SIZE, Some(8));
 
-        // ColdMetadata also has BlockNumber (u64) = 8 bytes
-        assert_eq!(ColdMetadata::FIXED_VAL_SIZE, Some(8));
-
         // Variable-size value tables should not have fixed value size
         assert_eq!(ColdHeaders::FIXED_VAL_SIZE, None);
         assert_eq!(ColdZenithHeaders::FIXED_VAL_SIZE, None);
     }
-
-    #[test]
-    fn test_metadata_key_try_from() {
-        assert_eq!(MetadataKey::try_from(0).unwrap(), MetadataKey::LatestBlock);
-        assert!(MetadataKey::try_from(1).is_err());
-        assert!(MetadataKey::try_from(255).is_err());
-    }
-
-    #[test]
-    fn test_metadata_key_ser_roundtrip() {
-        let mut buf = [0u8; MAX_KEY_SIZE];
-        let encoded = MetadataKey::LatestBlock.encode_key(&mut buf);
-        assert_eq!(encoded.len(), 1);
-
-        let decoded = MetadataKey::decode_key(encoded).unwrap();
-        assert_eq!(MetadataKey::LatestBlock, decoded);
-    }
 }

crates/cold-sql/migrations/001_initial.sql

@@ -108,8 +108,3 @@ CREATE TABLE IF NOT EXISTS zenith_headers (
     reward_address            BLOB NOT NULL,
     block_data_hash           BLOB NOT NULL
 );
-
-CREATE TABLE IF NOT EXISTS metadata (
-    key                       TEXT PRIMARY KEY NOT NULL,
-    block_number              INTEGER NOT NULL
-);

crates/cold-sql/migrations/001_initial_pg.sql

@@ -106,8 +106,3 @@ CREATE TABLE IF NOT EXISTS zenith_headers (
     reward_address            BYTEA NOT NULL,
     block_data_hash           BYTEA NOT NULL
 );
-
-CREATE TABLE IF NOT EXISTS metadata (
-    key                       TEXT PRIMARY KEY NOT NULL,
-    block_number              BIGINT NOT NULL
-);