Add CHKHISTPROOF TVM instruction for layer hash verification

New instruction (opcode 0xC7 0x51) verifies that a key block's common
section at a specified layer stores a particular layer hash value.
Takes 3 stack args: hash (256-bit), block_height (u64), layer_number (u8).
Returns boolean. Uses callback pattern for verification logic.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: alinaT95

tvm_assembler/src/simple.rs

@@ -861,6 +861,7 @@ impl Engine {
         CALCMINERTAPCOEF                     => 0xC7, 0x47
         CALCMINERREWARD                      => 0xC7, 0x48
         POSEIDON                             => 0xC7, 0x50
+        CHKHISTPROOF                         => 0xC7, 0x51
     }
 
     fn add_commands<'a>(

tvm_executor/src/transaction_executor.rs

@@ -149,6 +149,8 @@ pub struct ExecuteParams {
     pub wasm_component_cache: HashMap<[u8; 32], wasmtime::component::Component>,
     pub mvconfig: MVConfig,
     pub engine_version: semver::Version,
+    pub check_history_proof_hash:
+        Option<Arc<dyn Send + Sync + Fn(u64, u8, [u8; 32]) -> bool>>,
 }
 
 pub struct ActionPhaseResult {
@@ -202,6 +204,7 @@ impl Default for ExecuteParams {
             wasm_component_cache: HashMap::new(),
             mvconfig: MVConfig::default(),
             engine_version: "1.0.0".parse().unwrap(),
+            check_history_proof_hash: None,
         }
     }
 }
@@ -600,6 +603,8 @@ pub trait TransactionExecutor {
         };
 
         vm_setup = vm_setup.set_dapp_id(params.dapp_id.clone());
+        vm_setup =
+            vm_setup.set_check_history_proof_hash(params.check_history_proof_hash.clone());
 
         let mut vm = vm_setup.create();
 

tvm_executor/src/vmsetup.rs

@@ -55,6 +55,8 @@ pub struct VMSetup {
     block_collation_was_finished: Arc<Mutex<bool>>,
     termination_deadline: Option<Instant>,
     execution_timeout: Option<Duration>,
+    check_history_proof_hash:
+        Option<Arc<dyn Send + Sync + Fn(u64, u8, [u8; 32]) -> bool>>,
 }
 
 impl VMSetup {
@@ -83,6 +85,7 @@ impl VMSetup {
             block_collation_was_finished: Arc::new(Mutex::new(false)),
             termination_deadline: None,
             execution_timeout: None,
+            check_history_proof_hash: None,
         }
     }
 
@@ -199,6 +202,15 @@ impl VMSetup {
         self
     }
 
+    /// Sets check_history_proof_hash callback
+    pub fn set_check_history_proof_hash(
+        mut self,
+        callback: Option<Arc<dyn Send + Sync + Fn(u64, u8, [u8; 32]) -> bool>>,
+    ) -> VMSetup {
+        self.check_history_proof_hash = callback;
+        self
+    }
+
     /// Sets account dapp_id
     pub fn set_dapp_id(mut self, dapp_id: Option<UInt256>) -> VMSetup {
         self.vm.set_dapp_id(dapp_id);
@@ -267,6 +279,9 @@ impl VMSetup {
         );
         vm.set_termination_deadline(self.termination_deadline);
         vm.set_execution_timeout(self.execution_timeout);
+        if let Some(callback) = self.check_history_proof_hash {
+            vm.set_check_history_proof_hash(callback);
+        }
         vm
     }
 }

tvm_vm/src/executor/chk_hist_proof.rs

@@ -0,0 +1,41 @@
+// CHKHISTPROOF TVM instruction — verifies that a key block's common section
+// at a specified layer stores a particular layer hash value.
+//
+// Stack: hash (256-bit) | block_height (u64) | layer_number (u8, 1..=10)
+// Result: pushes boolean (-1 true, 0 false)
+
+use crate::executor::Engine;
+use crate::executor::engine::storage::fetch_stack;
+use crate::executor::gas::gas_state::Gas;
+use crate::stack::StackItem;
+use crate::stack::integer::IntegerData;
+use crate::stack::integer::serialization::UnsignedIntegerBigEndianEncoding;
+use crate::types::Status;
+
+pub const CHKHISTPROOF_GAS_PRICE: i64 = 100;
+
+pub(super) fn execute_chk_hist_proof(engine: &mut Engine) -> Status {
+    engine.mark_execution_as_block_related()?;
+    engine.load_instruction(crate::executor::types::Instruction::new("CHKHISTPROOF"))?;
+    engine.try_use_gas(Gas::chkhistproof_price())?;
+    fetch_stack(engine, 3)?;
+
+    // Stack order: var(0)=top=layer_number, var(1)=block_height, var(2)=hash
+    let layer_number: u8 = engine.cmd.var(0).as_integer()?.into(1..=10)?;
+    let block_height: u64 = engine.cmd.var(1).as_integer()?.into(0..=u64::MAX)?;
+    let hash_builder = engine
+        .cmd
+        .var(2)
+        .as_integer()?
+        .as_builder::<UnsignedIntegerBigEndianEncoding>(256)?;
+    let mut hash_bytes = [0u8; 32];
+    hash_bytes.copy_from_slice(hash_builder.data());
+
+    let result = match &engine.check_history_proof_hash {
+        Some(callback) => callback(block_height, layer_number, hash_bytes),
+        None => false,
+    };
+
+    engine.cc.stack.push(boolean!(result));
+    Ok(())
+}

tvm_vm/src/executor/engine/core.rs

@@ -153,6 +153,9 @@ pub struct Engine {
     engine_version: semver::Version,
 
     pub(in crate::executor) self_dapp_id: Option<UInt256>,
+
+    pub(in crate::executor) check_history_proof_hash:
+        Option<Arc<dyn Send + Sync + Fn(u64, u8, [u8; 32]) -> bool>>,
 }
 
 #[cfg(feature = "signature_no_check")]
@@ -327,6 +330,7 @@ impl Engine {
             self_dapp_id: None,
             mvconfig: MVConfig::default(),
             engine_version: "1.0.0".parse().unwrap(),
+            check_history_proof_hash: None,
         }
     }
 
@@ -504,6 +508,13 @@ impl Engine {
         self.self_dapp_id = dapp_id;
     }
 
+    pub fn set_check_history_proof_hash(
+        &mut self,
+        callback: Arc<dyn Send + Sync + Fn(u64, u8, [u8; 32]) -> bool>,
+    ) {
+        self.check_history_proof_hash = Some(callback);
+    }
+
     #[cfg(feature = "wasmtime")]
     pub fn extern_wasm_engine_init() -> Result<wasmtime::Engine> {
         log::debug!("Extern Initialising Wasm Engine");

tvm_vm/src/executor/engine/handlers.rs

@@ -43,6 +43,7 @@ use crate::executor::token::*;
 use crate::executor::tuple::*;
 use crate::executor::types::Instruction;
 use crate::executor::types::InstructionOptions;
+use crate::executor::chk_hist_proof::execute_chk_hist_proof;
 use crate::executor::zk::*;
 use crate::executor::zk_halo2::*;
 use crate::stack::integer::behavior::Quiet;
@@ -408,7 +409,8 @@ impl Handlers {
                 .set(0x46, execute_calculate_mbk)
                 .set(0x47, execute_calculate_miner_tap_coef)
                 .set(0x48, execute_calculate_miner_reward)
-                .set(0x49, execute_halo2_proof_verification);
+                .set(0x49, execute_halo2_proof_verification)
+                .set(0x51, execute_chk_hist_proof);
             // Pre-build VK + KZG params in background so the first
             // ZKHALO2VERIFY call doesn't block for seconds.
             crate::executor::zk_halo2::warmup_halo2();

tvm_vm/src/executor/gas/gas_state.rs

@@ -17,6 +17,7 @@ use tvm_types::error;
 use tvm_types::types::ExceptionCode;
 
 use crate::error::TvmError;
+use crate::executor::chk_hist_proof::CHKHISTPROOF_GAS_PRICE;
 use crate::executor::zk::POSEIDON_ZK_LOGIN_GAS_PRICE;
 use crate::executor::zk::VERGRTH16_GAS_PRICE;
 use crate::types::Exception;
@@ -213,6 +214,15 @@ impl Gas {
         self.use_gas(VERGRTH16_GAS_PRICE)
     }
 
+    /// Compute CHKHISTPROOF usage cost
+    pub const fn chkhistproof_price() -> i64 {
+        CHKHISTPROOF_GAS_PRICE
+    }
+
+    pub fn consume_chkhistproof(&mut self) -> i64 {
+        self.use_gas(CHKHISTPROOF_GAS_PRICE)
+    }
+
     #[cfg(feature = "gosh")]
     /// line cost for diff
     pub fn diff_fee_for_line(lines_first_file: usize, lines_second_file: usize) -> i64 {

tvm_vm/src/executor/mod.rs

@@ -65,6 +65,10 @@ mod test_vergrth_bad_args;
 #[path = "../tests/test_poseidon_bad_args.rs"]
 mod test_poseidon_bad_args;
 
+#[cfg(test)]
+#[path = "../tests/test_chk_hist_proof.rs"]
+mod test_chk_hist_proof;
+
 #[cfg(test)]
 #[path = "../tests/test_executor.rs"]
 mod tests;
@@ -75,6 +79,7 @@ mod test_data;
 #[path = "../tests/test_helper.rs"]
 mod test_helper;
 
+pub mod chk_hist_proof;
 pub mod zk;
 
 pub mod zk_halo2;

tvm_vm/src/tests/test_chk_hist_proof.rs

@@ -0,0 +1,133 @@
+use std::sync::Arc;
+
+use tvm_types::SliceData;
+
+use crate::executor::engine::Engine;
+use crate::executor::test_helper::*;
+use crate::executor::chk_hist_proof::execute_chk_hist_proof;
+use crate::stack::Stack;
+use crate::stack::StackItem;
+use crate::stack::integer::IntegerData;
+use crate::stack::savelist::SaveList;
+
+fn setup_engine() -> Engine {
+    let elector_code = load_boc("benches/elector-code.boc");
+    let elector_data = load_boc("benches/elector-data.boc");
+    let config_data = load_boc("benches/config-data.boc");
+    let mut ctrls = SaveList::default();
+    ctrls.put(4, &mut StackItem::Cell(elector_data)).unwrap();
+    let params = vec![
+        StackItem::int(0x76ef1ea),
+        StackItem::int(0),
+        StackItem::int(0),
+        StackItem::int(1633458077),
+        StackItem::int(0),
+        StackItem::int(0),
+        StackItem::int(0),
+        StackItem::tuple(vec![StackItem::int(1000000000), StackItem::None]),
+        StackItem::slice(
+            SliceData::from_string(
+                "9fe0000000000000000000000000000000000000000000000000000000000000001_",
+            )
+            .unwrap(),
+        ),
+        StackItem::cell(config_data.reference(0).unwrap()),
+        StackItem::None,
+        StackItem::int(0),
+    ];
+    ctrls.put(7, &mut StackItem::tuple(vec![StackItem::tuple(params)])).unwrap();
+    let stack = Stack::new();
+    Engine::with_capabilities(DEFAULT_CAPABILITIES).setup_with_libraries(
+        SliceData::load_cell_ref(&elector_code).unwrap(),
+        Some(ctrls),
+        Some(stack),
+        None,
+        vec![],
+    )
+}
+
+fn make_hash_bytes() -> [u8; 32] {
+    let mut hash = [0u8; 32];
+    for i in 0..32 {
+        hash[i] = (i + 1) as u8;
+    }
+    hash
+}
+
+fn push_chk_hist_proof_args(engine: &mut Engine, hash: &[u8; 32], block_height: u64, layer: i32) {
+    // Push in order: hash (bottom), block_height, layer_number (top)
+    engine
+        .cc
+        .stack
+        .push(StackItem::integer(IntegerData::from_unsigned_bytes_be(hash)));
+    engine.cc.stack.push(StackItem::int(block_height));
+    engine.cc.stack.push(StackItem::int(layer));
+}
+
+#[test]
+fn test_chk_hist_proof_callback_returns_true() {
+    let mut engine = setup_engine();
+    let hash = make_hash_bytes();
+    let expected_hash = hash;
+
+    engine.set_check_history_proof_hash(Arc::new(move |block_height, layer_number, h| {
+        block_height == 42 && layer_number == 3 && h == expected_hash
+    }));
+
+    push_chk_hist_proof_args(&mut engine, &hash, 42, 3);
+    execute_chk_hist_proof(&mut engine).unwrap();
+
+    let result = engine.cc.stack.get(0).as_bool().unwrap();
+    assert!(result, "Expected true (-1) when callback matches");
+}
+
+#[test]
+fn test_chk_hist_proof_callback_returns_false() {
+    let mut engine = setup_engine();
+    let hash = make_hash_bytes();
+
+    engine.set_check_history_proof_hash(Arc::new(move |_block_height, _layer_number, _h| false));
+
+    push_chk_hist_proof_args(&mut engine, &hash, 100, 5);
+    execute_chk_hist_proof(&mut engine).unwrap();
+
+    let result = engine.cc.stack.get(0).as_bool().unwrap();
+    assert!(!result, "Expected false (0) when callback returns false");
+}
+
+#[test]
+fn test_chk_hist_proof_no_callback() {
+    let mut engine = setup_engine();
+    let hash = make_hash_bytes();
+    // No callback set — should return false
+
+    push_chk_hist_proof_args(&mut engine, &hash, 42, 3);
+    execute_chk_hist_proof(&mut engine).unwrap();
+
+    let result = engine.cc.stack.get(0).as_bool().unwrap();
+    assert!(!result, "Expected false (0) when no callback is set");
+}
+
+#[test]
+fn test_chk_hist_proof_layer_zero_range_error() {
+    let mut engine = setup_engine();
+    let hash = make_hash_bytes();
+
+    engine.set_check_history_proof_hash(Arc::new(move |_, _, _| true));
+
+    push_chk_hist_proof_args(&mut engine, &hash, 42, 0);
+    let result = execute_chk_hist_proof(&mut engine);
+    assert!(result.is_err(), "layer_number=0 should cause RangeCheckError");
+}
+
+#[test]
+fn test_chk_hist_proof_layer_eleven_range_error() {
+    let mut engine = setup_engine();
+    let hash = make_hash_bytes();
+
+    engine.set_check_history_proof_hash(Arc::new(move |_, _, _| true));
+
+    push_chk_hist_proof_args(&mut engine, &hash, 42, 11);
+    let result = execute_chk_hist_proof(&mut engine);
+    assert!(result.is_err(), "layer_number=11 should cause RangeCheckError");
+}