Stylus SDK

To unit test Stylus contracts in native Rust without a real EVM or Arbitrum chain, use the TestVM provided by the stylus_sdk::testing module.

Requirement for Testability: For a contract to be testable with TestVM, it must access host methods through the HostAccess trait rather than calling stylus_sdk::msg functions directly. Instead of stylus_sdk::msg::value(), use self.vm().msg_value(). This allows the TestVM to inject mocked values into the contract's execution context.

Basic Workflow:

1. Import stylus_sdk::testing::* in your test module.
2. Initialize a TestVM using TestVM::default().
3. Initialize your contract from the VM using ContractName::from(&vm) (all Stylus storage types implement From<VM>).
4. Perform actions on the contract and use vm methods to mock environment variables like msg_value.

#[cfg(test)]
mod test {
    use super::*;
    use stylus_sdk::testing::*;

    #[test]
    fn test_counter() {
        let vm = TestVM::default();
        let mut contract = Counter::from(&vm);

        // Test basic logic
        contract.increment();
        assert_eq!(U256::from(1), contract.number());

        // Mock msg_value and test
        vm.set_value(U256::from(2));
        contract.add_from_msg_value();
        assert_eq!(U256::from(3), contract.number());
    }
}

Stylus contract WASM binaries must fit within a 24Kb Brotli-compressed limit. To ensure your contract fits while maintaining reproducible builds, you can pin a specific wasm-opt (Binaryen) version and set optimization flags in your Stylus.toml file.

How it works

• Opt-in: A contract is only optimized if it contains a [wasm-opt] table in Stylus.toml.
• Reproducibility: The version and flags are included in the project_hash. When using the default Docker-based deployment, cargo-stylus installs the pinned version automatically, ensuring the deployed bytes are reproducible.
• Local Builds: If running commands like check or deploy --no-verify locally, cargo-stylus will use the wasm-opt found on your PATH and will error if the version does not match your pinned version.
• Bypassing: Using the --wasm-file flag with commands bypasses the [wasm-opt] recipe; you must optimize such files manually before passing them to cargo-stylus.

[wasm-opt]
version = "131"     # pinned Binaryen version
flags = ["-Oz"]     # passed verbatim to wasm-opt

The SDK provides tools to abstract away Ethereum's storage layout, allowing you to write idiomatic Rust that behaves like a Solidity contract.

Key features include:

• sol_storage! macro: Generates storage-backed Rust structs.
• #[entrypoint] attribute: Marks a struct as a Stylus contract entrypoint.
• #[public] attribute: Defines language-agnostic methods and entrypoints.
• Storage Caching: Uses generic, storage-backed types with optimal caching.
• Alloy Integration: Uses powerful primitive types backed by the Alloy library (e.g., U256).
• Automatic Interface Export: Automatically exports Solidity interfaces to ensure interoperability.

use stylus_sdk::{alloy_primitives::U256, prelude::*};

// Generate Solidity-equivalent, Rust structs backed by storage.
sol_storage! {
  #[entrypoint]
  pub struct Counter {
    uint256 number;
  }
}

#[public]
impl Counter {
  // Gets the number value from storage.
  pub fn number(&self) -> Result<U256, Vec<u8>> {
    Ok(self.number.get())
  }

  // Sets a number in storage to a user-specified value.
  pub fn set_number(&mut self, new_number: U256) -> Result<(), Vec<u8>> {
    self.number.set(new_number);
    Ok(())
  }
}