@l.x/hashcash-native 1.0.2 → 1.0.3

package/src/benchmark.ts

@@ -0,0 +1,152 @@
+/**
+ * Hashcash Benchmark Utility
+ *
+ * Compares native vs JS hashcash implementation performance.
+ * Run this in your app to measure the speedup from native code.
+ */
+/** biome-ignore-all lint/suspicious/noConsole: dev only file */
+
+import { HashcashNative } from './index'
+
+interface BenchmarkResult {
+  implementation: 'native' | 'js'
+  difficulty: number
+  counter: string | null
+  attempts: number
+  timeMs: number
+}
+
+interface BenchmarkSummary {
+  native: BenchmarkResult
+  js: BenchmarkResult
+  speedup: number
+}
+
+/**
+ * Run a single benchmark with the native implementation
+ */
+export async function benchmarkNative(difficulty: number): Promise<BenchmarkResult> {
+  const challenge = {
+    difficulty,
+    subject: 'Benchmark',
+    nonce: 'dGVzdC1ub25jZS1iZW5jaG1hcms=', // "test-nonce-benchmark" in base64
+    maxProofLength: 10_000_000,
+  }
+
+  const startTime = performance.now()
+  const result = await HashcashNative.findProof({ challenge })
+  const endTime = performance.now()
+
+  return {
+    implementation: 'native',
+    difficulty,
+    counter: result?.counter ?? null,
+    attempts: result?.attempts ?? 0,
+    timeMs: endTime - startTime,
+  }
+}
+
+/**
+ * Run a single benchmark with the JS implementation
+ * Requires passing in the findProof function from @l.x/sessions
+ */
+export async function benchmarkJS(
+  difficulty: number,
+  findProof: (params: {
+    challenge: {
+      difficulty: number
+      subject: string
+      algorithm: 'sha256'
+      nonce: string
+      max_proof_length: number
+    }
+  }) => { counter: string; attempts: number; timeMs: number } | null,
+): Promise<BenchmarkResult> {
+  const challenge = {
+    difficulty,
+    subject: 'Benchmark',
+    algorithm: 'sha256' as const,
+    nonce: 'dGVzdC1ub25jZS1iZW5jaG1hcms=',
+    max_proof_length: 10_000_000,
+  }
+
+  const result = findProof({ challenge })
+
+  return {
+    implementation: 'js',
+    difficulty,
+    counter: result?.counter ?? null,
+    attempts: result?.attempts ?? 0,
+    timeMs: result?.timeMs ?? 0,
+  }
+}
+
+/**
+ * Run a comparison benchmark between native and JS implementations
+ */
+export async function runBenchmark(
+  difficulty: number,
+  jsFindProof: (params: {
+    challenge: {
+      difficulty: number
+      subject: string
+      algorithm: 'sha256'
+      nonce: string
+      max_proof_length: number
+    }
+  }) => { counter: string; attempts: number; timeMs: number } | null,
+): Promise<BenchmarkSummary> {
+  console.log(`\n🏁 Starting hashcash benchmark (difficulty=${difficulty})...\n`)
+
+  // Run native first
+  console.log('⏱️  Running native implementation...')
+  const nativeResult = await benchmarkNative(difficulty)
+  console.log(`   Native: ${nativeResult.timeMs.toFixed(2)}ms (${nativeResult.attempts} attempts)`)
+
+  // Run JS
+  console.log('⏱️  Running JS implementation...')
+  const jsResult = await benchmarkJS(difficulty, jsFindProof)
+  console.log(`   JS: ${jsResult.timeMs.toFixed(2)}ms (${jsResult.attempts} attempts)`)
+
+  const speedup = jsResult.timeMs / nativeResult.timeMs
+
+  console.log(`\n📊 Results:`)
+  console.log(`   Native: ${nativeResult.timeMs.toFixed(2)}ms`)
+  console.log(`   JS:     ${jsResult.timeMs.toFixed(2)}ms`)
+  console.log(`   Speedup: ${speedup.toFixed(2)}x faster with native\n`)
+
+  return {
+    native: nativeResult,
+    js: jsResult,
+    speedup,
+  }
+}
+
+/**
+ * Run benchmarks at multiple difficulty levels
+ */
+export async function runFullBenchmark(
+  jsFindProof: (params: {
+    challenge: {
+      difficulty: number
+      subject: string
+      algorithm: 'sha256'
+      nonce: string
+      max_proof_length: number
+    }
+  }) => { counter: string; attempts: number; timeMs: number } | null,
+): Promise<void> {
+  console.log('═══════════════════════════════════════════')
+  console.log('   HASHCASH NATIVE vs JS BENCHMARK')
+  console.log('═══════════════════════════════════════════')
+
+  const difficulties = [1, 2]
+
+  for (const difficulty of difficulties) {
+    await runBenchmark(difficulty, jsFindProof)
+  }
+
+  console.log('═══════════════════════════════════════════')
+  console.log('   BENCHMARK COMPLETE')
+  console.log('═══════════════════════════════════════════\n')
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+import { NitroModules } from 'react-native-nitro-modules'
+import type { Hashcash } from './specs/Hashcash.nitro'
+
+/**
+ * Native hashcash proof-of-work solver.
+ *
+ * Uses platform-native SHA256 implementation for better performance
+ * than JavaScript-based hashing.
+ */
+export const HashcashNative = NitroModules.createHybridObject<Hashcash>('Hashcash')
+
+export {
+  benchmarkJS,
+  benchmarkNative,
+  runBenchmark,
+  runFullBenchmark,
+} from './benchmark'
+export type {
+  FindProofParams,
+  Hashcash,
+  HashcashChallenge,
+  HashcashProofResult,
+} from './specs/Hashcash.nitro'

package/src/specs/Hashcash.nitro.ts

@@ -0,0 +1,64 @@
+import type { HybridObject } from 'react-native-nitro-modules'
+
+/**
+ * Challenge parameters for hashcash proof-of-work
+ */
+export interface HashcashChallenge {
+  /** Number of zero bytes required at start of hash */
+  difficulty: number
+  /** Subject string (e.g., "Lx") */
+  subject: string
+  /** Base64-encoded nonce from backend */
+  nonce: string
+  /** Maximum counter value to try */
+  maxProofLength: number
+}
+
+/**
+ * Result of a successful proof-of-work computation
+ */
+export interface HashcashProofResult {
+  /** The counter value that produced a valid hash */
+  counter: string
+  /** Base64-encoded SHA256 hash */
+  hashBase64: string
+  /** Number of hash attempts made */
+  attempts: number
+  /** Time taken in milliseconds */
+  timeMs: number
+}
+
+/**
+ * Parameters for findProof
+ */
+export interface FindProofParams {
+  challenge: HashcashChallenge
+  rangeStart?: number
+  rangeSize?: number
+}
+
+/**
+ * Native hashcash proof-of-work solver.
+ *
+ * Computes SHA256 hashes to find a counter value that produces
+ * a hash with the required number of leading zero bytes.
+ */
+export interface Hashcash
+  extends HybridObject<{
+    ios: 'swift'
+    android: 'kotlin'
+  }> {
+  /**
+   * Find a proof-of-work solution for the given challenge.
+   *
+   * @param params - Challenge parameters and optional range limits
+   * @returns ProofResult if found, undefined if cancelled or no solution in range
+   */
+  findProof(params: FindProofParams): Promise<HashcashProofResult | undefined>
+
+  /**
+   * Cancel any in-progress proof search.
+   * The current findProof call will return undefined.
+   */
+  cancel(): void
+}

package/index.d.ts

@@ -1 +0,0 @@
-export * from '@luxexchange/hashcash-native';

package/index.js

@@ -1 +0,0 @@
-module.exports = require('@luxexchange/hashcash-native');