zkVM symbol reference

Zesu builds its execution logic as a relocatable RISC-V ELF objectELF object An Executable and Linkable Format object. Zesu is compiled as a relocatable rv64im ELF object named zesu.rv64im.o that zkVM hosts link against to produce a guest binary. named zesu.rv64im.o. This object leaves platform-specific behavior as the unresolved extern symbol references of the symbol contract that each zero-knowledge virtual machine (zkVM)zkVM A zero-knowledge virtual machine that executes a guest program and produces a proof that the execution was correct. Zesu runs as a guest program inside a zkVM to generate block-validation proofs. target satisfies with a host object.

The host object implements each symbol using platform-native circuits or software fallbacks, then links against zesu.rv64im.o to produce the final guest binary. This keeps Ethereum Virtual Machine (EVM) logic separate from zkVM-specific integration code.

The symbols fall into three categories: I/O, runtime, and accelerators.

I/O symbols

I/O symbols are the channel between Zesu and the zkVM host at runtime. Zesu uses read_input to receive the zkVM private input and write_output to emit public output bytes.

Symbol	Signature	Description
read_input	(*[*]const u8, *usize) void	Return the location and length of the serialized input
write_output	([*]const u8, usize) void	Emit the public output bytes

Runtime symbols

Runtime symbols provide execution environment support for logging, process termination, and memory management.

Symbol	Signature	Description
zkvm_log	(u8, [*]const u8, usize) void	Log a message at the given level
zkvm_exit	(i32) noreturn	Terminate execution with the given exit code
ZKVM_HEAP_POS	usize (var)	Heap cursor the allocator advances when it grows the heap
ZKVM_HEAP_TOP	usize (var)	Heap upper bound the allocator must not exceed

note

On the zesu.rv64im.o guest build, Zesu defaults to a free-list allocator that recycles freed memory within the heap region [ZKVM_HEAP_POS, ZKVM_HEAP_TOP).

The allocator is selected at build time, and the source also retains a simpler bump allocator that never reclaims memory. To use the bump allocator instead, build the guest object from source with that allocator wired in, or import the allocator you want when you embed Zesu's modules in your own build. The bump allocator can exhaust the fixed heap on large blocks, so the free-list allocator is the default and the recommended choice. Allocator selection affects only how the guest manages the heap. The host contract is unchanged, because the host still reserves the heap region that these two symbols describe.

Accelerator symbols

Accelerator symbols delegate cryptographic operations to host-provided implementations. All accelerator symbols return i32: 0 for success, -1 for failure. Host implementations can satisfy these symbols using platform-native circuits or software fallbacks.

The precompile column shows the EVM precompile address that each accelerator corresponds to, where applicable. No precompile address is listed for zkvm_keccak256 or zkvm_secp256k1_verify.

Symbol	Precompile	Description
zkvm_keccak256		Keccak-256 hash
zkvm_sha256	0x02	SHA-256 hash
zkvm_secp256k1_ecrecover	0x01	secp256k1 signature recovery
zkvm_secp256k1_verify		secp256k1 signature verification
zkvm_ripemd160	0x03	RIPEMD-160 hash
zkvm_modexp	0x05	Modular exponentiation (EIP-198)
zkvm_bn254_g1_add	0x06	BN254 G1 point addition (EIP-196)
zkvm_bn254_g1_mul	0x07	BN254 G1 scalar multiplication (EIP-196)
zkvm_bn254_pairing	0x08	BN254 pairing check (EIP-197)
zkvm_blake2f	0x09	BLAKE2f compression (EIP-152)
zkvm_kzg_point_eval	0x0a	KZG point evaluation (EIP-4844)
zkvm_bls12_g1_add	0x0b	BLS12-381 G1 addition (EIP-2537)
zkvm_bls12_g1_msm	0x0c	BLS12-381 G1 multi-scalar multiplication (EIP-2537)
zkvm_bls12_g2_add	0x0d	BLS12-381 G2 addition (EIP-2537)
zkvm_bls12_g2_msm	0x0e	BLS12-381 G2 multi-scalar multiplication (EIP-2537)
zkvm_bls12_pairing	0x0f	BLS12-381 pairing check (EIP-2537)
zkvm_bls12_map_fp_to_g1	0x10	BLS12-381 Fp to G1 map (EIP-2537)
zkvm_bls12_map_fp2_to_g2	0x11	BLS12-381 Fp2 to G2 map (EIP-2537)
zkvm_secp256r1_verify	0x100	P-256 signature verification (EIP-7212)