Skip to main content

Crypto Reference

All crypto modules in src/crypto/. Implementations use Zig core with Rust/C for complex curves.

Hash Functions

Keccak256

Primary Ethereum hash function. Used for addresses, transaction hashes, storage keys.
import * as Keccak256 from "@voltaire/crypto/Keccak256";

// For string input, use hashString
const hash = Keccak256.hashString("hello");
// For Uint8Array input, use hash
const hash2 = Keccak256.hash(new Uint8Array([1, 2, 3]));
// For hex input, use hashHex
Keccak256.hashHex("0x1234");
Files:
  • Keccak256/index.ts - TypeScript API
  • keccak256.wasm.ts - WASM variant
  • keccak256_accel.zig - Hardware-accelerated implementation
  • keccak_asm.zig - Assembly-optimized
  • keccak_wrapper.rs - Rust keccak-asm wrapper
Performance: ~500ns native, ~2μs WASM

SHA256

SHA-256 for EVM precompile and general use.
import * as SHA256 from "@voltaire/crypto/SHA256";

const hash = SHA256.hash(data);
SHA256.hashHex(data);
Files:
  • SHA256/index.ts - TypeScript API
  • sha256.wasm.ts - WASM variant
  • sha256_accel.zig - Hardware-accelerated (SHA-NI)

Blake2

Blake2b hashing (EVM precompile 0x09).
import * as Blake2 from "@voltaire/crypto/Blake2";

Blake2.hash(data, { digestLength: 32 });
Blake2.f(rounds, h, m, t, f);  // Blake2f compression function
Files:
  • Blake2/index.ts - TypeScript API
  • blake2.zig - Zig implementation
  • blake2_c.zig - C bindings (optional)
  • blake2.fuzz.zig - Fuzz tests

Ripemd160

RIPEMD-160 for Bitcoin compatibility (EVM precompile 0x03).
import * as Ripemd160 from "@voltaire/crypto/Ripemd160";

const hash = Ripemd160.hash(data);
Files:
  • Ripemd160/index.ts - TypeScript API
  • ripemd160.zig - Zig implementation
  • ripemd160_c.zig - C bindings

Digital Signatures

Secp256k1

Bitcoin/Ethereum ECDSA curve. Core signing primitive.
import * as Secp256k1 from "@voltaire/crypto/Secp256k1";

// Sign message hash
const signature = Secp256k1.sign(messageHash, privateKey);

// Verify signature
const valid = Secp256k1.verify(signature, messageHash, publicKey);

// Recover public key from signature
const pubkey = Secp256k1.recover(signature, messageHash, recoveryId);

// Key operations
const pubkey = Secp256k1.derivePublicKey(privateKey);
const compressed = Secp256k1.compressPublicKey(pubkey);
const uncompressed = Secp256k1.decompressPublicKey(compressed);
Methods:
  • sign(hash, privateKey) - ECDSA sign
  • verify(signature, hash, publicKey) - Verify signature
  • recover(signature, hash, v) - Recover public key
  • getPublicKey(privateKey) - Derive public key
  • compressPublicKey(pubkey) - Compress to 33 bytes
  • decompressPublicKey(pubkey) - Decompress to 65 bytes
  • isValidPrivateKey(key) - Validate private key
  • isValidPublicKey(key) - Validate public key
Files:
  • Secp256k1/index.ts - TypeScript API
  • secp256k1.zig - Zig implementation
  • secp256k1.wasm.ts - WASM variant
  • secp256k1.bench.zig - Benchmarks
  • secp256k1.fuzz.zig - Fuzz tests

Ed25519

EdDSA signatures. Used by some L2s and alt chains.
import * as Ed25519 from "@voltaire/crypto/Ed25519";

const signature = Ed25519.sign(message, privateKey);
const valid = Ed25519.verify(signature, message, publicKey);
const pubkey = Ed25519.getPublicKey(privateKey);
Files:
  • Ed25519/index.ts - TypeScript API
  • ed25519.zig - Zig implementation
  • ed25519.wasm.ts - WASM variant

P256

NIST P-256 (secp256r1). Used by hardware wallets and WebAuthn.
import * as P256 from "@voltaire/crypto/P256";

const signature = P256.sign(hash, privateKey);
const valid = P256.verify(signature, hash, publicKey);
Files:
  • P256/index.ts - TypeScript API
  • p256.zig - Zig implementation
  • p256.wasm.ts - WASM variant

Elliptic Curves & Pairings

BN254

BN254 (alt_bn128) curve for zkSNARKs. Used by EVM precompiles 0x06-0x08.
import * as BN254 from "@voltaire/crypto/BN254";

// G1 operations
const sum = BN254.g1Add(p1, p2);
const product = BN254.g1Mul(point, scalar);

// G2 operations
const g2Sum = BN254.g2Add(p1, p2);
const g2Product = BN254.g2Mul(point, scalar);

// Pairing check
const valid = BN254.pairing(g1Points, g2Points);
Implementation: Dual implementation
  • bn254.zig - Pure Zig implementation
  • bn254_arkworks.zig - Rust arkworks wrapper (higher performance)
  • bn254_ark_c.zig - C interface to Rust
  • bn254_wrapper.rs - Rust arkworks bindings
Files:
  • bn254.ts - TypeScript API (auto-selects best impl)
  • bn254.wasm.ts - WASM variant
  • bn254.ark.ts - arkworks-specific exports

BLS12-381

BLS12-381 curve for beacon chain consensus. EVM precompiles 0x0B-0x13 (Prague). Uses blst C library for production performance.
// Via precompiles (no direct TS API yet)
import { execute } from "@voltaire/evm/precompiles";

// G1 operations via precompile
const result = execute(0x0B, g1AddInput);  // BLS12_G1_ADD
Precompile Operations:
AddressOperation
0x0BG1 Add
0x0CG1 Mul
0x0DG1 MSM (multi-scalar multiplication)
0x0EG2 Add
0x0FG2 Mul
0x10G2 MSM
0x11Pairing
0x12Map Fp to G1
0x13Map Fp2 to G2
Files (in src/evm/precompiles/):
  • bls12_g1_add.zig, bls12_g1_mul.zig, bls12_g1_msm.zig
  • bls12_g2_add.zig, bls12_g2_mul.zig, bls12_g2_msm.zig
  • bls12_pairing.zig
  • bls12_map_fp_to_g1.zig, bls12_map_fp2_to_g2.zig

KZG Commitments

KZG

Kate-Zaverucha-Goldberg polynomial commitments for EIP-4844 blob transactions.
import * as KZG from "@voltaire/crypto/KZG";

// Blob to commitment
const commitment = KZG.blobToCommitment(blob);

// Compute proof
const proof = KZG.computeProof(blob, z);

// Verify proof
const valid = KZG.verifyProof(commitment, z, y, proof);

// Batch verification
const valid = KZG.verifyBlobProof(blob, commitment, proof);
Dependencies:
  • c-kzg-4844 - C library (lib/c-kzg-4844)
  • Trusted setup: kzg_trusted_setup.zig
Limitation: Not available in WASM (library too large, requires trusted setup file) Files:
  • KZG/index.ts - TypeScript API
  • c_kzg.zig - C bindings
  • kzg_setup.zig - Setup loading
  • kzg_trusted_setup.zig - Embedded trusted setup

Typed Data (EIP-712)

EIP712

Typed structured data hashing and signing.
import * as EIP712 from "@voltaire/crypto/EIP712";

const domain = {
  name: "MyContract",
  version: "1",
  chainId: 1n,
  verifyingContract: "0x...",
};

const types = {
  Person: [
    { name: "name", type: "string" },
    { name: "wallet", type: "address" },
  ],
};

const message = {
  name: "Alice",
  wallet: "0x...",
};

// Hash typed data
const hash = EIP712.hashTypedData({ domain, types, primaryType: "Person", message });

// Sign
const signature = EIP712.signTypedData({ domain, types, primaryType: "Person", message, privateKey });
Files:
  • EIP712/index.ts - TypeScript API (placeholder/WIP)
  • eip712.zig - Zig implementation
  • eip712.wasm.ts - WASM variant

Symmetric Encryption

AesGcm

AES-256-GCM authenticated encryption.
import * as AesGcm from "@voltaire/crypto/AesGcm";

// Encrypt
const { ciphertext, tag } = AesGcm.encrypt(plaintext, key, nonce);

// Decrypt
const plaintext = AesGcm.decrypt(ciphertext, key, nonce, tag);
Files:
  • AesGcm/index.ts - TypeScript API
  • aes_gcm.zig - Zig implementation

X25519

Elliptic curve Diffie-Hellman key exchange.
import * as X25519 from "@voltaire/crypto/X25519";

// Generate key pair
const { publicKey, privateKey } = X25519.generateKeyPair();

// Compute shared secret
const sharedSecret = X25519.sharedSecret(myPrivateKey, theirPublicKey);
Files:
  • X25519/index.ts - TypeScript API
  • x25519.zig - Zig implementation
  • x25519.wasm.ts - WASM variant

Wallet Derivation

Bip39

Mnemonic seed phrase generation and validation.
import * as Bip39 from "@voltaire/crypto/Bip39";

// Generate mnemonic
const mnemonic = Bip39.generateMnemonic(128);  // 12 words

// Validate
const valid = Bip39.validateMnemonic(mnemonic);

// To seed
const seed = Bip39.mnemonicToSeed(mnemonic, passphrase);
Files:
  • Bip39/index.ts - TypeScript API (uses @scure/bip39)
  • bip39.test.ts - Tests

HDWallet

Hierarchical Deterministic wallet derivation (BIP-32).
import * as HDWallet from "@voltaire/crypto/HDWallet";

// From seed
const master = HDWallet.fromSeed(seed);

// Derive path
const account = HDWallet.derive(master, "m/44'/60'/0'/0/0");

// Get keys
const privateKey = HDWallet.privateKey(account);
const publicKey = HDWallet.publicKey(account);
const address = HDWallet.address(account);
Files:
  • HDWallet/index.ts - TypeScript API (uses @scure/bip32)
  • hdwallet.test.ts - Tests
  • signers/ - Hardware wallet signers (Ledger, Trezor)

Hardware Acceleration

CPU Feature Detection

Detects available CPU features for optimal implementation selection.
// cpu_features.zig
const features = cpu_features.detect();
if (features.sha) {
    // Use SHA-NI instructions
}
if (features.aes) {
    // Use AES-NI instructions
}

Accelerated Implementations

AlgorithmAccelerationSpeedup
Keccak256Assembly (keccak-asm)3-5x
SHA256SHA-NI instructions4-6x
AES-GCMAES-NI instructions5-10x
Files:
  • cpu_features.zig - Feature detection
  • keccak256_accel.zig - Accelerated Keccak
  • sha256_accel.zig - Accelerated SHA256
  • keccak_asm.zig - Assembly Keccak

Modular Exponentiation

ModExp

Modular exponentiation for MODEXP precompile (0x05).
// modexp.zig
const result = modexp.calculate(base, exp, mod);
Files:
  • modexp.zig - Zig implementation

Module Summary

ModulePurposeNativeWASM
Keccak256Ethereum hash
SHA256SHA-2 hash
Blake2Blake2b hash
Ripemd160Legacy hash
Secp256k1ECDSA signing
Ed25519EdDSA signing
P256NIST curve
BN254zkSNARK curve
BLS12-381Consensus curve
KZGBlob commitments
EIP712Typed data
AesGcmEncryption
X25519Key exchange
Bip39Mnemonics
HDWalletKey derivation
Native indicates the Bun native bindings. In Node.js, use the regular TypeScript API or the WASM variants.
WASM Limitations:
  • BLS12-381: Requires blst C library
  • KZG: Requires trusted setup file and c-kzg library