blockifier: verify that the proof facts block number matches the block hash

meship-starkware · meship-starkware · commit feee81fb167b · 2026-01-12T09:15:08.000+02:00
diff --git a/crates/apollo_consensus_orchestrator/resources/central_invoke_tx_client_side_proving.json b/crates/apollo_consensus_orchestrator/resources/central_invoke_tx_client_side_proving.json
@@ -35,8 +35,8 @@
         "proof_facts": [
             "0x5649525455414c5f534e4f53",
             "0x4",
-            "0x3",
-            "0x2",
+            "0x7a0",
+            "0x2FA80",
             "0x1"
         ],
         "type": "INVOKE_FUNCTION"
diff --git a/crates/apollo_consensus_orchestrator/resources/central_preconfirmed_block.json b/crates/apollo_consensus_orchestrator/resources/central_preconfirmed_block.json
@@ -60,8 +60,8 @@
             "proof_facts": [
                 "0x5649525455414c5f534e4f53",
                 "0x4",
-                "0x3",
-                "0x2",
+                "0x7a0",
+                "0x2FA80",
                 "0x1"
             ],
             "type":"INVOKE_FUNCTION"
diff --git a/crates/apollo_gateway/src/gateway_test.rs b/crates/apollo_gateway/src/gateway_test.rs
@@ -38,6 +38,7 @@ use apollo_network_types::network_types::BroadcastedMessageMetadata;
 use apollo_test_utils::{get_rng, GetTestInstance};
 use blockifier::blockifier::config::ContractClassManagerConfig;
 use blockifier::context::ChainInfo;
+use blockifier::test_utils::block_hash_contract_address;
 use blockifier::test_utils::initial_test_state::fund_account;
 use blockifier_test_utils::cairo_versions::{CairoVersion, RunnableCairo1};
 use blockifier_test_utils::calldata::create_trivial_calldata;
@@ -62,6 +63,7 @@ use starknet_api::test_utils::declare::{
 use starknet_api::test_utils::deploy_account::DeployAccountTxArgs;
 use starknet_api::test_utils::invoke::{executable_invoke_tx, InvokeTxArgs};
 use starknet_api::test_utils::{
+    generate_block_hash_storage_updates,
     valid_resource_bounds_for_testing,
     TestingTxArgs,
     CHAIN_ID_FOR_TESTS,
@@ -276,14 +278,22 @@ async fn setup_mock_state(
 
     setup_transaction_converter_mock(&mut mock_dependencies.mock_transaction_converter, tx_args);
 
+    // Setup state: fund account and store proof block hash if needed.
+    let state_reader =
+        &mut mock_dependencies.state_reader_factory.state_reader.blockifier_state_reader;
     let address = expected_internal_tx.contract_address();
     fund_account(
         &mock_dependencies.config.chain_info,
         address,
         VALID_ACCOUNT_BALANCE,
-        &mut mock_dependencies.state_reader_factory.state_reader.blockifier_state_reader,
+        state_reader,
     );
 
+    let block_hash_to_number_storage = generate_block_hash_storage_updates();
+    for (block_hash, block_number) in block_hash_to_number_storage {
+        state_reader.storage_view.insert((block_hash_contract_address(), block_hash), block_number);
+    }
+
     let mempool_add_tx_args = AddTransactionArgs {
         tx: expected_internal_tx.clone(),
         account_state: AccountState { address, nonce: *input_tx.nonce() },
diff --git a/crates/apollo_http_server/resources/deprecated_gateway/invoke_tx_client_side_proving.json b/crates/apollo_http_server/resources/deprecated_gateway/invoke_tx_client_side_proving.json
@@ -29,8 +29,8 @@
   "proof_facts": [
     "0x5649525455414c5f534e4f53",
     "0x4",
-    "0x3",
-    "0x2",
+    "0x7a0",
+    "0x2FA80",
     "0x1"
   ],
   "proof": [
diff --git a/crates/apollo_starknet_client/resources/reader/invoke_v3_client_side_proving.json b/crates/apollo_starknet_client/resources/reader/invoke_v3_client_side_proving.json
@@ -35,8 +35,8 @@
     "proof_facts": [
         "0x5649525455414c5f534e4f53",
         "0x4",
-        "0x3",
-        "0x2",
+        "0x7a0",
+        "0x2FA80",
         "0x1"
     ]
 }
diff --git a/crates/blockifier/src/test_utils.rs b/crates/blockifier/src/test_utils.rs
@@ -416,3 +416,11 @@ pub fn maybe_dummy_block_hash_and_number(block_number: BlockNumber) -> Option<Bl
         hash: BlockHash(StarkHash::ONE),
     })
 }
+
+/// Returns the contract address for the block hash contract used in tests.
+pub fn block_hash_contract_address() -> ContractAddress {
+    VersionedConstants::create_for_testing()
+        .os_constants
+        .os_contract_addresses
+        .block_hash_contract_address()
+}
diff --git a/crates/blockifier/src/test_utils/initial_test_state.rs b/crates/blockifier/src/test_utils/initial_test_state.rs
@@ -83,6 +83,7 @@ pub fn setup_test_state(
     }
 }
 
+// TODO(Meshi): create a client-side test state.
 pub fn test_state(
     chain_info: &ChainInfo,
     initial_balances: Fee,
diff --git a/crates/blockifier/src/transaction/account_transaction.rs b/crates/blockifier/src/transaction/account_transaction.rs
@@ -1,13 +1,14 @@
 use std::sync::Arc;
 
 use starknet_api::abi::abi_utils::selector_from_name;
-use starknet_api::block::GasPriceVector;
+use starknet_api::block::{BlockNumber, GasPriceVector};
 use starknet_api::calldata;
 use starknet_api::contract_class::EntryPointType;
 use starknet_api::core::{ClassHash, ContractAddress, EntryPointSelector, Nonce};
 use starknet_api::data_availability::DataAvailabilityMode;
 use starknet_api::executable_transaction::{AccountTransaction as Transaction, TransactionType};
 use starknet_api::execution_resources::GasAmount;
+use starknet_api::state::StorageKey;
 use starknet_api::transaction::fields::Resource::{L1DataGas, L1Gas, L2Gas};
 use starknet_api::transaction::fields::{
     AccountDeploymentData,
@@ -24,6 +25,8 @@ use starknet_api::transaction::{constants, TransactionHash, TransactionVersion};
 use starknet_types_core::felt::Felt;
 
 use super::errors::ResourceBoundsError;
+use crate::abi::constants::STORED_BLOCK_HASH_BUFFER;
+use crate::blockifier_versioned_constants::OsConstants;
 use crate::context::{BlockContext, GasCounter, TransactionContext};
 use crate::execution::call_info::CallInfo;
 use crate::execution::common_hints::ExecutionMode;
@@ -246,19 +249,62 @@ impl AccountTransaction {
         }
     }
 
-    fn validate_proof_facts(&self) -> TransactionPreValidationResult<()> {
-        if let Transaction::Invoke(tx) = &self.tx {
-            if tx.tx.version() == TransactionVersion::THREE {
-                let proof_facts_variant = ProofFactsVariant::try_from(&tx.tx.proof_facts())
-                    .map_err(|e| TransactionPreValidationError::InvalidProofFacts(e.to_string()))?;
-                match proof_facts_variant {
-                    ProofFactsVariant::Empty => {}
-                    ProofFactsVariant::Snos(_snos_proof_facts) => {
-                        // TODO(Meshi/ AvivG): add proof facts validations.
-                    }
-                }
-            }
+    fn validate_proof_facts(
+        &self,
+        os_constants: &OsConstants,
+        current_block_number: BlockNumber,
+        state: &mut dyn State,
+    ) -> TransactionPreValidationResult<()> {
+        // Only Invoke V3 transactions can carry proof facts.
+        let Transaction::Invoke(invoke_tx) = &self.tx else {
+            return Ok(());
+        };
+        if invoke_tx.version() < TransactionVersion::THREE {
+            return Ok(());
+        }
+
+        // Parse proof facts.
+        let proof_facts = invoke_tx.proof_facts();
+        let snos_proof_facts = match ProofFactsVariant::try_from(&proof_facts)
+            .map_err(|e| TransactionPreValidationError::InvalidProofFacts(e.to_string()))?
+        {
+            ProofFactsVariant::Empty => return Ok(()),
+            ProofFactsVariant::Snos(snos_proof_facts) => snos_proof_facts,
+        };
+
+        // Proof block must be old enough to have a stored block hash.
+        // Stored block hashes are guaranteed only up to: current - STORED_BLOCK_HASH_BUFFER.
+        let max_allowed = current_block_number.0.saturating_sub(STORED_BLOCK_HASH_BUFFER);
+
+        let proof_block_number = snos_proof_facts.block_number.0;
+        if proof_block_number >= max_allowed {
+            return Err(TransactionPreValidationError::InvalidProofFacts(format!(
+                "The proof block number {proof_block_number} is too recent to have a stored block \
+                 hash. The maximum allowed block number is {max_allowed}. The proof block number \
+                 must be less than the maximum allowed block number."
+            )));
+        }
+
+        // Compare the proof's block hash with the stored block hash.
+        let contract = os_constants.os_contract_addresses.block_hash_contract_address();
+
+        let stored_block_hash =
+            state.get_storage_at(contract, StorageKey::from(proof_block_number))?;
+
+        if stored_block_hash == Felt::ZERO {
+            return Err(TransactionPreValidationError::InvalidProofFacts(format!(
+                "Stored block hash is zero for block {proof_block_number}."
+            )));
         }
+
+        let proof_block_hash = snos_proof_facts.block_hash.0;
+        if stored_block_hash != proof_block_hash {
+            return Err(TransactionPreValidationError::InvalidProofFacts(format!(
+                "Block hash mismatch for block {proof_block_number}. Proof block hash: \
+                 {proof_block_hash}, stored block hash: {stored_block_hash}."
+            )));
+        }
+
         Ok(())
     }
 
@@ -278,7 +324,11 @@ impl AccountTransaction {
             verify_can_pay_committed_bounds(state, tx_context).map_err(Box::new)?;
         }
 
-        self.validate_proof_facts()?;
+        self.validate_proof_facts(
+            &tx_context.block_context.versioned_constants.os_constants,
+            tx_context.block_context.block_info.block_number,
+            state,
+        )?;
 
         Ok(())
     }
diff --git a/crates/starknet_api/resources/transaction_hash.json b/crates/starknet_api/resources/transaction_hash.json
@@ -146,7 +146,13 @@
             "0x78163ce5979e2bc8a944ba353a63c194ca4f63d393bbaaa95857daa9223e93c"
           ],
           "tip": "0x0",
-          "proof_facts": ["0x1", "0x2", "0x3"]
+          "proof_facts": [
+            "0x5649525455414c5f534e4f53",
+            "0x4",
+            "0x7a0",
+            "0x2FA80",
+            "0x1"
+          ]
         }
       }
     },
diff --git a/crates/starknet_api/src/test_utils.rs b/crates/starknet_api/src/test_utils.rs
@@ -1,4 +1,4 @@
-use std::collections::HashMap;
+use std::collections::{hash_map, HashMap};
 use std::fs::File;
 use std::path::{Path, PathBuf};
 use std::sync::LazyLock;
@@ -26,6 +26,7 @@ use crate::deprecated_contract_class::{ContractClass as DeprecatedContractClass,
 use crate::executable_transaction::AccountTransaction;
 use crate::execution_resources::GasAmount;
 use crate::rpc_transaction::{InternalRpcTransaction, RpcTransaction};
+use crate::state::StorageKey;
 use crate::transaction::fields::{
     AllResourceBounds,
     Fee,
@@ -54,6 +55,22 @@ pub const TEST_ERC20_CONTRACT_ADDRESS2: &str = "0x1002";
 pub const CURRENT_BLOCK_NUMBER: u64 = 2001;
 pub const CURRENT_BLOCK_NUMBER_FOR_VALIDATE: u64 = 2000;
 
+// Range of historical blocks to populate in the block hash contract.
+// For block number N, we populate blocks BLOCK_HASH_HISTORY_START to BLOCK_HASH_HISTORY_END.
+// E.g., for block 2001: blocks 1950 to 1990.
+pub const BLOCK_HASH_HISTORY_START: u64 = 1950;
+pub const BLOCK_HASH_HISTORY_END: u64 = 1990;
+
+/// Generates deterministic block hash storage updates for historical blocks.
+/// Populates blocks BLOCK_HASH_HISTORY_START to BLOCK_HASH_HISTORY_END with deterministic hash
+/// values (block_num * 100, i.e., 195000, 195100, ..., 199000).
+pub fn generate_block_hash_storage_updates() -> hash_map::IntoIter<StorageKey, Felt> {
+    (BLOCK_HASH_HISTORY_START..=BLOCK_HASH_HISTORY_END)
+        .map(|block_num| (StorageKey::from(block_num), Felt::from(block_num * 100)))
+        .collect::<HashMap<_, _>>()
+        .into_iter()
+}
+
 // The block timestamp of the BlockContext being used for testing.
 pub const CURRENT_BLOCK_TIMESTAMP: u64 = 1072023;
 pub const CURRENT_BLOCK_TIMESTAMP_FOR_VALIDATE: u64 = 1069200;
@@ -371,12 +388,17 @@ impl ProofFacts {
     ///
     /// See [`crate::transaction::fields::ProofFacts`].
     pub fn snos_proof_facts_for_testing() -> Self {
-        // TODO(AvivG): Change to valid values when available.
         let program_hash = felt!("0x4");
-        let block_number = felt!("0x3");
-        let block_hash = felt!("0x2");
-        let config_hash = felt!("0x1");
 
+        let block_number = felt!(BLOCK_HASH_HISTORY_START + 2);
+        let block_hash = block_number * felt!(100_u64);
+        assert!(
+            block_number <= felt!(BLOCK_HASH_HISTORY_END)
+                && block_number >= felt!(BLOCK_HASH_HISTORY_START),
+            "Block number is out of range"
+        );
+        // TODO(AvivG): Change to valid values when available.
+        let config_hash = felt!("0x1");
         proof_facts![felt!(VIRTUAL_SNOS), program_hash, block_number, block_hash, config_hash]
     }
 }
diff --git a/crates/starknet_os_flow_tests/src/initial_state.rs b/crates/starknet_os_flow_tests/src/initial_state.rs
@@ -1,7 +1,9 @@
 use std::collections::{BTreeMap, HashMap, HashSet};
 
 use blockifier::context::BlockContext;
+use blockifier::state::cached_state::StateMaps;
 use blockifier::state::state_api::UpdatableState;
+use blockifier::test_utils::block_hash_contract_address;
 use blockifier::transaction::transaction_execution::Transaction;
 use blockifier_test_utils::cairo_versions::{CairoVersion, RunnableCairo1};
 use blockifier_test_utils::calldata::create_calldata;
@@ -27,11 +29,20 @@ use starknet_api::hash::{HashOutput, StateRoots};
 use starknet_api::state::{ContractClassComponentHashes, SierraContractClass};
 use starknet_api::test_utils::deploy_account::deploy_account_tx;
 use starknet_api::test_utils::invoke::invoke_tx;
-use starknet_api::test_utils::{NonceManager, CHAIN_ID_FOR_TESTS, CURRENT_BLOCK_NUMBER};
+use starknet_api::test_utils::{
+    generate_block_hash_storage_updates,
+    NonceManager,
+    CHAIN_ID_FOR_TESTS,
+    CURRENT_BLOCK_NUMBER,
+};
 use starknet_api::transaction::constants::DEPLOY_CONTRACT_FUNCTION_ENTRY_POINT_NAME;
 use starknet_api::transaction::fields::{Calldata, ContractAddressSalt, ValidResourceBounds};
 use starknet_api::{calldata, deploy_account_tx_args, invoke_tx_args};
-use starknet_committer::block_committer::input::StateDiff;
+use starknet_committer::block_committer::input::{
+    StarknetStorageKey,
+    StarknetStorageValue,
+    StateDiff,
+};
 use starknet_committer::db::facts_db::db::FactsDb;
 use starknet_patricia_storage::map_storage::MapStorage;
 use starknet_types_core::felt::Felt;
@@ -174,8 +185,26 @@ pub(crate) async fn create_default_initial_state_data<S: FlowTestState, const N:
     );
     final_state.state.apply_writes(&state_diff, &final_state.class_hash_to_class.borrow());
 
-    // Commit the state diff.
-    let committer_state_diff = create_committer_state_diff(state_diff);
+    // Generate block hash storage updates for historical blocks.
+    let block_hash_storage_updates: HashMap<_, _> = generate_block_hash_storage_updates().collect();
+
+    // Commit the state diff with block hash mappings.
+    let mut committer_state_diff = create_committer_state_diff(state_diff);
+    committer_state_diff.storage_updates.entry(block_hash_contract_address()).or_default().extend(
+        block_hash_storage_updates
+            .iter()
+            .map(|(k, v)| (StarknetStorageKey(*k), StarknetStorageValue(*v))),
+    );
+
+    // Also apply block hash storage to the blockifier's cached state.
+    let mut block_hash_state_maps = StateMaps::default();
+    for (key, value) in &block_hash_storage_updates {
+        block_hash_state_maps.storage.insert((block_hash_contract_address(), *key), *value);
+    }
+    final_state
+        .state
+        .apply_writes(&block_hash_state_maps, &final_state.class_hash_to_class.borrow());
+
     let (commitment_output, commitment_storage) =
         commit_initial_state_diff(committer_state_diff).await;
 
diff --git a/crates/starknet_os_flow_tests/src/tests.rs b/crates/starknet_os_flow_tests/src/tests.rs
@@ -1063,11 +1063,14 @@ async fn test_v1_bound_accounts_cairo1() {
 async fn test_new_class_execution_info(#[values(true, false)] use_kzg_da: bool) {
     let test_contract = FeatureContract::TestContract(CairoVersion::Cairo1(RunnableCairo1::Casm));
     let test_class_hash = get_class_hash_of_feature_contract(test_contract);
+    // Create proof facts before creating the test builder, so it can set up the initial state.
+    let proof_facts = ProofFacts::snos_proof_facts_for_testing();
     let (mut test_builder, [main_contract_address]) = TestBuilder::create_standard_with_config(
         [(test_contract, calldata![Felt::ZERO, Felt::ZERO])],
         TestBuilderConfig { use_kzg_da, ..Default::default() },
     )
     .await;
+
     let chain_id = &test_builder.chain_id();
     let current_block_number = test_builder.first_block_number();
 
@@ -1081,7 +1084,6 @@ async fn test_new_class_execution_info(#[values(true, false)] use_kzg_da: bool)
     let test_execution_info_selector_name = "test_get_execution_info";
     let test_execution_info_selector = selector_from_name(test_execution_info_selector_name);
     let only_query = false;
-    let proof_facts = ProofFacts::snos_proof_facts_for_testing();
     let expected_execution_info = ExpectedExecutionInfo::new(
         only_query,
         *FUNDED_ACCOUNT_ADDRESS,
@@ -1104,7 +1106,7 @@ async fn test_new_class_execution_info(#[values(true, false)] use_kzg_da: bool)
             main_contract_address, test_execution_info_selector_name, &expected_execution_info
         ),
         resource_bounds: *NON_TRIVIAL_RESOURCE_BOUNDS,
-        proof_facts,
+        proof_facts: proof_facts.clone(),
     };
     // Put the tx hash in the signature.
     let tx = InvokeTransaction::create(invoke_tx(invoke_tx_args.clone()), chain_id).unwrap();

Original file line number	Diff line number	Diff line change
`@@ -35,8 +35,8 @@`
`35`	`35`	`"proof_facts": [`
`36`	`36`	`"0x5649525455414c5f534e4f53",`
`37`	`37`	`"0x4",`
`38`		`- "0x3",`
`39`		`- "0x2",`
	`38`	`+ "0x7a0",`
	`39`	`+ "0x2FA80",`
`40`	`40`	`"0x1"`
`41`	`41`	`]`
`42`	`42`	`}`
Original file line number	Diff line number	Diff line change
`@@ -83,6 +83,7 @@ pub fn setup_test_state(`
`83`	`83`	`}`
`84`	`84`	`}`
`85`	`85`
	`86`	`+// TODO(Meshi): create a client-side test state.`
`86`	`87`	`pub fn test_state(`
`87`	`88`	`chain_info: &ChainInfo,`
`88`	`89`	`initial_balances: Fee,`