@hus-js-sdk/sdk

HUS SDK — Browser-based biometric uniqueness verification with Halo2 IPA ZK proofs.

Install

npm install @hus-js-sdk/sdk @tvmsdk/lib-web

Peer dependency: @tvmsdk/lib-web is required for network communication with the Acki Nacki blockchain.

Build from source

# Requires: rustup target add wasm32-unknown-unknown, wasm-pack
cd sdk/js
./build.sh

Usage

import { initHus, checkUniqueness } from '@hus-js-sdk/sdk';

// 1. One-time init (keygen takes 30–120s)
const hus = await initHus(12, {
    contractAddress: '0eaae957b452e19d62cb99ebc9b29a01204aba38b73595b2799b7803fa39eecf::0eaae957b452e19d62cb99ebc9b29a01204aba38b73595b2799b7803fa39eecf',
    networkEndpoint: 'https://shellnet.ackinacki.org/graphql',
    walletKeys: {
        public: '0x05adc183c0b10b882e01ce5a22be31e5b579092b4f519719cfd863c7fca9fab4',
        secret: '<wallet-secret-key>',
    },
});

// 2. Capture biometric data (e.g. keystroke)
const rawData = capture_keystroke(); // from WASM capture functions
if (rawData.length === 0) {
    // handle capture failure
}

// 3. Check uniqueness
const result = await checkUniqueness(hus, {
    modality: 0,            // 0=Keystroke, 1=Touch, 2=Gait
    rawData,
    seed: '<64-char-hex>',  // app-specific seed from on-chain config
    appId: '<your-app-id>',  // 64-char hex, registered on-chain
});

console.log(result.isUnique, result.score);
// => true, 100  (first registration)
// => false, 95  (duplicate — V_obf too close to existing)

API

| Export | Description | |---|---| | initHus(k, config) | Generate Halo2 IPA params + keys. Returns a handle. | | checkUniqueness(ctx, params) | Full pipeline: extract → project → prove → submit. | | isDuplicate(config, appId, commitmentHex) | Quick commitment-hash duplicate check. | | HusHandle | Opaque handle (from initHus). | | capture_keystroke() | Returns raw keystroke data as Float32Array. | | capture_touch() | Returns raw touch data as Float32Array. | | capture_gait() | Returns raw gait data as Float32Array. | | generateSeed() | Generate 32 random bytes as hex string. |

Pipeline

capture → extract → BioHashing → ZK prove → encode → GraphQL submit → verify result
   │          │            │          │          │             │
   WASM      WASM         WASM       WASM        JS          @tvmsdk/core

Architecture

• WASM core (hus_sdk_bg.wasm): Capture, extraction, BioHashing projection, Halo2 IPA proving, Poseidon commitment.
• JS layer (index.js + src/submission.js): Orchestrates pipeline, encodes ABI, signs with HUS wallet key, sends via @tvmsdk/core.
• On-chain (HusRegistry.sol v2.0.0): Per-app partition storage, V_obf fixed-point L₂ distance, per-app gas balance (fundGas), UniquenessResult event.

Requirements

• Browser with WebAssembly + Web Workers (for non-blocking keygen).
• @tvmsdk/lib-web peer dependency for network communication.
• For custom extractor models (ONNX, face/iris/voice): host on Hugging Face Hub or GitHub Releases, load via register_ml_extractor.