Rustreexo WASM

WebAssembly (WASM) bindings for the Rustreexo Utreexo accumulator implementation. This package provides high-performance, cryptographically secure Utreexo accumulators that can run in web browsers and Node.js environments.

What is Utreexo?

Utreexo is a dynamic hash-based accumulator designed for Bitcoin's UTXO set. It provides:

• Compact State: O(log N) storage instead of O(N) for the full UTXO set
• Inclusion Proofs: Cryptographic proofs that elements exist in the accumulator
• Dynamic Updates: Efficient addition and removal of elements
• Verification: Fast proof verification without storing the full set

Features

• 🚀 High Performance: Compiled from Rust to WebAssembly for near-native speed
• 🌐 Universal: Works in browsers, Node.js, and other JavaScript environments
• 📦 Type Safe: Full TypeScript definitions included
• 🔧 Easy Integration: Simple JavaScript/TypeScript API

📦 JavaScript/TypeScript Usage

Ready-to-use packages are available on NPM for different environments:

| Package | Environment | Installation | |---------|-------------|--------------| | @rustreexo/rustreexo-wasm-web | Web browsers (ES modules) | npm install @rustreexo/rustreexo-wasm-web | | @rustreexo/rustreexo-wasm-nodejs | Node.js applications | npm install @rustreexo/rustreexo-wasm-nodejs | | @rustreexo/rustreexo-wasm-bundler | Webpack/Rollup/Vite | npm install @rustreexo/rustreexo-wasm-bundler |

Quick Start

// Browser
import init, { WasmStump, WasmPollard } from '@rustreexo/rustreexo-wasm-web';
await init();

// Node.js
const { WasmStump, WasmPollard } = require('@rustreexo/rustreexo-wasm-nodejs');

// Create accumulators
const stump = new WasmStump();
const pollard = new WasmPollard();

📚 See complete usage guide with examples →

Installation

Prerequisites

• Rust (latest stable)
• wasm-pack

Building from Source

# Clone the repository
git clone https://github.com/AbdelStark/rustreexo-wasm.git
cd rustreexo-wasm

# Build the WASM package
wasm-pack build --target web --out-dir pkg

# For Node.js target
wasm-pack build --target nodejs --out-dir pkg-node

Usage

Browser (ES Modules)

import init, { WasmStump, WasmPollard } from './pkg/rustreexo_wasm.js';

async function example() {
  // Initialize the WASM module
  await init();

  // Create a new Stump (lightweight accumulator)
  const stump = new WasmStump();
  
  // Add elements to the accumulator
  const emptyProof = JSON.stringify({ targets: [], hashes: [] });
  const elements = [
    "6e340b9cffb37a989ca544e6bb780a2c78901d3fb33738768511a30617afa01d",
    "4bf5122f344554c53bde2ebb8cd2b7e3d1600ad631c385a5d7cce23c7785459a"
  ];
  
  stump.modify(emptyProof, elements, []);
  
  console.log(`Accumulator has ${stump.num_leaves()} leaves`);
  console.log(`Root hashes:`, stump.roots());
}

example();

Node.js

const { WasmStump, WasmPollard } = require('./pkg-node/rustreexo_wasm.js');

// Create and use accumulators
const stump = new WasmStump();
const pollard = new WasmPollard();

// Generate proofs with Pollard
const proof = pollard.prove_single("6e340b9cffb37a989ca544e6bb780a2c78901d3fb33738768511a30617afa01d");

// Verify proofs with Stump
const isValid = stump.verify(proof, ["6e340b9cffb37a989ca544e6bb780a2c78901d3fb33738768511a30617afa01d"]);
console.log("Proof is valid:", isValid);

API Reference

WasmStump

Lightweight accumulator that only stores roots and leaf count. Perfect for clients that need to verify proofs but don't generate them.

Constructor

const stump = new WasmStump();

Methods

• num_leaves(): bigint - Returns the number of leaves in the accumulator
• roots(): string[] - Returns array of root hash strings
• modify(proof: string, addHashes: string[], delHashes: string[]): void - Modifies the accumulator
• verify(proof: string, hashes: string[]): boolean - Verifies an inclusion proof
• to_json(): string - Serializes the stump to JSON
• from_json(json: string): WasmStump - Creates stump from JSON (static method)

WasmPollard

Full accumulator implementation that can generate proofs. Stores the complete tree structure.

Constructor

const pollard = new WasmPollard();

Methods

• num_leaves(): bigint - Returns the number of leaves
• roots(): string[] - Returns array of root hash strings
• modify(proof: string, additions: string, delHashes: string[]): void - Modifies the accumulator
• prove_single(hash: string): string - Generates proof for a single element
• batch_proof(hashes: string[]): string - Generates batch proof for multiple elements
• verify(proof: string, hashes: string[]): boolean - Verifies inclusion proofs
• from_roots(roots: string[], leaves: bigint): WasmPollard - Creates from existing state (static method)

Proof Format

Proofs are JSON strings with the following structure:

{
  "targets": [0, 2, 5],
  "hashes": [
    "4bf5122f344554c53bde2ebb8cd2b7e3d1600ad631c385a5d7cce23c7785459a",
    "9576f4ade6e9bc3a6458b506ce3e4e890df29cb14cb5d3d887672aef55647a2b"
  ]
}

• targets: Array of leaf positions being proven
• hashes: Array of hash strings needed for the proof path

Development

Running Tests

# Run Rust tests
cargo test

# Run WASM tests
wasm-pack test --chrome --headless

Building for Different Targets

# Web (ES modules)
wasm-pack build --target web --out-dir pkg

# Node.js (CommonJS)
wasm-pack build --target nodejs --out-dir pkg-node

# Bundler (for webpack/rollup)
wasm-pack build --target bundler --out-dir pkg-bundler

Debugging

Enable debug mode for detailed logging:

wasm-pack build --dev --target web

Examples

See the examples directory for complete usage examples:

• Basic Usage: Simple accumulator operations
• Proof Generation: Creating and verifying proofs
• Batch Operations: Efficient batch updates
• Browser Integration: Complete web application
• Node.js Server: Server-side accumulator management

License

This project is licensed under the MIT License - see the LICENSE file for details.

Resources

• Utreexo Paper: Original research paper
• rustreexo: Rust Reference implementation