zksync_vm2/
lib.rs

1//! # High-Performance ZKsync Era VM
2//!
3//! This crate provides high-performance [`VirtualMachine`] for ZKsync Era.
4
5use std::hash::{DefaultHasher, Hash, Hasher};
6
7use primitive_types::{H160, U256};
8pub use zksync_vm2_interface as interface;
9use zksync_vm2_interface::Tracer;
10
11// Re-export missing modules if single instruction testing is enabled
12#[cfg(feature = "single_instruction_test")]
13pub(crate) use self::single_instruction_test::{heap, program, stack};
14pub use self::{
15    fat_pointer::FatPointer,
16    instruction::{ExecutionEnd, Instruction},
17    mode_requirements::ModeRequirements,
18    predication::Predicate,
19    program::Program,
20    vm::{Settings, VirtualMachine},
21    world_diff::{Snapshot, StorageChange, WorldDiff},
22};
23use crate::precompiles::{LegacyPrecompiles, Precompiles};
24
25pub mod addressing_modes;
26#[cfg(not(feature = "single_instruction_test"))]
27mod bitset;
28mod callframe;
29mod decode;
30mod decommit;
31mod fat_pointer;
32#[cfg(not(feature = "single_instruction_test"))]
33mod heap;
34mod instruction;
35mod instruction_handlers;
36mod mode_requirements;
37mod page_ids;
38pub mod precompiles;
39mod predication;
40#[cfg(not(feature = "single_instruction_test"))]
41mod program;
42mod rollback;
43#[cfg(feature = "single_instruction_test")]
44pub mod single_instruction_test;
45#[cfg(not(feature = "single_instruction_test"))]
46mod stack;
47mod state;
48pub mod testonly;
49#[cfg(all(test, not(feature = "single_instruction_test")))]
50mod tests;
51mod tracing;
52mod vm;
53mod world_diff;
54
55/// Storage slot information returned from [`StorageInterface::read_storage()`].
56#[derive(Debug, Clone, Copy)]
57pub struct StorageSlot {
58    /// Value of the storage slot.
59    pub value: U256,
60    /// Whether a write to the slot would be considered an initial write. This influences refunds.
61    pub is_write_initial: bool,
62}
63
64impl StorageSlot {
65    /// Represents an empty storage slot.
66    pub const EMPTY: Self = Self {
67        value: U256([0; 4]),
68        is_write_initial: true,
69    };
70}
71
72/// VM storage access operations.
73pub trait StorageInterface {
74    /// Reads the specified slot from the storage.
75    ///
76    /// There is no write counterpart; [`WorldDiff::get_storage_changes()`] gives a list of all storage changes.
77    fn read_storage(&mut self, contract: H160, key: U256) -> StorageSlot;
78
79    /// Same as [`Self::read_storage()`], but doesn't request the initialness flag for the read slot.
80    ///
81    /// The default implementation uses `read_storage()`.
82    fn read_storage_value(&mut self, contract: H160, key: U256) -> U256 {
83        self.read_storage(contract, key).value
84    }
85
86    /// Computes the cost of writing a storage slot.
87    fn cost_of_writing_storage(&mut self, initial_slot: StorageSlot, new_value: U256) -> u32;
88
89    /// Returns if the storage slot is free both in terms of gas and pubdata.
90    fn is_free_storage_slot(&self, contract: &H160, key: &U256) -> bool;
91}
92
93/// Encapsulates VM interaction with the external world. This includes VM storage and decomitting (loading) bytecodes
94/// for execution.
95pub trait World<T: Tracer>: StorageInterface + Sized {
96    /// Loads a bytecode with the specified hash.
97    ///
98    /// This method will be called *every* time a contract is called. Caching and decoding is
99    /// the world implementor's job.
100    fn decommit(&mut self, hash: U256) -> Program<T, Self>;
101
102    /// Loads bytecode bytes for the `decommit` opcode.
103    fn decommit_code(&mut self, hash: U256) -> Vec<u8>;
104
105    /// Returns precompiles to be used.
106    fn precompiles(&self) -> &impl Precompiles {
107        &LegacyPrecompiles
108    }
109}
110
111/// Deterministic (across program runs and machines) hash that can be used for `Debug` implementations
112/// to concisely represent large amounts of data.
113#[cfg_attr(feature = "single_instruction_test", allow(dead_code))] // Currently used entirely in types overridden by `single_instruction_test` feature
114pub(crate) fn hash_for_debugging(value: &impl Hash) -> u64 {
115    let mut hasher = DefaultHasher::new();
116    value.hash(&mut hasher);
117    hasher.finish()
118}
zksync_vm2/lib.rs

zksync_vm2/
lib.rs
