feat: Brush up repo for publishing (#58)

# What ❔

Starts brushing up the repo for publishing:

- Better structures the repo directories.
- Renames crates in a uniform way + uses workspace dependencies.
- Structures imports using well-defined configuration.
- Reduces visibility of some items.
- Adds more crate metadata, e.g. licenses and readmes.

## Why ❔

Part of preparations for publishing the library crates.

.github/workflows/ci.yml

@@ -22,31 +22,46 @@ jobs:
     steps:
       - uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
 
-      - name: Install stable toolchain
-        uses: actions-rs/toolchain@v1
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@master
         with:
           toolchain: stable
-          override: true
+          components: rustfmt, clippy, rust-src
 
       - name: Rust Cache
         uses: Swatinem/rust-cache@v2
 
+      - name: Install cargo-afl
+        run: cargo install cargo-afl --version=^0.15 --force
+
       - name: Build project
         run: |
-          cargo build
+          # AFL fuzzing requires a separate command
+          cargo build --workspace --all-targets --exclude zksync_vm2_afl_fuzz
+
+      - name: Build fuzzer
+        run: cargo afl build -p zksync_vm2_afl_fuzz
 
       # Two runs are needed. One for normal VM, another for the mocked version
       - name: Run clippy
         run: |
           # Check the main library with non-test features (needs to be tested in isolation since the fuzzing crate enables test features)
-          cargo clippy -p vm2 --all-targets -- -D warnings
+          cargo clippy -p zksync_vm2 --all-targets -- -D warnings
           # The benches in `vm2` don't compile with fuzzing enabled 
           cargo clippy --workspace --all-features --lib --bins --tests -- -D warnings
 
       - name: Check formatting
         run: |
-          cargo fmt --check
+          cargo fmt --check -- --config imports_granularity=Crate --config group_imports=StdExternalCrate
+
+      - name: Run tests
+        run: |
+          cargo test -p zksync_vm2_interface -p zksync_vm2 --all-targets
+
+      - name: Run doc tests
+        run: cargo test --workspace --doc
 
-      - name: Run Tests
+      - name: Run fuzzer for a bit
         run: |
-          cargo test -p vm2 --all-targets
+          AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES=1 \
+          cargo afl fuzz -i tests/afl-fuzz/in -o tests/afl-fuzz/out -V 60 target/debug/zksync_vm2_afl_fuzz

Cargo.toml

@@ -1,40 +1,40 @@
-[package]
-name = "vm2"
+[workspace]
+members = [
+    # Main published library crates
+    "crates/vm2-interface",
+    "crates/vm2",
+    # Testing crates
+    "tests/afl-fuzz"
+]
+resolver = "2"
+
+[workspace.package]
 version = "0.1.0"
-edition.workspace = true
+edition = "2021"
+authors = ["The Matter Labs Team <[email protected]>"]
 homepage = "https://zksync.io/"
-license.workspace = true
-authors.workspace = true
-
-[dependencies]
-eravm-stable-interface = { path = "./eravm-stable-interface" }
-zkevm_opcode_defs = "0.150.0"
-zk_evm_abstractions = "0.150.0"
-u256 = { package = "primitive-types", version = "0.12.1" }
-enum_dispatch = "0.3"
-
-# Optional dependencies (used for fuzzing)
-arbitrary = { version = "1", features = ["derive"], optional = true }
-# The commit incorporates a fix necessary for fuzzing to work correctly.
-zk_evm = { git = "https://github.com/matter-labs/era-zk_evm.git", rev = "b7caa02acc2119b2994730d92c8cb6b861f56484", optional = true }
-anyhow = { version = "1", optional = true }
+repository = "https://github.com/matter-labs/vm2"
+license = "MIT OR Apache-2.0"
+keywords = ["blockchain", "zksync"]
+categories = ["cryptography"]
 
-[dev-dependencies]
+[workspace.dependencies]
+# "External" dependencies
+afl = "0.15"
+anyhow = "1"
+arbitrary = "1"
 divan = "0.1"
+enum_dispatch = "0.3"
+pretty_assertions = "1.4.0"
+primitive-types = "0.12.1"
 proptest = "1.4"
 
-[[bench]]
-name = "nested_near_call"
-harness = false
-
-[features]
-default = []
-single_instruction_test = ["arbitrary", "u256/arbitrary", "zk_evm", "anyhow"]
-
-[workspace]
-members = [".", "afl-fuzz", "eravm-stable-interface"]
+# "Internal" dependencies
+zkevm_opcode_defs = "0.150.0"
+zk_evm_abstractions = "0.150.0"
+# The commit incorporates a fix necessary for fuzzing to work correctly.
+zk_evm = { git = "https://github.com/matter-labs/era-zk_evm.git", rev = "b7caa02acc2119b2994730d92c8cb6b861f56484" }
 
-[workspace.package]
-edition = "2021"
-license = "MIT OR Apache-2.0"
-authors = ["The Matter Labs Team <[email protected]>"]
+# Dependencies within the workspace
+zksync_vm2_interface = { version = "0.1.0", path = "crates/vm2-interface" }
+zksync_vm2 = { version = "0.1.0", path = "crates/vm2" }

README.md

@@ -1,3 +1,25 @@
-# zksync-era-vm2
+# High-Performance ZKsync Era VM
 
-A high-performance rewrite of the zksync-era VM.
+A high-performance rewrite of the out-of-circuit VM for ZKsync Era.
+
+## Overview
+
+This repository contains the following crates:
+
+- [`zksync_vm2_interface`](crates/vm2-interface): stable VM interface for tracers
+- [`zksync_vm2`](crates/vm2): VM implementation itself
+- [`zksync_vm2_afl_fuzz`](tests/afl-fuzz): [AFL](https://crates.io/crates/afl)-based fuzzing for the VM.
+
+## Policies
+
+- [Security policy](SECURITY.md)
+- [Contribution policy](CONTRIBUTING.md)
+
+## License
+
+ZKsync Era VM is distributed under the terms of either
+
+- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/blog/license/mit/>)
+
+at your option.

crates/vm2-interface/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "zksync_vm2_interface"
+description = "Stable interface for ZKsync VM tracers"
+readme = "README.md"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+homepage.workspace = true
+repository.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+primitive-types.workspace = true

crates/vm2-interface/LICENSE-APACHE

@@ -0,0 +1 @@
+../../LICENSE-APACHE

crates/vm2-interface/LICENSE-MIT

@@ -0,0 +1 @@
+../../LICENSE-MIT

crates/vm2-interface/README.md

@@ -0,0 +1,12 @@
+# 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.
+
+## License
+
+ZKsync Era VM is distributed under the terms of either
+
+- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/blog/license/mit/>)
+
+at your option.

eravm-stable-interface/src/lib.rs → crates/vm2-interface/src/lib.rs

@@ -6,7 +6,7 @@
 //! not necessary. In fact, tracers should depend on the oldest version that has the required
 //! features.
 //!
-//! A struct implementing [Tracer] may read and mutate the VM's state via [StateInterface]
+//! A struct implementing [`Tracer`] may read and mutate the VM's state via [`StateInterface`]
 //! when particular opcodes are executed.
 //!
 //! ## Why is extreme backwards compatibility required here?
@@ -23,9 +23,12 @@
 //! version that you publish and import it from the previous version instead.
 //!
 //! This is how you would add a new method to StateInterface and a new opcode.
+//!
 //! ```
-//! # use eravm_stable_interface as eravm_stable_interface_v1;
-//! use eravm_stable_interface_v1::{StateInterface as StateInterfaceV1, Tracer as TracerV1, opcodes::NearCall};
+//! # use zksync_vm2_interface as zksync_vm2_interface_v1;
+//! use zksync_vm2_interface_v1::{
+//!     StateInterface as StateInterfaceV1, Tracer as TracerV1, opcodes::NearCall,
+//! };
 //!
 //! trait StateInterface: StateInterfaceV1 {
 //!     fn get_some_new_field(&self) -> u32;
@@ -82,7 +85,7 @@
 //! }
 //! ```
 
+pub use self::{state_interface::*, tracer_interface::*};
+
 mod state_interface;
 mod tracer_interface;
-pub use state_interface::*;
-pub use tracer_interface::*;

eravm-stable-interface/src/tracer_interface.rs → crates/vm2-interface/src/tracer_interface.rs

@@ -53,9 +53,10 @@ macro_rules! pub_struct {
 }
 
 pub mod opcodes {
-    use super::{CallingMode, ReturnType};
     use std::marker::PhantomData;
 
+    use super::{CallingMode, ReturnType};
+
     forall_simple_opcodes!(pub_struct);
     pub struct FarCall<M: TypeLevelCallingMode>(PhantomData<M>);
     pub struct Ret<T: TypeLevelReturnType>(PhantomData<T>);
@@ -192,10 +193,12 @@ impl<T: opcodes::TypeLevelReturnType> OpcodeType for opcodes::Ret<T> {
 /// counter has advanced.
 ///
 /// # Examples
+///
 /// Here `FarCallCounter` counts the number of far calls.
 /// ```
-/// use eravm_stable_interface::{Tracer, StateInterface, OpcodeType, Opcode};
+/// # use zksync_vm2_interface::{Tracer, StateInterface, OpcodeType, Opcode};
 /// struct FarCallCounter(usize);
+///
 /// impl Tracer for FarCallCounter {
 ///     fn before_instruction<OP: OpcodeType, S: StateInterface>(&mut self, state: &mut S) {
 ///         match OP::VALUE {