Skip to main content

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, or p).
  • 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.
  • hints variants. The signatures below are for the ziskos crate, which has no hints feature (Cargo rejects features = ["hints"]). The same source is also built as the ziskos-hints crate, where the hints feature is on by default and each syscall gains a trailing hints: &mut Vec<u64> parameter (exported with a hints_ symbol prefix).
Changed in 1.4.0-alpha: direct operands

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​

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