Skip to main content

Crate revmc

Crate revmc 

Source
Expand description

§revmc

Experimental JIT and AOT compiler for the Ethereum Virtual Machine.

The compiler implementation is abstracted over an intermediate representation backend. It performs very well, as demonstrated below from our criterion benchmarks, and exposes an intuitive API via Revm.

image

The compiler backend is abstracted behind a trait (revmc-backend), with an LLVM implementation (revmc-llvm) providing full test coverage.

§Requirements

  • Latest stable Rust version

§LLVM backend

  • Linux or macOS, Windows is not supported
  • LLVM 22
    • On Debian-based Linux distros: see apt.llvm.org
    • On Arch-based Linux distros: pacman -S llvm
    • On macOS: brew install llvm@22
    • The following environment variables may be required:
      prefix=$(llvm-config --prefix)
# or
#prefix=$(llvm-config-22 --prefix)
# on macOS:
#prefix=$(brew --prefix llvm@22)
export LLVM_SYS_221_PREFIX=$prefix

§Usage

The compiler is implemented as a library and can be used as such through the revmc crate.

A minimal runtime is required to run AOT-compiled bytecodes. A default runtime implementation is provided through symbols exported in the revmc-builtins crate and must be exported in the final binary. This can be achieved with the following build script:

ⓘ
fn main() {
    revmc_build::emit();
}

You can check out the examples directory for example usage.

§Testing

The Ethereum state tests are included as a git submodule. The submodule is configured with update = none so it won’t be cloned automatically.

To check it out:

git submodule update --init --checkout --depth 1 tests/ethereum-tests

Then run the state tests:

# All three modes (interpreter baseline, JIT, AOT):
cargo nextest run -p revmc -E 'test(statetest::)'

# A specific mode:
cargo nextest run -p revmc -E 'test(statetest::jit)'

# A specific test subdirectory:
SUBDIR=stSelfBalance cargo nextest run -p revmc -E 'test(statetest::jit)'

§Credits

§License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in these crates by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Re-exports§

pub use llvm::EvmLlvmBackend;llvm
pub use revm_bytecode;
pub use revm_context_interface as context_interface;
pub use revm_handler as handler;
pub use revm_inspector as inspector;
pub use revm_interpreter as interpreter;
pub use revm_primitives as primitives;
pub use revm_primitives::hardfork::SpecId;

Modules§

eyre
This library provides eyre::Report, a trait object based error handling type for easy idiomatic error handling and reporting in Rust applications.
llvmllvm
revmc-llvm
revm_evm
Generic revm JIT EVM.
ruint
Rust uint crate using const-generics
runtime
Runtime JIT backend: O(1) compiled-function lookup with background compilation.
simple_revm_evm
Generic revm JIT EVM from revmc-context.
tests__fuzzing
Internal tests and testing utilities. Not public API.

Macros§

extern_revmc
Declare RawEvmCompilerFn functions in an extern "C" block.

Structs§

BackendConfig
Backend configuration.
CompileTimings
Per-phase timing breakdown from a compilation.
EvmCompiler
EVM bytecode compiler.
EvmCompilerFn
An EVM bytecode function.
EvmContext
The EVM bytecode compiler runtime context.
EvmStack
EVM context stack.
EvmWord
An EVM stack word, which is stored in native-endian order.
JitEvm
Wrapper around any [EvmTr] that overrides [EvmTr::frame_run] to dispatch to JIT-compiled functions by code hash, falling back to the interpreter.
Linker
EVM bytecode compiler linker.
Opcode
An opcode and its immediate data. Returned by OpcodesIter.
OpcodeInfo
Opcode information.
OpcodesIter
An iterator that yields opcodes and their immediate data.
OpcodesIterWithPc
A bytecode iterator that yields opcodes and their immediate data, alongside the program counter.
Pointer
A pointer to a value.

Enums§

Attribute
Function or parameter attribute.
CallConv
Calling convention.
EvmCompilerInput
EvmCompiler input.
FunctionAttributeLocation
Determines where on a function an attribute is assigned to.
IntCC
Integer comparison condition.
Linkage
Linkage type.
OptimizationLevel
Optimization level.
PointerBase
The base of a pointer. Either an address or a stack slot.
TailCallKind
Tail call kind.

Constants§

ABI_VERSION
ABI version of compiled artifacts. Bump when the calling convention changes.

Traits§

Backend
BackendTypes
Builder
TypeMethods

Functions§

decode_pair
Decodes an EXCHANGE immediate byte into a pair of stack indices (n, m).
decode_single
Decodes a DUPN/SWAPN immediate byte into a stack index.
encode_pair
Encodes a pair of stack indices into an EXCHANGE immediate byte.
encode_single
Encodes a stack index into a DUPN/SWAPN immediate byte.
format_bytecode
Returns a string representation of the given bytecode.
format_bytecode_to
Formats an EVM bytecode to the given writer.
format_bytes
Returns a Display formatter for a byte count in human-readable form (e.g. "1.5 KiB", "3.2 MiB").
min_imm_len
Returns the length of the immediate data for the given opcode, or 0 if none.
op_info_map
Returns the static info map for the given SpecId.
parse_asm
Parse EVM assembly from a string into bytecode.
revmc_exit⚠
Exit trampoline: loads ecx.exit_result, restores the saved RSP, pops callee-saved registers and returns to the caller of revmc_entry.
shared_library_path
Returns the path for a platform-native shared library filename.
stack_io
Returns the number of input and output stack elements of the given opcode.

Type Aliases§

Error
Compilation error.
RawEvmCompilerFn
The raw function signature of a bytecode function.
Result
Compilation result.
U256
Uint for 256 bits.