refactor: Brush up repo for publishing (pt. 2) (#59)

# What ❔

Continues brushing up the repo.

- Makes VM state types private and somewhat extends `StateInterface` to
compensate.
- Adds some doc comments (more to be added separately).

## Why ❔

Minimizes the API surface of the VM crate so that it's easier to
maintain.

README.md

@@ -1,6 +1,8 @@
-# High-Performance ZKsync Era VM
+# High-Performance ZKsync Era VM (EraVM)
 
-A high-performance rewrite of the out-of-circuit VM for ZKsync Era.
+A high-performance rewrite of the out-of-circuit VM for ZKsync Era (aka EraVM).
+
+See [Era docs](https://github.com/matter-labs/zksync-era/tree/main/docs/specs/zk_evm) for the VM overview and formal specification.
 
 ## Overview
 

crates/vm2-interface/README.md

@@ -1,6 +1,6 @@
 # Stable Interface for ZKsync Era VM
 
-This library provides a stable interface for the EraVM. It defines an interface for tracers that will never change but may be extended.
+This library provides a stable interface for EraVM. It defines an interface for tracers that will never change but may be extended.
 
 ## License
 

crates/vm2-interface/src/state_interface.rs

@@ -10,7 +10,12 @@ pub trait StateInterface {
     fn callframe(&mut self, n: usize) -> impl CallframeInterface + '_;
 
     fn read_heap_byte(&self, heap: HeapId, index: u32) -> u8;
-    fn write_heap_byte(&mut self, heap: HeapId, index: u32, byte: u8);
+    /// Reads an entire `U256` word in the big-endian order from the specified heap page / `index`
+    /// (which is the index of the most significant byte of the read value).
+    fn read_heap_u256(&self, heap: HeapId, index: u32) -> U256;
+    /// Writes an entire `U256` word in the big-endian order to the specified heap page at the specified `index`
+    /// (which is the index of the most significant byte of the written value).
+    fn write_heap_u256(&mut self, heap: HeapId, index: u32, value: U256);
 
     fn flags(&self) -> Flags;
     fn set_flags(&mut self, flags: Flags);
@@ -55,6 +60,7 @@ pub trait CallframeInterface {
     fn set_program_counter(&mut self, value: u16);
 
     fn exception_handler(&self) -> u16;
+    fn set_exception_handler(&mut self, value: u16);
 
     fn is_static(&self) -> bool;
     fn is_kernel(&self) -> bool;
@@ -85,16 +91,25 @@ pub trait CallframeInterface {
     fn read_code_page(&self, slot: u16) -> U256;
 }
 
+/// Identifier of a VM heap page.
 #[derive(Copy, Clone, PartialEq, Debug)]
 pub struct HeapId(u32);
 
 impl HeapId {
+    /// Identifier of the calldata heap page used by the first executed program (i.e., the bootloader).
+    pub const FIRST_CALLDATA: Self = Self(1);
+    /// Identifier of the heap page used by the first executed program (i.e., the bootloader).
+    pub const FIRST: Self = Self(2);
+    /// Identifier of the auxiliary heap page used by the first executed program (i.e., the bootloader)
+    pub const FIRST_AUX: Self = Self(3);
+
     /// Only for dealing with external data structures, never use internally.
+    #[doc(hidden)]
     pub const fn from_u32_unchecked(value: u32) -> Self {
         Self(value)
     }
 
-    pub const fn to_u32(self) -> u32 {
+    pub const fn as_u32(self) -> u32 {
         self.0
     }
 }
@@ -125,11 +140,11 @@ pub struct DummyState;
 
 #[cfg(test)]
 impl StateInterface for DummyState {
-    fn read_register(&self, _: u8) -> (primitive_types::U256, bool) {
+    fn read_register(&self, _: u8) -> (U256, bool) {
         unimplemented!()
     }
 
-    fn set_register(&mut self, _: u8, _: primitive_types::U256, _: bool) {
+    fn set_register(&mut self, _: u8, _: U256, _: bool) {
         unimplemented!()
     }
 
@@ -141,23 +156,27 @@ impl StateInterface for DummyState {
         unimplemented!()
     }
 
-    fn callframe(&mut self, _: usize) -> impl crate::CallframeInterface + '_ {
+    fn callframe(&mut self, _: usize) -> impl CallframeInterface + '_ {
         DummyState
     }
 
-    fn read_heap_byte(&self, _: crate::HeapId, _: u32) -> u8 {
+    fn read_heap_byte(&self, _: HeapId, _: u32) -> u8 {
+        unimplemented!()
+    }
+
+    fn read_heap_u256(&self, _: HeapId, _: u32) -> U256 {
         unimplemented!()
     }
 
-    fn write_heap_byte(&mut self, _: crate::HeapId, _: u32, _: u8) {
+    fn write_heap_u256(&mut self, _: HeapId, _: u32, _: U256) {
         unimplemented!()
     }
 
-    fn flags(&self) -> crate::Flags {
+    fn flags(&self) -> Flags {
         unimplemented!()
     }
 
-    fn set_flags(&mut self, _: crate::Flags) {
+    fn set_flags(&mut self, _: Flags) {
         unimplemented!()
     }
 
@@ -177,42 +196,19 @@ impl StateInterface for DummyState {
         unimplemented!()
     }
 
-    fn get_storage_state(
-        &self,
-    ) -> impl Iterator<
-        Item = (
-            (primitive_types::H160, primitive_types::U256),
-            primitive_types::U256,
-        ),
-    > {
+    fn get_storage_state(&self) -> impl Iterator<Item = ((H160, U256), U256)> {
         std::iter::empty()
     }
 
-    fn get_transient_storage_state(
-        &self,
-    ) -> impl Iterator<
-        Item = (
-            (primitive_types::H160, primitive_types::U256),
-            primitive_types::U256,
-        ),
-    > {
+    fn get_transient_storage_state(&self) -> impl Iterator<Item = ((H160, U256), U256)> {
         std::iter::empty()
     }
 
-    fn get_transient_storage(
-        &self,
-        _: primitive_types::H160,
-        _: primitive_types::U256,
-    ) -> primitive_types::U256 {
+    fn get_transient_storage(&self, _: H160, _: U256) -> U256 {
         unimplemented!()
     }
 
-    fn write_transient_storage(
-        &mut self,
-        _: primitive_types::H160,
-        _: primitive_types::U256,
-        _: primitive_types::U256,
-    ) {
+    fn write_transient_storage(&mut self, _: H160, _: U256, _: U256) {
         unimplemented!()
     }
 
@@ -235,27 +231,27 @@ impl StateInterface for DummyState {
 
 #[cfg(test)]
 impl CallframeInterface for DummyState {
-    fn address(&self) -> primitive_types::H160 {
+    fn address(&self) -> H160 {
         unimplemented!()
     }
 
-    fn set_address(&mut self, _: primitive_types::H160) {
+    fn set_address(&mut self, _: H160) {
         unimplemented!()
     }
 
-    fn code_address(&self) -> primitive_types::H160 {
+    fn code_address(&self) -> H160 {
         unimplemented!()
     }
 
-    fn set_code_address(&mut self, _: primitive_types::H160) {
+    fn set_code_address(&mut self, _: H160) {
         unimplemented!()
     }
 
-    fn caller(&self) -> primitive_types::H160 {
+    fn caller(&self) -> H160 {
         unimplemented!()
     }
 
-    fn set_caller(&mut self, _: primitive_types::H160) {
+    fn set_caller(&mut self, _: H160) {
         unimplemented!()
     }
 
@@ -271,6 +267,10 @@ impl CallframeInterface for DummyState {
         unimplemented!()
     }
 
+    fn set_exception_handler(&mut self, _: u16) {
+        unimplemented!()
+    }
+
     fn is_static(&self) -> bool {
         unimplemented!()
     }
@@ -303,11 +303,11 @@ impl CallframeInterface for DummyState {
         unimplemented!()
     }
 
-    fn read_stack(&self, _: u16) -> (primitive_types::U256, bool) {
+    fn read_stack(&self, _: u16) -> (U256, bool) {
         unimplemented!()
     }
 
-    fn write_stack(&mut self, _: u16, _: primitive_types::U256, _: bool) {
+    fn write_stack(&mut self, _: u16, _: U256, _: bool) {
         unimplemented!()
     }
 
@@ -343,7 +343,7 @@ impl CallframeInterface for DummyState {
         unimplemented!()
     }
 
-    fn read_code_page(&self, _: u16) -> primitive_types::U256 {
+    fn read_code_page(&self, _: u16) -> U256 {
         unimplemented!()
     }
 }