@fedimint/core-web 0.0.2 → 0.0.4

package/node_modules/@fedimint/fedimint-client-wasm/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@fedimint/fedimint-client-wasm",
+  "private": true,
+  "type": "module",
+  "description": "Wasm-pack output for fedimint-client-wasm",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fedimint/fedimint"
+  },
+  "files": [
+    "fedimint_client_wasm_bg.wasm",
+    "fedimint_client_wasm.js",
+    "fedimint_client_wasm_bg.js",
+    "fedimint_client_wasm.d.ts"
+  ],
+  "main": "fedimint_client_wasm.js",
+  "types": "fedimint_client_wasm.d.ts",
+  "sideEffects": [
+    "./fedimint_client_wasm.js",
+    "./snippets/*"
+  ]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fedimint/core-web",
   "description": "Library for building web apps with a fedimint client",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "repository": {
     "type": "git",
     "url": "https://github.com/fedimint/fedimint-web-sdk.git",
@@ -9,20 +9,27 @@
   },
   "files": [
     "dist",
-    "wasm",
     "src"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/worker.js",
+    "./dist/index.js"
+  ],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@fedimint/fedimint-client-wasm": "file:./wasm"
+  },
+  "bundleDependencies": [
+    "@fedimint/fedimint-client-wasm"
+  ],
   "devDependencies": {
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^11.1.6",
-    "@rollup/plugin-wasm": "^6.2.2",
     "@types/node": "^20.14.8",
-    "@web/rollup-plugin-import-meta-assets": "^2.2.1",
     "rollup": "^4.21.2",
+    "rollup-plugin-typescript2": "^0.36.0",
     "tslib": "^2.7.0",
     "typescript": "^5.2.2"
   },

package/src/FedimintWallet.test.ts

@@ -0,0 +1,74 @@
+import { test, expect, vi } from 'vitest'
+import { FedimintWallet } from './FedimintWallet'
+import { beforeAll } from 'vitest'
+
+let randomTestingId: string
+let wallet: FedimintWallet
+// Testnet
+const TESTING_FEDERATION =
+  'fed11qgqrgvnhwden5te0v9k8q6rp9ekh2arfdeukuet595cr2ttpd3jhq6rzve6zuer9wchxvetyd938gcewvdhk6tcqqysptkuvknc7erjgf4em3zfh90kffqf9srujn6q53d6r056e4apze5cw27h75'
+
+beforeAll(() => {
+  randomTestingId = Math.random().toString(36).substring(2, 15)
+  wallet = new FedimintWallet()
+  expect(wallet).toBeDefined()
+
+  // Cleanup after all tests
+  return async () => {
+    // clear up browser resources
+    await wallet.cleanup()
+    // remove the wallet db
+    indexedDB.deleteDatabase(randomTestingId)
+    // swap out the randomTestingId for a new one, to avoid raciness
+    randomTestingId = Math.random().toString(36).substring(2, 15)
+  }
+})
+
+test('initial open & join', async () => {
+  expect(wallet).toBeDefined()
+  expect(wallet.isOpen()).toBe(false)
+  // On initial open, it should return false
+  // because no federations have been joined
+  await expect(wallet.open(randomTestingId)).resolves.toBe(false)
+  await expect(
+    wallet.joinFederation(TESTING_FEDERATION, randomTestingId),
+  ).resolves.toBeUndefined()
+  expect(wallet.isOpen()).toBe(true)
+  await expect(wallet.waitForOpen()).resolves.toBeUndefined()
+})
+
+test('Error on open & join if wallet is already open', async () => {
+  expect(wallet).toBeDefined()
+  expect(wallet.isOpen()).toBe(true)
+
+  // Test opening an already open wallet
+  try {
+    await wallet.open(randomTestingId)
+  } catch (error) {
+    expect(error).toBeInstanceOf(Error)
+    expect((error as Error).message).toBe('The FedimintWallet is already open.')
+  }
+
+  // Test joining federation on an already open wallet
+  try {
+    await wallet.joinFederation(TESTING_FEDERATION, randomTestingId)
+  } catch (error) {
+    expect(error).toBeInstanceOf(Error)
+    expect((error as Error).message).toBe(
+      'The FedimintWallet is already open. You can only call `joinFederation` on closed clients.',
+    )
+  }
+})
+test('getConfig', async () => {
+  expect(wallet).toBeDefined()
+  expect(wallet.isOpen()).toBe(true)
+  const config = await wallet.federation.getConfig()
+  expect(config).toBeDefined()
+})
+
+test('empty getBalance', async () => {
+  expect(wallet).toBeDefined()
+  expect(wallet.isOpen()).toBe(true)
+  await expect(wallet.waitForOpen()).resolves.toBeUndefined()
+  await expect(wallet.balance.getBalance()).resolves.toEqual(0)
+})

package/src/FedimintWallet.ts

@@ -1,381 +1,127 @@
-import init, { RpcHandle, WasmClient } from '../wasm/fedimint_client_wasm.js'
+import { WorkerClient } from './worker/WorkerClient'
 import {
-  JSONValue,
-  JSONObject,
-  LightningGateway,
-  OutgoingLightningPayment,
-  LnPayState,
-  LnReceiveState,
-  StreamResult,
-  StreamError,
-  CreateBolt11Response,
-  ModuleKind,
-} from './types/wallet.js'
+  BalanceService,
+  MintService,
+  LightningService,
+  FederationService,
+  RecoveryService,
+} from './services'
 
 const DEFAULT_CLIENT_NAME = 'fm-default' as const
 
 export class FedimintWallet {
-  private _fed: WasmClient | null = null
-  private initPromise: Promise<void> | null = null
+  private client: WorkerClient
+
+  public balance: BalanceService
+  public mint: MintService
+  public lightning: LightningService
+  public federation: FederationService
+  public recovery: RecoveryService
+
   private openPromise: Promise<void> | null = null
   private resolveOpen: () => void = () => {}
+  private _isOpen: boolean = false
 
+  /**
+   * Creates a new instance of FedimintWallet.
+   *
+   * @description
+   * This constructor initializes a FedimintWallet instance, which manages communication
+   * with a Web Worker. The Web Worker is responsible for running WebAssembly code that
+   * handles the core Fedimint Client operations.
+   *
+   * (default) When not in lazy mode, the constructor immediately initializes the
+   * Web Worker and begins loading the WebAssembly module in the background. This
+   * allows for faster subsequent operations but may increase initial load time.
+   *
+   * In lazy mode, the Web Worker and WebAssembly initialization are deferred until
+   * the first operation that requires them, reducing initial overhead at the cost
+   * of a slight delay on the first operation.
+   *
+   * @param {boolean} lazy - If true, delays Web Worker and WebAssembly initialization
+   *                         until needed. Default is false.
+   *
+   * @example
+   * // Create a wallet with immediate initialization
+   * const wallet = new FedimintWallet();
+   * wallet.open();
+   *
+   * // Create a wallet with lazy initialization
+   * const lazyWallet = new FedimintWallet(true);
+   * // Some time later...
+   * lazyWallet.initialize();
+   * lazyWallet.open();
+   */
   constructor(lazy: boolean = false) {
-    if (lazy) return
-    this.initialize()
     this.openPromise = new Promise((resolve) => {
       this.resolveOpen = resolve
     })
+    this.client = new WorkerClient()
+    this.mint = new MintService(this.client)
+    this.lightning = new LightningService(this.client)
+    this.balance = new BalanceService(this.client)
+    this.federation = new FederationService(this.client)
+    this.recovery = new RecoveryService(this.client)
+
+    if (!lazy) {
+      this.initialize()
+    }
   }
 
-  // Setup
   async initialize() {
-    if (this.initPromise) return this.initPromise
-    // this.worker = new Worker(new URL('./wasm.worker.ts', import.meta.url))
-    this.initPromise = init().then(() => {
-      console.trace('Fedimint Client Wasm Initialization complete')
-    })
-    return this.initPromise
+    await this.client.initialize()
   }
 
-  async open(clientName: string = DEFAULT_CLIENT_NAME) {
-    await this.initialize()
-    const wasm = await WasmClient.open(clientName)
+  async waitForOpen() {
+    if (this._isOpen) return Promise.resolve()
+    return this.openPromise
+  }
 
-    if (wasm === undefined) return false
-    this._fed = wasm
-    this.resolveOpen()
-    return true
+  async open(clientName: string = DEFAULT_CLIENT_NAME) {
+    await this.client.initialize()
+    // TODO: Determine if this should be safe or throw
+    if (this._isOpen) throw new Error('The FedimintWallet is already open.')
+    const { success } = await this.client.sendSingleMessage('open', {
+      clientName,
+    })
+    if (success) {
+      this._isOpen = !!success
+      this.resolveOpen()
+    }
+    return success
   }
 
   async joinFederation(
     inviteCode: string,
     clientName: string = DEFAULT_CLIENT_NAME,
   ) {
-    await this.initialize()
-    this._fed = await WasmClient.join_federation(clientName, inviteCode)
-    this.resolveOpen()
-  }
-
-  // RPC
-  private async _rpcStream<
-    Response extends JSONValue = JSONValue,
-    Body extends JSONValue = JSONValue,
-  >(
-    module: ModuleKind,
-    method: string,
-    body: Body,
-    onSuccess: (res: Response) => void,
-    onError: (res: StreamError['error']) => void,
-  ): Promise<RpcHandle> {
-    await this.openPromise
-    if (!this._fed) throw new Error('FedimintWallet is not open')
-    const unsubscribe = await this._fed.rpc(
-      module,
-      method,
-      JSON.stringify(body),
-      (res: string) => {
-        // TODO: Validate the response?
-        const parsed = JSON.parse(res) as StreamResult<Response>
-        if (parsed.error) {
-          onError(parsed.error)
-        } else {
-          onSuccess(parsed.data)
-        }
-      },
-    )
-    return unsubscribe
-  }
-
-  private async _rpcSingle<Response extends JSONValue = JSONValue>(
-    module: ModuleKind,
-    method: string,
-    body: JSONValue,
-  ): Promise<Response> {
-    return new Promise((resolve, reject) => {
-      if (!this._fed) return reject('FedimintWallet is not open')
-      this._fed.rpc(module, method, JSON.stringify(body), (res: string) => {
-        // TODO: Validate the response?
-        const parsed = JSON.parse(res) as StreamResult<Response>
-        if (parsed.error) {
-          reject(parsed.error)
-        } else {
-          resolve(parsed.data)
-        }
-      })
-    })
-  }
-
-  async getBalance(): Promise<number> {
-    return await this._rpcSingle('', 'get_balance', {})
-  }
-
-  // Mint module methods
-
-  async redeemEcash(notes: string): Promise<void> {
-    await this._rpcSingle('mint', 'reissue_external_notes', {
-      oob_notes: notes, // "out of band notes"
-      extra_meta: null,
-    })
-  }
-
-  async reissueExternalNotes(
-    oobNotes: string,
-    extraMeta: JSONObject,
-  ): Promise<string> {
-    return await this._rpcSingle('mint', 'reissue_external_notes', {
-      oob_notes: oobNotes,
-      extra_meta: extraMeta,
+    await this.client.initialize()
+    // TODO: Determine if this should be safe or throw
+    if (this._isOpen)
+      throw new Error(
+        'The FedimintWallet is already open. You can only call `joinFederation` on closed clients.',
+      )
+    const response = await this.client.sendSingleMessage('join', {
+      inviteCode,
+      clientName,
     })
-  }
-
-  subscribeReissueExternalNotes(
-    operationId: string,
-    onSuccess: (state: JSONValue) => void = () => {},
-    onError: (error: string) => void = () => {},
-  ) {
-    type ReissueExternalNotesState =
-      | 'Created'
-      | 'Issuing'
-      | 'Done'
-      | { Failed: { error: string } }
-
-    const unsubscribe = this._rpcStream<ReissueExternalNotesState>(
-      'mint',
-      'subscribe_reissue_external_notes',
-      { operation_id: operationId },
-      (res) => onSuccess(res),
-      onError,
-    )
-
-    return () => {
-      unsubscribe.then((unsub) => {
-        unsub.cancel()
-        unsub.free()
-      })
+    if (response.success) {
+      this._isOpen = true
+      this.resolveOpen()
     }
   }
 
-  async spendNotes(
-    minAmount: number,
-    tryCancelAfter: number,
-    includeInvite: boolean,
-    extraMeta: JSONValue,
-  ): Promise<JSONValue> {
-    return await this._rpcSingle('mint', 'spend_notes', {
-      min_amount: minAmount,
-      try_cancel_after: tryCancelAfter,
-      include_invite: includeInvite,
-      extra_meta: extraMeta,
-    })
-  }
-
-  async validateNotes(oobNotes: string): Promise<number> {
-    return await this._rpcSingle('mint', 'validate_notes', {
-      oob_notes: oobNotes,
-    })
-  }
-
-  async tryCancelSpendNotes(operationId: string): Promise<void> {
-    await this._rpcSingle('mint', 'try_cancel_spend_notes', {
-      operation_id: operationId,
-    })
-  }
-
-  subscribeSpendNotes(
-    operationId: string,
-    onSuccess: (state: JSONValue) => void = () => {},
-    onError: (error: string) => void = () => {},
-  ) {
-    const unsubscribe = this._rpcStream(
-      'mint',
-      'subscribe_spend_notes',
-      { operation_id: operationId },
-      (res) => onSuccess(res),
-      onError,
-    )
-
-    return () => {
-      unsubscribe.then((unsub) => {
-        unsub.cancel()
-        unsub.free()
-      })
-    }
-  }
-
-  async awaitSpendOobRefund(operationId: string): Promise<JSONValue> {
-    return await this._rpcSingle('mint', 'await_spend_oob_refund', {
-      operation_id: operationId,
-    })
-  }
-
   /**
    * This should ONLY be called when UNLOADING the wallet client.
    * After this call, the FedimintWallet instance should be discarded.
    */
   async cleanup() {
-    await this._fed?.free()
-    this._fed = null
     this.openPromise = null
+    this._isOpen = false
+    this.client.cleanup()
   }
 
   isOpen() {
-    return this._fed !== null
-  }
-
-  async getConfig(): Promise<JSONValue> {
-    return await this._rpcSingle('', 'get_config', {})
-  }
-
-  async getFederationId(): Promise<string> {
-    return await this._rpcSingle('', 'get_federation_id', {})
-  }
-
-  async getInviteCode(peer: number): Promise<string | null> {
-    return await this._rpcSingle('', 'get_invite_code', { peer })
-  }
-
-  async listOperations(): Promise<JSONValue[]> {
-    return await this._rpcSingle('', 'list_operations', {})
-  }
-
-  async hasPendingRecoveries(): Promise<boolean> {
-    return await this._rpcSingle('', 'has_pending_recoveries', {})
-  }
-
-  async waitForAllRecoveries(): Promise<void> {
-    await this._rpcSingle('', 'wait_for_all_recoveries', {})
-  }
-
-  /// STREAMING RPCs --------------------
-
-  subscribeBalance(
-    onSuccess: (balance: number) => void = () => {},
-    onError: (error: string) => void = () => {},
-  ) {
-    const unsubscribe = this._rpcStream<string>(
-      '',
-      'subscribe_balance_changes',
-      {},
-      (res) => onSuccess(parseInt(res)),
-      onError,
-    )
-
-    return () => {
-      unsubscribe.then((unsub) => {
-        unsub.cancel()
-        unsub.free()
-      })
-    }
-  }
-
-  subscribeToRecoveryProgress(
-    onSuccess: (progress: {
-      module_id: number
-      progress: JSONValue
-    }) => void = () => {},
-    onError: (error: string) => void = () => {},
-  ) {
-    const unsubscribe = this._rpcStream<{
-      module_id: number
-      progress: JSONValue
-    }>('', 'subscribe_to_recovery_progress', {}, onSuccess, onError)
-
-    return () => {
-      unsubscribe.then((unsub) => {
-        unsub.cancel()
-        unsub.free()
-      })
-    }
-  }
-
-  // Lightning Network module methods
-
-  async createBolt11Invoice(
-    amount: number,
-    description: string,
-    expiryTime: number | null = null,
-    extraMeta: JSONObject = {},
-    gateway: LightningGateway | null = null,
-  ): Promise<CreateBolt11Response> {
-    return await this._rpcSingle('ln', 'create_bolt11_invoice', {
-      amount,
-      description,
-      expiry_time: expiryTime,
-      extra_meta: extraMeta,
-      gateway,
-    })
-  }
-
-  async payBolt11Invoice(
-    invoice: string,
-    maybeGateway: LightningGateway | null = null,
-    extraMeta: JSONObject = {},
-  ): Promise<OutgoingLightningPayment> {
-    return await this._rpcSingle('ln', 'pay_bolt11_invoice', {
-      maybe_gateway: maybeGateway,
-      invoice,
-      extra_meta: extraMeta,
-    })
-  }
-
-  subscribeLnPay(
-    operationId: string,
-    onSuccess: (state: LnPayState) => void = () => {},
-    onError: (error: string) => void = () => {},
-  ) {
-    const unsubscribe = this._rpcStream(
-      'ln',
-      'subscribe_ln_pay',
-      { operation_id: operationId },
-      onSuccess,
-      onError,
-    )
-
-    return () => {
-      unsubscribe.then((unsub) => {
-        unsub.cancel()
-        unsub.free()
-      })
-    }
-  }
-
-  subscribeLnReceive(
-    operationId: string,
-    onSuccess: (state: LnReceiveState) => void = () => {},
-    onError: (error: string) => void = () => {},
-  ) {
-    const unsubscribe = this._rpcStream(
-      'ln',
-      'subscribe_ln_receive',
-      { operation_id: operationId },
-      onSuccess,
-      onError,
-    )
-
-    return () => {
-      unsubscribe.then((unsub) => {
-        unsub.cancel()
-        unsub.free()
-      })
-    }
-  }
-
-  async getGateway(
-    gatewayId: string | null = null,
-    forceInternal: boolean = false,
-  ): Promise<LightningGateway | null> {
-    return await this._rpcSingle('ln', 'get_gateway', {
-      gateway_id: gatewayId,
-      force_internal: forceInternal,
-    })
-  }
-
-  async listGateways(): Promise<LightningGateway[]> {
-    return await this._rpcSingle('ln', 'list_gateways', {})
-  }
-
-  async updateGatewayCache(): Promise<void> {
-    await this._rpcSingle('ln', 'update_gateway_cache', {})
+    return this._isOpen
   }
 }

package/src/services/BalanceService.ts

@@ -0,0 +1,24 @@
+import { WorkerClient } from '../worker'
+
+export class BalanceService {
+  constructor(private client: WorkerClient) {}
+
+  async getBalance(): Promise<number> {
+    return await this.client.rpcSingle('', 'get_balance', {})
+  }
+
+  subscribeBalance(
+    onSuccess: (balance: number) => void = () => {},
+    onError: (error: string) => void = () => {},
+  ) {
+    const unsubscribe = this.client.rpcStream<string>(
+      '',
+      'subscribe_balance_changes',
+      {},
+      (res) => onSuccess(parseInt(res)),
+      onError,
+    )
+
+    return unsubscribe
+  }
+}

package/src/services/FederationService.ts

@@ -0,0 +1,32 @@
+import { JSONValue } from '../types/wallet'
+import { WorkerClient } from '../worker'
+
+export class FederationService {
+  constructor(private client: WorkerClient) {}
+
+  async getConfig(): Promise<JSONValue> {
+    return await this.client.rpcSingle('', 'get_config', {})
+  }
+
+  async getFederationId(): Promise<string> {
+    return await this.client.rpcSingle('', 'get_federation_id', {})
+  }
+
+  async getInviteCode(peer: number): Promise<string | null> {
+    return await this.client.rpcSingle('', 'get_invite_code', { peer })
+  }
+
+  async joinFederation(inviteCode: string, clientName: string): Promise<void> {
+    const response = await this.client.sendSingleMessage('join', {
+      inviteCode,
+      clientName,
+    })
+    if (!response.success) {
+      throw new Error('Failed to join federation')
+    }
+  }
+
+  async listOperations(): Promise<JSONValue[]> {
+    return await this.client.rpcSingle('', 'list_operations', {})
+  }
+}