@fedimint/core-web 0.0.0-20250617190659

package/src/test/fixtures.test.ts

@@ -0,0 +1,18 @@
+import { expect } from 'vitest'
+import { walletTest } from './fixtures'
+
+walletTest('Fund wallet 1', async ({ fundedWallet }) => {
+  expect(fundedWallet).toBeDefined()
+})
+
+walletTest('Fund wallet 2', async ({ fundedWallet }) => {
+  expect(fundedWallet).toBeDefined()
+})
+
+walletTest('Fund wallet 3', async ({ fundedWallet }) => {
+  expect(fundedWallet).toBeDefined()
+})
+
+walletTest('Fund wallet 4', async ({ fundedWallet }) => {
+  expect(fundedWallet).toBeDefined()
+})

package/src/test/fixtures.ts

@@ -0,0 +1,70 @@
+import { expect, test } from 'vitest'
+import { TestFedimintWallet } from './TestFedimintWallet'
+import { WorkerClient } from '../worker/WorkerClient'
+
+/**
+ * Adds Fixtures for setting up and tearing down a test FedimintWallet instance
+ */
+export const walletTest = test.extend<{
+  wallet: TestFedimintWallet
+  fundedWallet: TestFedimintWallet
+  unopenedWallet: TestFedimintWallet
+}>({
+  wallet: async ({}, use) => {
+    const randomTestingId = Math.random().toString(36).substring(2, 15)
+    const wallet = new TestFedimintWallet()
+    expect(wallet).toBeDefined()
+    const inviteCode = await wallet.testing.getInviteCode()
+    await expect(
+      wallet.joinFederation(inviteCode, randomTestingId),
+    ).resolves.toBe(true)
+
+    await use(wallet)
+
+    // clear up browser resources
+    await wallet.cleanup()
+
+    // remove the wallet db
+    await new Promise((resolve) => {
+      const request = indexedDB.deleteDatabase(randomTestingId)
+      request.onsuccess = resolve
+      request.onerror = resolve
+      request.onblocked = resolve
+    })
+  },
+
+  fundedWallet: async ({ wallet }, use) => {
+    await wallet.fundWallet(10_000)
+    await use(wallet)
+  },
+  unopenedWallet: async ({}, use) => {
+    const wallet = new TestFedimintWallet()
+    await wallet.initialize()
+    await use(wallet)
+  },
+})
+
+/**
+ * Adds Fixtures for setting up and tearing down a test Worker instance
+ */
+export const workerTest = test.extend<{
+  worker: Worker
+  clientName: string
+  workerClient: WorkerClient
+}>({
+  worker: async ({}, use) => {
+    const worker = new Worker(new URL('../worker/worker.js', import.meta.url), {
+      type: 'module',
+    })
+    await use(worker)
+    worker.terminate()
+  },
+  clientName: async ({}, use) => {
+    const randomTestingId = Math.random().toString(36).substring(2, 15)
+    await use(randomTestingId)
+  },
+  workerClient: async ({}, use) => {
+    const workerClient = new WorkerClient()
+    await use(workerClient)
+  },
+})

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export * from './wallet'
+export * from './utils'
+export * from './worker'

package/src/types/utils.ts

@@ -0,0 +1,29 @@
+type Alias<T> = T & {}
+type Resolve<T> = T & unknown
+
+type Seconds = Alias<number>
+type Nanos = Alias<number>
+
+type Duration = {
+  nanos: Nanos
+  secs: Seconds
+}
+
+type MSats = Alias<number>
+type Sats = Alias<number>
+
+type JSONValue =
+  | string
+  | number
+  | boolean
+  | null
+  | { [key: string]: JSONValue }
+  | JSONValue[]
+
+type JSONObject = Record<string, JSONValue>
+
+type Result<T, U = string> =
+  | { success: true; data?: T }
+  | { success: false; error: U }
+
+export { Alias, Resolve, Duration, MSats, Sats, JSONValue, JSONObject, Result }

package/src/types/wallet.ts

@@ -0,0 +1,141 @@
+import { MSats, Duration, JSONValue, JSONObject } from './utils'
+
+const MODULE_KINDS = ['', 'ln', 'mint', 'wallet'] as const
+type ModuleKind = (typeof MODULE_KINDS)[number]
+
+// TODO: Define the structure of FederationConfig
+type FederationConfig = JSONObject
+
+type GatewayInfo = {
+  gateway_id: string
+  api: string
+  node_pub_key: string
+  federation_index: number
+  route_hints: RouteHint[]
+  fees: FeeToAmount
+}
+type LightningGateway = {
+  info: GatewayInfo
+  vetted: boolean
+  ttl: Duration
+}
+
+type RouteHint = {
+  // TODO: Define the structure of RouteHint
+}
+
+type FeeToAmount = {
+  // TODO: Define the structure of FeeToAmount
+}
+
+type OutgoingLightningPayment = {
+  payment_type: PayType
+  contract_id: string
+  fee: MSats
+}
+
+type PayType = { lightning: string } | { internal: string }
+
+type LnPayState =
+  | 'created'
+  | 'canceled'
+  | { funded: { block_height: number } }
+  | { waiting_for_refund: { error_reason: string } }
+  | 'awaiting_change'
+  | { success: { preimage: string } }
+  | { refunded: { gateway_error: string } }
+  | { unexpected_error: { error_message: string } }
+
+type LnReceiveState =
+  | 'created'
+  | { waiting_for_payment: { invoice: string; timeout: number } }
+  | { canceled: { reason: string } }
+  | 'funded'
+  | 'awaiting_funds'
+  | 'claimed'
+
+type CreateBolt11Response = {
+  operation_id: string
+  invoice: string
+}
+
+type StreamError = {
+  error: string
+  data: never
+  end: never
+}
+
+type StreamSuccess<T extends JSONValue> = {
+  data: T
+  error: never
+  end: never
+}
+
+type StreamEnd = {
+  end: string
+  data: never
+  error: never
+}
+
+type StreamResult<T extends JSONValue> =
+  | StreamSuccess<T>
+  | StreamError
+  | StreamEnd
+
+type CancelFunction = () => void
+
+type ReissueExternalNotesState = 'Created' | 'Issuing' | 'Done'
+// | { Failed: { error: string } }
+
+type MintSpendNotesResponse = Array<string>
+
+type SpendNotesState =
+  | 'Created'
+  | 'UserCanceledProcessing'
+  | 'UserCanceledSuccess'
+  | 'UserCanceledFailure'
+  | 'Success'
+  | 'Refunded'
+
+type TxOutputSummary = {
+  outpoint: {
+    txid: string
+    vout: number
+  }
+  amount: number
+}
+
+type WalletSummary = {
+  spendable_utxos: TxOutputSummary[]
+  unsigned_peg_out_txos: TxOutputSummary[]
+  unsigned_change_utxos: TxOutputSummary[]
+  unconfirmed_peg_out_txos: TxOutputSummary[]
+  unconfirmed_change_utxos: TxOutputSummary[]
+}
+
+/** Keys are powers of 2 */
+type NoteCountByDenomination = Record<number, number>
+
+export {
+  LightningGateway,
+  FederationConfig,
+  RouteHint,
+  FeeToAmount,
+  OutgoingLightningPayment,
+  PayType,
+  LnPayState,
+  LnReceiveState,
+  CreateBolt11Response,
+  GatewayInfo,
+  StreamError,
+  StreamSuccess,
+  StreamResult,
+  ModuleKind,
+  CancelFunction,
+  ReissueExternalNotesState,
+  MintSpendNotesResponse,
+  SpendNotesState,
+  WalletSummary,
+  TxOutputSummary,
+  NoteCountByDenomination,
+}

package/src/types/worker.ts

@@ -0,0 +1,16 @@
+const WorkerMessageTypes = [
+  'init',
+  'initialized',
+  'rpc',
+  'log',
+  'open',
+  'join',
+  'error',
+  'unsubscribe',
+  'cleanup',
+  'parseInviteCode',
+  'parseBolt11Invoice',
+  'previewFederation',
+] as const
+
+export type WorkerMessageType = (typeof WorkerMessageTypes)[number]

package/src/utils/logger.ts

@@ -0,0 +1,61 @@
+const logLevels = ['debug', 'info', 'warn', 'error', 'none'] as const
+export type LogLevel = (typeof logLevels)[number]
+
+export class Logger {
+  private level: LogLevel
+
+  constructor(level: LogLevel = 'none') {
+    this.level = level
+  }
+
+  setLevel(level: LogLevel) {
+    this.level = level
+  }
+
+  coerceLevel(level: string): LogLevel {
+    if (logLevels.includes(level.toLocaleUpperCase() as LogLevel)) {
+      return level.toLocaleUpperCase() as LogLevel
+    }
+    return 'info'
+  }
+
+  log(level: string, message: string, ...args: any[]) {
+    const logLevel = this.coerceLevel(level)
+    if (!this.shouldLog(logLevel)) {
+      return
+    }
+    const consoleFn = console[logLevel]
+    consoleFn(`[${logLevel.toUpperCase()}] ${message}`, ...args)
+  }
+
+  debug(message: string, ...args: any[]) {
+    this.log('debug', message, ...args)
+  }
+
+  info(message: string, ...args: any[]) {
+    this.log('info', message, ...args)
+  }
+
+  warn(message: string, ...args: any[]) {
+    this.log('warn', message, ...args)
+  }
+
+  error(message: string, ...args: any[]) {
+    this.log('error', message, ...args)
+  }
+
+  private shouldLog(
+    messageLevel: LogLevel,
+  ): messageLevel is Exclude<LogLevel, 'none'> {
+    const levels: LogLevel[] = ['debug', 'info', 'warn', 'error', 'none']
+    const messageLevelIndex = levels.indexOf(messageLevel)
+    const currentLevelIndex = levels.indexOf(this.level)
+    return (
+      currentLevelIndex <= messageLevelIndex &&
+      this.level !== 'none' &&
+      messageLevel !== 'none'
+    )
+  }
+}
+
+export const logger = new Logger()

package/src/worker/WorkerClient.test.ts

@@ -0,0 +1,6 @@
+import { expect } from 'vitest'
+import { workerTest } from '../test/fixtures'
+
+workerTest('should initialize', async ({ workerClient }) => {
+  expect(workerClient).toBeDefined()
+})

package/src/worker/WorkerClient.ts

@@ -0,0 +1,236 @@
+import type {
+  CancelFunction,
+  JSONValue,
+  ModuleKind,
+  StreamError,
+  StreamResult,
+  WorkerMessageType,
+} from '../types'
+import { logger } from '../utils/logger'
+
+// Handles communication with the wasm worker
+// TODO: Move rpc stream management to a separate "SubscriptionManager" class
+export class WorkerClient {
+  private worker: Worker
+  private requestCounter = 0
+  private requestCallbacks = new Map<number, (value: any) => void>()
+  private initPromise: Promise<boolean> | undefined = undefined
+
+  constructor() {
+    // Must create the URL inside the constructor for vite
+    this.worker = new Worker(new URL('./worker.js', import.meta.url), {
+      type: 'module',
+    })
+    this.worker.onmessage = this.handleWorkerMessage.bind(this)
+    this.worker.onerror = this.handleWorkerError.bind(this)
+    logger.info('WorkerClient instantiated')
+    logger.debug('WorkerClient', this.worker)
+  }
+
+  // Idempotent setup - Loads the wasm module
+  initialize() {
+    if (this.initPromise) return this.initPromise
+    this.initPromise = this.sendSingleMessage('init')
+    return this.initPromise
+  }
+
+  private handleWorkerLogs(event: MessageEvent) {
+    const { type, level, message, ...data } = event.data
+    logger.log(level, message, ...data)
+  }
+
+  private handleWorkerError(event: ErrorEvent) {
+    logger.error('Worker error', event)
+  }
+
+  private handleWorkerMessage(event: MessageEvent) {
+    const { type, requestId, ...data } = event.data
+    if (type === 'log') {
+      this.handleWorkerLogs(event.data)
+    }
+    const streamCallback = this.requestCallbacks.get(requestId)
+    // TODO: Handle errors... maybe have another callbacks list for errors?
+    logger.debug('WorkerClient - handleWorkerMessage', event.data)
+    if (streamCallback) {
+      streamCallback(data) // {data: something} OR {error: something}
+    } else {
+      logger.warn(
+        'WorkerClient - handleWorkerMessage - received message with no callback',
+        requestId,
+        event.data,
+      )
+    }
+  }
+
+  // TODO: Handle errors... maybe have another callbacks list for errors?
+  // TODO: Handle timeouts
+  // TODO: Handle multiple errors
+
+  sendSingleMessage<
+    Response extends JSONValue = JSONValue,
+    Payload extends JSONValue = JSONValue,
+  >(type: WorkerMessageType, payload?: Payload) {
+    return new Promise<Response>((resolve, reject) => {
+      const requestId = ++this.requestCounter
+      logger.debug('WorkerClient - sendSingleMessage', requestId, type, payload)
+      this.requestCallbacks.set(
+        requestId,
+        (response: StreamResult<Response>) => {
+          this.requestCallbacks.delete(requestId)
+          logger.debug(
+            'WorkerClient - sendSingleMessage - response',
+            requestId,
+            response,
+          )
+          if (response.data) resolve(response.data)
+          else if (response.error) reject(response.error)
+          else
+            logger.warn(
+              'WorkerClient - sendSingleMessage - malformed response',
+              requestId,
+              response,
+            )
+        },
+      )
+      this.worker.postMessage({ type, payload, requestId })
+    })
+  }
+
+  /**
+   * @summary Initiates an RPC stream with the specified module and method.
+   *
+   * @description
+   * This function sets up an RPC stream by sending a request to a worker and
+   * handling responses asynchronously. It ensures that unsubscription is handled
+   * correctly, even if the unsubscribe function is called before the subscription
+   * is fully established, by deferring the unsubscription attempt using `setTimeout`.
+   *
+   * The function operates in a non-blocking manner, leveraging Promises to manage
+   * asynchronous operations and callbacks to handle responses.
+   *
+   *
+   * @template Response - The expected type of the successful response.
+   * @template Body - The type of the request body.
+   * @param module - The module kind to interact with.
+   * @param method - The method name to invoke on the module.
+   * @param body - The request payload.
+   * @param onSuccess - Callback invoked with the response data on success.
+   * @param onError - Callback invoked with error information if an error occurs.
+   * @param onEnd - Optional callback invoked when the stream ends.
+   * @returns A function that can be called to cancel the subscription.
+   *
+   */
+  rpcStream<
+    Response extends JSONValue = JSONValue,
+    Body extends JSONValue = JSONValue,
+  >(
+    module: ModuleKind,
+    method: string,
+    body: Body,
+    onSuccess: (res: Response) => void,
+    onError: (res: StreamError['error']) => void,
+    onEnd: () => void = () => {},
+  ): CancelFunction {
+    const requestId = ++this.requestCounter
+    logger.debug('WorkerClient - rpcStream', requestId, module, method, body)
+    let unsubscribe: (value: void) => void = () => {}
+    let isSubscribed = false
+
+    const unsubscribePromise = new Promise<void>((resolve) => {
+      unsubscribe = () => {
+        if (isSubscribed) {
+          // If already subscribed, resolve immediately to trigger unsubscription
+          resolve()
+        } else {
+          // If not yet subscribed, defer the unsubscribe attempt to the next event loop tick
+          // This ensures that subscription setup has time to complete
+          setTimeout(() => unsubscribe(), 0)
+        }
+      }
+    })
+
+    // Initiate the inner RPC stream setup asynchronously
+    this._rpcStreamInner(
+      requestId,
+      module,
+      method,
+      body,
+      onSuccess,
+      onError,
+      onEnd,
+      unsubscribePromise,
+    ).then(() => {
+      isSubscribed = true
+    })
+
+    return unsubscribe
+  }
+
+  private async _rpcStreamInner<
+    Response extends JSONValue = JSONValue,
+    Body extends JSONValue = JSONValue,
+  >(
+    requestId: number,
+    module: ModuleKind,
+    method: string,
+    body: Body,
+    onSuccess: (res: Response) => void,
+    onError: (res: StreamError['error']) => void,
+    onEnd: () => void = () => {},
+    unsubscribePromise: Promise<void>,
+    // Unsubscribe function
+  ) {
+    // await this.openPromise
+    // if (!this.worker || !this._isOpen)
+    //   throw new Error('FedimintWallet is not open')
+
+    this.requestCallbacks.set(requestId, (response: StreamResult<Response>) => {
+      if (response.error !== undefined) {
+        onError(response.error)
+      } else if (response.data !== undefined) {
+        onSuccess(response.data)
+      } else if (response.end !== undefined) {
+        this.requestCallbacks.delete(requestId)
+        onEnd()
+      }
+    })
+    this.worker.postMessage({
+      type: 'rpc',
+      payload: { module, method, body },
+      requestId,
+    })
+
+    unsubscribePromise.then(() => {
+      this.worker?.postMessage({
+        type: 'unsubscribe',
+        requestId,
+      })
+      this.requestCallbacks.delete(requestId)
+    })
+  }
+
+  rpcSingle<
+    Response extends JSONValue = JSONValue,
+    Error extends string = string,
+  >(module: ModuleKind, method: string, body: JSONValue) {
+    logger.debug('WorkerClient - rpcSingle', module, method, body)
+    return new Promise<Response>((resolve, reject) => {
+      this.rpcStream<Response>(module, method, body, resolve, reject)
+    })
+  }
+
+  async cleanup() {
+    await this.sendSingleMessage('cleanup')
+    this.requestCounter = 0
+    this.initPromise = undefined
+    this.requestCallbacks.clear()
+  }
+
+  // For Testing
+  _getRequestCounter() {
+    return this.requestCounter
+  }
+  _getRequestCallbackMap() {
+    return this.requestCallbacks
+  }
+}

package/src/worker/index.ts

@@ -0,0 +1 @@
+export { WorkerClient } from './WorkerClient'