v0.20.0

Highlights

• risc0 zkVM Support - The emulator now supports creating and verifying zero-knowledge proofs of machine state transitions through risc0 zkVM.
• Optimized Hash Tree - Replaced the Merkle tree with a significantly faster hash tree implementation supporting Keccak-256 and SHA-256, accelerated with SIMD (AVX2, AVX-512, NEON), OpenMP multithreading, and on-disk caching.
• On-Disk Machine State - Machines can now operate with fully disk-backed state, with backing store support across all address ranges and efficient cloning via reflinks/hardlinks on copy-on-write filesystems.
• Bulk Hash Collection - New C API functions for collecting root hashes at configurable intervals with subtree bundling, enabling efficient construction of computation hashes over long executions.
• Console I/O Redirection - Console input/output can now be routed to and from pipes, files, or in-memory buffers.
• Proof Slicing - The C API now supports generating proofs for arbitrary sub-ranges of the address space.
• Interpreter Hardening - The interpreter has been hardened against adversarially crafted machine states, validated through extensive fuzzing.

Added

• Added RISC0 zkVM integration for fraud proof verification, with C++, Rust, and Solidity implementations
• Added cm_collect_mcycle_root_hashes and cm_collect_uarch_cycle_root_hashes C API functions for bulk hash collection with subtree bundling support
• Added cm_get_version C API function to retrieve emulator semantic version at runtime
• Added cm_write_word C API function to write a word by physical address
• Added cm_get_node_hash C API function to get hash of a specific node in the hash tree
• Added cm_clone_stored and cm_remove_stored C API functions to clone and remove stored machines
• Added cm_read_console_output and cm_write_console_input C API functions for buffered console I/O
• Added cm_get_hash and cm_get_concat_hash C API functions for general-purpose hashing
• Added cm_get_hash_tree_stats C API function to retrieve hash tree statistics
• Added cm_sharing_mode enum (CM_SHARING_NONE, CM_SHARING_CONFIG, CM_SHARING_ALL) to control on-disk vs in-memory machine state
• Added cm_hash_function enum (CM_HASH_KECCAK256, CM_HASH_SHA256) to select the hash function used in the hash tree
• Added CM_BREAK_REASON_CONSOLE_OUTPUT and CM_BREAK_REASON_CONSOLE_INPUT break reasons
• Added CM_UARCH_BREAK_REASON_CYCLE_OVERFLOW break reason and CM_UARCH_CYCLE_MAX constant
• Added CM_AR_SHADOW_STATE_START, CM_AR_SHADOW_STATE_LENGTH, CM_AR_SHADOW_REVERT_ROOT_HASH_START, CM_AR_SHADOW_TLB_START, CM_AR_SHADOW_TLB_LENGTH, CM_AR_PMAS_START, and CM_AR_PMAS_LENGTH address range constants
• Added --no-reserve command line option to skip reserving swap memory for flash drives
• Added --assert-version command line option to verify emulator version on startup
• Added --create=<directory> command line option to create machines with fully on-disk state
• Added --console-io=<key>:<value> command line option for console input/output redirection (to/from null, stdout, stderr, file descriptor, file, or buffer)
• Added --dense-uarch-hashes command line option to print root hash at every uarch cycle
• Added --processor, --ram, --dtb, --pmas, --uarch-ram, and --uarch-processor command line options with backing store configuration
• Added --hash-tree command line option to configure hash function (keccak256 or sha256), sparse hash-tree and page hash-tree cache backing files
• Added sharing mode support (none, config, all) to --load and --store command line options
• Added clone option to --load for efficient machine cloning using reflinks/hardlinks
• Added mke2fs option to --flash-drive for automatic ext2 filesystem formatting on init (defaults to true when no backing file is provided)
• Added read_only option to --flash-drive to mark flash drives as read-only to host and guest
• Added vectorized SIMD Keccak-256 and SHA-256 hashers with AVX2, AVX-512, and ARM NEON support
• Added on-disk persistence for hash tree state via sparse hash-tree and page hash-tree cache files
• Added backing store support for processor, DTB, and CMIO address ranges (previously only RAM and flash drives)
• Added revert root hash to the shadow address range
• Added lazy verification of TLB slots, hardening against attacker-crafted TLB state
• Added computation of coverage for code run inside uarch
• Added Cartesi EVM utility Lua API (evmu.lua) for encoding EVM call data
• Added fuzzing infrastructure with LLVM libFuzzer, including fuzzers for machine config, shadow-state, and step verification
• Added ankerl::unordered_dense third-party library for high-performance hash maps
• Added bundled third-party pure Lua libraries: BINT big integer and Lester testing framework

Fixed

• Fixed linting errors and compiler warnings with recent Clang
• Fixed cm_jsonrpc_spawn_server not respecting the specific bind address
• Fixed zombie processes left behind by Lua tests
• Fixed interpreter PC alignment invariant not enforced at startup
• Fixed interpreter fetch cache not being properly invalidated in some edge cases
• Fixed iunrep coupled to mutable shadow state
• Fixed assert_no_brk incorrectly asserting no pending interrupts when higher-privilege interrupts are expected
• Fixed errno code not shown on fork() errors
• Fixed issues with likely/unlikely macros by replacing them with C++20 [[likely]]/[[unlikely]] attributes

Changed

• Bumped C++ standard from C++20 to C++23
• Bumped base Docker image from Debian 12 (Bookworm) to Debian 13 (Trixie)
• Bumped MARCHID version to 20
• Bumped GCC RISC-V cross-compiler from 12 to 14
• Bumped Boost library to 1.87 on macOS for compatibility
• Bumped test rootfs to guest tools 0.17.2
• Renamed cartesi-merkle-tree-hash binary to cartesi-hash-tree-hash
• Renamed libcartesi_merkle_tree library to libcartesi_hash_tree (both static and shared)
• Renamed --flash-drive option key filename to data_filename
• Renamed image_filename to data_filename across all configs and CLI options
• Renamed update_merkle_tree concurrency key to update_hash_tree
• Renamed CM_TREE_LOG2_* constants to CM_HASH_TREE_LOG2_*
• Renamed CM_PMA_* constants to CM_AR_* and enum from cm_pma_constant to cm_pmas_constant
• Renamed cm_verify_merkle_tree to cm_verify_hash_tree
• Renamed cm_get_memory_ranges to cm_get_address_ranges
• Changed cm_create / cm_create_new signatures to accept a dir parameter for on-disk machine creation
• Changed cm_load / cm_load_new signatures to accept a cm_sharing_mode parameter
• Changed cm_store signature to accept a cm_sharing_mode parameter
• Changed cm_replace_memory_range to accept a JSON config string instead of individual parameters
• Changed cm_read_memory to allow reading across the entire address space (previously restricted to a single memory range)
• Changed cm_get_proof signature to accept a log2_root_size parameter for proof slicing
• Changed cm_verify_step to no longer require a machine pointer (now a static function)
• Changed processor JSON config to nest register fields under processor.registers sub-object
• Changed stored machine directory layout: new .dht, .dpt files per address range, new hash_tree.sht and hash_tree.phtc global files, and hash file is no longer generated
• Changed cartesi-machine-stored-hash to compute hash by loading the full machine instead of reading the hash file
• Changed flash drive label from mandatory to optional (defaults to driveX)
• Changed step log format to include root hashes and mcycle count in the header for self-contained verification
• Changed CSR registers to enforce WARL (Write Any Read Legal) semantics through a centralized legalization layer on reads and writes
• Changed WFI instruction to clamp wait time to mcycle_end, preventing cycle overshooting
• Replaced the Merkle tree implementation with a new hash tree supporting configurable hash functions
• Replaced image_filename / shared fields with unified backing_store_config structure (data_filename, dht_filename, dpt_filename, shared, create, truncate)
• Replaced htif_runtime_config with console_runtime_config supporting full I/O redirection
• Replaced PMA naming throughout the codebase by "address range" / AR
• Optimized SQRT instruction using digit-by-digit calculation
• Optimized hash tree computation using OpenMP for threading and vectorized hashing
• Optimized shadow register access in replay step by using caches

Removed

• Removed hash file from stored machine snapshot directories (root hash is now computed on demand from the hash tree)
• Removed default_ram_image and default_rootfs_image fields from --version-json output
• Removed --htif-no-console-putchar command line option (replaced by --console-io=output_destination:to_null)
• Removed --skip-root-hash-check and --skip-root-hash-store command line options
• Removed cm_verify_dirty_page_maps C API function
• Removed tlb_config, clint_config, plic_config, and htif_config from machine configuration
• Removed tiny_sha3 third-party library (replaced by built-in Keccak-256 hasher)
• Removed proof.lua Lua module
• Removed circular_buffer implementation in favor of standard containers
• Removed old Merkle tree implementation (complete-merkle-tree, full-merkle-tree, machine-merkle-tree, pristine-merkle-tree)

v0.20.0-test

fix: replay invalidate tlb slot

v0.19.0

Added

• Added libluacartesi.a and libluacartesi_jsonrpc.a static libraries when installing to allow packaging statically linked Lua programs
• Added --remote-spawn command line option to spawn remote machines
• Added --remote-health-check command line option to check availability of remote machines
• Added --store-json-config command line option to store machine configs to JSON files
• Added --load-json-config command line option to load machine configs from JSON files
• Added --server-fd command line option to JSON-RPC remote machine
• Added --setpgid command line option to JSON-RPC remote machine
• Added cartesi.tobase64, cartesi.frombase64, cartesi.tojson, and cartesi.fromjson Lua functions
• Added various new methods to JSON-RPC remote machine interface to allow more precise management of remote machine processes
• Added timeout support to JSON-RPC remote machine requests
• Added capability to retrieve PID of spawned remote machines
• Added support for VirtIO devices in JSON configs
• Added the --log-step command line option to log multiple machine cycles
• Added the cm_log_step and cm_verify_step methods to log multiple machine cycles and verify with ZK VMs
• Added the cm_receive_cmio_request method, the counterpart of cm_send_cmio_response method
• Added timeout support for jsonrpc requests

Fixed

• Fixed various linting errors with the latest Clang static analyzer
• Fixed broken link when running make bundle-boost
• Fixed many broken links in the README and markdown files
• Fixed issues when using --network option in Alpine guests
• Fixed issue when using --assert-rolling-template
• Fixed --skip-root-hash-store not skipping root hash computation
• Fixed kernel panic bug when feeding 100k stdin inputs into VirtIO console
• Fixed bug when trying to advance multiple inputs through the cartesi-machine CLI
• Fixed compile errors when targeting Windows, Alpine Linux, and WebAssembly
• Fixed conflicting symbols between libcartesi and libcartesi_jsonrpc
• Fixed --sync-init-date and --virtio-console command line options
• Fixed various issues when forking jsonrpc machines inside a Go environment
• Fixed potential data races in multi-threaded environments

Changed

• Optimized RISC-V instruction decoder to use token threading, computed goto, and big jump tables
• Optimized RISC-V instruction fetcher to cache latest accessed pages
• Refactored the code to use C++20 standard, which is now a minimum requirement
• Refactored the public C API to be simpler and easier to use with other programming languages
• Refactored the Lua API to make remote and local use the same API interface
• Refactored and simplified many portions of the code, improving maintainability of the project
• Changed default GCC compiler flags to better optimize the RISC-V interpreter
• Changed flash drive start address configuration to be non-mandatory (it will be automatically chosen)
• Changed sibling hashes ordering in JSON logs to match the expected ordering in Lua test suite
• Changed rebind method of remote machines to support binding on port 0 and return the bound address
• Changed to Debian RISC-V toolchain when compiling microarchitecture
• Changed --remote-fork command line option to accept an address
• Changed add-generated-files.diff to be applied with patch -Np1 to make packaging easier
• Changed default machine config to include bootargs
• Changed machine configs and access logs to be represented as JSON strings in the C API
• Renamed --log-uarch-step command line option to --log-step-uarch
• Renamed --log-uarch-reset command line option to --log-reset-uarch
• Renamed --auto-uarch-reset command line option to --auto-reset-uarch
• Renamed various C API functions, structs, and enumerations
• Renamed jsonrpc-remote-cartesi-machine to cartesi-jsonrpc-machine
• Renamed merkle-tree-hash to cartesi-merkle-tree-hash
• Removed cartesi- prefix and versioning suffix from CI artifacts names
• Revamped project README with more up-to-date explanations and simplified instructions
• Changed help and configs to be printed to stdout instead of stderr
• Changed the public C API to require less manual memory management
• Improved documentation in the public C API header
• Improved CI to use more parallel jobs when testing
• Improved send_cmio_response bounds checking
• Split iflags CSR into multiple CSRs
• Bumped MARCHID version to 19
• Updated test rootfs to guest tools 0.17.1

Removed

• Removed publishing of Debian package artifacts in favor of official Linux package repositories
• Removed use of cartesi/toolchain image
• Removed automatic strip of binaries when performing make install (stripping should now be done when packaging)
• Removed no4lvl from bootargs (Sv57 address translation is now disabled at interpreter level to fix NodeJS JIT issues)
• Removed rootfstype=ext2 from bootargs, allowing use of root filesystems in other formats, such as Ext4 and SquashFS
• Removed all *-defines.h headers
• Removed all specific read/write of machine registers from the public API
• Removed various C API functions
• Removed dkjson Lua library (not needed since we have our own JSON encoding functions now)
• Removed GDB documentation from the repository (moved to the wiki)
• Removed internal development documentation from the README (moved to the wiki)
• Removed many dead code segments after the refactoring

v0.18.1

Changed

• Updated tools rootfs to 0.16.1

v0.18.0

Added

• Makefile target create-generated-files-patch to generate add-generated-files.diff patch
• CI now creates and uploads add-generated-files.diff as artifact on tagged releases
• Added unversioned symlinks to shared libraries in src directory

Changed

• Updated test rootfs to 0.16.0
• Updated outputs merkle height (for output unification v2)
• Updated makefile to make it compatible with a homebrew formulae
• Changed listening port to close immediately in JSONRPC shutdown
• Bundled nlohmann JSON into third party directory
• Rewritten jsonrpc-remote-machine using Boost ASIO
• Updated test data due to input contract prev_randao field
• Bumped MARCHID version to 18
• Changed compile to release mode with debug info by default
• Changed layout of uarch json logs

Fixed

• Fixed regression saving snapshots on first machine yield
• Fixed TIME_WAIT connections accumulation on Linux
• Fixed Homebrew build
• Ensured make clean target works with no submodules
• Fixed TLB reads while computing hash with uarch
• Fixed rollback remote machine for rejected advance state via the cli
• Fixed prefix when brew is present in the system
• Fixed system error when loading or saving snapshots