@luxexchange/sessions 1.0.0

package/src/challenge-solvers/hashcash/core.test.ts

@@ -0,0 +1,314 @@
+import {
+  checkDifficulty,
+  computeHash,
+  findProof,
+  formatHashcashString,
+  type HashcashChallenge,
+  verifyProof,
+} from '@luxfi/sessions/src/challenge-solvers/hashcash/core'
+import { describe, expect, it } from 'vitest'
+
+describe('hashcash core', () => {
+  // Backend example data for testing
+  const backendExample: HashcashChallenge = {
+    difficulty: 1,
+    subject: 'Lux',
+    algorithm: 'sha256',
+    nonce: 'Qlquffem7d8RrL6fmveE68XK0KxcoczdiVpFrV1qeUk=',
+    max_proof_length: 1000,
+  }
+
+  // Basic smoke test
+  it('exports all required functions', () => {
+    expect(checkDifficulty).toBeDefined()
+    expect(computeHash).toBeDefined()
+    expect(findProof).toBeDefined()
+    expect(verifyProof).toBeDefined()
+    expect(formatHashcashString).toBeDefined()
+  })
+
+  describe('checkDifficulty', () => {
+    it('validates difficulty 1 (1 full zero byte)', () => {
+      // Backend treats difficulty as number of zero BYTES
+      // difficulty=1 means first byte must be 0
+      const validHash = new Uint8Array([0, 255, 255, 255])
+      expect(checkDifficulty(validHash, 1)).toBe(true)
+
+      const invalidHash = new Uint8Array([1, 255, 255, 255])
+      expect(checkDifficulty(invalidHash, 1)).toBe(false)
+
+      const invalidHash2 = new Uint8Array([0b00000001, 255, 255, 255]) // Even 1 bit set fails
+      expect(checkDifficulty(invalidHash2, 1)).toBe(false)
+    })
+
+    it('validates difficulty 2 (2 full zero bytes)', () => {
+      // First two bytes must be all zeros
+      const validHash = new Uint8Array([0, 0, 255, 255])
+      expect(checkDifficulty(validHash, 2)).toBe(true)
+
+      const invalidHash = new Uint8Array([0, 1, 255, 255]) // Second byte not zero
+      expect(checkDifficulty(invalidHash, 2)).toBe(false)
+    })
+
+    it('validates difficulty 0 (no requirement)', () => {
+      const anyHash = new Uint8Array([255, 255, 255, 255])
+      expect(checkDifficulty(anyHash, 0)).toBe(true)
+    })
+  })
+
+  describe('computeHash', () => {
+    it('produces consistent SHA-256 hashes', async () => {
+      const params = {
+        subject: 'test',
+        nonce: 'AQIDBA==', // Base64 string
+        counter: 42,
+      }
+
+      const hash1 = await computeHash(params)
+      const hash2 = await computeHash(params)
+
+      expect(hash1).toEqual(hash2)
+      expect(hash1.length).toBe(32) // SHA-256 is 32 bytes
+    })
+
+    it('works with real backend nonce', async () => {
+      const hash = await computeHash({
+        subject: backendExample.subject,
+        nonce: backendExample.nonce, // Use nonce string directly
+        counter: 0,
+      })
+
+      expect(hash).toBeDefined()
+      expect(hash.length).toBe(32)
+    })
+
+    it('hashes colon-separated string format like backend', async () => {
+      // Test that we're using the backend's expected format: "${subject}:${nonce}:${counter}"
+      const nonceString = 'AQIDBA=='
+
+      const hash = await computeHash({
+        subject: 'Lux',
+        nonce: nonceString,
+        counter: 123,
+      })
+
+      // The hash should be of the string "Lux:AQIDBA==:123"
+      expect(hash).toBeDefined()
+      expect(hash.length).toBe(32)
+
+      // Verify the expected string format
+      const expectedString = `Lux:${nonceString}:123`
+      expect(expectedString).toBe('Lux:AQIDBA==:123')
+    })
+
+    it('matches known SHA-256 test vector', async () => {
+      // computeHash("Lux:AQIDBA==:123") verified against @noble/hashes/webcrypto SHA-256
+      const hash = await computeHash({
+        subject: 'Lux',
+        nonce: 'AQIDBA==',
+        counter: 123,
+      })
+
+      const expectedHex = '222c2db479a1ff907a329fc3ff8e99b1f19f0695d938b74ccd95323b9c853510'
+      const actualHex = Array.from(hash)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('')
+
+      expect(actualHex).toBe(expectedHex)
+    })
+  })
+
+  describe('findProof', () => {
+    it('finds a valid proof for difficulty 1', async () => {
+      const challenge: HashcashChallenge = {
+        ...backendExample,
+        difficulty: 1,
+        max_proof_length: 10000, // Increase range for testing
+      }
+
+      const proof = await findProof({ challenge })
+
+      expect(proof).not.toBeNull()
+      if (proof) {
+        expect(proof.counter).toBeDefined()
+        expect(proof.hash).toBeDefined()
+        expect(proof.attempts).toBeGreaterThan(0)
+        expect(checkDifficulty(proof.hash, 1)).toBe(true)
+      }
+    })
+
+    it('respects max_proof_length limit', async () => {
+      const challenge: HashcashChallenge = {
+        ...backendExample,
+        difficulty: 20, // High difficulty unlikely to be found
+        max_proof_length: 100,
+      }
+
+      const proof = await findProof({
+        challenge,
+        rangeSize: challenge.max_proof_length,
+      })
+
+      // Should return null since difficulty 20 (20 zero bytes) is impossible in 100 attempts
+      expect(proof).toBeNull()
+    })
+
+    it('returns null when shouldStop signals cancellation', async () => {
+      let calls = 0
+      const shouldStop = (): boolean => {
+        calls++
+        // Stop after the first batch boundary check
+        return calls >= 2
+      }
+
+      const challenge: HashcashChallenge = {
+        ...backendExample,
+        difficulty: 20, // High difficulty so it won't find a proof naturally
+        max_proof_length: 100_000,
+      }
+
+      const proof = await findProof({
+        challenge,
+        shouldStop,
+        batchSize: 64,
+      })
+
+      expect(proof).toBeNull()
+      // shouldStop was called at least twice (once to pass, once to cancel)
+      expect(calls).toBeGreaterThanOrEqual(2)
+    })
+
+    it('finds proof with custom rangeStart', async () => {
+      // First, find a valid proof starting from 0
+      const challenge: HashcashChallenge = {
+        ...backendExample,
+        difficulty: 1,
+        max_proof_length: 10000,
+      }
+
+      const baseProof = await findProof({ challenge })
+      expect(baseProof).not.toBeNull()
+
+      if (baseProof) {
+        const knownCounter = parseInt(baseProof.counter)
+
+        // Now search again starting from that known counter
+        const proof = await findProof({
+          challenge,
+          rangeStart: knownCounter,
+          rangeSize: 1, // Only check the one counter
+        })
+
+        expect(proof).not.toBeNull()
+        expect(proof!.counter).toBe(knownCounter.toString())
+      }
+    })
+  })
+
+  describe('verifyProof', () => {
+    it('verifies a valid proof', async () => {
+      const challenge: HashcashChallenge = {
+        ...backendExample,
+        difficulty: 1,
+        max_proof_length: 10000,
+      }
+
+      // First find a proof
+      const proof = await findProof({ challenge })
+      expect(proof).not.toBeNull()
+
+      if (proof) {
+        // Then verify it
+        const isValid = await verifyProof(challenge, proof.counter)
+        expect(isValid).toBe(true)
+      }
+    })
+
+    it('rejects an invalid proof', async () => {
+      // Test with non-numeric counter (always invalid)
+      expect(await verifyProof(backendExample, 'not-a-number')).toBe(false)
+
+      // Test with higher difficulty where most counters are invalid
+      const higherDifficultyChallenge = {
+        ...backendExample,
+        difficulty: 16, // 2 full zero bytes required
+      }
+
+      // This counter is very unlikely to produce 2 zero bytes
+      const isValid = await verifyProof(higherDifficultyChallenge, '12345')
+      expect(isValid).toBe(false)
+    })
+  })
+
+  describe('formatHashcashString', () => {
+    it('formats hashcash string correctly', () => {
+      const proof = {
+        counter: '123',
+        hash: new Uint8Array(32).fill(0),
+        attempts: 123,
+        timeMs: 10,
+      }
+
+      const formatted = formatHashcashString(backendExample, proof)
+
+      // Check format: version:bits:date:resource:extension:counter:hash
+      const parts = formatted.split(':')
+
+      expect(parts.length).toBe(7)
+      expect(parts[0]).toBe('1') // Version
+      expect(parts[1]).toBe('1') // Difficulty
+      expect(parts[2]).toMatch(/^\d{6}$/) // Date format YYMMDD (always 6 digits)
+      expect(parts[3]).toBe('Lux') // Resource
+      expect(parts[4]).toBe('') // Extension (empty)
+      expect(parts[5]).toBe('123') // Counter
+      expect(parts[6]).toMatch(/^[A-Za-z0-9+/=]+$/) // Base64 hash
+    })
+  })
+
+  describe('integration with backend example', () => {
+    it('completes full hashcash flow with real backend data', async () => {
+      const challenge: HashcashChallenge = {
+        ...backendExample,
+        max_proof_length: 10000, // Give enough range to find solution
+      }
+
+      // Step 1: Find proof
+      const proof = await findProof({ challenge })
+      expect(proof).not.toBeNull()
+
+      if (proof) {
+        // Step 2: Verify the proof is valid
+        const isValid = await verifyProof(challenge, proof.counter)
+        expect(isValid).toBe(true)
+
+        // Step 3: Check the hash meets difficulty requirement
+        expect(checkDifficulty(proof.hash, challenge.difficulty)).toBe(true)
+
+        // Step 4: Format for submission
+        const hashcashString = formatHashcashString(challenge, proof)
+        expect(hashcashString).toBeTruthy()
+
+        // Verify format includes our subject
+        expect(hashcashString).toContain('Lux')
+      }
+    })
+
+    it('handles backend difficulty vs verifier discrepancy', async () => {
+      // The backend example shows difficulty: 1
+      // But the verifier checks: hash.slice(0,1).every(x => x === 0)
+      // which actually requires the first byte to be 0 (difficulty 8)
+
+      const challenge = backendExample
+      const proof = await findProof({
+        challenge,
+        rangeSize: 10000,
+      })
+
+      if (proof) {
+        // Check our difficulty 1 validation
+        const meetsSpecifiedDifficulty = checkDifficulty(proof.hash, 1)
+        expect(meetsSpecifiedDifficulty).toBe(true)
+      }
+    })
+  })
+})

package/src/challenge-solvers/hashcash/core.ts

@@ -0,0 +1,35 @@
+/**
+ * Base stub for hashcash core functions.
+ * Platform-specific implementations override this file.
+ *
+ * - Web: core.web.ts (Web Crypto + batching)
+ * - Native: core.native.ts (mobile uses Nitro modules)
+ *
+ * Shared types and platform-agnostic functions live in shared.ts.
+ */
+
+import { PlatformSplitStubError } from '@luxfi/utilities/src/errors'
+
+export type { HashcashChallenge, ProofResult } from '@luxexchange/sessions/src/challenge-solvers/hashcash/shared'
+// Re-export everything from shared — types, checkDifficulty, formatHashcashString
+export { checkDifficulty, formatHashcashString } from '@luxexchange/sessions/src/challenge-solvers/hashcash/shared'
+
+import type { HashcashChallenge, ProofResult } from '@luxexchange/sessions/src/challenge-solvers/hashcash/shared'
+
+export async function computeHash(_params: { subject: string; nonce: string; counter: number }): Promise<Uint8Array> {
+  throw new PlatformSplitStubError('computeHash')
+}
+
+export async function findProof(_params: {
+  challenge: HashcashChallenge
+  rangeStart?: number
+  rangeSize?: number
+  shouldStop?: () => boolean
+  batchSize?: number
+}): Promise<ProofResult | null> {
+  throw new PlatformSplitStubError('findProof')
+}
+
+export async function verifyProof(_challenge: HashcashChallenge, _proofCounter: string): Promise<boolean> {
+  throw new PlatformSplitStubError('verifyProof')
+}

package/src/challenge-solvers/hashcash/core.web.ts

@@ -0,0 +1,123 @@
+/**
+ * Web-optimized hashcash core implementation.
+ *
+ * Uses Web Crypto API via @noble/hashes/webcrypto.js for hardware-accelerated
+ * SHA-256 hashing. Includes batching to amortize async overhead.
+ *
+ * This is the web platform implementation - mobile uses native Nitro modules.
+ */
+import { sha256 } from '@noble/hashes/webcrypto.js'
+
+export type { HashcashChallenge, ProofResult } from '@luxexchange/sessions/src/challenge-solvers/hashcash/shared'
+// Re-export shared types and platform-agnostic functions
+export { checkDifficulty, formatHashcashString } from '@luxexchange/sessions/src/challenge-solvers/hashcash/shared'
+
+import type { HashcashChallenge, ProofResult } from '@luxexchange/sessions/src/challenge-solvers/hashcash/shared'
+import { checkDifficulty } from '@luxexchange/sessions/src/challenge-solvers/hashcash/shared'
+
+// Pre-allocated TextEncoder for memory efficiency (avoids creating new instance per hash)
+const encoder = new TextEncoder()
+
+// Default batch size for async hashing
+// Tuned to balance async overhead vs responsiveness to cancellation
+const DEFAULT_BATCH_SIZE = 256
+
+/**
+ * Compute SHA-256 hash using Web Crypto API.
+ * Async for hardware acceleration.
+ */
+export async function computeHash(params: { subject: string; nonce: string; counter: number }): Promise<Uint8Array> {
+  const { subject, nonce, counter } = params
+
+  // Backend expects: "${subject}:${nonce}:${counter}"
+  const solutionString = `${subject}:${nonce}:${counter}`
+
+  // Hash using Web Crypto (hardware-accelerated)
+  const inputBytes = encoder.encode(solutionString)
+  return sha256(inputBytes)
+}
+
+/**
+ * Find a proof-of-work solution using batched Web Crypto hashing.
+ *
+ * Processes hashes in batches to amortize async overhead while remaining
+ * responsive to cancellation requests.
+ */
+export async function findProof(params: {
+  challenge: HashcashChallenge
+  rangeStart?: number
+  rangeSize?: number
+  shouldStop?: () => boolean
+  batchSize?: number
+}): Promise<ProofResult | null> {
+  const {
+    challenge,
+    rangeStart = 0,
+    rangeSize = challenge.max_proof_length || 1_000_000,
+    shouldStop,
+    batchSize = DEFAULT_BATCH_SIZE,
+  } = params
+
+  const startTime = Date.now()
+  const rangeEnd = rangeStart + rangeSize
+  const { subject, nonce, difficulty } = challenge
+
+  for (let batchStart = rangeStart; batchStart < rangeEnd; batchStart += batchSize) {
+    // Check for cancellation at batch boundaries
+    if (shouldStop?.()) {
+      return null
+    }
+
+    // Determine actual batch end (don't exceed range)
+    const batchEnd = Math.min(batchStart + batchSize, rangeEnd)
+    const currentBatchSize = batchEnd - batchStart
+
+    // Generate counter values for this batch
+    const counters: number[] = new Array(currentBatchSize)
+    for (let i = 0; i < currentBatchSize; i++) {
+      counters[i] = batchStart + i
+    }
+
+    // Hash all counters in this batch in parallel
+    const hashes = await Promise.all(counters.map((counter) => computeHash({ subject, nonce, counter })))
+
+    // Check each hash for valid proof
+    for (let i = 0; i < hashes.length; i++) {
+      const hash = hashes[i]
+      const counter = counters[i]
+      // Safety check (shouldn't happen since arrays are same size)
+      if (!hash || counter === undefined) {
+        continue
+      }
+      if (checkDifficulty(hash, difficulty)) {
+        return {
+          counter: counter.toString(),
+          hash,
+          attempts: counter - rangeStart + 1,
+          timeMs: Date.now() - startTime,
+        }
+      }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Verify a proof solution.
+ * Async because it uses Web Crypto.
+ */
+export async function verifyProof(challenge: HashcashChallenge, proofCounter: string): Promise<boolean> {
+  const counter = parseInt(proofCounter)
+
+  if (isNaN(counter)) {
+    return false
+  }
+
+  const hash = await computeHash({
+    subject: challenge.subject,
+    nonce: challenge.nonce,
+    counter,
+  })
+  return checkDifficulty(hash, challenge.difficulty)
+}

package/src/challenge-solvers/hashcash/createWorkerHashcashSolver.test.ts

@@ -0,0 +1,195 @@
+import { ChallengeType } from '@uniswap/client-platform-service/dist/uniswap/platformservice/v1/sessionService_pb'
+import { createWorkerHashcashSolver } from '@luxexchange/sessions/src/challenge-solvers/hashcash/createWorkerHashcashSolver'
+import type { HashcashWorkerChannelFactory } from '@luxexchange/sessions/src/challenge-solvers/hashcash/worker/types'
+import type { ChallengeData } from '@luxexchange/sessions/src/challenge-solvers/types'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+describe('createWorkerHashcashSolver', () => {
+  // Real backend example data
+  const backendExample = {
+    difficulty: 1,
+    subject: 'Lux',
+    algorithm: 'sha256' as const,
+    nonce: 'Qlquffem7d8RrL6fmveE68XK0KxcoczdiVpFrV1qeUk=',
+    max_proof_length: 10000,
+  }
+
+  // Mock channel factory for testing
+  function createMockChannelFactory(
+    findProofResult: { counter: string; hash: Uint8Array; attempts: number; timeMs: number } | null = {
+      counter: '123',
+      hash: new Uint8Array([0, 0, 1, 2, 3]),
+      attempts: 124,
+      timeMs: 50,
+    },
+  ): {
+    factory: HashcashWorkerChannelFactory
+    mocks: {
+      findProof: ReturnType<typeof vi.fn>
+      cancel: ReturnType<typeof vi.fn>
+      terminate: ReturnType<typeof vi.fn>
+    }
+  } {
+    const findProof = vi.fn().mockResolvedValue(findProofResult)
+    const cancel = vi.fn().mockResolvedValue(undefined)
+    const terminate = vi.fn()
+
+    const factory: HashcashWorkerChannelFactory = () => ({
+      api: { findProof, cancel },
+      terminate,
+    })
+
+    return { factory, mocks: { findProof, cancel, terminate } }
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('successfully solves a valid challenge using worker', async () => {
+    const { factory, mocks } = createMockChannelFactory()
+    const solver = createWorkerHashcashSolver({ createChannel: factory })
+
+    const challengeData: ChallengeData = {
+      challengeId: 'test-challenge-123',
+      challengeType: ChallengeType.HASHCASH,
+      extra: {
+        challengeData: JSON.stringify(backendExample),
+      },
+    }
+
+    const solution = await solver.solve(challengeData)
+
+    // Check format: "${subject}:${nonce}:${counter}"
+    expect(solution).toBe(`Lux:${backendExample.nonce}:123`)
+
+    // Verify worker was called correctly
+    expect(mocks.findProof).toHaveBeenCalledOnce()
+    expect(mocks.findProof).toHaveBeenCalledWith({
+      challenge: expect.objectContaining({
+        subject: 'Lux',
+        difficulty: 1,
+        nonce: backendExample.nonce,
+      }),
+      rangeStart: 0,
+      rangeSize: 10000,
+    })
+
+    // Verify channel was terminated
+    expect(mocks.terminate).toHaveBeenCalledOnce()
+  })
+
+  it('throws error when challengeData is missing', async () => {
+    const { factory } = createMockChannelFactory()
+    const solver = createWorkerHashcashSolver({ createChannel: factory })
+
+    const challengeData: ChallengeData = {
+      challengeId: 'test-challenge-123',
+      challengeType: ChallengeType.HASHCASH,
+      extra: {}, // Missing challengeData
+    }
+
+    await expect(solver.solve(challengeData)).rejects.toThrow('Missing challengeData in challenge extra field')
+  })
+
+  it('throws error when no proof is found', async () => {
+    const { factory } = createMockChannelFactory(null)
+    const solver = createWorkerHashcashSolver({ createChannel: factory })
+
+    const challengeData: ChallengeData = {
+      challengeId: 'test-challenge-123',
+      challengeType: ChallengeType.HASHCASH,
+      extra: {
+        challengeData: JSON.stringify(backendExample),
+      },
+    }
+
+    await expect(solver.solve(challengeData)).rejects.toThrow('Failed to find valid proof within allowed range')
+  })
+
+  it('terminates channel even when error occurs', async () => {
+    const findProof = vi.fn().mockRejectedValue(new Error('Worker error'))
+    const terminate = vi.fn()
+
+    const factory: HashcashWorkerChannelFactory = () => ({
+      api: { findProof, cancel: vi.fn() },
+      terminate,
+    })
+
+    const solver = createWorkerHashcashSolver({ createChannel: factory })
+
+    const challengeData: ChallengeData = {
+      challengeId: 'test-challenge-123',
+      challengeType: ChallengeType.HASHCASH,
+      extra: {
+        challengeData: JSON.stringify(backendExample),
+      },
+    }
+
+    await expect(solver.solve(challengeData)).rejects.toThrow('Worker error')
+
+    // Channel should still be terminated
+    expect(terminate).toHaveBeenCalledOnce()
+  })
+
+  describe('cancellation', () => {
+    it('cancels solving when AbortSignal is triggered', async () => {
+      const controller = new AbortController()
+      const { factory, mocks } = createMockChannelFactory()
+
+      // Make findProof take a while and check abort during it
+      mocks.findProof.mockImplementation(async () => {
+        // Simulate work, then check if cancelled
+        await new Promise((resolve) => setTimeout(resolve, 50))
+        return null // Simulates cancelled result
+      })
+
+      const solver = createWorkerHashcashSolver({
+        createChannel: factory,
+        signal: controller.signal,
+      })
+
+      const challengeData: ChallengeData = {
+        challengeId: 'test-challenge-123',
+        challengeType: ChallengeType.HASHCASH,
+        extra: {
+          challengeData: JSON.stringify(backendExample),
+        },
+      }
+
+      // Start solving and cancel after a short delay
+      const solvePromise = solver.solve(challengeData)
+      controller.abort()
+
+      await expect(solvePromise).rejects.toThrow('Challenge solving was cancelled')
+
+      // Verify cancel was called on the worker
+      expect(mocks.cancel).toHaveBeenCalled()
+    })
+
+    it('throws immediately if already aborted', async () => {
+      const controller = new AbortController()
+      controller.abort() // Abort before starting
+
+      const { factory, mocks } = createMockChannelFactory()
+
+      const solver = createWorkerHashcashSolver({
+        createChannel: factory,
+        signal: controller.signal,
+      })
+
+      const challengeData: ChallengeData = {
+        challengeId: 'test-challenge-123',
+        challengeType: ChallengeType.HASHCASH,
+        extra: {
+          challengeData: JSON.stringify(backendExample),
+        },
+      }
+
+      await expect(solver.solve(challengeData)).rejects.toThrow('Challenge solving was cancelled')
+
+      // Worker should not be called if already aborted
+      expect(mocks.findProof).not.toHaveBeenCalled()
+    })
+  })
+})