apollo_storage,starknet_api: add helper to build declared class component hashes for a block (#14460)

Add `get_declared_class_hash_to_component_hashes`, mapping each Cairo 1 class
freshly declared in a block to its contract class component hashes (matching the
OS block input). Classes whose compiled class hash was merely migrated in the
block (declared in an earlier block) are excluded.

The helper takes `impl StateStorageReader + ClassStorageReader` rather than a
concrete transaction. Derive `Eq`/`PartialEq` for `ContractClassComponentHashes`
so the test can assert on the returned map directly.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: yoavGrs

crates/apollo_storage/src/class.rs

@@ -68,16 +68,23 @@
 #[path = "class_test.rs"]
 mod class_test;
 
+use std::collections::HashMap;
+
 use apollo_proc_macros::latency_histogram;
 use starknet_api::block::BlockNumber;
 use starknet_api::core::ClassHash;
 use starknet_api::deprecated_contract_class::ContractClass as DeprecatedContractClass;
-use starknet_api::state::SierraContractClass;
+use starknet_api::state::{ContractClassComponentHashes, SierraContractClass};
 
 use crate::db::table_types::Table;
 use crate::db::RW;
 use crate::mmap_file::LocationInFile;
-use crate::state::{DeclaredClassesTable, DeprecatedDeclaredClassesTable, FileOffsetTable};
+use crate::state::{
+    DeclaredClassesTable,
+    DeprecatedDeclaredClassesTable,
+    FileOffsetTable,
+    StateStorageReader,
+};
 use crate::{
     DbTransaction,
     FileHandlers,
@@ -87,6 +94,7 @@ use crate::{
     StorageError,
     StorageResult,
     StorageTransaction,
+    TransactionKind,
 };
 
 /// Interface for reading data related to classes or deprecated classes.
@@ -205,6 +213,45 @@ impl<T: StorageTransaction> ClassStorageReader for T {
     }
 }
 
+/// Builds the map from each Cairo 1 class hash declared in `block_number` to its contract class
+/// component hashes, matching the `declared_class_hash_to_component_hashes` field of the OS block
+/// input. This excludes classes whose compiled class hash was merely migrated in `block_number`.
+pub fn get_declared_class_hash_to_component_hashes<Mode: TransactionKind>(
+    reader: &(impl StateStorageReader<Mode> + ClassStorageReader),
+    block_number: BlockNumber,
+) -> StorageResult<HashMap<ClassHash, ContractClassComponentHashes>> {
+    let state_diff = reader.get_state_diff(block_number)?.ok_or(StorageError::MissingObject {
+        object_name: "state diff".to_string(),
+        height: block_number,
+    })?;
+    let state_reader = reader.get_state_reader()?;
+
+    let mut declared_sierra_classes = Vec::new();
+    // Read all Sierra classes declared in this block from storage.
+    for class_hash in state_diff.class_hash_to_compiled_class_hash.keys() {
+        // `class_hash_to_compiled_class_hash` merges fresh declarations with migrated classes,
+        // while `declared_classes_block` records each class's original declaration block.
+        // Only classes first declared in this block contribute component hashes.
+        if state_reader.get_class_definition_block_number(class_hash)? != Some(block_number) {
+            // A migrated class that was declared in an earlier block.
+            continue;
+        }
+        let sierra_class = reader.get_class(class_hash)?.ok_or(StorageError::DBInconsistency {
+            msg: format!(
+                "Class {class_hash} is declared in block {} but its Sierra class is missing from \
+                 storage.",
+                block_number.0
+            ),
+        })?;
+        declared_sierra_classes.push((*class_hash, sierra_class));
+    }
+
+    Ok(declared_sierra_classes
+        .into_iter()
+        .map(|(class_hash, sierra_class)| (class_hash, sierra_class.get_component_hashes()))
+        .collect())
+}
+
 impl<T: StorageTransaction<Mode = RW>> ClassStorageWriter for T {
     #[latency_histogram("storage_append_classes_latency_seconds", false)]
     fn append_classes(

crates/apollo_storage/src/class_test.rs

@@ -1,3 +1,5 @@
+use std::collections::HashMap;
+
 use assert_matches::assert_matches;
 use indexmap::indexmap;
 use pretty_assertions::assert_eq;
@@ -9,7 +11,7 @@ use starknet_api::hash::StarkHash;
 use starknet_api::state::{SierraContractClass, StateNumber, ThinStateDiff};
 use starknet_api::test_utils::read_json_file;
 
-use super::{ClassStorageReader, ClassStorageWriter};
+use super::{get_declared_class_hash_to_component_hashes, ClassStorageReader, ClassStorageWriter};
 use crate::state::{StateStorageReader, StateStorageWriter};
 use crate::test_utils::get_test_storage;
 use crate::{MarkerKind, StorageError};
@@ -119,3 +121,62 @@ fn append_deprecated_class_not_in_state_diff() {
         expected_deprecated_class
     );
 }
+
+/// Verifies that `get_declared_class_hash_to_component_hashes` returns the component hashes of
+/// classes freshly declared in a block.
+#[test]
+fn test_declared_class_hash_to_component_hashes() {
+    let class_a = SierraContractClass::default();
+    let class_b: SierraContractClass = read_json_file("class.json");
+    let class_hash_a = ClassHash::default();
+    let class_hash_b = ClassHash(StarkHash::ONE);
+
+    let ((reader, mut writer), _temp_dir) = get_test_storage();
+
+    writer
+        .begin_rw_txn()
+        .unwrap()
+        // Block 0: class A is freshly declared.
+        .append_state_diff(
+            BlockNumber(0),
+            ThinStateDiff {
+                class_hash_to_compiled_class_hash: indexmap! {
+                    class_hash_a => compiled_class_hash!(1_u8),
+                },
+                ..Default::default()
+            },
+        )
+        .unwrap()
+        .append_classes(BlockNumber(0), &[(class_hash_a, &class_a)], &[])
+        .unwrap()
+        // Block 1: class B is freshly declared, while class A's compiled class hash is migrated.
+        .append_state_diff(
+            BlockNumber(1),
+            ThinStateDiff {
+                class_hash_to_compiled_class_hash: indexmap! {
+                    class_hash_a => compiled_class_hash!(2_u8),
+                    class_hash_b => compiled_class_hash!(3_u8),
+                },
+                ..Default::default()
+            },
+        )
+        .unwrap()
+        .append_classes(BlockNumber(1), &[(class_hash_b, &class_b)], &[])
+        .unwrap()
+        .commit()
+        .unwrap();
+
+    let txn = reader.begin_ro_txn().unwrap();
+
+    // Block 0: only the freshly declared class A.
+    assert_eq!(
+        get_declared_class_hash_to_component_hashes(&txn, BlockNumber(0)).unwrap(),
+        HashMap::from([(class_hash_a, class_a.get_component_hashes())]),
+    );
+
+    // Block 1: only the freshly declared class B; the migrated class A is excluded.
+    assert_eq!(
+        get_declared_class_hash_to_component_hashes(&txn, BlockNumber(1)).unwrap(),
+        HashMap::from([(class_hash_b, class_b.get_component_hashes())]),
+    );
+}

crates/starknet_api/src/state.rs

@@ -290,7 +290,7 @@ impl From<FlattenedSierraClass> for SierraContractClass {
     }
 }
 
-#[derive(Clone, Debug, Deserialize)]
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq)]
 pub struct ContractClassComponentHashes {
     pub contract_class_version: Felt,
     pub external_functions_hash: PoseidonHash,