Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions docs/concepts/architecture.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand Down
5 changes: 4 additions & 1 deletion docs/get-started/get-guest-program.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
:::

Expand Down
43 changes: 36 additions & 7 deletions docs/reference/zkvm-symbols.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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.
Expand Down
Loading