From 6596b5e476a49163064883fb5fda42c5dfdb2258 Mon Sep 17 00:00:00 2001 From: bgravenorst Date: Mon, 31 Aug 2026 08:50:09 +1000 Subject: [PATCH] Remove zkvm exit symbol. Signed-off-by: bgravenorst --- docs/concepts/architecture.mdx | 13 +++++--- docs/get-started/get-guest-program.mdx | 5 ++- docs/reference/zkvm-symbols.mdx | 43 +++++++++++++++++++++----- 3 files changed, 49 insertions(+), 12 deletions(-) diff --git a/docs/concepts/architecture.mdx b/docs/concepts/architecture.mdx index 3651e07..f0b7934 100644 --- a/docs/concepts/architecture.mdx +++ b/docs/concepts/architecture.mdx @@ -101,7 +101,7 @@ Zesu without a source dependency on this repository. The [`zesu-zkvm` repository](https://github.com/Consensys/zesu-zkvm) provides example integrations for the Zisk, OpenVM, and Linea zkVMs. It is a stop-gap for zkVMs that don't yet implement the -[zkVM standards](https://github.com/eth-act/zkvm-standards); as they adopt the common +[zkVM standards](https://github.com/eth-act/zkevm-standards); as they adopt the common interface, they can satisfy the symbol contract directly. The same source also builds as a native binary that runs on a host CPU without any zkVM, used for debugging execution against captured blocks and validating zkVM integrations @@ -119,15 +119,20 @@ The extern references that zkVM hosts must satisfy fall into three categories. commitment back. The two I/O symbols (`read_input` and `write_output`) are the only channel between the guest and the host at runtime. -- **Runtime**: execution environment support: logging, process termination, and the heap -allocator's position and upper-bound variables. These let Zesu operate in a -freestanding environment without an operating system. +- **Runtime**: execution environment support: logging and the heap allocator's position +and upper-bound variables. These let Zesu operate in a freestanding environment without +an operating system. - **Accelerators**: EVM precompile operations (keccak256, secp256k1 recovery, BN254 pairings, and so on) delegated to zkVM-native implementations where available. Hardware-accelerated precompiles reduce proof cost significantly for computationally expensive EVM operations. +Termination sits outside the symbol contract. +Zesu's `main` returns an exit status that the host entry point maps to the zkVM's halt +sequence, following the +[execution termination semantics standard](https://github.com/eth-act/zkevm-standards/tree/main/standards/standard-termination-semantics). + See [zkVM symbol reference](../reference/zkvm-symbols.mdx) for the full symbol tables including signatures and descriptions. diff --git a/docs/get-started/get-guest-program.mdx b/docs/get-started/get-guest-program.mdx index 96e373e..c3ea91d 100644 --- a/docs/get-started/get-guest-program.mdx +++ b/docs/get-started/get-guest-program.mdx @@ -37,12 +37,15 @@ against `zesu.rv64im.o` to produce the final guest binary your zkVM runs. Linking conventions are platform-specific. Your zkVM target determines the linker script, entry point, heap layout, and accelerator wiring. +Your entry point also calls Zesu's `main` symbol and maps its return value (`0` for +success, non-zero for failure) to the zkVM's halt sequence. + :::note The [`zesu-zkvm` repository](https://github.com/Consensys/zesu-zkvm) contains example integrations for the Zisk, OpenVM, and Linea zkVMs. It is a stop-gap for zkVMs that don't yet implement the common guest interface, and shows how to wire a non-compliant zkVM to Zesu. -As zkVMs adopt the [zkVM standards](https://github.com/eth-act/zkvm-standards), they can +As zkVMs adopt the [zkVM standards](https://github.com/eth-act/zkevm-standards), they can satisfy the symbol contract directly and the example integrations become unnecessary. ::: diff --git a/docs/reference/zkvm-symbols.mdx b/docs/reference/zkvm-symbols.mdx index 5f965fe..40874a4 100644 --- a/docs/reference/zkvm-symbols.mdx +++ b/docs/reference/zkvm-symbols.mdx @@ -28,6 +28,9 @@ This keeps Ethereum Virtual Machine (EVM) logic separate from zkVM-specific inte code. The symbols fall into three categories: I/O, runtime, and accelerators. +Termination isn't part of the symbol contract. +Zesu returns an exit status to the host entry point instead, as described in +[Exit status and panics](#exit-status-and-panics). ## I/O symbols @@ -42,15 +45,14 @@ public output bytes. ## Runtime symbols -Runtime symbols provide execution environment support for logging, process termination, -and memory management. +Runtime symbols provide execution environment support for logging 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 | +| Symbol | Signature | Description | +|-----------------|---------------------------------|-----------------------------------------------------------| +| `zkvm_log` | `(u8, [*]const u8, usize) void` | Log a message at the given level | | `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 | +| `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 @@ -70,6 +72,33 @@ that these two symbols describe. ::: +## Exit status and panics + +Zesu's exported `main` symbol follows the RISC-V C calling convention and returns a +C `int` exit status in register `a0`: `0` on success and `1` on failure. +Before returning `1`, Zesu logs the error name through `zkvm_log`. + +Your host entry point (`_start`, or the equivalent for your target) calls `main` and +converts the returned value into the platform's halt sequence. +The [`zesu-zkvm` repository](https://github.com/Consensys/zesu-zkvm) shows how the Zisk, +OpenVM, and Linea integrations each do this. + +A Zig panic logs the panic message through `zkvm_log`, then executes the +compiler-emitted `@trap()` builtin, which raises an illegal instruction. +A panic doesn't return through `main`, so no exit status reaches your host entry point. + +This convention matches the +[application entry point return value](https://github.com/eth-act/zkevm-standards/tree/main/standards/standard-termination-semantics#application-entry-point-return-value) +rule in the execution termination semantics standard, which makes `_start` responsible +for mapping the return value to the zkVM's termination mechanism. + +:::note +Earlier Zesu releases required a `zkvm_exit` runtime symbol for termination. + +If your host object still defines `zkvm_exit`, the guest no longer calls it, and your +entry point must honor the `main` return value instead. +::: + ## Accelerator symbols Accelerator symbols delegate cryptographic operations to host-provided implementations.