refactor(vara.eth): introduce typed MB/EB hashes, move MB/BlockPayload to ethexe-common

Move the consensus block envelope `MB` (formerly `ethexe_malachite_core::Block`),
the versioned `BlockPayload`, and the on-disk `CompactMb` shape into
`ethexe_common::malachite` so the executor (`ethexe-compute`, etc.)
can reason about them without depending on the consensus layer.

Type-safe MB / EB hashes:
- `CompactMb { parent: HashOf<MB>, height, payload_hash, reserved }` —
  same shape as `MB` with the opaque payload bytes replaced by the
  payload digest. Renames the legacy `transactions_hash` field.
- `MbMeta::last_advanced_eb: HashOf<EB>`.
- `BlockMeta::{last_committed_mb, last_committed_eb}` typed.
- `DBGlobals::{start_block_hash, latest_prepared_eb_hash,
  latest_finalized_mb_hash, latest_computed_mb_hash}` typed.
- `DBConfig::genesis_block_hash: HashOf<EB>`.
- New `pub type EB = SimpleBlockData` alias + `SimpleBlockData::typed_hash()`
  / `eb_hash_of(H256)` for lifting raw Ethereum block hashes into the typed
  envelope.

`HashOf<T>` SCALE-encodes as a bare 32-byte hash (phantom is `#[codec(skip)]`),
so the on-wire/on-disk byte layout is identical to the previous bare
`H256` columns where these fields used to be plain hashes.

Trait sigs in `MbStorageRO/RW` keep `mb_hash: H256` for now — the gain
from threading `HashOf<MB>` through every storage call site (compute,
cli, consensus, processor, etc.) doesn't justify the cascade right now;
typed wrappers at boundary structs already catch the EB-vs-MB confusion
the refactor was about. Call sites pass `field.inner()` where needed.

Fixes #5507

Author: grishasobol

ethexe/cli/src/commands/check.rs

@@ -163,7 +163,7 @@ impl Checker {
     /// Traverses the persisted block DAG and validates referential integrity.
     async fn integrity_check(&self) -> Result<()> {
         let db = &self.db;
-        let bottom = self.globals.start_block_hash;
+        let bottom = self.globals.start_block_hash.inner();
         let head = self.globals.latest_synced_eb.hash;
 
         let bottom = db
@@ -244,7 +244,7 @@ impl Checker {
     /// Each MB runs against an overlaid DB so writes from the
     /// re-execution don't pollute the on-disk state.
     async fn computation_check(&self) -> Result<()> {
-        let head = self.globals.latest_finalized_mb_hash;
+        let head = self.globals.latest_finalized_mb_hash.inner();
         if head.is_zero() {
             println!("📋 No finalized MB yet — nothing to verify");
             return Ok(());
@@ -337,10 +337,10 @@ impl Checker {
                 pb.inc(1);
             };
 
-            if current_compact_mb.parent == H256::zero() {
+            if current_compact_mb.parent.is_zero() {
                 break;
             }
-            current_mb = current_compact_mb.parent;
+            current_mb = current_compact_mb.parent.inner();
         }
 
         Ok(())

ethexe/cli/src/commands/dump.rs

@@ -76,7 +76,7 @@ impl DumpCommand {
         let db = Database::try_from_raw(raw_db)?;
 
         let block_hash = block_hash.unwrap_or_else(|| {
-            let latest_prepared_block = db.globals().latest_prepared_eb_hash;
+            let latest_prepared_block = db.globals().latest_prepared_eb_hash.inner();
             log::info!(
                 "No block hash provided, using latest committed block: {latest_prepared_block:?}"
             );

ethexe/common/src/db.rs

@@ -4,13 +4,17 @@
 //! Common db types and traits.
 
 use crate::{
-    Address, BlockHeader, CodeBlobInfo, Digest, HashOf, ProgramStates, ProtocolTimelines, Schedule,
-    SimpleBlockData, ValidatorsVec,
+    Address, BlockHeader, CodeBlobInfo, Digest, EB, HashOf, ProgramStates, ProtocolTimelines,
+    Schedule, ValidatorsVec,
     events::BlockEvent,
     gear::StateTransition,
     injected::{InjectedTransaction, Promise, SignedCompactPromise, SignedInjectedTransaction},
-    malachite::Transactions,
+    malachite::{MB, Transactions},
 };
+
+// Re-export so existing `ethexe_common::db::CompactMb` imports keep working
+// — the type itself now lives in `ethexe_common::malachite` alongside `MB`.
+pub use crate::malachite::CompactMb;
 use alloc::{
     collections::{BTreeSet, VecDeque},
     vec::Vec,
@@ -34,9 +38,9 @@ pub struct BlockMeta {
     /// Last committed on-chain batch hash (digest).
     pub last_committed_batch: Option<Digest>,
     /// Last committed MB hash.
-    pub last_committed_mb: Option<H256>,
+    pub last_committed_mb: Option<HashOf<MB>>,
     /// Last committed EB hash.
-    pub last_committed_eb: Option<H256>,
+    pub last_committed_eb: Option<HashOf<EB>>,
     /// Latest era with committed validators.
     pub latest_era_validators_committed: Option<u64>,
 }
@@ -88,8 +92,8 @@ pub trait OnChainStorageRO {
     fn block_synced(&self, block_hash: H256) -> bool;
     fn validators(&self, era_index: u64) -> Option<ValidatorsVec>;
 
-    fn block_simple_data(&self, block_hash: H256) -> Option<SimpleBlockData> {
-        self.block_header(block_hash).map(|header| SimpleBlockData {
+    fn block_simple_data(&self, block_hash: H256) -> Option<EB> {
+        self.block_header(block_hash).map(|header| EB {
             hash: block_hash,
             header,
         })
@@ -129,35 +133,23 @@ pub trait InjectedStorageRW: InjectedStorageRO {
     fn set_compact_promise(&self, promise: &SignedCompactPromise);
 }
 
-/// MB static identity. Keyed by the Blake2b envelope hash; existence implies
-/// the matching `Transactions` blob is in CAS at `transactions_hash`.
-#[derive(
-    Debug, Clone, Copy, Default, Encode, Decode, TypeInfo, PartialEq, Eq, Hash, derive_more::Display,
-)]
-#[display("MB(height {height}, parent {parent}, transactions_hash {transactions_hash})")]
-pub struct CompactMb {
-    pub parent: H256,
-    pub height: u64,
-    pub transactions_hash: H256,
-}
-
 /// MB dynamic state. `last_advanced_eb` is propagated forward at save time
-/// (resets on `AdvanceTillEthereumBlock`); `synced` requires this MB and every
-/// ancestor to be persisted.
+/// (resets on `AdvanceTillEthereumBlock`).
 #[derive(Debug, Clone, Default, Encode, Decode, TypeInfo, PartialEq, Eq, Hash)]
 pub struct MbMeta {
     pub computed: bool,
-    pub last_advanced_eb: H256,
+    pub last_advanced_eb: HashOf<EB>,
 }
 
 #[auto_impl::auto_impl(&, Box)]
 pub trait MbStorageRO {
-    /// Static identity (parent + height + `transactions_hash`).
-    /// Existence implies the matching [`Transactions`] blob is in the
-    /// CAS at `transactions_hash`.
+    /// Static identity (parent + height + `payload_hash`).
+    /// Existence implies the matching application-side [`Transactions`]
+    /// blob is in the CAS at `payload_hash`.
     fn mb_compact_block(&self, mb_hash: H256) -> Option<CompactMb>;
-    /// Read the [`Transactions`] blob from CAS by its content hash.
-    fn transactions(&self, transactions_hash: H256) -> Option<Transactions>;
+    /// Read the application-level [`Transactions`] blob from CAS by
+    /// the same content hash stored in [`CompactMb::payload_hash`].
+    fn transactions(&self, payload_hash: H256) -> Option<Transactions>;
     fn mb_program_states(&self, mb_hash: H256) -> Option<ProgramStates>;
     fn mb_outcome(&self, mb_hash: H256) -> Option<Vec<StateTransition>>;
     fn mb_schedule(&self, mb_hash: H256) -> Option<Schedule>;
@@ -168,7 +160,7 @@ pub trait MbStorageRO {
 pub trait MbStorageRW: MbStorageRO {
     fn set_mb_compact_block(&self, mb_hash: H256, compact: CompactMb);
     /// Write a [`Transactions`] blob into the CAS and return its hash
-    /// (the value stored in [`CompactMb::transactions_hash`]).
+    /// (the value stored in [`CompactMb::payload_hash`]).
     fn set_transactions(&self, transactions: Transactions) -> H256;
     fn set_mb_program_states(&self, mb_hash: H256, program_states: ProgramStates);
     fn set_mb_outcome(&self, mb_hash: H256, outcome: Vec<StateTransition>);
@@ -182,8 +174,8 @@ pub struct PreparedBlockData {
     pub latest_era_with_committed_validators: u64,
     pub codes_queue: VecDeque<CodeId>,
     pub last_committed_batch: Digest,
-    pub last_committed_mb: H256,
-    pub last_committed_eb: H256,
+    pub last_committed_mb: HashOf<MB>,
+    pub last_committed_eb: HashOf<EB>,
 }
 
 #[derive(Debug, Clone, Encode, Decode, TypeInfo, PartialEq, Eq)]
@@ -192,24 +184,24 @@ pub struct DBConfig {
     pub chain_id: u64,
     pub router_address: Address,
     pub timelines: ProtocolTimelines,
-    pub genesis_block_hash: H256,
+    pub genesis_block_hash: HashOf<EB>,
     pub max_validators: u16,
 }
 
 #[derive(Debug, Clone, Encode, Decode, TypeInfo, PartialEq, Eq)]
 pub struct DBGlobals {
-    pub start_block_hash: H256,
-    pub latest_synced_eb: SimpleBlockData,
-    pub latest_prepared_eb_hash: H256,
+    pub start_block_hash: HashOf<EB>,
+    pub latest_synced_eb: EB,
+    pub latest_prepared_eb_hash: HashOf<EB>,
     /// Latest MB BFT-finalized by Malachite. Rows
     /// (`mb_program_states`/`mb_outcome`/`mb_schedule`) may not yet
     /// be persisted — use [`Self::latest_computed_mb_hash`] for any
     /// read that depends on those rows existing.
-    pub latest_finalized_mb_hash: H256,
+    pub latest_finalized_mb_hash: HashOf<MB>,
     /// Latest MB whose per-row state has been written by the compute
     /// pipeline. Trails `latest_finalized_mb_hash` until compute
     /// catches up.
-    pub latest_computed_mb_hash: H256,
+    pub latest_computed_mb_hash: HashOf<MB>,
 }
 
 #[cfg(feature = "std")]
@@ -257,15 +249,17 @@ pub use mock_interfaces::{SetConfig, SetGlobals};
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::malachite::{BlockPayload, Transactions};
+    use crate::malachite::{BlockPayload, MB, Transactions};
     use indoc::formatdoc;
     use scale_info::{PortableRegistry, Registry, meta_type};
     use sha3::{Digest, Sha3_256};
 
     #[test]
     fn ensure_types_unchanged() {
+        // Recomputed by running the test once after the typed-hash + MB
+        // move refactor — see Task 2 (typed MB/EB hashes).
         const EXPECTED_TYPE_INFO_HASH: &str =
-            "7e0ef3b2f5f720c051c6dc3084995abb1cf256e1fa5f0d818f64eaa2c99eae4d";
+            "70489b881e7564a322d1b42766934a3e164c99affbc962f2b8ddd8a42d559499";
 
         let types = [
             meta_type::<BlockMeta>(),
@@ -282,8 +276,9 @@ mod tests {
             meta_type::<StateTransition>(),
             meta_type::<Schedule>(),
             meta_type::<MbMeta>(),
-            meta_type::<CompactMb>(),
+            meta_type::<MB>(),
             meta_type::<BlockPayload>(),
+            meta_type::<CompactMb>(),
             meta_type::<Transactions>(),
             meta_type::<DBConfig>(),
             meta_type::<DBGlobals>(),

ethexe/common/src/hash.rs

@@ -109,6 +109,13 @@ impl<T> HashOf<T> {
         }
     }
 
+    /// True iff this is the zero-byte sentinel hash. Useful where a
+    /// caller treats `H256::zero()` as "no value yet" (genesis pre-MB,
+    /// uninitialised parent links, etc.).
+    pub fn is_zero(&self) -> bool {
+        self.hash.is_zero()
+    }
+
     #[cfg(feature = "mock")]
     pub fn random() -> Self {
         Self {

ethexe/common/src/malachite.rs

@@ -1,26 +1,26 @@
 // Copyright (C) Gear Technologies Inc.
 // SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
 
-//! Application-level block shape produced by the Malachite sequencer
-//! and consumed by the ethexe executor.
-//!
-//! Two layers live here:
+//! Malachite block model shared by the consensus service
+//! (`ethexe-malachite-core`), the consensus glue layer
+//! (`ethexe-malachite`), and the executor (`ethexe-compute`).
 //!
+//! - [`MB`] is the consensus block envelope: `(parent_hash, height,
+//!   payload, reserved)`. Its hash is [`HashOf<MB>`].
 //! - [`BlockPayload`] is the opaque, versioned, size-capped wire
-//!   envelope the consensus engine ships around. The application
-//!   schema — [`Transactions`] (an ordered list of [`Transaction`]s) —
-//!   lives SCALE-encoded inside [`BlockPayload::bytes`].
-//! - Block-level identity (parent linkage, height) lives in
-//!   [`crate::db::CompactMb`], indexed by the consensus block envelope
-//!   hash. The matching [`BlockPayload`] / [`Transactions`] blob is
-//!   stored in the content-addressed half of the ethexe db and
-//!   referenced by `CompactMb::transactions_hash`.
+//!   payload carried by an MB. The application schema
+//!   ([`Transactions`]) lives inside [`BlockPayload::bytes`].
+//! - [`CompactMb`] is `MB` with the payload bytes replaced by
+//!   `payload_hash` — what gets indexed in the ethexe DB once the
+//!   matching [`BlockPayload`] / [`Transactions`] blob is in CAS.
+//! - [`Transactions`] is the application-level ordered list of
+//!   [`Transaction`]s that the executor consumes.
 //!
 //! These types live in `ethexe-common` (rather than inside
 //! `ethexe-malachite`) so `ethexe-processor` can accept them without
 //! depending on the consensus layer.
 
-use crate::injected::SignedInjectedTransaction;
+use crate::{HashOf, injected::SignedInjectedTransaction};
 use alloc::vec::Vec;
 use anyhow::{Result, anyhow};
 use derive_more::{Deref, DerefMut, IntoIterator};
@@ -33,8 +33,8 @@ use scale_info::TypeInfo;
 use serde::{Deserialize, Serialize};
 
 /// Per-block payload size cap: 1000 KiB, leaving headroom under the
-/// 1 MiB engine block ceiling for the consensus block envelope
-/// (parent hash, height, reserved tail) and SCALE framing.
+/// 1 MiB consensus block ceiling for the [`MB`] envelope (parent hash,
+/// height, reserved tail) and SCALE framing.
 pub const MAX_BLOCK_PAYLOAD_BYTES: usize = 1024 * 1000;
 
 /// Current `BlockPayload::version` written by this code path.
@@ -45,14 +45,12 @@ pub const MAX_BLOCK_PAYLOAD_BYTES: usize = 1024 * 1000;
 /// ones.
 pub const BLOCK_PAYLOAD_VERSION: u16 = 0;
 
-/// Versioned, size-capped block payload.
+/// Versioned, size-capped block payload carried by an [`MB`].
 ///
-/// The consensus engine treats `bytes` as an opaque byte string —
-/// the application crate is responsible for the schema (today, a
-/// SCALE-encoded [`Transactions`]). `version` exists so a future
-/// protocol bump can change the `bytes` encoding without breaking the
-/// consensus block wire shape: decoders inspect `version` and
-/// dispatch accordingly.
+/// The consensus service treats `bytes` as opaque. The ethexe
+/// application schema lives inside as a SCALE-encoded [`Transactions`]
+/// — `version` exists so a future protocol bump can change that
+/// encoding without breaking the [`MB`] wire shape.
 #[derive(Clone, Debug, Default, PartialEq, Eq, Encode, Decode, TypeInfo)]
 pub struct BlockPayload {
     pub version: u16,
@@ -73,6 +71,91 @@ impl BlockPayload {
             bytes,
         })
     }
+
+    /// Content-addressed hash of the application bytes (the value
+    /// stored in [`CompactMb::payload_hash`]). The `version` prefix
+    /// deliberately does NOT contribute to the digest: at v0 the
+    /// bytes are SCALE-encoded [`Transactions`], so this hash
+    /// matches the legacy `Transactions`-keyed CAS slot byte-for-byte.
+    pub fn hash(&self) -> H256 {
+        gear_core::utils::hash(self.bytes.as_ref()).into()
+    }
+}
+
+/// Malachite block envelope: opaque versioned payload plus
+/// chain-position fields (parent hash + height) and a [`Self::reserved`]
+/// tail for future protocol extensions.
+///
+/// The block hash ([`Self::hash`]) is [`gear_core::utils::hash`]
+/// (Blake2b-256) over a SCALE-encoded
+/// `(parent_hash, height, payload_hash, reserved)` tuple, where
+/// `payload_hash = BlockPayload::hash()`. Two nodes with the same
+/// envelope content produce the same hash.
+#[derive(Clone, Debug, PartialEq, Eq, Encode, Decode, TypeInfo)]
+pub struct MB {
+    pub parent_hash: HashOf<MB>,
+    pub height: u64,
+    pub payload: BlockPayload,
+    pub reserved: [u8; 64],
+}
+
+impl MB {
+    /// Construct an MB with `reserved` zeroed out.
+    pub fn new(parent_hash: HashOf<MB>, height: u64, payload: BlockPayload) -> Self {
+        Self {
+            parent_hash,
+            height,
+            payload,
+            reserved: [0u8; 64],
+        }
+    }
+
+    /// Compute the canonical [`HashOf<MB>`] for this envelope.
+    pub fn hash(&self) -> HashOf<MB> {
+        let payload_hash = self.payload.hash();
+        let inner = (self.parent_hash, self.height, payload_hash, self.reserved).encode();
+        let raw: H256 = gear_core::utils::hash(&inner).into();
+        // SAFETY: `raw` is the canonical MB envelope digest. Wrapping
+        // it in `HashOf<MB>` is exactly what the constructor exists for.
+        unsafe { HashOf::new(raw) }
+    }
+}
+
+/// MB static identity. Same shape as [`MB`] but with the opaque
+/// payload bytes replaced by `payload_hash`. Existence implies the
+/// matching application-level [`Transactions`] blob is in the
+/// content-addressed half of the ethexe DB at `payload_hash`.
+#[derive(
+    Debug, Clone, Copy, Encode, Decode, TypeInfo, PartialEq, Eq, Hash, derive_more::Display,
+)]
+#[display("MB(height {height}, parent {parent}, payload_hash {payload_hash})")]
+pub struct CompactMb {
+    pub parent: HashOf<MB>,
+    pub height: u64,
+    pub payload_hash: H256,
+    pub reserved: [u8; 64],
+}
+
+impl Default for CompactMb {
+    fn default() -> Self {
+        Self {
+            parent: HashOf::zero(),
+            height: 0,
+            payload_hash: H256::zero(),
+            reserved: [0u8; 64],
+        }
+    }
+}
+
+impl CompactMb {
+    /// Recompute the [`HashOf<MB>`] from this compact record. Matches
+    /// [`MB::hash`] byte-for-byte by construction (same SCALE tuple).
+    pub fn mb_hash(&self) -> HashOf<MB> {
+        let inner = (self.parent, self.height, self.payload_hash, self.reserved).encode();
+        let raw: H256 = gear_core::utils::hash(&inner).into();
+        // SAFETY: identical derivation to `MB::hash`.
+        unsafe { HashOf::new(raw) }
+    }
 }
 
 /// A single transaction in the malachite block.