Advanced Build

Build Voltaire from source for maximum performance, custom targets, and supply chain security

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

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

Cross-Platform Builds

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

• Zig 0.15.1 Release Notes - Language reference
• Zig Build System Guide - Intermediate build system usage
• WebAssembly with Zig - WASM tutorial
• Zig Cross-Compilation - Target triples and flags
• WASM Target Reference - wasm32-wasi vs freestanding

Learn More

Getting Started

Standard installation via npm/bun

Branded Types

Type-safe primitives with zero overhead