Syscalls
ziskos::syscalls is the lowest layer of the precompile stack. Each
syscall_* function becomes one precompiled instruction inside the
zkVM, and on native targets it falls back to a software implementation
with the same semantics.
Overview
Most guest programs never call these functions directly. The safe, validated wrappers in zisklib (hashing, curve arithmetic, pairings) are built on top of them and are the recommended entry point. Reach for a syscall only when you need a primitive that zisklib does not wrap, or when you are writing your own wrapper.
use ziskos::syscalls::{syscall_secp256k1_add, SyscallPoint256};
Almost every syscall is #[no_mangle] extern "C", so C and C++ guests can
link against the same symbols. The exceptions are
syscall_blake2b_round_const (generic over the round index) and
syscall_blake2b_rounds_chain, which are plain Rust pub fns.
Calling conventions
- Alignment. Every buffer passed to a syscall must be aligned to a 64-bit boundary. A misaligned operand is undefined behavior.
- In-place results. Unless noted otherwise, the result overwrites
the first operand (
p1,f1,state, orp). - Caller-checked preconditions. Syscalls do not validate their
inputs. Requirements such as "the point is on the curve" or "
p1 ≠ p2" are listed under each function and are the caller's job. The zisklib wrappers check them for you. hintsvariants. The signatures below are for theziskoscrate, which has nohintsfeature (Cargo rejectsfeatures = ["hints"]). The same source is also built as theziskos-hintscrate, where thehintsfeature is on by default and each syscall gains a trailinghints: &mut Vec<u64>parameter (exported with ahints_symbol prefix).
The two-operand syscalls no longer take a parameter struct. They now
take the two addresses directly (#1344): the transpiler folds the
csrs and the following add/addi into a single precompiled
instruction, so no struct is built in memory. The Syscall*Params
structs for these calls were removed. Update call sites as follows:
// 1.3
let mut params = SyscallSecp256k1AddParams { p1: &mut p1, p2: &p2 };
syscall_secp256k1_add(&mut params);
// 1.4.0-alpha
syscall_secp256k1_add(&mut p1, &p2);
The affected calls are the point additions (secp256k1, secp256r1,
bn254, bls12_381, babyjubjub), the Fp2 operations (bn254_complex_*,
bls12_381_complex_*), sha256_f, blake2sf, blake3f and
blake2b_round. The arithmetic syscalls (add256, arith256,
arith256_mod, arith384_mod) still take a parameter struct.
Shared types
Points and Fp2 elements are passed as #[repr(C)] structs of
little-endian u64 limbs.
pub struct SyscallPoint256 { // affine (x, y), 256-bit coordinates
pub x: [u64; 4],
pub y: [u64; 4],
}
pub struct SyscallPoint384 { // affine (x, y), 384-bit coordinates
pub x: [u64; 6],
pub y: [u64; 6],
}
pub struct SyscallComplex256 { // x + y·i over a 256-bit base field
pub x: [u64; 4],
pub y: [u64; 4],
}
pub struct SyscallComplex384 { // x + y·i over a 384-bit base field
pub x: [u64; 6],
pub y: [u64; 6],
}
Arithmetic
Wide integer and modular multiply-add. These four calls still take a parameter struct holding references to the operands and results.
256-bit addition with carry: a + b + cin = cout | c. The carry-out
is returned.
pub struct SyscallAdd256Params<'a> {
pub a: &'a [u64; 4],
pub b: &'a [u64; 4],
pub cin: u64,
pub c: &'a mut [u64; 4],
}
pub extern "C" fn syscall_add256(params: &mut SyscallAdd256Params) -> u64
Returns
| Type | Description |
|---|---|
u64 | The carry-out cout, 0 or 1. The sum is written to params.c. |
Hash permutations and compression
Single-permutation or single-compression primitives. The zisklib hash
functions (sha256,
keccak256, blake2b_compress, and so on) handle padding, IVs and
feed-forward around them.
Keccak-f[1600] permutation on a 25-word state, in place.
pub unsafe extern "C" fn syscall_keccak_f(state: *mut [u64; 25])
Short Weierstrass curves
Affine point addition and doubling on secp256k1, secp256r1 (P-256),
BN254 and BLS12-381 G1. None of these calls handle the point at
infinity or the p1 = ±p2 cases. The zisklib curve functions do.
Adds p2 to p1 on secp256k1. The result is stored in p1.
pub extern "C" fn syscall_secp256k1_add(p1: &mut SyscallPoint256, p2: &SyscallPoint256)
Both points must be finite points on the curve with canonical
coordinates, and p1 ≠ p2 and p1 ≠ −p2. The result is canonical.
Twisted Edwards curves
Complete addition on BabyJubJub and Ed25519. The addition law is
complete, so the same call doubles a point (pass p1 = p2 = P) and the
identity needs no special case.
Adds p2 to p1 on BabyJubJub (circomlib). The result is stored in
p1.
pub extern "C" fn syscall_babyjubjub_add(p1: &mut SyscallPoint256, p2: &SyscallPoint256)
Both points must be on the curve with coordinates in the BN254 scalar field. In 1.4.0-alpha this call is proven by the TwistedEdwards state machine (#1387).
Complex extension fields (Fp2)
Addition, subtraction and multiplication in the quadratic extensions
used by the BN254 and BLS12-381 pairings. The result is stored in f1.
Inputs need not be canonical; results are always canonical.
pub extern "C" fn syscall_bn254_complex_add(f1: &mut SyscallComplex256, f2: &SyscallComplex256)