@iam-protocol/pulse-sdk 0.1.0

package/src/identity/anchor.ts

@@ -0,0 +1,75 @@
+import { PROGRAM_IDS } from "../config";
+import type { IdentityState, StoredVerificationData } from "./types";
+
+const STORAGE_KEY = "iam-protocol-verification-data";
+
+/**
+ * Fetch identity state from the on-chain IdentityState PDA.
+ */
+export async function fetchIdentityState(
+  walletPubkey: string,
+  connection: any
+): Promise<IdentityState | null> {
+  try {
+    const { PublicKey } = await import("@solana/web3.js");
+    const anchor = await import("@coral-xyz/anchor");
+
+    const programId = new PublicKey(PROGRAM_IDS.iamAnchor);
+    const [identityPda] = PublicKey.findProgramAddressSync(
+      [Buffer.from("identity"), new PublicKey(walletPubkey).toBuffer()],
+      programId
+    );
+
+    const accountInfo = await connection.getAccountInfo(identityPda);
+    if (!accountInfo) return null;
+
+    // Decode using Anchor's BorshAccountsCoder
+    const idl = await anchor.Program.fetchIdl(programId, {
+      connection,
+    } as any);
+    if (!idl) return null;
+
+    const coder = new anchor.BorshAccountsCoder(idl);
+    const decoded = coder.decode("identityState", accountInfo.data);
+
+    return {
+      owner: decoded.owner.toBase58(),
+      creationTimestamp: decoded.creationTimestamp.toNumber(),
+      lastVerificationTimestamp: decoded.lastVerificationTimestamp.toNumber(),
+      verificationCount: decoded.verificationCount,
+      trustScore: decoded.trustScore,
+      currentCommitment: new Uint8Array(decoded.currentCommitment),
+      mint: decoded.mint.toBase58(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store verification data locally for re-verification.
+ * Uses localStorage (browser) or in-memory fallback (Node.js).
+ */
+export function storeVerificationData(data: StoredVerificationData): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
+  } catch {
+    // localStorage not available (Node.js or private browsing)
+    inMemoryStore = data;
+  }
+}
+
+/**
+ * Load previously stored verification data.
+ */
+export function loadVerificationData(): StoredVerificationData | null {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return inMemoryStore;
+    return JSON.parse(raw);
+  } catch {
+    return inMemoryStore;
+  }
+}
+
+let inMemoryStore: StoredVerificationData | null = null;

package/src/identity/types.ts

@@ -0,0 +1,18 @@
+/** On-chain identity state (mirrors the Anchor program's IdentityState) */
+export interface IdentityState {
+  owner: string;
+  creationTimestamp: number;
+  lastVerificationTimestamp: number;
+  verificationCount: number;
+  trustScore: number;
+  currentCommitment: Uint8Array;
+  mint: string;
+}
+
+/** Local storage of previous verification data (needed for re-verification) */
+export interface StoredVerificationData {
+  fingerprint: number[];
+  salt: string;
+  commitment: string;
+  timestamp: number;
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+// Main SDK
+export { PulseSDK, PulseSession } from "./pulse";
+
+// Configuration
+export type { PulseConfig } from "./config";
+export { PROGRAM_IDS, DEFAULT_THRESHOLD, FINGERPRINT_BITS, MIN_CAPTURE_MS, MAX_CAPTURE_MS, DEFAULT_CAPTURE_MS } from "./config";
+
+// Hashing
+export type { TemporalFingerprint, TBH, PackedFingerprint } from "./hashing/types";
+export { simhash, hammingDistance } from "./hashing/simhash";
+export {
+  computeCommitment,
+  generateSalt,
+  generateTBH,
+  packBits,
+  bigintToBytes32,
+} from "./hashing/poseidon";
+
+// Feature extraction
+export type { StatsSummary, FeatureVector, FusedFeatureVector } from "./extraction/types";
+export { mean, variance, skewness, kurtosis, condense, fuseFeatures } from "./extraction/statistics";
+
+// Proof generation
+export type { SolanaProof, CircuitInput, ProofResult } from "./proof/types";
+export { serializeProof, toBigEndian32 } from "./proof/serializer";
+export { generateProof, generateSolanaProof, prepareCircuitInput } from "./proof/prover";
+
+// Submission
+export type { SubmissionResult, VerificationResult } from "./submit/types";
+export { submitViaWallet } from "./submit/wallet";
+export { submitViaRelayer } from "./submit/relayer";
+
+// Identity
+export type { IdentityState, StoredVerificationData } from "./identity/types";
+export { fetchIdentityState, storeVerificationData, loadVerificationData } from "./identity/anchor";
+
+// Sensor types
+export type { AudioCapture, MotionSample, TouchSample, SensorData, CaptureOptions, CaptureStage, StageState } from "./sensor/types";
+
+// Challenge
+export { generatePhrase } from "./challenge/phrase";
+export { randomLissajousParams, generateLissajousPoints } from "./challenge/lissajous";
+export type { LissajousParams, Point2D } from "./challenge/lissajous";

package/src/proof/prover.ts

@@ -0,0 +1,87 @@
+import type { TBH } from "../hashing/types";
+import type { CircuitInput, ProofResult, SolanaProof } from "./types";
+import { serializeProof } from "./serializer";
+import { DEFAULT_THRESHOLD } from "../config";
+
+// Use dynamic import for snarkjs (it's a CJS module)
+let snarkjsModule: any = null;
+
+async function getSnarkjs(): Promise<any> {
+  if (!snarkjsModule) {
+    snarkjsModule = await import("snarkjs");
+  }
+  return snarkjsModule;
+}
+
+/**
+ * Prepare circuit input from current and previous TBH data.
+ */
+export function prepareCircuitInput(
+  current: TBH,
+  previous: TBH,
+  threshold: number = DEFAULT_THRESHOLD
+): CircuitInput {
+  return {
+    ft_new: current.fingerprint,
+    ft_prev: previous.fingerprint,
+    salt_new: current.salt.toString(),
+    salt_prev: previous.salt.toString(),
+    commitment_new: current.commitment.toString(),
+    commitment_prev: previous.commitment.toString(),
+    threshold: threshold.toString(),
+  };
+}
+
+/**
+ * Generate a Groth16 proof for the Hamming distance circuit.
+ *
+ * @param input - Circuit input (fingerprints, salts, commitments, threshold)
+ * @param wasmPath - Path or URL to iam_hamming.wasm
+ * @param zkeyPath - Path or URL to iam_hamming_final.zkey
+ */
+export async function generateProof(
+  input: CircuitInput,
+  wasmPath: string,
+  zkeyPath: string
+): Promise<ProofResult> {
+  const snarkjs = await getSnarkjs();
+  const { proof, publicSignals } = await snarkjs.groth16.fullProve(
+    input,
+    wasmPath,
+    zkeyPath
+  );
+  return { proof, publicSignals };
+}
+
+/**
+ * Generate a proof and serialize it for Solana submission.
+ */
+export async function generateSolanaProof(
+  current: TBH,
+  previous: TBH,
+  wasmPath: string,
+  zkeyPath: string,
+  threshold?: number
+): Promise<SolanaProof> {
+  const input = prepareCircuitInput(current, previous, threshold);
+  const { proof, publicSignals } = await generateProof(
+    input,
+    wasmPath,
+    zkeyPath
+  );
+  return serializeProof(proof, publicSignals);
+}
+
+/**
+ * Verify a proof locally using snarkjs (for debugging/testing).
+ */
+export async function verifyProofLocally(
+  proof: any,
+  publicSignals: string[],
+  vkeyPath: string
+): Promise<boolean> {
+  const snarkjs = await getSnarkjs();
+  const fs = await import("fs");
+  const vk = JSON.parse(fs.readFileSync(vkeyPath, "utf-8"));
+  return snarkjs.groth16.verify(vk, publicSignals, proof);
+}

package/src/proof/serializer.ts

@@ -0,0 +1,79 @@
+import {
+  BN254_BASE_FIELD,
+  PROOF_A_SIZE,
+  PROOF_B_SIZE,
+  PROOF_C_SIZE,
+  TOTAL_PROOF_SIZE,
+  NUM_PUBLIC_INPUTS,
+} from "../config";
+import type { RawProof, SolanaProof } from "./types";
+
+/**
+ * Convert a decimal string to a 32-byte big-endian Uint8Array.
+ */
+export function toBigEndian32(decStr: string): Uint8Array {
+  let n = BigInt(decStr);
+  const bytes = new Uint8Array(32);
+  for (let i = 31; i >= 0; i--) {
+    bytes[i] = Number(n & BigInt(0xff));
+    n >>= BigInt(8);
+  }
+  return bytes;
+}
+
+/**
+ * Negate a G1 y-coordinate for groth16-solana proof_a format.
+ */
+function negateG1Y(yDecStr: string): Uint8Array {
+  const y = BigInt(yDecStr);
+  const yNeg = (BN254_BASE_FIELD - y) % BN254_BASE_FIELD;
+  return toBigEndian32(yNeg.toString());
+}
+
+/**
+ * Serialize an snarkjs proof into the 256-byte format groth16-solana expects.
+ *
+ * proof_a: 64 bytes (x + negated y)
+ * proof_b: 128 bytes (G2 with reversed coordinate ordering: c1 before c0)
+ * proof_c: 64 bytes (x + y)
+ */
+export function serializeProof(
+  proof: RawProof,
+  publicSignals: string[]
+): SolanaProof {
+  // proof_a: x (32 bytes) + negated y (32 bytes)
+  const a0 = toBigEndian32(proof.pi_a[0]!);
+  const a1 = negateG1Y(proof.pi_a[1]!);
+  const proofA = new Uint8Array(PROOF_A_SIZE);
+  proofA.set(a0, 0);
+  proofA.set(a1, 32);
+
+  // proof_b: G2 reversed coordinate ordering
+  const b00 = toBigEndian32(proof.pi_b[0]![1]!); // c1 first
+  const b01 = toBigEndian32(proof.pi_b[0]![0]!); // c0 second
+  const b10 = toBigEndian32(proof.pi_b[1]![1]!);
+  const b11 = toBigEndian32(proof.pi_b[1]![0]!);
+  const proofB = new Uint8Array(PROOF_B_SIZE);
+  proofB.set(b00, 0);
+  proofB.set(b01, 32);
+  proofB.set(b10, 64);
+  proofB.set(b11, 96);
+
+  // proof_c: x + y (no negation)
+  const c0 = toBigEndian32(proof.pi_c[0]!);
+  const c1 = toBigEndian32(proof.pi_c[1]!);
+  const proofC = new Uint8Array(PROOF_C_SIZE);
+  proofC.set(c0, 0);
+  proofC.set(c1, 32);
+
+  // Combine into single 256-byte blob
+  const proofBytes = new Uint8Array(TOTAL_PROOF_SIZE);
+  proofBytes.set(proofA, 0);
+  proofBytes.set(proofB, PROOF_A_SIZE);
+  proofBytes.set(proofC, PROOF_A_SIZE + PROOF_B_SIZE);
+
+  // Public inputs as 32-byte big-endian arrays
+  const publicInputs = publicSignals.map((s) => toBigEndian32(s));
+
+  return { proofBytes, publicInputs };
+}

package/src/proof/types.ts

@@ -0,0 +1,31 @@
+/** Serialized proof ready for on-chain submission */
+export interface SolanaProof {
+  proofBytes: Uint8Array;
+  publicInputs: Uint8Array[];
+}
+
+/** Raw snarkjs proof output */
+export interface RawProof {
+  pi_a: string[];
+  pi_b: string[][];
+  pi_c: string[];
+  protocol: string;
+  curve: string;
+}
+
+/** Circuit input for proof generation */
+export interface CircuitInput {
+  ft_new: number[];
+  ft_prev: number[];
+  salt_new: string;
+  salt_prev: string;
+  commitment_new: string;
+  commitment_prev: string;
+  threshold: string;
+}
+
+/** Proof generation result */
+export interface ProofResult {
+  proof: RawProof;
+  publicSignals: string[];
+}