Skip to main content
Voltaire is a Zig library at its core. The TypeScript and native bindings you install from npm are pre-built artifacts optimized for bundle size (ReleaseSmall). Building from source unlocks capabilities not available in the distributed packages.

Why Build From Source

Performance Optimization

npm distributions use ReleaseSmall which prioritizes bundle size over raw speed. Building from source with ReleaseFast yields measurable performance gains:
# Default npm build (size-optimized)
zig build build-ts-wasm           # ReleaseSmall - ~180KB WASM

# Performance build (speed-optimized)
zig build build-ts-wasm-fast      # ReleaseFast - ~240KB WASM, faster execution
For native FFI, the difference is even more significant since native code benefits from aggressive LLVM optimizations:
zig build build-ts-native         # ReleaseFast by default

Granular Tree-Shaking

The full Voltaire WASM bundle includes all primitives and crypto. If you only need specific functionality, build individual WASM modules:
# Build only what you need
zig build keccak256-wasm          # ~8KB  - just Keccak-256
zig build blake2-wasm             # ~12KB - just BLAKE2b
zig build address-wasm            # ~15KB - address operations

# Build all individual modules
zig build crypto-wasm
This produces wasm/crypto/*.wasm files you can load independently:
// Load only keccak256 (~8KB instead of ~180KB)
const keccak = await WebAssembly.instantiateStreaming(
  fetch('/wasm/crypto/keccak256.wasm')
);

Custom Platform Targets

Zig’s cross-compilation is best-in-class. Build for any platform supporting C FFI:
# Cross-compile for specific platforms
zig build -Dtarget=aarch64-linux          # ARM64 Linux (Raspberry Pi, AWS Graviton)
zig build -Dtarget=x86_64-windows         # Windows x64
zig build -Dtarget=riscv64-linux          # RISC-V Linux
zig build -Dtarget=mips-linux-gnueabi     # MIPS embedded

# Build all supported native platforms
zig build build-native-all
Pre-built distributions only ship macOS (arm64/x64), Linux (arm64/x64), and Windows (x64). Building from source lets you target:
  • Embedded systems (ARM Cortex, RISC-V, MIPS)
  • Exotic operating systems (FreeBSD, NetBSD, Haiku)
  • Custom architectures with C FFI support
  • WebAssembly variants (wasm32-freestanding vs wasm32-wasi)

Vendored Dependencies

Building from source means you control every byte of code that executes:
git clone https://github.com/voltaire-org/voltaire.git
cd voltaire
git submodule update --init --recursive   # Fetch all vendored deps
zig build                                  # Build everything from source
Benefits:
  • Audit everything - No opaque binaries, every line is reviewable
  • Contribute upstream - Make changes and submit PRs easily
  • LLM context - Full codebase available for AI-assisted development
  • Reproducible builds - Same source always produces same output

Supply Chain Security

The npm ecosystem has demonstrated systemic vulnerability to supply chain attacks that specifically target cryptocurrency applications.

Recent Attacks

September 2025: A phishing attack compromised 18 npm packages with 2+ billion weekly downloads (chalk, debug, ansi-styles). Malicious code injected wallet-draining malware that hooked window.ethereum and Solana APIs. December 2024: The @solana/web3.js library was backdoored (CVE-2024-54134) through spear-phishing, stealing private keys from developers. These attacks share a pattern:
  1. Compromise trusted maintainer accounts
  2. Inject malicious code into popular packages
  3. Target cryptocurrency wallets specifically
  4. Exist for hours before detection

Defense Through Source Builds

Building from source with vendored dependencies eliminates npm as an attack vector:
# Clone with all submodules pinned to specific commits
git clone --recurse-submodules https://github.com/voltaire-org/voltaire.git

# Verify git history and commit signatures
git log --show-signature

# Build entirely from source - no npm fetch during build
zig build
What this eliminates:
  • npm registry as single point of failure
  • Account compromise attacks (no accounts to compromise)
  • Malicious version injection (you control the commits)
  • Typosquatting attacks (no package names to confuse)
We encourage anyone handling significant value to build from source. The cryptocurrency industry faces unique risk from supply chain attacks, and source builds are the only complete mitigation.

Build Prerequisites

# Required
zig version          # 0.15.x (https://ziglang.org/download/)
cargo --version      # Rust 1.70+ (for crypto wrappers)

# Optional
bun --version        # For TypeScript tests/builds
go version           # For Go bindings

Quick Start

# Clone repository
git clone --recurse-submodules https://github.com/voltaire-org/voltaire.git
cd voltaire

# Install dependencies and build
zig build deps       # Fetch all dependencies
zig build           # Full build (Zig + C + Rust libraries)

# Run tests
zig build test      # All Zig tests

Build Commands Reference

Core Builds

CommandDescriptionUse Case
zig buildFull buildDevelopment
zig build -Doptimize=ReleaseFastPerformance buildBenchmarking
zig build -Doptimize=ReleaseSmallSize-optimizedDistribution
zig build -Doptimize=ReleaseSafeSafe releaseProduction with checks

TypeScript/WASM Builds

CommandDescriptionOutput
zig build build-ts-wasmWASM (ReleaseSmall)wasm/primitives.wasm
zig build build-ts-wasm-fastWASM (ReleaseFast)wasm/primitives-fast.wasm
zig build build-ts-nativeNative FFInative/libprimitives_ts_native.*
zig build crypto-wasmIndividual crypto moduleswasm/crypto/*.wasm

Cross-Platform Builds

CommandDescription
zig build build-native-allAll supported platforms
zig build build-native-darwin-arm64macOS Apple Silicon
zig build build-native-linux-x64Linux x64
zig build build-native-win32-x64Windows x64

Testing

CommandDescription
zig build testAll Zig tests
zig build test -Dtest-filter=keccakFilter tests
zig build test-tsTypeScript tests
zig build test-allZig + TypeScript + Go

WASM Build Modes

Zig supports two primary WASM targets:

wasm32-wasi (Default)

Used when C libraries are involved (blst, c-kzg, Rust crypto):
const wasm_target = b.resolveTargetQuery(.{
    .cpu_arch = .wasm32,
    .os_tag = .wasi,
});
  • Requires WASI runtime (browser polyfills available)
  • Full libc support
  • All crypto features enabled

wasm32-freestanding

For pure Zig code without C dependencies:
const wasm_target = b.resolveTargetQuery(.{
    .cpu_arch = .wasm32,
    .os_tag = .freestanding,
});
  • No WASI requirements
  • Smaller output
  • Limited to pure Zig implementations

Optimization Modes

ModeSizeSpeedSafetyUse Case
DebugLargeSlowFullDevelopment
ReleaseSafeMediumFastBounds checkedProduction
ReleaseFastMediumFastestMinimalBenchmarking
ReleaseSmallSmallestGoodMinimalDistribution
ReleaseSmall is 20-40% smaller than ReleaseFast but can be 10-30% slower for compute-intensive operations like cryptographic primitives.

External Resources

Learn More