Skip to main content

Entrypoint

Every guest program must opt out of the standard Rust runtime and declare its entry point. Without it, the zkVM has no function to execute.

entrypoint!​

Registers a function as the zkVM entry point and opts the crate out of the standard Rust runtime. The #![no_main] crate attribute is also required — the zkVM has no OS to provide a default runtime or main symbol.

ziskos::entrypoint!(fn_name)

Parameters​

NameTypeDescription
fn_nameidentifierName of the function to register as the guest entry point. It must take no arguments, and its return type must implement ZiskTermination — (), i32, or Result<T, E>.

Example​

#![no_main]
ziskos::entrypoint!(main);

fn main() {
// guest code runs here
}
note

The #![no_main] attribute is required at the crate root. Without it, the Rust compiler generates a default main function that conflicts with the #[no_mangle] main the macro produces, causing a linker error.

The macro expands to a #[no_mangle] extern "C" fn main() -> i32 that initializes the guest runtime, calls the registered function, tears the runtime down, and returns the exit code its return value maps to.


ZiskTermination​

macro_rules! cannot branch on the signature of the function it is handed — macros expand before type checking — so entrypoint! resolves the entry point's return type through a trait instead, the same role std::process::Termination plays for a regular fn main.

pub trait ZiskTermination {
fn to_exit_code(self) -> i32;
}

Any return type implementing this trait is accepted by entrypoint!. Three implementations ship with ziskos:

Return typeExit code
()0 — a plain return is a successful completion.
i32The returned value, verbatim.
Result<T, E> where T: ZiskTerminationOk(value) delegates to value.to_exit_code(); Err(_) is 1.

Only exit code 0 is a successful execution. Any other code, including the 1 an Err maps to, makes the execution fail, and a failed execution is never proven. See Where the exit code goes.

Because Result delegates through its Ok type, Result<(), E> exits with 0 on success and Result<i32, E> exits with the returned code. E is unconstrained — it does not need to implement Debug or Display.

New in 1.1.0-alpha

Earlier versions accepted only fn() -> (). Existing entry points keep working unchanged: () maps to exit code 0, which is what the macro previously returned unconditionally.

Examples​

Returning an explicit code:

#![no_main]
ziskos::entrypoint!(main);

use ziskos::io;

fn main() -> i32 {
let n: u64 = io::read();
if n == 0 {
return 2; // nonzero: the execution fails and cannot be proven
}
io::commit(&(n * 2));
0
}

Propagating errors with ?:

#![no_main]
ziskos::entrypoint!(main);

use ziskos::io;

fn main() -> Result<(), MyError> {
let raw = io::read_slice();
let parsed = parse(raw)?; // an Err exits with code 1: no proof
io::commit(&parsed.digest);
Ok(())
}
warning

The Err value is discarded, not printed. ZiskTermination cannot format it without coupling the trait to a target-specific writer, so an error return produces exit code 1 and nothing else. Log the error inside the entry point before returning if you need a diagnostic:

fn main() -> Result<(), MyError> {
if let Err(e) = run() {
println!("guest failed: {e:?}");
return Err(e);
}
Ok(())
}

Where the exit code goes​

The code the macro computes is placed in a0 and handed to the termination mechanism of whichever target the program was built for:

TargetDestination
ZisK guestThe exit syscall (93), which ends the run.
QEMUThe sifive_test device: 0 becomes 0x5555 (pass), anything else (code << 16) | 0x3333.
NativeThe process exit status, as with any C main.
Changed in 1.4.0-alpha

Under the zkVM a nonzero exit code is a failed execution. The emulator and the prover stop with an ExecutionFailed error instead of producing a proof, so no proof of a failed execution can exist. ziskemu exits with the low 8 bits of the guest's code, or 1 if those bits are 0, so a failure never looks like success to the shell.

A trap fails the execution in the same way. Traps include a panic (Rust aborts through unimp), ebreak and a write to a read-only CSR.

In 1.3 and earlier the exit code was not reported, and a nonzero code or a panic could still be proven. Do not use a nonzero code to mean "valid run, negative answer". If the verifier must learn that an input was rejected, return 0 and commit the verdict with io::commit.