npm package: @rustreexo/rustreexo-wasm-web
Description: WebAssembly bindings for Utreexo
Author: AbdelStark
Latest version: 0.1.9

# Rustreexo WASM

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/AbdelStark/rustreexo-wasm/workflows/CI/badge.svg)](https://github.com/AbdelStark/rustreexo-wasm/actions/workflows/ci.yml)
[![TypeScript Tests](https://github.com/AbdelStark/rustreexo-wasm/workflows/TypeScript%20Reference%20Tests/badge.svg)](https://github.com/AbdelStark/rustreexo-wasm/actions/workflows/typescript-tests.yml)
[![Performance Benchmark](https://github.com/AbdelStark/rustreexo-wasm/workflows/Performance%20Benchmark/badge.svg)](https://github.com/AbdelStark/rustreexo-wasm/actions/workflows/benchmark.yml)

WebAssembly (WASM) bindings for the [Rustreexo](https://github.com/mit-dci/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](https://www.npmjs.com/package/@rustreexo/rustreexo-wasm-web) | Web browsers (ES modules) | `npm install @rustreexo/rustreexo-wasm-web` |
| [@rustreexo/rustreexo-wasm-nodejs](https://www.npmjs.com/package/@rustreexo/rustreexo-wasm-nodejs) | Node.js applications | `npm install @rustreexo/rustreexo-wasm-nodejs` |
| [@rustreexo/rustreexo-wasm-bundler](https://www.npmjs.com/package/@rustreexo/rustreexo-wasm-bundler) | Webpack/Rollup/Vite | `npm install @rustreexo/rustreexo-wasm-bundler` |

### Quick Start

```javascript
// 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 →](./USAGE.md)**

## Installation

### Prerequisites

- [Rust](https://rustup.rs/) (latest stable)
- [wasm-pack](https://rustwasm.github.io/wasm-pack/installer/)

### Building from Source

```bash
# 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)

```javascript
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

```javascript
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
```javascript
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
```javascript
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:

```json
{
  "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

```bash
# Run Rust tests
cargo test

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

### Building for Different Targets

```bash
# 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:

```bash
wasm-pack build --dev --target web
```

## Examples

See the [examples](./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](LICENSE) file for details.

## Resources

- [Utreexo Paper](https://eprint.iacr.org/2019/611.pdf): Original research paper
- [rustreexo](https://github.com/mit-dci/rustreexo/tree/main): Rust Reference implementation