Struct NAlloc 

pub struct NAlloc { /* private fields */ }

The global ZK-optimized allocator.

NAlloc provides a drop-in replacement for the standard Rust global allocator, with special optimizations for ZK-Proof workloads.

Memory Strategy

• Large allocations (>1MB): Routed to Polynomial Arena (FFT vectors)
• Small allocations: Routed to Scratch Arena (temporary buffers)
• Witness data: Use NAlloc::witness() for security-critical allocations

Thread Safety

This allocator uses lock-free atomic operations for initialization and allocation. It’s safe to use from multiple threads concurrently.

Fallback Behavior

If arena initialization fails (e.g., out of memory), NAlloc gracefully falls back to the system allocator rather than panicking. This ensures your application continues to function even under memory pressure.

Security: static Usage and Witness Wipe

When used as a #[global_allocator] static, Rust does not run Drop for statics. The impl Drop for NAlloc therefore only fires for non-static instances (e.g. NAlloc::try_new() in tests or scoped provers).

For the static use-case you must wipe witness memory manually before the prover exits:

use zk_nalloc::NAlloc;

#[global_allocator]
static ALLOC: NAlloc = NAlloc::new();

fn shutdown() {
    // Must be called explicitly — Drop will NOT run for a static.
    unsafe { ALLOC.witness().secure_wipe(); }
}

Failure to do so leaves witness data in RAM until the OS reclaims the pages, which may be observable by other processes on the same host.

Implementations

impl NAlloc

pub const fn new() -> Self

Create a new NAlloc instance.

The arenas are lazily initialized on the first allocation.

pub fn try_new() -> Result<Self, AllocFailed>

Try to create NAlloc and initialize arenas immediately.

Returns an error if arena allocation fails, allowing the caller to handle the failure gracefully.

pub fn is_fallback_mode(&self) -> bool

Check if NAlloc is operating in fallback mode (using system allocator).

pub fn is_initialized(&self) -> bool

Check if NAlloc is fully initialized with arenas.

pub fn witness(&self) -> WitnessArena

Access the witness arena directly.

Use this for allocating sensitive private inputs that need zero-initialization and secure wiping.

Panics

Panics if arena initialization failed. Use try_witness() for fallible access.

Example

use zk_nalloc::NAlloc;

let alloc = NAlloc::new();
let witness = alloc.witness();
let secret_ptr = witness.alloc(256, 8);
assert!(!secret_ptr.is_null());

// Securely wipe when done
unsafe { witness.secure_wipe(); }

pub fn try_witness(&self) -> Option<WitnessArena>

Try to access the witness arena.

Returns None if arena initialization failed.

pub fn polynomial(&self) -> PolynomialArena

Access the polynomial arena directly.

Use this for FFT/NTT-friendly polynomial coefficient vectors. Provides 64-byte alignment by default for SIMD operations.

Panics

Panics if arena initialization failed. Use try_polynomial() for fallible access.

Example

use zk_nalloc::NAlloc;

let alloc = NAlloc::new();
let poly = alloc.polynomial();
let coeffs = poly.alloc_fft_friendly(1024); // 1K coefficients
assert!(!coeffs.is_null());
assert_eq!((coeffs as usize) % 64, 0); // 64-byte aligned

pub fn try_polynomial(&self) -> Option<PolynomialArena>

Try to access the polynomial arena.

Returns None if arena initialization failed.

pub fn scratch(&self) -> Arc<BumpAlloc>

Access the scratch arena directly.

Use this for temporary computation space.

Panics

Panics if arena initialization failed. Use try_scratch() for fallible access.

pub fn try_scratch(&self) -> Option<Arc<BumpAlloc>>

Try to access the scratch arena.

Returns None if arena initialization failed.

pub unsafe fn reset_all(&self)

Reset all arenas, freeing all allocated memory.

The witness arena is securely wiped before reset.

Safety

This will invalidate all previously allocated memory.

Note

Does nothing if operating in fallback mode.

pub fn stats(&self) -> Option<ArenaStats>

Get statistics about arena usage.

Returns None if operating in fallback mode.

Useful for monitoring memory consumption and tuning arena sizes.

pub fn stats_or_default(&self) -> ArenaStats

Get statistics, returning default stats if in fallback mode.

Trait Implementations

impl Default for NAlloc

fn default() -> Self

Returns the “default value” for a type.

impl Drop for NAlloc

fn drop(&mut self)

Executes the destructor for this type.

impl GlobalAlloc for NAlloc

unsafe fn alloc(&self, layout: Layout) -> *mut u8

Allocates memory as described by the given layout.

unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout)

Deallocates the block of memory at the given ptr pointer with the given layout.

unsafe fn realloc( &self, ptr: *mut u8, layout: Layout, new_size: usize, ) -> *mut u8

Shrinks or grows a block of memory to the given new_size in bytes. The block is described by the given ptr pointer and layout.

unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8

Behaves like alloc, but also ensures that the contents are set to zero before being returned.

impl Send for NAlloc

impl Sync for NAlloc