@iam-protocol/pulse-sdk 0.1.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@iam-protocol/pulse-sdk",
+  "version": "0.1.0",
+  "description": "Client-side SDK for IAM Protocol — sensor capture, TBH generation, ZK proof construction",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "circomlibjs": "^0.1.7",
+    "meyda": "^5.6.3",
+    "snarkjs": "^0.7.6"
+  },
+  "peerDependencies": {
+    "@coral-xyz/anchor": "^0.32.1",
+    "@solana/wallet-adapter-base": "^0.9.0",
+    "@solana/web3.js": "^1.98.0"
+  },
+  "peerDependenciesMeta": {
+    "@coral-xyz/anchor": {
+      "optional": true
+    },
+    "@solana/web3.js": {
+      "optional": true
+    },
+    "@solana/wallet-adapter-base": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@coral-xyz/anchor": "^0.32.1",
+    "@solana/spl-token": "^0.4.14",
+    "@solana/web3.js": "^1.98.0",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/challenge/lissajous.ts

@@ -0,0 +1,56 @@
+/**
+ * Generate Lissajous curve points for the touch tracing challenge.
+ * The user traces this shape on screen while speaking the phrase.
+ *
+ * x(t) = A * sin(a*t + delta)
+ * y(t) = B * sin(b*t)
+ */
+export interface LissajousParams {
+  a: number;
+  b: number;
+  delta: number;
+  points: number;
+}
+
+export interface Point2D {
+  x: number;
+  y: number;
+}
+
+/**
+ * Generate random Lissajous parameters for a challenge.
+ */
+export function randomLissajousParams(): LissajousParams {
+  const ratios = [
+    [1, 2],
+    [2, 3],
+    [3, 4],
+    [3, 5],
+    [4, 5],
+  ];
+  const pair = ratios[Math.floor(Math.random() * ratios.length)]!;
+  return {
+    a: pair[0]!,
+    b: pair[1]!,
+    delta: Math.PI * (0.25 + Math.random() * 0.5),
+    points: 200,
+  };
+}
+
+/**
+ * Generate Lissajous curve points normalized to [0, 1] range.
+ */
+export function generateLissajousPoints(params: LissajousParams): Point2D[] {
+  const { a, b, delta, points } = params;
+  const result: Point2D[] = [];
+
+  for (let i = 0; i < points; i++) {
+    const t = (i / points) * 2 * Math.PI;
+    result.push({
+      x: (Math.sin(a * t + delta) + 1) / 2,
+      y: (Math.sin(b * t) + 1) / 2,
+    });
+  }
+
+  return result;
+}

package/src/challenge/phrase.ts

@@ -0,0 +1,29 @@
+// Phonetically-balanced nonsense syllables for the voice challenge.
+// Designed to elicit diverse vocal patterns while preventing dictionary-based deepfake attacks.
+const SYLLABLES = [
+  "ba", "da", "fa", "ga", "ha", "ja", "ka", "la", "ma", "na",
+  "pa", "ra", "sa", "ta", "wa", "za", "be", "de", "fe", "ge",
+  "ke", "le", "me", "ne", "pe", "re", "se", "te", "we", "ze",
+  "bi", "di", "fi", "gi", "ki", "li", "mi", "ni", "pi", "ri",
+  "si", "ti", "wi", "zi", "bo", "do", "fo", "go", "ko", "lo",
+  "mo", "no", "po", "ro", "so", "to", "wo", "zo", "bu", "du",
+  "fu", "gu", "ku", "lu", "mu", "nu", "pu", "ru", "su", "tu",
+];
+
+/**
+ * Generate a random phonetically-balanced phrase for the voice challenge.
+ * Each phrase is 5-6 syllable pairs, forming nonsensical but speakable words.
+ */
+export function generatePhrase(wordCount: number = 5): string {
+  const words: string[] = [];
+  for (let w = 0; w < wordCount; w++) {
+    const syllableCount = 2 + Math.floor(Math.random() * 2); // 2-3 syllables per word
+    let word = "";
+    for (let s = 0; s < syllableCount; s++) {
+      const idx = Math.floor(Math.random() * SYLLABLES.length);
+      word += SYLLABLES[idx];
+    }
+    words.push(word);
+  }
+  return words.join(" ");
+}

package/src/config.ts

@@ -0,0 +1,40 @@
+// BN254 base field prime (for G1 point negation in proof_a)
+export const BN254_BASE_FIELD = BigInt(
+  "21888242871839275222246405745257275088696311157297823662689037894645226208583"
+);
+
+// BN254 scalar field prime (for salt generation, field element bounds)
+export const BN254_SCALAR_FIELD = BigInt(
+  "21888242871839275222246405745257275088548364400416034343698204186575808495617"
+);
+
+export const FINGERPRINT_BITS = 256;
+export const DEFAULT_THRESHOLD = 30;
+export const NUM_PUBLIC_INPUTS = 3;
+
+export const PROOF_A_SIZE = 64;
+export const PROOF_B_SIZE = 128;
+export const PROOF_C_SIZE = 64;
+export const TOTAL_PROOF_SIZE = 256;
+
+export const SIMHASH_SEED = "IAM-PROTOCOL-SIMHASH-V1";
+
+// Capture duration bounds (ms)
+export const MIN_CAPTURE_MS = 2000;
+export const MAX_CAPTURE_MS = 60000;
+export const DEFAULT_CAPTURE_MS = 7000;
+
+export const PROGRAM_IDS = {
+  iamAnchor: "GZYwTp2ozeuRA5Gof9vs4ya961aANcJBdUzB7LN6q4b2",
+  iamVerifier: "4F97jNoxQzT2qRbkWpW3ztC3Nz2TtKj3rnKG8ExgnrfV",
+  iamRegistry: "6VBs3zr9KrfFPGd6j7aGBPQWwZa5tajVfA7HN6MMV9VW",
+} as const;
+
+export interface PulseConfig {
+  cluster: "devnet" | "mainnet-beta" | "localnet";
+  rpcEndpoint?: string;
+  relayerUrl?: string;
+  zkeyUrl?: string;
+  wasmUrl?: string;
+  threshold?: number;
+}

package/src/extraction/kinematic.ts

@@ -0,0 +1,101 @@
+import type { MotionSample, TouchSample } from "../sensor/types";
+import { condense } from "./statistics";
+
+/**
+ * Extract kinematic features from motion (IMU) data.
+ * Computes jerk (3rd derivative) and jounce (4th derivative) of acceleration,
+ * then condenses each axis into statistics.
+ *
+ * Returns: ~48 values (6 axes × 2 derivatives × 4 stats)
+ */
+export function extractMotionFeatures(samples: MotionSample[]): number[] {
+  if (samples.length < 5) return new Array(48).fill(0);
+
+  // Extract acceleration and rotation time series
+  const axes = {
+    ax: samples.map((s) => s.ax),
+    ay: samples.map((s) => s.ay),
+    az: samples.map((s) => s.az),
+    gx: samples.map((s) => s.gx),
+    gy: samples.map((s) => s.gy),
+    gz: samples.map((s) => s.gz),
+  };
+
+  const features: number[] = [];
+
+  for (const values of Object.values(axes)) {
+    // Jerk = 3rd derivative of position = 1st derivative of acceleration
+    const jerk = derivative(values);
+    // Jounce = 4th derivative of position = 2nd derivative of acceleration
+    const jounce = derivative(jerk);
+
+    const jerkStats = condense(jerk);
+    const jounceStats = condense(jounce);
+
+    features.push(
+      jerkStats.mean,
+      jerkStats.variance,
+      jerkStats.skewness,
+      jerkStats.kurtosis,
+      jounceStats.mean,
+      jounceStats.variance,
+      jounceStats.skewness,
+      jounceStats.kurtosis
+    );
+  }
+
+  return features;
+}
+
+/**
+ * Extract kinematic features from touch data.
+ * Computes velocity and acceleration of touch coordinates,
+ * plus pressure and area statistics.
+ *
+ * Returns: ~32 values
+ */
+export function extractTouchFeatures(samples: TouchSample[]): number[] {
+  if (samples.length < 5) return new Array(32).fill(0);
+
+  const x = samples.map((s) => s.x);
+  const y = samples.map((s) => s.y);
+  const pressure = samples.map((s) => s.pressure);
+  const area = samples.map((s) => s.width * s.height);
+
+  const features: number[] = [];
+
+  // X velocity and acceleration
+  const vx = derivative(x);
+  const accX = derivative(vx);
+  features.push(...Object.values(condense(vx)));
+  features.push(...Object.values(condense(accX)));
+
+  // Y velocity and acceleration
+  const vy = derivative(y);
+  const accY = derivative(vy);
+  features.push(...Object.values(condense(vy)));
+  features.push(...Object.values(condense(accY)));
+
+  // Pressure statistics
+  features.push(...Object.values(condense(pressure)));
+
+  // Contact area statistics
+  features.push(...Object.values(condense(area)));
+
+  // Jerk of touch path
+  const jerkX = derivative(accX);
+  const jerkY = derivative(accY);
+  features.push(...Object.values(condense(jerkX)));
+  features.push(...Object.values(condense(jerkY)));
+
+  return features;
+}
+
+/** Compute discrete derivative (differences between consecutive values) */
+function derivative(values: number[]): number[] {
+  const d: number[] = [];
+  for (let i = 1; i < values.length; i++) {
+    d.push((values[i] ?? 0) - (values[i - 1] ?? 0));
+  }
+  return d;
+}

package/src/extraction/mfcc.ts

@@ -0,0 +1,93 @@
+import type { AudioCapture } from "../sensor/types";
+import { condense } from "./statistics";
+
+// Frame parameters matching the research paper spec
+const FRAME_SIZE = 400; // 25ms at 16kHz
+const HOP_SIZE = 160; // 10ms hop
+const NUM_MFCC = 13;
+
+/**
+ * Extract MFCC features from audio data.
+ * Computes 13 MFCCs per frame, plus delta and delta-delta coefficients,
+ * then condenses each coefficient's time series into 4 statistics.
+ *
+ * Returns: 13 coefficients × 3 (raw + delta + delta-delta) × 4 stats = 156 values
+ */
+export function extractMFCC(audio: AudioCapture): number[] {
+  const { samples, sampleRate } = audio;
+
+  // Lazy import of Meyda (browser/Node compatible)
+  let Meyda: any;
+  try {
+    Meyda = require("meyda");
+  } catch {
+    // Meyda not available — return zeros (fallback for environments without it)
+    return new Array(NUM_MFCC * 3 * 4).fill(0);
+  }
+
+  // Extract MFCCs per frame
+  const numFrames = Math.floor((samples.length - FRAME_SIZE) / HOP_SIZE) + 1;
+  if (numFrames < 3) return new Array(NUM_MFCC * 3 * 4).fill(0);
+
+  const mfccFrames: number[][] = [];
+
+  for (let i = 0; i < numFrames; i++) {
+    const start = i * HOP_SIZE;
+    const frame = samples.slice(start, start + FRAME_SIZE);
+
+    // Pad if frame is shorter than expected
+    const paddedFrame = new Float32Array(FRAME_SIZE);
+    paddedFrame.set(frame);
+
+    const features = Meyda.extract(["mfcc"], paddedFrame, {
+      sampleRate,
+      bufferSize: FRAME_SIZE,
+      numberOfMFCCCoefficients: NUM_MFCC,
+    });
+
+    if (features?.mfcc) {
+      mfccFrames.push(features.mfcc);
+    }
+  }
+
+  if (mfccFrames.length < 3) return new Array(NUM_MFCC * 3 * 4).fill(0);
+
+  // Compute delta (1st derivative) and delta-delta (2nd derivative)
+  const deltaFrames = computeDeltas(mfccFrames);
+  const deltaDeltaFrames = computeDeltas(deltaFrames);
+
+  // Condense each coefficient across all frames into 4 statistics
+  const features: number[] = [];
+
+  for (let c = 0; c < NUM_MFCC; c++) {
+    // Raw MFCC coefficient c across all frames
+    const raw = mfccFrames.map((f) => f[c] ?? 0);
+    const stats = condense(raw);
+    features.push(stats.mean, stats.variance, stats.skewness, stats.kurtosis);
+  }
+
+  for (let c = 0; c < NUM_MFCC; c++) {
+    const delta = deltaFrames.map((f) => f[c] ?? 0);
+    const stats = condense(delta);
+    features.push(stats.mean, stats.variance, stats.skewness, stats.kurtosis);
+  }
+
+  for (let c = 0; c < NUM_MFCC; c++) {
+    const dd = deltaDeltaFrames.map((f) => f[c] ?? 0);
+    const stats = condense(dd);
+    features.push(stats.mean, stats.variance, stats.skewness, stats.kurtosis);
+  }
+
+  return features;
+}
+
+/** Compute delta coefficients (frame-to-frame differences) */
+function computeDeltas(frames: number[][]): number[][] {
+  const deltas: number[][] = [];
+  for (let i = 1; i < frames.length; i++) {
+    const prev = frames[i - 1]!;
+    const curr = frames[i]!;
+    deltas.push(curr.map((v, j) => v - (prev[j] ?? 0)));
+  }
+  return deltas;
+}

package/src/extraction/statistics.ts

@@ -0,0 +1,59 @@
+import type { StatsSummary } from "./types";
+
+export function mean(values: number[]): number {
+  if (values.length === 0) return 0;
+  let sum = 0;
+  for (const v of values) sum += v;
+  return sum / values.length;
+}
+
+export function variance(values: number[], mu?: number): number {
+  if (values.length < 2) return 0;
+  const m = mu ?? mean(values);
+  let sum = 0;
+  for (const v of values) sum += (v - m) ** 2;
+  return sum / (values.length - 1);
+}
+
+export function skewness(values: number[]): number {
+  if (values.length < 3) return 0;
+  const n = values.length;
+  const m = mean(values);
+  const s = Math.sqrt(variance(values, m));
+  if (s === 0) return 0;
+  let sum = 0;
+  for (const v of values) sum += ((v - m) / s) ** 3;
+  return (n / ((n - 1) * (n - 2))) * sum;
+}
+
+export function kurtosis(values: number[]): number {
+  if (values.length < 4) return 0;
+  const n = values.length;
+  const m = mean(values);
+  const s2 = variance(values, m);
+  if (s2 === 0) return 0;
+  let sum = 0;
+  for (const v of values) sum += ((v - m) ** 4) / s2 ** 2;
+  const k =
+    ((n * (n + 1)) / ((n - 1) * (n - 2) * (n - 3))) * sum -
+    (3 * (n - 1) ** 2) / ((n - 2) * (n - 3));
+  return k;
+}
+
+export function condense(values: number[]): StatsSummary {
+  const m = mean(values);
+  return {
+    mean: m,
+    variance: variance(values, m),
+    skewness: skewness(values),
+    kurtosis: kurtosis(values),
+  };
+}
+
+export function fuseFeatures(
+  audio: number[],
+  motion: number[],
+  touch: number[]
+): number[] {
+  return [...audio, ...motion, ...touch];
+}

package/src/extraction/types.ts

@@ -0,0 +1,17 @@
+/** Statistical summary of a time series */
+export interface StatsSummary {
+  mean: number;
+  variance: number;
+  skewness: number;
+  kurtosis: number;
+}
+
+/** Feature vector from all sensor modalities */
+export interface FeatureVector {
+  audio: number[];
+  motion: number[];
+  touch: number[];
+}
+
+/** Concatenated feature vector for SimHash input */
+export type FusedFeatureVector = number[];

package/src/hashing/poseidon.ts

@@ -0,0 +1,92 @@
+import { BN254_SCALAR_FIELD, FINGERPRINT_BITS } from "../config";
+import type { PackedFingerprint, TBH, TemporalFingerprint } from "./types";
+
+// Lazy-initialized Poseidon instance
+let poseidonInstance: any = null;
+
+async function getPoseidon(): Promise<any> {
+  if (!poseidonInstance) {
+    const circomlibjs = await import("circomlibjs");
+    poseidonInstance = await (circomlibjs as any).buildPoseidon();
+  }
+  return poseidonInstance;
+}
+
+/**
+ * Pack 256-bit fingerprint into two 128-bit field elements.
+ * Little-endian bit ordering within each chunk (matches circuit's Bits2Num).
+ */
+export function packBits(fingerprint: TemporalFingerprint): PackedFingerprint {
+  let lo = BigInt(0);
+  for (let i = 0; i < 128; i++) {
+    if (fingerprint[i] === 1) {
+      lo += BigInt(1) << BigInt(i);
+    }
+  }
+
+  let hi = BigInt(0);
+  for (let i = 0; i < 128; i++) {
+    if (fingerprint[128 + i] === 1) {
+      hi += BigInt(1) << BigInt(i);
+    }
+  }
+
+  return { lo, hi };
+}
+
+/**
+ * Compute Poseidon commitment: Poseidon(pack_lo, pack_hi, salt).
+ * Matches the circuit's CommitmentCheck template exactly.
+ */
+export async function computeCommitment(
+  fingerprint: TemporalFingerprint,
+  salt: bigint
+): Promise<bigint> {
+  const poseidon = await getPoseidon();
+  const { lo, hi } = packBits(fingerprint);
+  const hash = poseidon([lo, hi, salt]);
+  return poseidon.F.toObject(hash) as bigint;
+}
+
+/**
+ * Generate a random salt within the BN254 scalar field.
+ */
+export function generateSalt(): bigint {
+  const bytes = new Uint8Array(31);
+  crypto.getRandomValues(bytes);
+  let val = BigInt(0);
+  for (let i = 0; i < bytes.length; i++) {
+    val = (val << BigInt(8)) + BigInt(bytes[i] ?? 0);
+  }
+  return val % BN254_SCALAR_FIELD;
+}
+
+/**
+ * Convert a BigInt to a 32-byte big-endian Uint8Array.
+ */
+export function bigintToBytes32(n: bigint): Uint8Array {
+  const bytes = new Uint8Array(32);
+  let val = n;
+  for (let i = 31; i >= 0; i--) {
+    bytes[i] = Number(val & BigInt(0xff));
+    val >>= BigInt(8);
+  }
+  return bytes;
+}
+
+/**
+ * Generate a complete TBH from a fingerprint.
+ */
+export async function generateTBH(
+  fingerprint: TemporalFingerprint,
+  salt?: bigint
+): Promise<TBH> {
+  const s = salt ?? generateSalt();
+  const commitment = await computeCommitment(fingerprint, s);
+  return {
+    fingerprint,
+    salt: s,
+    commitment,
+    commitmentBytes: bigintToBytes32(commitment),
+  };
+}

package/src/hashing/simhash.ts

@@ -0,0 +1,87 @@
+import { FINGERPRINT_BITS, SIMHASH_SEED } from "../config";
+import type { TemporalFingerprint } from "./types";
+
+// Mulberry32 PRNG: deterministic, fast, good distribution
+function mulberry32(seed: number): () => number {
+  let state = seed | 0;
+  return () => {
+    state = (state + 0x6d2b79f5) | 0;
+    let t = Math.imul(state ^ (state >>> 15), 1 | state);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+// Derive a numeric seed from the protocol seed string
+function deriveSeed(seedStr: string): number {
+  let hash = 0;
+  for (let i = 0; i < seedStr.length; i++) {
+    const ch = seedStr.charCodeAt(i);
+    hash = ((hash << 5) - hash + ch) | 0;
+  }
+  return hash;
+}
+
+let cachedHyperplanes: number[][] | null = null;
+let cachedDimension = 0;
+
+function getHyperplanes(dimension: number): number[][] {
+  if (cachedHyperplanes && cachedDimension === dimension) {
+    return cachedHyperplanes;
+  }
+
+  const rng = mulberry32(deriveSeed(SIMHASH_SEED));
+  const planes: number[][] = [];
+
+  for (let i = 0; i < FINGERPRINT_BITS; i++) {
+    const plane: number[] = [];
+    for (let j = 0; j < dimension; j++) {
+      // Random value in [-1, 1]
+      plane.push(rng() * 2 - 1);
+    }
+    planes.push(plane);
+  }
+
+  cachedHyperplanes = planes;
+  cachedDimension = dimension;
+  return planes;
+}
+
+/**
+ * Compute a 256-bit SimHash fingerprint from a feature vector.
+ * Uses deterministic random hyperplanes seeded from the protocol constant.
+ * Similar feature vectors produce fingerprints with low Hamming distance.
+ */
+export function simhash(features: number[]): TemporalFingerprint {
+  if (features.length === 0) {
+    return new Array(FINGERPRINT_BITS).fill(0);
+  }
+
+  const planes = getHyperplanes(features.length);
+  const fingerprint: TemporalFingerprint = [];
+
+  for (let i = 0; i < FINGERPRINT_BITS; i++) {
+    const plane = planes[i];
+    let dot = 0;
+    for (let j = 0; j < features.length; j++) {
+      dot += (features[j] ?? 0) * (plane?.[j] ?? 0);
+    }
+    fingerprint.push(dot >= 0 ? 1 : 0);
+  }
+
+  return fingerprint;
+}
+
+/**
+ * Compute Hamming distance between two fingerprints.
+ */
+export function hammingDistance(
+  a: TemporalFingerprint,
+  b: TemporalFingerprint
+): number {
+  let distance = 0;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) distance++;
+  }
+  return distance;
+}

package/src/hashing/types.ts

@@ -0,0 +1,16 @@
+/** 256-bit Temporal Fingerprint as an array of 0/1 values */
+export type TemporalFingerprint = number[];
+
+/** Temporal-Biometric Hash: commitment + data needed for re-verification */
+export interface TBH {
+  fingerprint: TemporalFingerprint;
+  salt: bigint;
+  commitment: bigint;
+  commitmentBytes: Uint8Array;
+}
+
+/** Packed field elements from bit packing (2 × 128-bit) */
+export interface PackedFingerprint {
+  lo: bigint;
+  hi: bigint;
+}