npm package: @lof-lang/toolkit-browser
Description: Browser helpers for integrating Lof circuits with WASM artifacts.
Latest version: 0.1.0

# @lof-lang/toolkit-browser

Browser-friendly helpers for wiring Lof circuits into web applications. This package is designed to sit on top of the artifacts generated by `lof compile … --target wasm`, orchestrating the witness calculator and prover WASM modules without requiring a bespoke integration script.

> ⚠️ The WASM bindings themselves (e.g. `prover/lofit.js`) are expected to be generated by `wasm-pack` as part of the circuit packaging workflow. This package provides typed glue code and ergonomic APIs for loading and using those bindings.

## Installation

```bash
npm install @lof-lang/toolkit-browser
```

You also need the circuit-specific assets produced by:

```bash
lof compile path/to/circuit.lof --target wasm --output web/circuit
```

which yields directories such as `build/`, `keys/`, `witness/`, and `prover/`.

## Quick start

### Simple (auto-discovery)

The easiest way to use the toolkit is to specify `bundleRoot`, which automatically discovers all circuit artifacts:

```ts
import { createLofCircuit } from '@lof-lang/toolkit-browser';

const circuit = await createLofCircuit({
  bundleRoot: '/circuits/multiply',  // Points to your compiled circuit bundle
  publicSignals: ['a', 'b'],
  witnessSignals: ['c']
});

const { proofBytes, publicInputs } = await circuit.generateProof({
  a: '5',
  b: '7',
  c: '35'
});
```

With `bundleRoot`, the toolkit automatically constructs paths:
- `${bundleRoot}/build/${circuitName}.r1cs`
- `${bundleRoot}/keys/${circuitName}_pk.bin`
- `${bundleRoot}/witness/${circuitName}_witness_wasm.js`
- `${bundleRoot}/prover/lofit.js`

The circuit name is inferred from the last path segment of `bundleRoot` (e.g., `/circuits/multiply` → `multiply`).

### Explicit URLs

For full control, you can specify each URL individually:

```ts
const circuit = await createLofCircuit({
  publicSignals: ['a', 'b'],
  witnessSignals: ['c'],
  r1csUrl: '/circuit/build/circuit.r1cs',
  provingKeyUrl: '/circuit/keys/circuit_pk.bin',
  loadWitnessModule: () => import('/circuit/witness/circuit_witness_wasm.js'),
  loadProverModule: () => import('/circuit/prover/lofit.js'),
});

const { proofBytes, publicInputs } = await circuit.generateProof(userInputs);
```

All URLs are served relative to your web app. The `publicSignals` / `witnessSignals` arrays describe the signal order.

## API

### `createLofCircuit(options)`

Loads the WASM modules, fetches the R1CS and proving key, and returns a circuit instance.

**Options:**
- `publicSignals: string[]` – Ordered list of public input signal names (required)
- `witnessSignals: string[]` – Ordered list of private witness signal names (required)
- `bundleRoot?: string` – Base URL where circuit bundle is served (enables auto-discovery)
- `artifactName?: string` – Circuit name (defaults to last segment of `bundleRoot`)
- `r1csUrl?: string` – Explicit R1CS file URL (overrides auto-discovery)
- `provingKeyUrl?: string` – Explicit proving key URL (overrides auto-discovery)
- `witnessModuleUrl?: string` – Explicit witness WASM module URL
- `proverModuleUrl?: string` – Explicit prover WASM module URL
- `loadWitnessModule?: () => Promise<WitnessModule>` – Custom witness module loader
- `loadProverModule?: () => Promise<ProverModule>` – Custom prover module loader
- `r1cs?: Uint8Array` – Pre-loaded R1CS bytes (for offline use)
- `provingKey?: Uint8Array` – Pre-loaded proving key bytes (for offline use)

**Returns a circuit instance with:**
- `generateProof(inputs)` – computes the witness, builds ordered inputs, and invokes the prover
- `buildWitnessArray(witness)` – helper for packing witness objects into ordered arrays
- `buildPublicInputs(witness)` – converts witness output into a JSON-ready public input object
- `computeWitness(inputs)` – wraps the witness calculator for reuse or debugging
- `getProver()` – access to the underlying WASM prover instance

See the inline TypeScript docs for the full contract.