neo_vm_core/
lib.rs

1//! # Neo VM Core
2//!
3//! Core virtual machine implementation for Neo zkVM.
4//!
5//! ## Features
6//!
7//! - Full Neo N3 opcode support
8//! - Gas metering
9//! - Execution tracing for proof generation
10//! - Cryptographic operations (SHA256, RIPEMD160, ECDSA)
11//!
12//! ## Quick Start
13//!
14//! ```rust
15//! use neo_vm_core::{NeoVM, VMState, StackItem};
16//!
17//! // Create a VM with 1M gas limit
18//! let mut vm = NeoVM::new(1_000_000);
19//!
20//! // Load a script: 2 + 3 = 5
21//! vm.load_script(vec![0x12, 0x13, 0x9E, 0x40]).unwrap();
22//!
23//! // Execute until halt
24//! while !matches!(vm.state, VMState::Halt | VMState::Fault) {
25//!     vm.execute_next().unwrap();
26//! }
27//!
28//! // Get the result
29//! assert_eq!(vm.eval_stack.pop(), Some(StackItem::Integer(5)));
30//! ```
31//!
32//! ## Script Format
33//!
34//! Scripts are byte vectors containing Neo N3 opcodes. Common operations:
35//!
36//! - `0x10` - `0x20`: Push integers 0-16
37//! - `0x0F`: Push -1
38//! - `0x0B`: Push Null
39//! - `0x9E`: ADD
40//! - `0x9F`: SUB
41//! - `0xA0`: MUL
42//! - `0xA1`: DIV
43//! - `0xA2`: MOD
44//! - `0x40`: RET (return)
45//!
46//! ## Example: Simple Arithmetic
47//!
48//! ```rust
49//! use neo_vm_core::{NeoVM, VMState, StackItem};
50//!
51//! // Compute 5 * 4 = 20
52//! let script = vec![0x15, 0x14, 0xA0, 0x40];
53//!
54//! let mut vm = NeoVM::new(1_000_000);
55//! vm.load_script(script).unwrap();
56//!
57//! while !matches!(vm.state, VMState::Halt | VMState::Fault) {
58//!     vm.execute_next().unwrap();
59//! }
60//!
61//! assert_eq!(vm.eval_stack.pop(), Some(StackItem::Integer(20)));
62//! ```
63//!
64//! ## Example: Hash Computation
65//!
66//! ```rust
67//! use neo_vm_core::{NeoVM, VMState, StackItem};
68//!
69//! // Compute SHA256 of "hello"
70//! let script = vec![
71//!     0x0C, 0x05, b'h', b'e', b'l', b'l', b'o', // PUSHDATA1 "hello"
72//!     0xF0, // SHA256
73//!     0x40, // RET
74//! ];
75//!
76//! let mut vm = NeoVM::new(1_000_000);
77//! vm.load_script(script).unwrap();
78//!
79//! while !matches!(vm.state, VMState::Halt | VMState::Fault) {
80//!     vm.execute_next().unwrap();
81//! }
82//!
83//! if let Some(StackItem::ByteString(hash)) = vm.eval_stack.pop() {
84//!     assert_eq!(hash.len(), 32); // SHA256 produces 32 bytes
85//! }
86//! ```
87//!
88//! ## Example: Gas Metering
89//!
90//! ```rust
91//! use neo_vm_core::{NeoVM, VMState};
92//!
93//! let mut vm = NeoVM::new(10); // Very low gas limit
94//!
95//! // Create a script that will exhaust gas (multiple operations)
96//! let script = vec![0x11, 0x11, 0x11, 0x11, 0x11]; // Multiple PUSH1 operations
97//! vm.load_script(script).unwrap();
98//!
99//! // Execute until out of gas or halt
100//! while !matches!(vm.state, VMState::Halt | VMState::Fault) {
101//!     let _ = vm.execute_next();
102//! }
103//!
104//! // VM may halt normally or fault due to gas depending on execution
105//! assert!(vm.gas_consumed > 0);
106//! ```
107//!
108//! ## Example: Error Handling
109//!
110//! The VM correctly handles errors like division by zero:
111//!
112//! ```rust
113//! use neo_vm_core::{NeoVM, VMState};
114//!
115//! let mut vm = NeoVM::new(1_000_000);
116//!
117//! // Division by zero should cause a fault
118//! // Script: PUSH5, PUSH0, DIV, RET
119//! let script = vec![0x15, 0x10, 0xA1, 0x40];
120//! vm.load_script(script).unwrap();
121//!
122//! while !matches!(vm.state, VMState::Halt | VMState::Fault) {
123//!     let _ = vm.execute_next();
124//! }
125//!
126//! assert!(matches!(vm.state, VMState::Fault));
127//! ```
128//!
129
130pub mod engine;
131pub mod native;
132pub mod opcode;
133pub mod stack_item;
134pub mod storage;
135
136pub use engine::{NeoVM, VMError, VMState};
137pub use native::{CryptoLib, NativeContract, NativeRegistry, StdLib};
138pub use opcode::OpCode;
139pub use stack_item::StackItem;
140pub use storage::{MemoryStorage, StorageBackend, StorageContext, TrackedStorage};
neo_vm_core/lib.rs

neo_vm_core/
lib.rs
