Merge pull request #78 from bitfinity-network/evm_state_recovery_api

[EPROD-564] EVMc state recovery API

Author: F3kilo

Cargo.toml

@@ -61,6 +61,7 @@ sha3 = "0.10"
 thiserror = "1.0"
 tokio = { version = "1.24", features = ["macros", "rt"] }
 zip = "0.6"
+murmur3 = "0.5"
 alloy-primitives = { version = "0.4", default-features = false }
 
 [profile.dev]

src/did/Cargo.toml

@@ -33,6 +33,7 @@ sha3 = { workspace = true }
 thiserror = { workspace = true }
 once_cell = { workspace = true }
 alloy-primitives = { workspace = true }
+murmur3 = { workspace = true }
 
 [dev-dependencies]
 eth-signer = { path = "../eth-signer" }

src/did/src/lib.rs

@@ -15,14 +15,14 @@ pub mod integer;
 pub mod keccak;
 pub mod mint_order_exemption;
 pub mod notify;
+pub mod state;
 pub mod transaction;
 
 pub mod fees;
 #[cfg(test)]
 mod test_utils;
 
 pub use block::Block;
-use candid::{CandidType, Deserialize};
 pub use error::{ExitFatal, HaltError};
 pub use fees::FeeHistory;
 pub use gas::*;
@@ -33,11 +33,3 @@ pub use notify::NotificationInput;
 pub use transaction::{BlockNumber, Transaction, TransactionReceipt};
 
 pub use crate::bytes::Bytes;
-
-#[derive(Clone, Debug, Default, Deserialize, PartialEq, Eq, CandidType)]
-pub struct BasicAccount {
-    /// Account balance.
-    pub balance: U256,
-    /// Account nonce.
-    pub nonce: U256,
-}

src/did/src/state.rs

@@ -0,0 +1,100 @@
+use std::borrow::Cow;
+use std::io::Cursor;
+use std::{fmt, mem};
+
+use candid::CandidType;
+use ic_stable_structures::{Bound, Storable};
+use serde::{Deserialize, Serialize};
+
+use crate::codec::ByteChunkReader;
+use crate::U256;
+
+/// Describes basic state of an EVM account.
+#[derive(Clone, Debug, Default, Deserialize, PartialEq, Eq, CandidType)]
+pub struct BasicAccount {
+    /// Account balance.
+    pub balance: U256,
+    /// Account nonce.
+    pub nonce: U256,
+}
+
+/// Action to update key-value state
+#[derive(Debug, CandidType, Deserialize, Clone)]
+pub enum StateUpdateAction<K, V> {
+    Removed { key: K },
+    Replace { key: K, value: V },
+}
+
+/// StableDBStorage indices information
+#[derive(Debug, Clone, Serialize, CandidType, Deserialize, Eq, PartialEq)]
+pub struct Indices {
+    /// Index of the current block
+    pub pending_block: u64,
+    /// Number of block to keep history
+    pub history_size: u64,
+}
+
+impl Indices {
+    const STORABLE_BYTE_SIZE: usize = mem::size_of::<u64>() * 2;
+}
+
+impl Storable for Indices {
+    fn to_bytes(&self) -> std::borrow::Cow<[u8]> {
+        let mut buf = Vec::with_capacity(Self::STORABLE_BYTE_SIZE);
+        buf.extend_from_slice(&self.pending_block.to_be_bytes());
+        buf.extend_from_slice(&self.history_size.to_be_bytes());
+        buf.into()
+    }
+
+    fn from_bytes(bytes: Cow<'_, [u8]>) -> Self {
+        let mut reader = ByteChunkReader::new(&bytes);
+        let pending_block = u64::from_be_bytes(*reader.read_slice());
+        let history_size = u64::from_be_bytes(*reader.read_slice());
+        Self {
+            pending_block,
+            history_size,
+        }
+    }
+
+    const BOUND: Bound = Bound::Bounded {
+        max_size: Self::STORABLE_BYTE_SIZE as _,
+        is_fixed_size: true,
+    };
+}
+
+/// Full information about entry
+#[derive(Clone, CandidType, Deserialize)]
+pub struct FullStorageValue {
+    /// Data
+    pub data: Vec<u8>,
+    /// Number of inserts subtracted by number of removals.
+    /// May be zero for the values which were removed in past before the moment they are cleaned.
+    pub ref_count: u32,
+    /// Index of the block when the item was removed last time (ref counter set to zeo)
+    pub removed_at_block: u64,
+}
+
+impl fmt::Debug for FullStorageValue {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("FullStorageValue")
+            .field("data_len", &self.data.len())
+            .field("ref_count", &self.ref_count)
+            .field("removed_at_block", &self.removed_at_block)
+            .finish()
+    }
+}
+
+impl FullStorageValue {
+    pub fn hash(&self) -> u128 {
+        let mut all_data = Vec::with_capacity(
+            self.data.len()
+                + mem::size_of_val(&self.ref_count)
+                + mem::size_of_val(&self.removed_at_block),
+        );
+        all_data.extend(&self.data);
+        all_data.extend(self.ref_count.to_le_bytes());
+        all_data.extend(self.removed_at_block.to_le_bytes());
+
+        murmur3::murmur3_x86_128(&mut Cursor::new(&all_data), 0).expect("should calculate hash")
+    }
+}

src/evm-canister-client/src/client.rs

@@ -1,15 +1,16 @@
 use candid::Principal;
 use did::block::{BlockResult, ExeResult};
 use did::error::Result;
+use did::state::{BasicAccount, FullStorageValue, Indices, StateUpdateAction};
 use did::{
-    BasicAccount, Block, BlockNumber, Bytes, EstimateGasRequest, Transaction, TransactionReceipt,
-    H160, H256, U256,
+    Block, BlockNumber, Bytes, EstimateGasRequest, Transaction, TransactionReceipt, H160, H256,
+    U256,
 };
 use ic_canister_client::{CanisterClient, CanisterClientResult};
 
 use crate::EvmResult;
 
-type BlockWithData = Vec<(Block<H256>, Vec<(Transaction, ExeResult)>)>;
+pub type BlockWithData = Vec<(Block<H256>, Vec<(Transaction, ExeResult)>)>;
 
 /// An EVM canister client.
 #[derive(Debug)]
@@ -455,6 +456,129 @@ impl<C: CanisterClient> EvmCanisterClient<C> {
             .await
     }
 
+    /// Returns requested part of low-level representation of EVM state.
+    /// Supports pagination.
+    ///
+    /// # Arguments
+    ///
+    /// * `prev_key` - returned keys will be `key > prev_key` if provided.
+    /// * `limit` - maximum number of keys to return.
+    ///
+    /// # Returns
+    ///
+    /// - Vector of ordered pairs `(storage_key, storage_value_hash)` with `len <= limit`.
+    /// - First `storage_key > prev_key` if `prev_key` is `Some(_)`.
+    ///
+    /// # Errors
+    ///
+    /// - If evm-canister not disabled, returns `EvmError::Internal(msg)`;
+    /// - If caller have not `Permission::UpdateBlockchain` permission, returns `EvmError::Unauthorized`;
+    pub async fn get_state_storage_item_hashes(
+        &self,
+        prev_key: Option<H256>,
+        limit: u32,
+    ) -> CanisterClientResult<EvmResult<Vec<(H256, u128)>>> {
+        self.client
+            .query("get_state_storage_item_hashes", (prev_key, limit))
+            .await
+    }
+
+    /// Applies the given list of low-level state changes.
+    ///
+    /// # Arguments
+    ///
+    /// * `actions` - list of operations should be applied.
+    ///
+    /// # Errors
+    ///
+    /// - If evm-canister not disabled, returns `EvmError::Internal(msg)`;
+    /// - If caller have not `Permission::UpdateBlockchain` permission, returns `EvmError::Unauthorized`;
+    pub async fn apply_state_storage_changes(
+        &self,
+        actions: Vec<StateUpdateAction<H256, FullStorageValue>>,
+    ) -> CanisterClientResult<EvmResult<()>> {
+        self.client
+            .update("apply_state_storage_changes", (actions,))
+            .await
+    }
+
+    /// Returns requested part of low-level representation of EVM clear info.
+    /// Supports pagination.
+    ///
+    /// # Arguments
+    ///
+    /// * `prev_key` - returned keys will be `key > prev_key` if provided.
+    /// * `limit` - maximum number of keys to return.
+    ///
+    /// # Returns
+    ///
+    /// - Vector of ordered pairs `(key_1, key_2)` with `len <= limit`.
+    /// - First pair `(key_1, key_2) > prev_key` if `prev_key` is `Some(_)`.
+    ///
+    /// # Errors
+    ///
+    /// - If evm-canister not disabled, returns `EvmError::Internal(msg)`;
+    /// - If caller have not `Permission::UpdateBlockchain` permission, returns `EvmError::Unauthorized`;
+    pub async fn get_clear_info_entries(
+        &self,
+        prev_key: Option<(u64, H256)>,
+        limit: u32,
+    ) -> CanisterClientResult<EvmResult<Vec<(u64, H256)>>> {
+        self.client
+            .query("get_clear_info_entries", (prev_key, limit))
+            .await
+    }
+
+    /// Applies the given list of low-level clear info changes.
+    ///
+    /// # Arguments
+    ///
+    /// * `actions` - list of operations should be applied.
+    ///
+    /// # Errors
+    ///
+    /// - If evm-canister not disabled, returns `EvmError::Internal(msg)`;
+    /// - If caller have not `Permission::UpdateBlockchain` permission, returns `EvmError::Unauthorized`;
+    pub async fn apply_clear_info_changes(
+        &self,
+        actions: Vec<StateUpdateAction<(u64, H256), ()>>,
+    ) -> CanisterClientResult<EvmResult<()>> {
+        self.client
+            .update("apply_clear_info_changes", (actions,))
+            .await
+    }
+
+    /// Sets low-level storage indices.
+    ///
+    /// # Arguments
+    ///
+    /// * `indices` - indices to set.
+    ///
+    /// # Errors
+    ///
+    /// - If evm-canister not disabled, returns `EvmError::Internal(msg)`;
+    /// - If caller have not `Permission::UpdateBlockchain` permission, returns `EvmError::Unauthorized`;
+    pub async fn set_storage_indices(
+        &self,
+        indices: Indices,
+    ) -> CanisterClientResult<EvmResult<()>> {
+        self.client.update("set_storage_indices", (indices,)).await
+    }
+
+    /// Sets state root hash.
+    ///
+    /// # Arguments
+    ///
+    /// * `root` - root to set.
+    ///
+    /// # Errors
+    ///
+    /// - If evm-canister not disabled, returns `EvmError::Internal(msg)`;
+    /// - If caller have not `Permission::UpdateBlockchain` permission, returns `EvmError::Unauthorized`;
+    pub async fn set_state_root(&self, root: H256) -> CanisterClientResult<EvmResult<()>> {
+        self.client.update("set_state_root", (root,)).await
+    }
+
     /// Updates the runtime configuration of the logger with a new filter in the same form as the `RUST_LOG`
     /// environment variable.
     /// Example of valid filters: