"The best way to understand how something works is to build it yourself."
rust-vm is an educational blockchain virtual machine written in Rust that teaches you how virtual machines, smart contracts, and blockchain systems actually work. Instead of just reading about these concepts, you can explore a real implementation with comprehensive documentation that explains every design decision.
Before diving into the code, we recommend reading our comprehensive blog series that walks you through the entire project:
Read the full article on Medium →
This first chapter introduces the fundamental concepts behind blockchain virtual machines and explains why we built this project. You'll learn:
- What virtual machines are and why they're crucial for blockchain technology
- How smart contracts actually work under the hood
- The design philosophy behind our educational approach
- What you'll learn by studying this implementation
Read the full article on Medium →
This second chapter covers the evolution of AVM from a basic instruction interpreter into a modular, extensible smart contract runtime. You'll learn about:
- Cross-program contract calls and composability
- RISC-V IMAC instruction compliance testing
- Persistent key-value storage systems
- A complete ERC-20 implementation with events and logging
- Transaction receipts and event decoding
Read the full article on Medium →
This third chapter explores the new kernel-first architecture and what it unlocks. You'll learn about:
- Bootloader + kernel separation
- Sv32 memory and trap-driven syscalls
- Task-based execution and receipts
- aTester framework and avm32 toolchain
- First ECDSA verification and the full DEX example
More chapters coming soon covering advanced features, optimizations, and real-world applications!
💡 Pro Tip: Read each blog chapter first, then explore the corresponding code sections. This combination of theory and practice will give you the deepest understanding.
Blockchain technology is revolutionizing how we think about trust, decentralization, and programmable money. But understanding how it all works under the hood can be daunting. This project bridges that gap by providing:
- 🧠 Complete Implementation: A working RISC-V-based virtual machine that can execute smart contracts
- 📚 Comprehensive Documentation: Every function, struct, and design decision is thoroughly explained
- 🎓 Educational Focus: Designed specifically for learning, not production use
- 🔍 Transparent Code: No magic, no black boxes - everything is visible and understandable
- How CPUs fetch, decode, and execute instructions
- RISC-V instruction set and binary encoding
- Memory management and isolation between contracts
- Deterministic execution for blockchain environments
- Smart contract deployment and execution
- Account-based state management (like Ethereum)
- Persistent storage and state transitions
- Transaction processing and atomicity
- Zero-copy data structures and memory safety
- Interior mutability with
RefCellandRc - No-std programming for embedded systems
- Defensive programming and error handling
- Modular architecture with clear boundaries
- Strategy patterns for extensibility
- Resource management and safety limits
- Error handling and graceful degradation
- RV32IM: Integer + multiply/divide (M). Atomics (A) are implemented; compressed (C) decoding is present but experimental—core target is RV32IM.
- Write contracts in pure Rust (no WebAssembly needed)
- Direct compilation to VM bytecode
- Rich standard library with storage, logging, and validation
- Type-safe contract interfaces
- Clear Architecture: Each component has a single, well-defined responsibility
- Comprehensive Comments: Every function explains its purpose, design decisions, and educational value
- Real-World Comparisons: See how this relates to Ethereum, Bitcoin, and other blockchain systems
- Performance Insights: Understand the trade-offs between simplicity and efficiency
- Deterministic Execution: Same input always produces same output
- Memory Isolation: Contracts can't interfere with each other
- State Management: Account-based system with persistent storage
- Transaction Processing: Atomic execution with rollback capability
rust-vm/
├── crates/
│ ├── bootloader/ # Guest bootloader and test harness integration
│ ├── kernel/ # Guest kernel (tasks, syscalls, memory layout)
│ ├── compiler/ # Rust-to-bytecode compiler
│ ├── examples/ # Smart contract examples and tutorials
│ │ ├── README.md # 📖 [Detailed guide to all examples](crates/examples/README.md)
│ │ └── src/
│ │ ├── simple.rs # Basic smart contract example
│ │ ├── erc20.rs # Full ERC-20 implementation
│ │ ├── storage.rs # Storage system examples
│ │ ├── multi_func.rs # Multi-function contract
│ │ └── call_program.rs # Cross-program calls
│ ├── clibc/ # Chain Libc smart contract runtime library
│ ├── state/ # Blockchain state management
│ ├── storage/ # Persistent storage system
│ ├── test-suite/ # End-to-end and integration tests
│ ├── types/ # Common types and data structures
│ └── vm/ # RISC-V virtual machine core
│ └── tests/ # RISC-V compliance tests
│ └── riscv-tests/ # Official RISC-V test suite
├── Cargo.toml # Workspace configuration
├── Makefile # Build and test automation
└── README.md # This file
┌───────────────┐ ┌───────────────────┐ ┌──────────────────┐
│ Bootloader │─▶│ Kernel │─▶│ User Tasks │
│ (BootInfo, │ │ init, traps, │ │ (addr space, │
│ VM setup) │ │ syscalls) │ │ trapframe) │
└───────────────┘ └─────────┬─────────┘ └────────┬─────────┘
│ │
v v
┌───────────────────┐ ┌──────────────────┐
│ State + Storage │ │ RISC-V VM │
│ (accounts, │ │ (CPU + decoder) │
│ receipts) │ └──────────────────┘
└───────────────────┘
- Rust 1.70+ with Cargo
- Basic understanding of Rust syntax
- Curiosity about how computers work at a low level
-
Clone and Explore
git clone https://github.com/your-username/rust-vm.git cd rust-vm -
Explore the Examples We provide comprehensive examples with detailed documentation:
- 📖 Examples Guide - Complete guide to all smart contract examples
- Start with
crates/examples/src/simple.rs- a basic smart contract that compares two numbers - Progress through increasingly complex examples like ERC-20 tokens and cross-contract calls
-
Explore the Core Components
- CPU:
crates/vm/src/cpu.rs- See how instructions are executed - Decoder:
crates/vm/src/decoder.rs- Learn how binary data becomes instructions - State:
crates/state/src/state.rs- Understand blockchain state management - AVM:
crates/avm/src/avm.rs- The main virtual machine orchestrator
- CPU:
-
Build and Run Tests
make all
The heart of the virtual machine. Learn about:
- Instruction Cycle: Fetch → Decode → Execute
- Register Management: 32 general-purpose registers
- Program Counter: How execution flows through code
- Error Handling: Graceful handling of invalid instructions
Converts binary data into executable instructions:
- RISC-V Formats: R-type, I-type, S-type, B-type, U-type, J-type
- Bit Manipulation: How to extract fields from 32-bit words
- Compressed Instructions: 16-bit variants for code size optimization
- Immediate Extraction: Different patterns for different instruction types
Manages the blockchain's global state:
- Account Model: Like Ethereum's account-based system
- Lazy Initialization: Accounts created only when needed
- Contract Deployment: How smart contracts are installed
- State Transitions: Atomic updates across all accounts
Provides persistent data storage:
- Key-Value Store: Simple but effective storage model
- Memory Safety: Using Rust's type system for safety
- Persistence: Data survives across transactions
- Thread Safety: Considerations for concurrent access
Understanding this VM helps you understand:
- Ethereum's EVM: How smart contracts are executed
- Bitcoin's Script: How transaction validation works
- Solana's Runtime: How high-performance blockchains operate
- WebAssembly: How portable code execution works
- Operating Systems: How processes and memory management work
This project is designed for learning and education. Contributions that improve:
- Documentation: Better explanations, more examples, clearer concepts
- Examples: More smart contract examples, tutorials, use cases
- Educational Value: Better learning materials, diagrams, explanations
- Code Clarity: Cleaner implementations, better comments, more readable code
...are especially welcome!
- Fork the repository
- Create a feature branch
- Make your changes with educational focus
- Add comprehensive documentation
- Submit a pull request
- "Computer Organization and Design" by Patterson & Hennessy
- "Programming Rust" by Blandy & Orendorff
- "Mastering Ethereum" by Antonopoulos & Wood
- RISC-V Foundation
- RISC-V Specification (also available in
crates/vm/tests/riscv-tests/) - Ethereum Documentation
- Rust Book
This project is licensed under the MIT License - see the LICENSE file for details.
This project was created to help students and developers understand the fascinating world of virtual machines and blockchain technology. Special thanks to:
- The RISC-V Foundation for the open instruction set architecture
- The Rust community for the amazing programming language
- The blockchain community for pushing the boundaries of what's possible
- All the students and developers who will learn from this project
Ready to dive deep into the world of virtual machines? Start exploring the code! 🚀
"The only way to learn a new programming language is by writing programs in it." - Dennis Ritchie