@fedimint/core-web 0.0.0-20250617190659

package/src/services/LightningService.ts

@@ -0,0 +1,274 @@
+import { WorkerClient } from '../worker'
+import type {
+  CreateBolt11Response,
+  GatewayInfo,
+  JSONObject,
+  LightningGateway,
+  LnPayState,
+  LnReceiveState,
+  OutgoingLightningPayment,
+} from '../types'
+
+export class LightningService {
+  constructor(private client: WorkerClient) {}
+
+  /** https://web.fedimint.org/core/FedimintWallet/LightningService/createInvoice#lightning-createinvoice */
+  async createInvoice(
+    amountMsats: number,
+    description: string,
+    expiryTime?: number, // in seconds
+    gatewayInfo?: GatewayInfo,
+    extraMeta?: JSONObject,
+  ) {
+    const gateway = gatewayInfo ?? (await this._getDefaultGatewayInfo())
+    return await this.client.rpcSingle<CreateBolt11Response>(
+      'ln',
+      'create_bolt11_invoice',
+      {
+        amount: amountMsats,
+        description,
+        expiry_time: expiryTime ?? null,
+        extra_meta: extraMeta ?? {},
+        gateway,
+      },
+    )
+  }
+
+  async createInvoiceTweaked(
+    amountMsats: number,
+    description: string,
+    tweakKey: string,
+    index: number,
+    expiryTime?: number, // in seconds
+    gatewayInfo?: GatewayInfo,
+    extraMeta?: JSONObject,
+  ) {
+    const gateway = gatewayInfo ?? (await this._getDefaultGatewayInfo())
+    return await this.client.rpcSingle<CreateBolt11Response>(
+      'ln',
+      'create_bolt11_invoice_for_user_tweaked',
+      {
+        amount: amountMsats,
+        description,
+        expiry_time: expiryTime ?? null,
+        user_key: tweakKey,
+        index,
+        extra_meta: extraMeta ?? {},
+        gateway,
+      },
+    )
+  }
+
+  // Returns the operation ids of payments received to the tweaks of the user secret key
+  async scanReceivesForTweaks(
+    tweakKey: string,
+    indices: number[],
+    extraMeta?: JSONObject,
+  ) {
+    return await this.client.rpcSingle<string[]>(
+      'ln',
+      'scan_receive_for_user_tweaked',
+      {
+        user_key: tweakKey,
+        indices,
+        extra_meta: extraMeta ?? {},
+      },
+    )
+  }
+
+  private async _getDefaultGatewayInfo() {
+    await this.updateGatewayCache()
+    const gateways = await this.listGateways()
+    return gateways[0]?.info
+  }
+
+  /** https://web.fedimint.org/core/FedimintWallet/LightningService/payInvoice#lightning-payinvoice-invoice-string */
+  async payInvoice(
+    invoice: string,
+    gatewayInfo?: GatewayInfo,
+    extraMeta?: JSONObject,
+  ) {
+    const gateway = gatewayInfo ?? (await this._getDefaultGatewayInfo())
+    return await this.client.rpcSingle<OutgoingLightningPayment>(
+      'ln',
+      'pay_bolt11_invoice',
+      {
+        maybe_gateway: gateway,
+        invoice,
+        extra_meta: extraMeta ?? {},
+      },
+    )
+  }
+
+  /** https://web.fedimint.org/core/FedimintWallet/LightningService/payInvoice#lightning-payinvoicesync-invoice-string */
+  async payInvoiceSync(
+    invoice: string,
+    timeoutMs: number = 10000,
+    gatewayInfo?: GatewayInfo,
+    extraMeta?: JSONObject,
+  ) {
+    return new Promise<
+      | { success: false; error?: string }
+      | {
+          success: true
+          data: { feeMsats: number; preimage: string }
+        }
+    >(async (resolve, reject) => {
+      const { contract_id, fee } = await this.payInvoice(
+        invoice,
+        gatewayInfo,
+        extraMeta,
+      )
+
+      // TODO: handle  error handling for other subscription statuses
+      const unsubscribe = this.subscribeLnPay(contract_id, (res) => {
+        if (typeof res !== 'string' && 'success' in res) {
+          clearTimeout(timeoutId)
+          unsubscribe()
+          resolve({
+            success: true,
+            data: { feeMsats: fee, preimage: res.success.preimage },
+          })
+        } else if (typeof res !== 'string' && 'unexpected_error' in res) {
+          reject(new Error(res.unexpected_error.error_message))
+        }
+      })
+
+      const timeoutId = setTimeout(() => {
+        unsubscribe()
+        resolve({ success: false, error: 'Payment timeout' })
+      }, timeoutMs)
+    })
+  }
+
+  // TODO: Document
+  subscribeLnClaim(
+    operationId: string,
+    onSuccess: (state: LnReceiveState) => void = () => {},
+    onError: (error: string) => void = () => {},
+  ) {
+    return this.client.rpcStream(
+      'ln',
+      'subscribe_ln_claim',
+      { operation_id: operationId },
+      onSuccess,
+      onError,
+    )
+  }
+
+  // TODO: Document (for external payments only)
+  // TODO: Make this work for BOTH internal and external payments
+  /** https://web.fedimint.org/core/FedimintWallet/LightningService/payInvoice#lightning-payinvoice-invoice-string */
+  subscribeLnPay(
+    operationId: string,
+    onSuccess: (state: LnPayState) => void = () => {},
+    onError: (error: string) => void = () => {},
+  ) {
+    return this.client.rpcStream(
+      'ln',
+      'subscribe_ln_pay',
+      { operation_id: operationId },
+      onSuccess,
+      onError,
+    )
+  }
+
+  /** https://web.fedimint.org/core/FedimintWallet/LightningService/payInvoice#lightning-payinvoice-invoice-string */
+  async waitForPay(operationId: string) {
+    return new Promise<
+      | { success: false; error?: string }
+      | { success: true; data: { preimage: string } }
+    >((resolve, reject) => {
+      let unsubscribe: () => void
+      const timeoutId = setTimeout(() => {
+        resolve({ success: false, error: 'Waiting for receive timeout' })
+      }, 15000)
+
+      unsubscribe = this.subscribeLnPay(
+        operationId,
+        (res) => {
+          if (typeof res !== 'string' && 'success' in res) {
+            clearTimeout(timeoutId)
+            unsubscribe()
+            resolve({
+              success: true,
+              data: { preimage: res.success.preimage },
+            })
+          }
+        },
+        (error) => {
+          clearTimeout(timeoutId)
+          unsubscribe()
+          reject(error)
+        },
+      )
+    })
+  }
+
+  /** https://web.fedimint.org/core/FedimintWallet/LightningService/createInvoice#lightning-createinvoice */
+  subscribeLnReceive(
+    operationId: string,
+    onSuccess: (state: LnReceiveState) => void = () => {},
+    onError: (error: string) => void = () => {},
+  ) {
+    return this.client.rpcStream(
+      'ln',
+      'subscribe_ln_receive',
+      { operation_id: operationId },
+      onSuccess,
+      onError,
+    )
+  }
+
+  /** https://web.fedimint.org/core/FedimintWallet/LightningService/createInvoice#lightning-createinvoice */
+  async waitForReceive(operationId: string, timeoutMs: number = 15000) {
+    return new Promise<LnReceiveState>((resolve, reject) => {
+      let unsubscribe: () => void
+      const timeoutId = setTimeout(() => {
+        reject(new Error('Timeout waiting for receive'))
+      }, timeoutMs)
+
+      unsubscribe = this.subscribeLnReceive(
+        operationId,
+        (res) => {
+          if (res === 'claimed') {
+            clearTimeout(timeoutId)
+            unsubscribe()
+            resolve(res)
+          }
+        },
+        (error) => {
+          clearTimeout(timeoutId)
+          unsubscribe()
+          reject(error)
+        },
+      )
+    })
+  }
+
+  async getGateway(
+    gatewayId: string | null = null,
+    forceInternal: boolean = false,
+  ) {
+    return await this.client.rpcSingle<LightningGateway | null>(
+      'ln',
+      'get_gateway',
+      {
+        gateway_id: gatewayId,
+        force_internal: forceInternal,
+      },
+    )
+  }
+
+  async listGateways() {
+    return await this.client.rpcSingle<LightningGateway[]>(
+      'ln',
+      'list_gateways',
+      {},
+    )
+  }
+
+  async updateGatewayCache() {
+    return await this.client.rpcSingle('ln', 'update_gateway_cache', {})
+  }
+}

package/src/services/MintService.test.ts

@@ -0,0 +1,74 @@
+import { expect } from 'vitest'
+import { walletTest } from '../test/fixtures'
+
+walletTest('redeemEcash should error on invalid ecash', async ({ wallet }) => {
+  expect(wallet).toBeDefined()
+  expect(wallet.isOpen()).toBe(true)
+
+  await expect(wallet.mint.redeemEcash('test')).rejects.toThrow()
+})
+
+walletTest(
+  'reissueExternalNotes should throw if wallet is empty',
+  async ({ wallet }) => {
+    expect(wallet).toBeDefined()
+    expect(wallet.isOpen()).toBe(true)
+
+    await expect(wallet.mint.reissueExternalNotes('test')).rejects.toThrow()
+  },
+)
+
+walletTest('spendNotes should throw if wallet is empty', async ({ wallet }) => {
+  expect(wallet).toBeDefined()
+  expect(wallet.isOpen()).toBe(true)
+
+  await expect(wallet.mint.spendNotes(100)).rejects.toThrow()
+})
+
+walletTest('parseNotes should parse notes', async ({ wallet }) => {
+  expect(wallet).toBeDefined()
+  expect(wallet.isOpen()).toBe(true)
+
+  await expect(wallet.mint.reissueExternalNotes('test')).rejects.toThrow()
+})
+
+walletTest(
+  'getNotesByDenomination should return empty object if wallet is empty',
+  async ({ wallet }) => {
+    expect(wallet).toBeDefined()
+    expect(wallet.isOpen()).toBe(true)
+
+    const notes = await wallet.mint.getNotesByDenomination()
+    const balance = await wallet.balance.getBalance()
+    expect(balance).toEqual(0)
+    expect(notes).toBeDefined()
+    expect(notes).toEqual({})
+  },
+)
+
+walletTest(
+  'getNotesByDenomination should get notes by denomination',
+  async ({ fundedWallet }) => {
+    expect(fundedWallet).toBeDefined()
+    expect(fundedWallet.isOpen()).toBe(true)
+
+    const notes = await fundedWallet.mint.getNotesByDenomination()
+    const balance = await fundedWallet.balance.getBalance()
+    expect(balance).toEqual(10000)
+    expect(notes).toBeDefined()
+    expect(notes).toEqual({
+      '1': 2,
+      '1024': 3,
+      '128': 2,
+      '16': 3,
+      '2': 3,
+      '2048': 2,
+      '256': 3,
+      '32': 2,
+      '4': 2,
+      '512': 3,
+      '64': 2,
+      '8': 2,
+    })
+  },
+)

package/src/services/MintService.ts

@@ -0,0 +1,129 @@
+import { WorkerClient } from '../worker'
+import type {
+  Duration,
+  JSONObject,
+  JSONValue,
+  MintSpendNotesResponse,
+  MSats,
+  NoteCountByDenomination,
+  ReissueExternalNotesState,
+  SpendNotesState,
+} from '../types'
+
+export class MintService {
+  constructor(private client: WorkerClient) {}
+
+  /** https://web.fedimint.org/core/FedimintWallet/MintService/redeemEcash */
+  async redeemEcash(notes: string) {
+    return await this.client.rpcSingle<string>(
+      'mint',
+      'reissue_external_notes',
+      {
+        oob_notes: notes, // "out of band notes"
+        extra_meta: null,
+      },
+    )
+  }
+
+  async reissueExternalNotes(oobNotes: string, extraMeta: JSONObject = {}) {
+    return await this.client.rpcSingle<string>(
+      'mint',
+      'reissue_external_notes',
+      {
+        oob_notes: oobNotes,
+        extra_meta: extraMeta,
+      },
+    )
+  }
+
+  subscribeReissueExternalNotes(
+    operationId: string,
+    onSuccess: (state: ReissueExternalNotesState) => void = () => {},
+    onError: (error: string) => void = () => {},
+  ) {
+    const unsubscribe = this.client.rpcStream<ReissueExternalNotesState>(
+      'mint',
+      'subscribe_reissue_external_notes',
+      { operation_id: operationId },
+      onSuccess,
+      onError,
+    )
+
+    return unsubscribe
+  }
+
+  /** https://web.fedimint.org/core/FedimintWallet/MintService/spendNotes */
+  async spendNotes(
+    amountMsats: number,
+    // Tells the wallet to automatically try to cancel the spend if it hasn't completed
+    // after the specified number of seconds. If the receiver has already redeemed
+    // the notes at this time, the notes will not be cancelled.
+    tryCancelAfter: number | Duration = 3600 * 24, // defaults to 1 day
+    includeInvite: boolean = false,
+    extraMeta: JSONValue = {},
+  ) {
+    const duration =
+      typeof tryCancelAfter === 'number'
+        ? { nanos: 0, secs: tryCancelAfter }
+        : tryCancelAfter
+
+    const res = await this.client.rpcSingle<MintSpendNotesResponse>(
+      'mint',
+      'spend_notes',
+      {
+        amount: amountMsats,
+        try_cancel_after: duration,
+        include_invite: includeInvite,
+        extra_meta: extraMeta,
+      },
+    )
+    const notes = res[1]
+    const operationId = res[0]
+
+    return {
+      notes,
+      operation_id: operationId,
+    }
+  }
+
+  /** https://web.fedimint.org/core/FedimintWallet/MintService/parseEcash */
+  async parseNotes(oobNotes: string) {
+    return await this.client.rpcSingle<MSats>('mint', 'validate_notes', {
+      oob_notes: oobNotes,
+    })
+  }
+
+  async tryCancelSpendNotes(operationId: string) {
+    await this.client.rpcSingle('mint', 'try_cancel_spend_notes', {
+      operation_id: operationId,
+    })
+  }
+
+  subscribeSpendNotes(
+    operationId: string,
+    onSuccess: (state: SpendNotesState) => void = () => {},
+    onError: (error: string) => void = () => {},
+  ) {
+    return this.client.rpcStream<SpendNotesState>(
+      'mint',
+      'subscribe_spend_notes',
+      { operation_id: operationId },
+      (res) => onSuccess(res),
+      onError,
+    )
+  }
+
+  async awaitSpendOobRefund(operationId: string) {
+    return await this.client.rpcSingle('mint', 'await_spend_oob_refund', {
+      operation_id: operationId,
+    })
+  }
+
+  async getNotesByDenomination() {
+    return await this.client.rpcSingle<NoteCountByDenomination>(
+      'mint',
+      'note_counts_by_denomination',
+      {},
+    )
+  }
+}

package/src/services/RecoveryService.ts

@@ -0,0 +1,28 @@
+import type { JSONValue } from '../types'
+import { WorkerClient } from '../worker'
+
+export class RecoveryService {
+  constructor(private client: WorkerClient) {}
+
+  async hasPendingRecoveries() {
+    return await this.client.rpcSingle<boolean>(
+      '',
+      'has_pending_recoveries',
+      {},
+    )
+  }
+
+  async waitForAllRecoveries() {
+    await this.client.rpcSingle('', 'wait_for_all_recoveries', {})
+  }
+
+  subscribeToRecoveryProgress(
+    onSuccess: (progress: { module_id: number; progress: JSONValue }) => void,
+    onError: (error: string) => void,
+  ) {
+    return this.client.rpcStream<{
+      module_id: number
+      progress: JSONValue
+    }>('', 'subscribe_to_recovery_progress', {}, onSuccess, onError)
+  }
+}

package/src/services/WalletService.test.ts

@@ -0,0 +1,24 @@
+import { expect } from 'vitest'
+import { walletTest } from '../test/fixtures'
+import { TxOutputSummary, WalletSummary } from '../types'
+
+walletTest(
+  'getWalletSummary should return empty object if wallet is empty',
+  async ({ wallet }) => {
+    expect(wallet).toBeDefined()
+    expect(wallet.isOpen()).toBe(true)
+
+    const balance = await wallet.balance.getBalance()
+    expect(balance).toEqual(0)
+
+    const summary = await wallet.wallet.getWalletSummary()
+    const expectedSummary = {
+      spendable_utxos: expect.any(Array<TxOutputSummary>),
+      unsigned_peg_out_txos: expect.any(Array<TxOutputSummary>),
+      unsigned_change_utxos: expect.any(Array<TxOutputSummary>),
+      unconfirmed_peg_out_txos: expect.any(Array<TxOutputSummary>),
+      unconfirmed_change_utxos: expect.any(Array<TxOutputSummary>),
+    } satisfies WalletSummary
+    expect(summary).toEqual(expect.objectContaining(expectedSummary))
+  },
+)

package/src/services/WalletService.ts

@@ -0,0 +1,10 @@
+import { WalletSummary } from '../types'
+import { WorkerClient } from '../worker'
+
+export class WalletService {
+  constructor(private client: WorkerClient) {}
+
+  async getWalletSummary(): Promise<WalletSummary> {
+    return await this.client.rpcSingle('wallet', 'get_wallet_summary', {})
+  }
+}

package/src/services/index.ts

@@ -0,0 +1,6 @@
+export { MintService } from './MintService'
+export { BalanceService } from './BalanceService'
+export { LightningService } from './LightningService'
+export { RecoveryService } from './RecoveryService'
+export { FederationService } from './FederationService'
+export { WalletService } from './WalletService'

package/src/test/TestFedimintWallet.ts

@@ -0,0 +1,26 @@
+import { FedimintWallet } from '../FedimintWallet'
+import { WorkerClient } from '../worker/WorkerClient'
+import { TestingService } from './TestingService'
+
+export class TestFedimintWallet extends FedimintWallet {
+  public testing: TestingService
+
+  constructor() {
+    super()
+    this.testing = new TestingService(this.getWorkerClient(), this.lightning)
+  }
+
+  async fundWallet(amount: number) {
+    const info = await this.testing.getFaucetGatewayInfo()
+    const invoice = await this.lightning.createInvoice(amount, '', 1000, info)
+    await Promise.all([
+      this.testing.payFaucetInvoice(invoice.invoice),
+      this.lightning.waitForReceive(invoice.operation_id),
+    ])
+  }
+
+  // Method to expose the WorkerClient
+  getWorkerClient(): WorkerClient {
+    return this['_client']
+  }
+}

package/src/test/TestingService.ts

@@ -0,0 +1,79 @@
+import { LightningService } from '../services'
+import { WorkerClient } from '../worker'
+
+export const TESTING_INVITE =
+  'fed11qgqrsdnhwden5te0v9cxjtt4dekxzamxw4kz6mmjvvkhydted9ukg6r9xfsnx7th0fhn26tf093juamwv4u8gtnpwpcz7qqpyz0e327ua8geceutfrcaezwt22mk6s2rdy09kg72jrcmncng2gn0kp2m5sk'
+
+// This is a testing service that allows for inspecting the internals
+// of the WorkerClient. It is not intended for use in production.
+export class TestingService {
+  public TESTING_INVITE: string
+  constructor(
+    private client: WorkerClient,
+    private lightning: LightningService,
+  ) {
+    // Solo Mint on mutinynet
+    this.TESTING_INVITE = TESTING_INVITE
+  }
+
+  getRequestCounter() {
+    return this.client._getRequestCounter()
+  }
+
+  getRequestCallbackMap() {
+    return this.client._getRequestCallbackMap()
+  }
+
+  async getInviteCode() {
+    const res = await fetch(`${import.meta.env.FAUCET}/connect-string`)
+    if (res.ok) {
+      return await res.text()
+    } else {
+      throw new Error(`Failed to get invite code: ${await res.text()}`)
+    }
+  }
+
+  private async getFaucetGatewayApi() {
+    const res = await fetch(`${import.meta.env.FAUCET}/gateway-api`)
+    if (res.ok) {
+      return await res.text()
+    } else {
+      throw new Error(`Failed to get gateway: ${await res.text()}`)
+    }
+  }
+
+  async getFaucetGatewayInfo() {
+    await this.lightning.updateGatewayCache()
+    const gateways = await this.lightning.listGateways()
+    const api = await this.getFaucetGatewayApi()
+    const gateway = gateways.find((g) => g.info.api === api)
+    if (!gateway) {
+      throw new Error(`Gateway not found: ${api}`)
+    }
+    return gateway.info
+  }
+
+  async payFaucetInvoice(invoice: string) {
+    const res = await fetch(`${import.meta.env.FAUCET}/pay`, {
+      method: 'POST',
+      body: invoice,
+    })
+    if (res.ok) {
+      return await res.text()
+    } else {
+      throw new Error(`Failed to pay faucet invoice: ${await res.text()}`)
+    }
+  }
+
+  async createFaucetInvoice(amount: number) {
+    const res = await fetch(`${import.meta.env.FAUCET}/invoice`, {
+      method: 'POST',
+      body: amount.toString(),
+    })
+    if (res.ok) {
+      return await res.text()
+    } else {
+      throw new Error(`Failed to generate faucet invoice: ${await res.text()}`)
+    }
+  }
+}

package/src/test/crypto.ts

@@ -0,0 +1,44 @@
+import * as secp256k1 from 'secp256k1'
+
+const randomBytes = (size: number): Uint8Array => {
+  const array = new Uint8Array(size)
+  window.crypto.getRandomValues(array)
+  return array
+}
+
+interface KeyPair {
+  secretKey: string
+  publicKey: string
+}
+
+export const keyPair = (secretKey?: Uint8Array): KeyPair => {
+  const privateKey: Uint8Array = secretKey
+    ? validatePrivateKey(secretKey)
+    : generatePrivateKey()
+
+  const publicKey = secp256k1.publicKeyCreate(privateKey)
+
+  return {
+    secretKey: Array.from(privateKey)
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join(''), // Convert Uint8Array to hex string
+    publicKey: Array.from(publicKey)
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join(''), // Convert Uint8Array to hex string
+  }
+}
+
+const validatePrivateKey = (key: Uint8Array): Uint8Array => {
+  if (!secp256k1.privateKeyVerify(key)) {
+    throw new Error('Invalid private key provided')
+  }
+  return key
+}
+
+const generatePrivateKey = (): Uint8Array => {
+  let key: Uint8Array
+  do {
+    key = randomBytes(32)
+  } while (!secp256k1.privateKeyVerify(key))
+  return key
+}