apollo_committer_types: add patricia proofs request and response types

Author: ArielElp

Cargo.lock

@@ -7,6 +7,7 @@ license.workspace = true
 description = "Type definitions and interfaces for the Apollo committer component."
 
 [features]
+os_input = ["starknet_committer/os_input"]
 testing = ["mockall", "tokio"]
 
 [dependencies]
@@ -17,6 +18,7 @@ mockall = { workspace = true, optional = true }
 serde.workspace = true
 starknet_api.workspace = true
 starknet_committer.workspace = true
+starknet-types-core = { workspace = true, features = ["serde"] }
 strum = { workspace = true, features = ["derive"] }
 thiserror.workspace = true
 tokio = { workspace = true, optional = true }

crates/apollo_committer_types/Cargo.toml

@@ -2,6 +2,10 @@ use serde::{Deserialize, Serialize};
 use starknet_api::block::BlockNumber;
 use starknet_api::core::{GlobalRoot, StateDiffCommitment};
 use starknet_api::state::ThinStateDiff;
+#[cfg(feature = "os_input")]
+pub use starknet_committer::block_committer::input::AccessedKeys;
+#[cfg(feature = "os_input")]
+use starknet_committer::patricia_merkle_tree::types::StarknetForestProofs;
 
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct CommitBlockRequest {
@@ -32,3 +36,19 @@ pub enum RevertBlockResponse {
     // Nothing to revert. A future block that has not been committed.
     Uncommitted,
 }
+
+/// Commit a block and return merged Patricia witness proofs for OS input (pre- and post-commit
+/// paths).
+#[cfg(feature = "os_input")]
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ReadPathsAndCommitBlockRequest {
+    pub commit: CommitBlockRequest,
+    pub accessed_keys: AccessedKeys,
+}
+
+#[cfg(feature = "os_input")]
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ReadPathsAndCommitBlockResponse {
+    pub global_root: GlobalRoot,
+    pub patricia_proofs: StarknetForestProofs,
+}

crates/apollo_committer_types/src/committer_types.rs

@@ -48,6 +48,20 @@ pub enum CommitterError {
         calculated_commitment: StateDiffCommitment,
         height: BlockNumber,
     },
+    /// Patricia trie path collection for OS input failed.
+    #[cfg(feature = "os_input")]
+    #[error("Failed Patricia paths collection at block {height}: {message}")]
+    PatriciaPathsCollectionFailed { height: BlockNumber, message: String },
+    /// Stored accessed-keys digest does not match the request (or no digest was stored).
+    #[cfg(feature = "os_input")]
+    #[error(
+        "Accessed-keys digest mismatch at block {height}: expected {expected:?}, stored {stored:?}"
+    )]
+    AccessedKeysDigestMismatch { height: BlockNumber, stored: Option<[u8; 32]>, expected: [u8; 32] },
+    /// Merged Patricia witness paths are missing for replay.
+    #[cfg(feature = "os_input")]
+    #[error("Missing Patricia paths for block {height}")]
+    MissingPatriciaPaths { height: BlockNumber },
 }
 
 pub type CommitterResult<T> = Result<T, CommitterError>;

crates/apollo_committer_types/src/errors.rs

@@ -74,6 +74,15 @@ impl From<u128> for StarknetStorageKey {
 #[derive(Clone, Copy, Default, Debug, Deserialize, Eq, PartialEq, Serialize)]
 pub struct StarknetStorageValue(pub Felt);
 
+/// Trie leaves read during block execution (classes, contracts, and per-contract storage slots).
+#[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
+#[cfg(feature = "os_input")]
+pub struct AccessedKeys {
+    pub class_hashes: Vec<ClassHash>,
+    pub contract_addresses: Vec<ContractAddress>,
+    pub contract_storage_keys: HashMap<ContractAddress, Vec<StarknetStorageKey>>,
+}
+
 #[derive(Clone, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
 pub struct StateDiff {
     pub address_to_class_hash: HashMap<ContractAddress, ClassHash>,

crates/starknet_committer/src/block_committer/input.rs

@@ -117,6 +117,27 @@ impl StarknetForestProofs {
     }
 }
 
+impl serde::Serialize for StarknetForestProofs {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        let encoded = Self::serialize(self).map_err(serde::ser::Error::custom)?;
+        encoded.0.serialize(serializer)
+    }
+}
+
+impl<'de> serde::Deserialize<'de> for StarknetForestProofs {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        use serde::de::Error;
+        let bytes = Vec::<u8>::deserialize(deserializer)?;
+        Self::deserialize(&DbValue(bytes)).map_err(Error::custom)
+    }
+}
+
 fn bincode_ser_err(error: bincode::Error) -> SerializationError {
     SerializationError::IOSerialize(std::io::Error::other(error))
 }

crates/starknet_committer/src/patricia_merkle_tree/starknet_forest_proofs_serde.rs

@@ -36,13 +36,13 @@ pub type ClassesTrie = FilledTreeImpl<CompiledClassHash>;
 pub type ContractsTrie = FilledTreeImpl<ContractState>;
 pub type StorageTrieMap = HashMap<ContractAddress, StorageTrie>;
 
-#[derive(Debug, PartialEq)]
+#[derive(Debug, Clone, PartialEq)]
 pub struct ContractsTrieProof {
     pub nodes: PreimageMap,
     pub leaves: HashMap<ContractAddress, ContractState>,
 }
 
-#[derive(Debug, PartialEq)]
+#[derive(Debug, Clone, PartialEq)]
 pub struct StarknetForestProofs {
     pub classes_trie_proof: PreimageMap,
     pub contracts_trie_proof: ContractsTrieProof,