Skip to main content

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.

New in 1.4.0-alpha

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​

TypeDescription
u64The 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:

CommandFlag
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>
bash
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().

Multi-process runs

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_u64 panics.
getrandom is not host randomness

ziskos 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.