Modules

What they are

Each module is a small, self-contained object file — C, C++, or assembly — that the linker pulls into the final binary, overriding a specific symbol via --wrap=. Together they replace exactly the parts of .NET, musl and compiler-RT that a zkVM cannot honour, without editing a single line of upstream source: a .NET version bump is a rebase, not a fork.

A zkVM gives you far less than a Linux host: no kernel (so no syscalls, files, threads, signals or clock), no floating-point hardware, no compressed instructions, no randomness, and a requirement that every run be bit-for-bit reproducible. Each module closes one of those gaps.

Module	What it provides	Constraint it answers
ubootstrap	Runtime entry point — brings .NET up and calls `Main`	No glibc-style startup / OS loader
zkvm_zisk · zkvm_zisk_sim	`_start` + the memory layout the prover expects	No kernel; fixed prover memory map
pal	env, scheduling, files, time, memory, clean exit	No OS to answer syscalls
rhp	Allocation, dispatch, exception/exit handling	Single-threaded, never-collecting runtime
rhp_native	GC ref-assign + dispatch trampoline (asm)	No write barrier; bespoke dispatch
eh	Synthetic program headers for the unwinder	No loader, so nothing maps the real ones
tls	A single thread-local block	One thread, no dynamic loader
nofp	Soft-float and libm entry points that trap loudly	No floating-point hardware
zisk_subst	ILC-stage substitutions and C# snippets — data, not an object file	Managed code that carries FP
rng_stupid	Deterministic PRNG	No `/dev/urandom`; proofs must reproduce
security-stub	Security/GSS functions return failure	Unused network paths must still link
gs_cookie	Stack cookie pinned to a constant	No clock for entropy, no page protection
stdcppshim	`operator new` / `new[]`	Runtime’s C++ needs them without libc++
rust_sys	`sys_alloc_aligned`	Interop with adjacent Rust precompiles
ugc-zero	A GC that allocates but never collects	Short-lived proof workloads

Results

No upstream source is modified to make C# run in a zkVM: every adaptation is an object the linker pulls in, or — for zisk_subst — data the driver applies one stage earlier. The same set carries Nethermind’s StatelessExecutor end to end through a zkVM prover.

These modules are also the most heavily checked code in the repository: contracts, unit tests on the real ISA, fuzzing and machine-checked proofs. See Verification.

Under the hood

The rest of this page is developer reference: the wrapped symbols, the data structures and the assembly, module by module. The architecture page shows where these objects sit in the link line.

Modules live under src/bflat/modules/. Each has a module.c/module.cpp/module.S source, an optional module_params.yml listing its linker switches (mostly --wrap= declarations), and a compiled module.o from build.sh modules riscv64. The sections below follow roughly the order they matter at runtime.

ubootstrap — runtime entry point

File: modules/ubootstrap/module.cpp

A minimal re-implementation of the .NET NativeAOT bootstrap. It owns uBootstrap_main, which:

Initialises the runtime (RhInitialize).
Registers the OS module by handing the runtime the start/end of the __managedcode and __unbox linker-defined sections, plus the classlib callback table (failfast, exception helpers, etc.).
Invokes every module initialiser via InitializeModules.
Jumps into __managed__Main — the AOT-emitted C# entry point.

The argv it passes is a fake ["app"] because there is no real command-line on a zkVM.

zkvm_zisk / zkvm_zisk_sim — entry point and memory map

Files: modules/zkvm_zisk/{module.S,script.ld}, modules/zkvm_zisk_sim/{module.S,script.ld}

Two siblings. Both contain a tiny _start written in assembly that sets gp, sp, and tail-calls __libc_start_main(uBootstrap_main, …).

The linker scripts diverge:

Aspect	`zisk`	`zisk_sim`
Image base	Split ROM (`0x80000000`, 256 MiB) and RAM (`0xa0020000`, ~256 MiB)	`0x50000000` (see below)
Entry section	`.text.init` at the head of `.text`	Same
Managed-code anchors	`__start___managedcode` / `__stop___managedcode` and the `__unbox` pair	Same
Heap	`_kernel_heap_bottom..._kernel_heap_top` at the tail of RAM	`.heap` as a `NOLOAD` segment mirroring the zisk RAM window (`0xa0020000..0xbfff0000`)
Bump-pointer cell	`g_zk_bump_ptr` = `ORIGIN(ram)+LENGTH(ram)-8` = `0xbffefff8`; heap top lowered by 16 so the cell never overlaps	Same address, provided at the exact `0xbffefff8`
Discarded sections	`.debug*`, `.comment`, `.riscv.attributes`	(looser — kept for ease of debugging)

Both linker scripts force code that contains the C# entry point to land near the start of .text, which keeps the call distance short enough for non-PIC near-jump encodings.

The fixed bump-pointer cell. Both scripts reserve the top 8 bytes of the (real or mirrored) RAM map as a fixed-address cell, g_zk_bump_ptr at 0xbffefff8, holding the downward bump pointer. Because the address is fixed, the JIT can bake it into machine code as an lui/addiw/slli immediate with no relocation, and JIT-emitted inline allocation shares the same pointer with pal’s C allocator. pal/module.c does #define mem g_zk_bump_ptr so both views are literally the same word.

Why zisk_sim rebases to 0x50000000. pal/module.c reaches the heap symbols (g_zk_bump_ptr, _kernel_heap_top/_bottom) with PC-relative auipc/addi pairs, whose reach is ±2 GB. From the usual 0x10000 base the fixed cell at 0xbffefff8 is ~2.68 GB away and R_RISCV_PCREL_HI20 overflows; basing the image at 0x50000000 keeps the whole 0x50000000..0xbfff0000 span within ±2 GB. Real zisk avoids this by placing text in ROM at 0x80000000. The .heap is declared NOLOAD so the Linux loader maps it as zero pages (p_memsz > p_filesz), matching zkVM RAM being zero at boot — so g_zk_bump_ptr starts at 0 and is lazily initialised exactly as on real zisk, and the binary stays small.

pal — platform abstraction layer

File: modules/pal/module.c · symbols

The largest module by behavioural surface. It overrides musl primitives that .NET calls during startup or runtime:

Wrapped symbol	What we return
`getenv`	`"1"` for three CoreLib feature flags, `NULL` otherwise
`getcwd`	`/`
`getpid`, `getegid`, `geteuid`	`1`
`sched_getaffinity`, `sched_getcpu`	Always CPU 0
`sysconf`	Hard-coded answers (CPU count = 1, page size = 4 KiB, …)
`open`, `__stdio_write`	Failure (`-1`) — there is no filesystem and no console
`clock_gettime`	`-1` — time is non-deterministic; CoreLib must use defaults
`pthread_create`, `pthread_sigmask`	No-ops
`mmap`, `munmap`, `mlock*`	mmap routed to the bump allocator; lock calls are no-ops
`__libc_malloc_impl`, `__libc_realloc`, `__libc_free`	A custom downward bump allocator using the heap symbols from the linker script
`signal`, `sigaction`, `sched_yield`	No-ops
`syscall`	Whitelist: 0x11b → 0; everything else → `__real_syscall`
`exit`, `_Exit`, `abort`	Emit the real ZisK exit ecall (`a7 = 93`, `CAUSE_EXIT`) via `zkvm_raw_exit`

The bump allocator deserves a note: it grows downward from _kernel_heap_top, stores an 8-byte size header before each allocation, and never frees. That is enough to satisfy a managed runtime whose own GC sits on top — see the ugc-zero module below — and it removes any need for musl’s mallocng, which is large and uses syscalls. Managed allocation reaches it indirectly: objects come from the runtime’s own riscv64 AllocFast.S fast path, whose allocation-context budget uGCHeap::Alloc refills from this heap.

The bump pointer itself lives in a fixed-address cell — the top 8 bytes of RAM (g_zk_bump_ptr, 0xbffefff8), provided by the linker script — rather than a static variable. That lets JIT-emitted inline allocation reference it by a hardcoded constant address and share the very same pointer with this C allocator. zkVM RAM is zero at boot, so the cell starts at 0 and is lazily initialised to _kernel_heap_top on first use.

Clean termination. ZisK only treats an ecall with a7 == 93 (CAUSE_EXIT) as “program end”; its trap handler routes that to ROM_EXIT, whose instruction carries the end flag the emulator waits for. musl’s exit/_Exit issue exit_group (94), which ZisK does not recognise — the run would stop “not completed”. So pal wraps all three terminators to emit the real ZisK exit ecall (abort exits with 134 = 128 + SIGABRT).

rhp — Redhawk Platform shims

File: modules/rhp/module.c

Replacements for parts of the .NET runtime itself. Responsibilities:

P/Invoke transitions. RhpPInvoke/RhpReversePInvoke and their return halves become no-ops: the frames they build park a thread at a GC rendezvous that never comes in a single-threaded, never-collecting guest.
Subsystem stubs. EventPipe and EventSource registration, and — on the real zkVM, which has no terminal — console initialisation and SystemNative_Write.
Write barrier. RhBulkMoveWithWriteBarrier is a plain memmove; uGC never scans, so there is nothing to record.
Integer replacements for FP-carrying helpers. HashHelpers.IsPrime (one copy per assembly that embeds the shared source) and FrozenHashTable.CalcNumBuckets, whose managed bodies are stubbed by the ILC substitutions.
Fail-fast. FailFast, and under --remove-eh also RhpThrowEx — see below.

Managed exceptions under `--remove-eh`

With the unwind tables stripped a throw cannot be dispatched, so rhp wraps RhpThrowEx and the guest exits on it. (The default build dispatches exceptions normally; that path runs through the eh module and nothing here.)

A managed throw is lowered by the JIT to CORINFO_HELP_THROW, which calls RhpThrowEx with the exception object in a0. The wrapper hands that object to a weak ZkvmThrow symbol:

extern void ZkvmThrow(void *exceptionObj) __attribute__((weak));

void __wrap_RhpThrowEx(void *exceptionObj)
{
    if (ZkvmThrow != NULL) { ZkvmThrow(exceptionObj); return; }
    exit(1);
}

A program that exports ZkvmThrow via [UnmanagedCallersOnly(EntryPoint = "ZkvmThrow")] takes full control of the throw and receives the live Exception reference (the a0 pointer is the managed object reference). A program that doesn’t export it links fine — the weak reference stays null and the wrapper falls back to exit(1). No catch or finally runs on this path: the guest is gone. FailFast carries a message string, not an exception object, so it keeps the plain exit(1) path rather than routing through ZkvmThrow. See the ExceptionHandler sample.

To let the handler be entered from the throw path, RhpReversePInvoke and RhpReversePInvokeReturn are no-op’d. The real CoreLib transition attaches the thread and parks it at a GC-safe point — meaningful only for a native→managed boundary entered in preemptive mode. When a managed handler (an [UnmanagedCallersOnly] method) is entered from __wrap_RhpThrowEx, the thread is already cooperative, so the real transition would spin on a GC rendezvous that never comes in the single-threaded, never-collecting zkVM.

rhp_native — assembly RISC-V64 patches

File: modules/rhp_native/module.S

Two functions in hand-written RISC-V64 assembly:

__wrap_RhpAssignRefRiscV64 — a write-without-write-barrier reference assignment. Our GC has no write barrier, so the byref-assign helper must be a plain sd + post-increment.
__wrap_RhpCidResolve — a trampoline that tail-calls into the C resolver above, preserving the dispatch cell pointer that the runtime passes in t5.

tls — minimal thread-local storage

File: modules/tls/module.c

A static 100 KiB buffer plays the role of TLS. On first access we copy .tdata into it, zero .tbss, and return its address. There is one thread, so there is only ever one TLS block. Calls to __tls_get_addr, __init_tls, __init_tp, and __copy_tls are wrapped to use this buffer instead of the dynamic-loader logic in musl.

nofp — floating-point runtime stubs

File: modules/nofp/module.c

A definition for every soft-float compiler-RT helper (__addsf3, __divdf3, __floatsidf, __fixunsdfsi, …) and for the libm surface the runtime references (pow, sqrt, fmod, …). They exist because a RISC-V toolchain emits calls to these even when double appears only in code that is never reached; without the module the link fails with hundreds of unresolved symbols.

Every one of them traps: the body calls a noreturn helper that exits with status 255. Empty bodies would let a stray FP call return an undefined register value and the run continue with a silently wrong result — the worst failure mode for a proving system. The policy lives in one function (nofp_trap).

One exception, deliberately not a trap: __wrap_asprintf returns -1. It is referenced only by the cgroup parsing that pal already stubs out, and -1 is the documented failure result its callers handle — so if that path is ever reached it degrades instead of aborting.

eh — synthetic program headers for the unwinder

File: modules/eh/module.c

The runtime’s unwinder locates its DWARF tables through dl_iterate_phdr: it wants a PT_LOAD covering the queried PC and a PT_GNU_EH_FRAME over .eh_frame_hdr. A zkVM image has no program headers to walk — ZisK materialises memory from segments and jumps to the entry point, so there is no loader, no auxv, and the ELF header is not mapped.

libunwind reads only what the callback hands it, so this module wraps dl_iterate_phdr and describes the image from linker-script symbols: one PT_LOAD over the executable range (__image_text_start … __image_text_end, which the script extends across __managedcode and __unbox) and one PT_GNU_EH_FRAME over .eh_frame_hdr. The image is not position independent, so dlpi_addr is 0 and the vaddrs are absolute. When .eh_frame_hdr is empty — a --remove-eh link — only the load segment is reported and the lookup fails cleanly rather than decoding a stripped range.

The module is linked with the unwind tables, so --remove-eh drops both. Its contracts are proved with Frama-C; see Fuzzing and machine-checked proofs.

rng_stupid — deterministic PRNG

File: modules/rng_stupid/module.c

A linear-congruential PRNG seeded with 0x34095153. Wraps:

minipal_get_cryptographically_secure_random_bytes (returns 0 on success)
minipal_get_non_cryptographically_secure_random_bytes — feeds the hash seeds (Marvin, HashCode), so it matters for determinism even though nothing here is cryptographic
CryptoNative_GetRandomBytes (returns 1 on success — the opposite convention from the minipal pair, matching each caller’s expectation)
CryptoNative_EnsureOpenSslInitialized (returns 0; there is no OpenSSL)

zkVMs cannot consult /dev/urandom. A truly random number would also make the proof non-deterministic. The PRNG produces the same bytes for the same execution, which is exactly what proving requires; whether the caller’s algorithm tolerates non-cryptographic randomness is the caller’s problem.

security-stub — GSS / security functions

File: modules/security-stub/module.c

A long list of NetSecurityNative_* functions that all return -1. .NET’s networking stack references these even when no GSS is in use; returning failure is enough to prevent link errors and never gets executed at runtime in our workloads.

File: modules/gs_cookie/module.c

One line — __wrap___security_cookie = 0, placed in .data and bound via --wrap=__security_cookie.

Upstream .NET uses a GS cookie (stack canary) to catch buffer overruns: the JIT copies a process-global __security_cookie into each guarded frame and re-checks it on return, and the runtime seeds that global once at startup from a timer (minipal_lowres_ticks) into a read-only page. Neither half survives a zkVM:

No entropy. There is no clock, so a timer-seeded cookie is either constant (no protection anyway) or non-deterministic — a different value each run, which would make the proof non-reproducible.
No page protection. mprotect / PalVirtualProtect is a no-op in the pal layer, and a read-only .rodata cookie collides with the code/data-split layout the postprocessor manages.

So the cookie is pinned to a constant 0 and the JIT’s check always passes. This disables stack-canary defense-in-depth by design — an accepted trade-off for a single-threaded, deterministic guest with no untrusted in-process boundary. Forcing the symbol into .data also keeps it out of the read-only segment the postprocessor rewrites.

Two paths reach this symbol: with --stdlib dotnet the JIT still emits the check and binds it to this wrapped 0; for zerolib builds bflat instead tells ILC not to emit GS cookies at all (SettingsTunnel.EmitGSCookies = false, which bakes a constant into the code and emits no reference).

stdcppshim — C++ allocator shims

File: modules/stdcppshim/module.cpp

Just two operators: operator new(size_t) and operator new[](size_t), each forwarded to malloc. The .NET runtime’s GC code is C++ and uses new in a few places; without these shims we’d need to link a full libc++.

rust_sys — Rust compatibility layer

File: modules/rust_sys/module.c

A single function: __wrap_sys_alloc_aligned forwards to our bump allocator. Some Rust libraries used in adjacent precompile binaries call it; including the wrapper unconditionally costs nothing.

ugc-zero — minimal GC

Pulled from: dotnet-riscv release archive, unpacked into modules/ugc-zero/release/ by build.sh modules riscv64. The upstream source lives in NethermindEth/ugc.

A complete drop-in for the .NET GC: uGC.cpp, uGCHandleManager.cpp, uGCHandleStore.cpp, uGCHeap.cpp. It implements the GC interface but never collects — every allocation goes straight to the underlying bump allocator. For the proof workload this is acceptable because each execution is short and the heap is sized to hold its working set in full. --wrap=GC_Initialize and --wrap=GC_VersionInfo route the runtime’s GC discovery into this shim.

zisk_subst — ILC-stage substitutions

The odd one out: it ships no object file. zisk_subst carries the data that removes floating point from managed code before it is ever compiled to RISC-V64 — zisk.substitutions.xml (an ILLink substitutions file) and zisk.snippets.cs (whole-body C# replacements). Both are copied into the layout and consumed by the driver at guest-build time; the mechanism is described under Stage 1.5.

It is grouped with the modules because it answers the same kind of constraint in the same spirit — replace, don’t patch — but it acts one stage earlier, on IL rather than on symbols.

Build flow for modules

build.sh modules riscv64 walks every directory under src/bflat/modules/ and:

Compiles module.c with clang --target=riscv64-linux-gnu -march=rv64imad -mabi=lp64 -mcmodel=medany -flto=full -funified-lto.
Assembles module.S with riscv64-linux-gnu-as --march=rv64ima --mabi=lp64 — assembly is the one input that does not go through clang, since bitcode does not apply to it.
Compiles module.cpp with clang++ and the same flags as (1).
Patches the resulting object’s ABI marker byte to keep the linker happy when mixing soft-float-marked and hard-float-marked objects.
If module_params.yml declares a remote repo + tag + release file, downloads the release tarball into the module’s release/ directory.

Step 4 — patching offset 0x30 of the ELF e_flags — clears the hard-float bit so the bflat-side modules carry the lp64 (soft-float) marker in their ELF header.

That patch exists because the objects being linked together do not all agree on their marker. The modules are compiled -mabi=lp64 and the runtime’s native objects are tagged soft-float, but the C runtime bits that come from the distribution feed are built for rv64gc and still advertise a double-float ABI. ld.lld refuses to mix markers, so bflat normalizes them. The codegen on either side is unchanged — this is purely about the bits the linker checks for ABI consistency, and it is a workaround: the proper fix is for those artifacts to be built for the target ISA in the first place, which is what the runtime project is moving to.