@fedimint/core-web 0.0.0-20250617190659

package/src/FedimintWallet.ts

@@ -0,0 +1,215 @@
+import { WorkerClient } from './worker'
+import {
+  BalanceService,
+  MintService,
+  LightningService,
+  FederationService,
+  RecoveryService,
+  WalletService,
+} from './services'
+import { logger, type LogLevel } from './utils/logger'
+import { FederationConfig, JSONValue } from './types'
+
+const DEFAULT_CLIENT_NAME = 'fm-default' as const
+
+export class FedimintWallet {
+  private _client: WorkerClient
+
+  public balance: BalanceService
+  public mint: MintService
+  public lightning: LightningService
+  public federation: FederationService
+  public recovery: RecoveryService
+  public wallet: WalletService
+
+  private _openPromise: Promise<void> | undefined = undefined
+  private _resolveOpen: () => void = () => {}
+  private _isOpen: boolean = false
+
+  /**
+   * Creates a new instance of FedimintWallet.
+   *
+   * 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) {
+    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)
+    this.wallet = new WalletService(this._client)
+
+    logger.info('FedimintWallet instantiated')
+
+    if (!lazy) {
+      this.initialize()
+    }
+  }
+
+  async initialize() {
+    logger.info('Initializing WorkerClient')
+    await this._client.initialize()
+    logger.info('WorkerClient initialized')
+  }
+
+  async waitForOpen() {
+    if (this._isOpen) return Promise.resolve()
+    return this._openPromise
+  }
+
+  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<{
+      success: boolean
+    }>('open', { clientName })
+    if (success) {
+      this._isOpen = !!success
+      this._resolveOpen()
+    }
+    return success
+  }
+
+  async joinFederation(
+    inviteCode: string,
+    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. You can only call `joinFederation` on closed clients.',
+      )
+    try {
+      const response = await this._client.sendSingleMessage<{
+        success: boolean
+      }>('join', { inviteCode, clientName })
+      if (response.success) {
+        this._isOpen = true
+        this._resolveOpen()
+      }
+
+      return response.success
+    } catch (e) {
+      logger.error('Error joining federation', e)
+      return false
+    }
+  }
+
+  /**
+   * This should ONLY be called when UNLOADING the wallet client.
+   * After this call, the FedimintWallet instance should be discarded.
+   */
+  async cleanup() {
+    this._openPromise = undefined
+    this._isOpen = false
+    await this._client.cleanup()
+  }
+
+  isOpen() {
+    return this._isOpen
+  }
+
+  async previewFederation(inviteCode: string) {
+    const response = this._client.sendSingleMessage<{
+      config: FederationConfig
+      federation_id: string
+    }>('previewFederation', { inviteCode })
+    return response
+  }
+
+  /**
+   * Sets the log level for the library.
+   * @param level The desired log level ('DEBUG', 'INFO', 'WARN', 'ERROR', 'NONE').
+   */
+  setLogLevel(level: LogLevel) {
+    logger.setLevel(level)
+    logger.info(`Log level set to ${level}.`)
+  }
+
+  /**
+   * Parses a federation invite code and retrieves its details.
+   *
+   * This method sends the provided invite code to the WorkerClient for parsing.
+   * The response includes the federation_id and url.
+   *
+   * @param {string} inviteCode - The invite code to be parsed.
+   * @returns {Promise<{ federation_id: string, url: string}>}
+   *          A promise that resolves to an object containing:
+   *          - `federation_id`: The id of the feder.
+   *          - `url`: One of the apipoints to connect to the federation
+   *
+   * @throws {Error} If the WorkerClient encounters an issue during the parsing process.
+   *
+   * @example
+   * const inviteCode = "example-invite-code";
+   * const parsedCode = await wallet.parseInviteCode(inviteCode);
+   * console.log(parsedCode.federation_id, parsedCode.url);
+   */
+  async parseInviteCode(inviteCode: string) {
+    const response = await this._client.sendSingleMessage<{
+      type: string
+      data: JSONValue
+      requestId: number
+    }>('parseInviteCode', { inviteCode })
+    return response
+  }
+
+  /**
+   * Parses a BOLT11 Lightning invoice and retrieves its details.
+   *
+   * This method sends the provided invoice string to the WorkerClient for parsing.
+   * The response includes details such as the amount, expiry, and memo.
+   *
+   * @param {string} invoiceStr - The BOLT11 invoice string to be parsed.
+   * @returns {Promise<{ amount: string, expiry: number, memo: string }>}
+   *          A promise that resolves to an object containing:
+   *          - `amount`: The amount specified in the invoice.
+   *          - `expiry`: The expiry time of the invoice in seconds.
+   *          - `memo`: A description or memo attached to the invoice.
+   *
+   * @throws {Error} If the WorkerClient encounters an issue during the parsing process.
+   *
+   * @example
+   * const invoiceStr = "lnbc1...";
+   * const parsedInvoice = await wallet.parseBolt11Invoice(invoiceStr);
+   * console.log(parsedInvoice.amount, parsedInvoice.expiry, parsedInvoice.memo);
+   */
+  async parseBolt11Invoice(invoiceStr: string) {
+    const response = await this._client.sendSingleMessage<{
+      type: string
+      data: JSONValue
+      requestId: number
+    }>('parseBolt11Invoice', { invoiceStr })
+    return response
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { FedimintWallet } from './FedimintWallet'
+export type * from './types'

package/src/services/BalanceService.test.ts

@@ -0,0 +1,50 @@
+import { test, expect } from 'vitest'
+import { TestFedimintWallet } from '../test/TestFedimintWallet'
+import { beforeAll } from 'vitest'
+
+let randomTestingId: string
+let wallet: TestFedimintWallet
+
+beforeAll(async () => {
+  randomTestingId = Math.random().toString(36).substring(2, 15)
+  wallet = new TestFedimintWallet()
+  expect(wallet).toBeDefined()
+  await expect(
+    wallet.joinFederation(wallet.testing.TESTING_INVITE, randomTestingId),
+  ).resolves.toBe(true)
+  expect(wallet.isOpen()).toBe(true)
+
+  // 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('getBalance should be initially zero', async () => {
+  expect(wallet).toBeDefined()
+  expect(wallet.isOpen()).toBe(true)
+  const beforeGetBalance = wallet.testing.getRequestCounter()
+  await expect(wallet.balance.getBalance()).resolves.toEqual(0)
+  expect(wallet.testing.getRequestCounter()).toBe(beforeGetBalance + 1)
+})
+
+test('subscribe balance', async () => {
+  expect(wallet).toBeDefined()
+  expect(wallet.isOpen()).toBe(true)
+
+  const counterBefore = wallet.testing.getRequestCounter()
+  const callbacksBefore = wallet.testing.getRequestCallbackMap().size
+  const unsubscribe = await wallet.balance.subscribeBalance((balance) => {
+    expect(balance).toEqual(0)
+  })
+  expect(wallet.testing.getRequestCounter()).toBe(counterBefore + 1)
+  expect(wallet.testing.getRequestCallbackMap().size).toBe(callbacksBefore + 1)
+
+  await expect(wallet.balance.getBalance()).resolves.toEqual(0)
+  expect(unsubscribe()).toBeUndefined()
+})

package/src/services/BalanceService.ts

@@ -0,0 +1,29 @@
+import { WorkerClient } from '../worker'
+
+/**
+ * Balance Service
+ *
+ * The Balance Service provides methods to interact with the balance of a Fedimint wallet.
+ */
+export class BalanceService {
+  constructor(private client: WorkerClient) {}
+
+  /** https://web.fedimint.org/core/FedimintWallet/BalanceService/getBalance */
+  async getBalance() {
+    return await this.client.rpcSingle<number>('', 'get_balance', {})
+  }
+
+  /** https://web.fedimint.org/core/FedimintWallet/BalanceService/subscribeBalance */
+  subscribeBalance(
+    onSuccess: (balanceMsats: number) => void = () => {},
+    onError: (error: string) => void = () => {},
+  ) {
+    return this.client.rpcStream<string>(
+      '',
+      'subscribe_balance_changes',
+      {},
+      (res) => onSuccess(parseInt(res)),
+      onError,
+    )
+  }
+}

package/src/services/FederationService.test.ts

@@ -0,0 +1,58 @@
+import { expect } from 'vitest'
+import { walletTest } from '../test/fixtures'
+
+walletTest(
+  'getConfig should return the federation config',
+  async ({ wallet }) => {
+    expect(wallet).toBeDefined()
+    expect(wallet.isOpen()).toBe(true)
+    const counterBefore = wallet.testing.getRequestCounter()
+    await expect(wallet.federation.getConfig()).resolves.toMatchObject({
+      api_endpoints: expect.any(Object),
+      broadcast_public_keys: expect.any(Object),
+      consensus_version: expect.any(Object),
+      meta: expect.any(Object),
+      modules: expect.any(Object),
+    })
+    expect(wallet.testing.getRequestCounter()).toBe(counterBefore + 1)
+  },
+)
+
+walletTest(
+  'getFederationId should return the federation id',
+  async ({ wallet }) => {
+    expect(wallet).toBeDefined()
+    expect(wallet.isOpen()).toBe(true)
+
+    const counterBefore = wallet.testing.getRequestCounter()
+    const federationId = await wallet.federation.getFederationId()
+    expect(federationId).toBeTypeOf('string')
+    expect(federationId).toHaveLength(64)
+    expect(wallet.testing.getRequestCounter()).toBe(counterBefore + 1)
+  },
+)
+
+walletTest(
+  'getInviteCode should return the invite code',
+  async ({ wallet }) => {
+    expect(wallet).toBeDefined()
+    expect(wallet.isOpen()).toBe(true)
+
+    const counterBefore = wallet.testing.getRequestCounter()
+    const inviteCode = await wallet.federation.getInviteCode(0)
+    expect(inviteCode).toBeTypeOf('string')
+    expect(wallet.testing.getRequestCounter()).toBe(counterBefore + 1)
+  },
+)
+
+walletTest(
+  'listOperations should return the list of operations',
+  async ({ wallet }) => {
+    expect(wallet).toBeDefined()
+    expect(wallet.isOpen()).toBe(true)
+
+    const counterBefore = wallet.testing.getRequestCounter()
+    await expect(wallet.federation.listOperations()).resolves.toMatchObject([])
+    expect(wallet.testing.getRequestCounter()).toBe(counterBefore + 1)
+  },
+)

package/src/services/FederationService.ts

@@ -0,0 +1,24 @@
+import type { JSONValue } from '../types'
+import { WorkerClient } from '../worker'
+
+export class FederationService {
+  constructor(private client: WorkerClient) {}
+
+  async getConfig() {
+    return await this.client.rpcSingle('', 'get_config', {})
+  }
+
+  async getFederationId() {
+    return await this.client.rpcSingle<string>('', 'get_federation_id', {})
+  }
+
+  async getInviteCode(peer: number = 0) {
+    return await this.client.rpcSingle<string | null>('', 'get_invite_code', {
+      peer,
+    })
+  }
+
+  async listOperations() {
+    return await this.client.rpcSingle<JSONValue[]>('', 'list_operations', {})
+  }
+}

package/src/services/LightningService.test.ts

@@ -0,0 +1,208 @@
+import { expect } from 'vitest'
+import { keyPair } from '../test/crypto'
+import { walletTest } from '../test/fixtures'
+
+walletTest(
+  'createInvoice should create a bolt11 invoice',
+  async ({ wallet }) => {
+    expect(wallet).toBeDefined()
+    expect(wallet.isOpen()).toBe(true)
+
+    const counterBefore = wallet.testing.getRequestCounter()
+    const invoice = await wallet.lightning.createInvoice(100, 'test')
+    expect(invoice).toBeDefined()
+    expect(invoice).toMatchObject({
+      invoice: expect.any(String),
+      operation_id: expect.any(String),
+    })
+    // 3 requests were made, one for the invoice, one for refreshing the
+    // gateway cache, one for getting the gateway info
+    expect(wallet.testing.getRequestCounter()).toBe(counterBefore + 3)
+
+    // Test with expiry time
+    await expect(
+      wallet.lightning.createInvoice(100, 'test', 1000),
+    ).resolves.toBeDefined()
+  },
+)
+
+walletTest('createInvoice with expiry', async ({ wallet }) => {
+  expect(wallet).toBeDefined()
+  expect(wallet.isOpen()).toBe(true)
+
+  const invoice = await wallet.lightning.createInvoice(100, 'test', 1000)
+  expect(invoice).toBeDefined()
+  expect(invoice).toMatchObject({
+    invoice: expect.any(String),
+    operation_id: expect.any(String),
+  })
+})
+
+walletTest(
+  'listGateways should return a list of gateways',
+  async ({ wallet }) => {
+    expect(wallet).toBeDefined()
+    expect(wallet.isOpen()).toBe(true)
+
+    const counterBefore = wallet.testing.getRequestCounter()
+    const gateways = await wallet.lightning.listGateways()
+    expect(wallet.testing.getRequestCounter()).toBe(counterBefore + 1)
+    expect(gateways).toBeDefined()
+    expect(gateways).toMatchObject(expect.any(Array))
+  },
+)
+
+walletTest(
+  'updateGatewayCache should update the gateway cache',
+  async ({ wallet }) => {
+    expect(wallet).toBeDefined()
+    expect(wallet.isOpen()).toBe(true)
+
+    const counterBefore = wallet.testing.getRequestCounter()
+    await expect(wallet.lightning.updateGatewayCache()).resolves.toBeDefined()
+    expect(wallet.testing.getRequestCounter()).toBe(counterBefore + 1)
+  },
+)
+
+walletTest('getGateway should return a gateway', async ({ wallet }) => {
+  expect(wallet).toBeDefined()
+  expect(wallet.isOpen()).toBe(true)
+
+  const counterBefore = wallet.testing.getRequestCounter()
+  const gateway = await wallet.lightning.getGateway()
+  expect(wallet.testing.getRequestCounter()).toBe(counterBefore + 1)
+  expect(gateway).toMatchObject({
+    api: expect.any(String),
+    fees: expect.any(Object),
+    gateway_id: expect.any(String),
+    gateway_redeem_key: expect.any(String),
+    lightning_alias: expect.any(String),
+    mint_channel_id: expect.any(Number),
+    node_pub_key: expect.any(String),
+    route_hints: expect.any(Array),
+  })
+})
+
+walletTest(
+  'payInvoice should throw on insufficient funds',
+  async ({ wallet }) => {
+    expect(wallet).toBeDefined()
+    expect(wallet.isOpen()).toBe(true)
+
+    const invoice = await wallet.lightning.createInvoice(100, 'test')
+    expect(invoice).toBeDefined()
+    expect(invoice).toMatchObject({
+      invoice: expect.any(String),
+      operation_id: expect.any(String),
+    })
+
+    const counterBefore = wallet.testing.getRequestCounter()
+    // Insufficient funds
+    try {
+      await wallet.lightning.payInvoice(invoice.invoice)
+      expect.unreachable('Should throw error')
+    } catch (error) {
+      expect(error).toBeDefined()
+    }
+    // 3 requests were made, one for paying the invoice, one for refreshing the
+    // gateway cache, one for getting the gateway info
+    expect(wallet.testing.getRequestCounter()).toBe(counterBefore + 3)
+  },
+)
+
+walletTest(
+  'payInvoice should pay a bolt11 invoice',
+  { timeout: 20_000 },
+  async ({ fundedWallet }) => {
+    expect(fundedWallet).toBeDefined()
+    expect(fundedWallet.isOpen()).toBe(true)
+    const initialBalance = await fundedWallet.balance.getBalance()
+    expect(initialBalance).toBeGreaterThan(0)
+    const externalInvoice = await fundedWallet.testing.createFaucetInvoice(1)
+    const gatewayInfo = await fundedWallet.testing.getFaucetGatewayInfo()
+    const payment = await fundedWallet.lightning.payInvoice(
+      externalInvoice,
+      gatewayInfo,
+    )
+    expect(payment).toMatchObject({
+      contract_id: expect.any(String),
+      fee: expect.any(Number),
+      payment_type: expect.any(Object),
+    })
+    const finalBalance = await fundedWallet.balance.getBalance()
+    expect(finalBalance).toBeLessThan(initialBalance)
+  },
+)
+
+walletTest(
+  'createInvoiceTweaked should create a bolt11 invoice with a tweaked public key',
+  async ({ wallet }) => {
+    expect(wallet).toBeDefined()
+    expect(wallet.isOpen()).toBe(true)
+
+    // Make an ephemeral key pair
+    const { publicKey, secretKey } = keyPair()
+    const tweak = 1
+
+    // Create an invoice paying to the tweaked public key
+    const invoice = await wallet.lightning.createInvoiceTweaked(
+      1000,
+      'test tweaked',
+      publicKey,
+      tweak,
+    )
+    expect(invoice).toBeDefined()
+    expect(invoice).toMatchObject({
+      invoice: expect.any(String),
+      operation_id: expect.any(String),
+    })
+  },
+)
+
+walletTest(
+  'scanReceivesForTweaks should return the operation id',
+  async ({ wallet }) => {
+    expect(wallet).toBeDefined()
+    expect(wallet.isOpen()).toBe(true)
+
+    // Make an ephemeral key pair
+    const { publicKey, secretKey } = keyPair()
+    const tweak = 1
+
+    const gatewayInfo = await wallet.testing.getFaucetGatewayInfo()
+
+    // Create an invoice paying to the tweaked public key
+    const invoice = await wallet.lightning.createInvoiceTweaked(
+      1000,
+      'test tweaked',
+      publicKey,
+      tweak,
+      undefined,
+      gatewayInfo,
+    )
+    await expect(
+      wallet.testing.payFaucetInvoice(invoice.invoice),
+    ).resolves.toBeDefined()
+
+    // Scan for the receive
+    const operationIds = await wallet.lightning.scanReceivesForTweaks(
+      secretKey,
+      [tweak],
+      {},
+    )
+    expect(operationIds).toBeDefined()
+    expect(operationIds).toHaveLength(1)
+
+    // Subscribe to claiming the receive
+    const subscription = await wallet.lightning.subscribeLnClaim(
+      operationIds[0],
+      (state) => {
+        expect(state).toBeDefined()
+        expect(state).toMatchObject({
+          state: 'claimed',
+        })
+      },
+    )
+    expect(subscription).toBeDefined()
+  },
+)