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
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')
);
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:
- Compromise trusted maintainer accounts
- Inject malicious code into popular packages
- Target cryptocurrency wallets specifically
- 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
| Command | Description | Use Case |
|---|
zig build | Full build | Development |
zig build -Doptimize=ReleaseFast | Performance build | Benchmarking |
zig build -Doptimize=ReleaseSmall | Size-optimized | Distribution |
zig build -Doptimize=ReleaseSafe | Safe release | Production with checks |
TypeScript/WASM Builds
| Command | Description | Output |
|---|
zig build build-ts-wasm | WASM (ReleaseSmall) | wasm/primitives.wasm |
zig build build-ts-wasm-fast | WASM (ReleaseFast) | wasm/primitives-fast.wasm |
zig build build-ts-native | Native FFI | native/libprimitives_ts_native.* |
zig build crypto-wasm | Individual crypto modules | wasm/crypto/*.wasm |
| Command | Description |
|---|
zig build build-native-all | All supported platforms |
zig build build-native-darwin-arm64 | macOS Apple Silicon |
zig build build-native-linux-x64 | Linux x64 |
zig build build-native-win32-x64 | Windows x64 |
Testing
| Command | Description |
|---|
zig build test | All Zig tests |
zig build test -Dtest-filter=keccak | Filter tests |
zig build test-ts | TypeScript tests |
zig build test-all | Zig + 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
| Mode | Size | Speed | Safety | Use Case |
|---|
Debug | Large | Slow | Full | Development |
ReleaseSafe | Medium | Fast | Bounds checked | Production |
ReleaseFast | Medium | Fastest | Minimal | Benchmarking |
ReleaseSmall | Smallest | Good | Minimal | Distribution |
ReleaseSmall is 20-40% smaller than ReleaseFast but can be 10-30% slower for compute-intensive operations like cryptographic primitives.
External Resources
Learn More