@fedimint/core 0.1.0

package/src/services/LightningService.test.ts

@@ -0,0 +1,265 @@
+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()
+  },
+)
+
+walletTest(
+  'subscribe_internal_pay should return state',
+  async ({ fundedWallet }) => {
+    expect(fundedWallet).toBeDefined()
+    expect(fundedWallet.isOpen()).toBe(true)
+    const initialBalance = await fundedWallet.balance.getBalance()
+    expect(initialBalance).toBeGreaterThan(0)
+    const externalInvoice = (
+      await fundedWallet.lightning.createInvoice(1, 'test invoice')
+    ).invoice
+    const payment = await fundedWallet.lightning.payInvoice(externalInvoice)
+    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)
+    expect(payment.payment_type).toHaveProperty('internal')
+    if ('internal' in payment.payment_type) {
+      const id = payment.payment_type.internal
+      await new Promise<void>((resolve, reject) => {
+        const unsubscribe = fundedWallet.lightning.subscribeInternalPayment(
+          id,
+          (state) => {
+            try {
+              expect(state).toBeDefined()
+              expect(state).toBe('funding')
+              unsubscribe()
+              resolve()
+            } catch (err) {
+              reject(err)
+            }
+          },
+        )
+      })
+    } else {
+      const id = payment.payment_type.lightning
+      await new Promise<void>((resolve, reject) => {
+        const unsubscribe = fundedWallet.lightning.subscribeLnPay(
+          id,
+          (state) => {
+            try {
+              expect(state).toBeDefined()
+              expect(state).toBe('created')
+              unsubscribe()
+              resolve()
+            } catch (err) {
+              reject(err)
+            }
+          },
+        )
+      })
+    }
+  },
+)

package/src/services/LightningService.ts

@@ -0,0 +1,289 @@
+import { TransportClient } from '../transport'
+import type {
+  CreateBolt11Response,
+  GatewayInfo,
+  JSONObject,
+  LightningGateway,
+  LnInternalPayState,
+  LnPayState,
+  LnReceiveState,
+  OutgoingLightningPayment,
+} from '../types'
+
+export class LightningService {
+  constructor(private client: TransportClient) {}
+
+  /** 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)
+    })
+  }
+
+  subscribeInternalPayment(
+    operation_id: string,
+    onSuccess: (state: LnInternalPayState) => void = () => {},
+    onError: (error: string) => void = () => {},
+  ) {
+    return this.client.rpcStream(
+      'ln',
+      'subscribe_internal_pay',
+      { operation_id: operation_id },
+      onSuccess,
+      onError,
+    )
+  }
+
+  // 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,
+    })
+  },
+)