Host randomness
zkvm_random_u64 gives the guest 64 random bits per call, drawn from a
fresh seed that the host picks for each execution. The values are
unconstrained: the proof does not attest to them, so the program's
public output must be the same whatever they are.
Host randomness was added in 1.4.0-alpha (#1384). It implements the proposed zkVM host-randomness standard (an open pull request at the time of writing).
Overview
Some guest code needs values that whoever writes the input cannot predict. The main example is hash-map seeding. With a fixed hasher seed, one set of colliding keys found offline slows down every prover that runs the same guest. With a fresh seed per execution, such an attack has to be redone for every run.
The guest cannot pick or see the seed. It only reads the stream of values derived from it.
zkvm_random_u64
Returns the next 64 random bits. It cannot fail.
pub unsafe extern "C" fn zkvm_random_u64() -> u64
It is defined in ziskos::zisklib::zkvm_random and exported as a
#[no_mangle] C symbol. C and C++ guests declare it as
uint64_t zkvm_random_u64(void). The function is unsafe only because
it uses the C ABI of the standard. Calling it is always safe.
Returns
| Type | Description |
|---|---|
u64 | The next word of the random stream. |
Example
#![no_main]
ziskos::entrypoint!(main);
use ziskos::zisklib::zkvm_random::zkvm_random_u64;
fn main() {
// Seed a hasher so colliding keys cannot be precomputed offline.
let k0 = unsafe { zkvm_random_u64() };
let k1 = unsafe { zkvm_random_u64() };
// ... build the hash map with (k0, k1); the committed output must
// not depend on the iteration order the seed produces.
}
How the values are produced
Every execution has a 256-bit seed. zkvm_random_u64 returns the
SHAKE256 output stream of the seed's 32 bytes, read as consecutive
little-endian u64 words.
Inside the zkVM, the call is a zkvmcall to a ZisK-lib routine. On the first call the routine reads the seed from the host through an unconstrained fcall. Each call then returns the next word, and one Keccak-f permutation produces the next block every 17 words. The common case costs a few steps.
When the guest runs natively (outside the zkVM), the same SHAKE256
stream is generated from a seed drawn from the OS. The --random-seed
flag does not affect a native run.
The seed
The seed is decided once per task, before any emulator runs. Every emulation of the task must see the same values: emulator threads, the ASM services, MPI ranks and distributed workers. By default it is drawn from the operating system's CSPRNG.
Providing a seed
To replay a run, pass the seed it used. Every command that runs a guest
takes --random-seed <HEX>, or reads the ZISK_RANDOM_SEED
environment variable:
| Command | Flag |
|---|---|
cargo-zisk run | --random-seed <HEX> |
cargo-zisk execute | --random-seed <HEX> |
cargo-zisk prove | --random-seed <HEX> |
cargo-zisk remote execute / remote prove | --random-seed <HEX> |
ziskemu | --random-seed <HEX> |
cargo-zisk run --release -i input.bin --random-seed 0x2a
Every run reports the seed it used in a Random seed: <64 hex chars>
line, so a failed run can be replayed. cargo-zisk run prints it on
stderr and marks a provided seed with (provided). ziskemu prints it
only with -v. Commands that log also warn Using a provided random seed, so a ZISK_RANDOM_SEED left in the environment cannot silently
pin every run to the same seed.
From the SDK, the execute and prove requests take
.random_seed(seed) with a RandomSeed, and every result reports the
seed it ran with through get_random_seed().
Under mpirun every process parses its own command line and
environment, and they must all see the same seed. Prefer
--random-seed. If you use ZISK_RANDOM_SEED, export it to every
process (Open MPI: -x ZISK_RANDOM_SEED). Processes that see no seed,
or a different one, make the run hang or diverge.
Seed format
The seed is 1 to 64 hexadecimal characters, with an optional 0x or
0X prefix. Shorter values are left-padded with zeros, so 10 is the
seed 00…0010. The seed is always displayed as 64 lowercase hex
characters.
The 32 seed bytes are, in order, the input to SHAKE256.
Remote coordinators
A remote coordinator rejects jobs that carry a client seed unless its configuration enables them:
[coordinator]
allow_client_random_seed = false # default
A rejected job fails with error 1006
(CLIENT_RANDOM_SEED_NOT_ALLOWED). Keep the option off when clients are
not trusted. A client that also writes the input could pick a seed to
craft worst-case inputs, such as hash collisions.
Rules for guest code
The output must not depend on the values
The random values are free witness values. The proof does not constrain them, so the seed is not part of what the proof attests to. A prover can run the guest with any seed, and the verifier cannot tell which one was used.
So for a fixed input, the guest's public output and exit code must be the same for every possible stream. Use the values only where the result does not change: hasher seeds, randomized algorithms whose answer is checked, and similar uses. Never commit a random value, and never let one decide what gets committed.
No hints
A guest that calls zkvm_random_u64 cannot be proven with precompile
hints. Hints come from a separate native run of the guest, which draws
different values from the prover's. The precompile calls it records
could then differ from the ones the prover executes. ZisK enforces
this:
- the hints setup of the ASM emulator rejects a guest that uses
zkvm_random_u64; - in a hints build, the native
zkvm_random_u64panics.
getrandom is not host randomnessziskos still registers a custom getrandom backend for the guest
(sys_rand), and it is not wired to zkvm_random_u64. It is a
SmallRng with a fixed seed, so every run returns the same bytes, and
it prints WARNING: Using insecure random number generator. the first
time it is used. Never use getrandom, rand::thread_rng() or
anything built on them for keys, nonces or any value that must be
unpredictable. Call zkvm_random_u64 when you need host randomness.