nx9-chronoseal-rs/docs/WASM_BUILD.md

ChronoSeal WASM Build Guide

ChronoSeal uses a Rust-based WASM runtime to power browser-side attestation logic, signing, hash chaining, VM execution, and mutation commitment preview.

Why WASM

The WASM runtime provides a deterministic, sandboxed environment for the following tasks:

• generate Ed25519 keypairs in-browser
• sign canonical heartbeat payloads
• execute randomized VM opcode programs
• compute Blake3 hash chain progression
• preview and commit synthetic gene mutations

This enables server/client parity and prevents the private key from leaving the browser runtime.

Build Requirements

Install the Rust WASM target and wasm-pack:

rustup target add wasm32-unknown-unknown
cargo install wasm-pack

Verify:

wasm-pack --version

Build the WASM Module

From the repository root:

wasm-pack build wasm --target web --release
rm -rf frontend/pkg
mv wasm/pkg frontend/pkg

--target web produces an ES module compatible with the existing frontend JavaScript.

--release enables optimizations for runtime performance and size.

Output

After a successful build, frontend/pkg/ contains:

• antibot_wasm.js
• antibot_wasm_bg.wasm
• antibot_wasm_bg.js
• antibot_wasm.d.ts
• antibot_wasm_bg.d.ts
• package.json

The frontend expects the WASM package under frontend/pkg/.

Runtime Exports

The WASM module exports the following functions:

• generate_keypair() — generate a new Ed25519 keypair and return public key hex
• get_public_key() — return the current public key hex
• sign_message(msg) — sign a UTF-8 payload and return the hex signature
• compute_next_hash(prev, ts, entropy, stack, salt) — compute the next Blake3 chain hash
• run_program(b64) — execute a base64 VM program and return stack state
• init_gene_state(gene_size) — initialise the synthetic gene buffer
• preview_gene_commitment(order_b64) — preview the next gene commitment from a mutation order
• commit_gene_preview() — commit the previewed mutation after successful heartbeat
• discard_gene_preview() — discard the previewed mutation after rejection or error
• current_gene_commitment() — return the current committed gene commitment

Browser Integration

The frontend imports the generated module like this:

import init, {
  generate_keypair,
  sign_message,
  compute_next_hash,
  run_program,
  init_gene_state,
  preview_gene_commitment,
  commit_gene_preview,
  discard_gene_preview,
  current_gene_commitment
} from './pkg/antibot_wasm.js';

await init() must be called before invoking any other exported function.

Deployment Note

The .wasm binary must be served with the correct MIME type:

Content-Type: application/wasm

The built-in Axum static file handler already sets the appropriate MIME type for .wasm files.

Build Script

Use the convenience script:

bash scripts/build.sh

This builds the WASM package, moves it into frontend/pkg/, and builds the server binary.

Recommended Development Flow

• For WASM-only changes:

wasm-pack build wasm --target web
rm -rf frontend/pkg
mv wasm/pkg frontend/pkg

• For server-only changes:

cargo build -p server

Notes

Generated files in wasm/pkg/ and frontend/pkg/ are not tracked in source control. They are build artifacts and should be regenerated as part of the release workflow.