@fedimint/core 0.1.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@fedimint/core",
+  "description": "Core Fedimint client library for JavaScript environments",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fedimint/fedimint-web-sdk.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": [
+    "./dist/index.js"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@fedimint/types": "0.0.1"
+  },
+  "devDependencies": {
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@types/node": "^20.17.49",
+    "rollup": "^4.41.0",
+    "rollup-plugin-dts": "^6.2.1",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "rollup --config",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "clean:deep": "pnpm run clean && rm -rf node_modules",
+    "typecheck": "tsc --noEmit",
+    "typedoc": "typedoc"
+  }
+}

package/src/FedimintWallet.ts

@@ -0,0 +1,119 @@
+import { TransportClient } from './transport'
+import {
+  BalanceService,
+  MintService,
+  LightningService,
+  FederationService,
+  RecoveryService,
+  WalletService,
+} from './services'
+
+const DEFAULT_CLIENT_NAME = 'fm-default' as const
+
+export class FedimintWallet {
+  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.
+   *
+   * @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(private _client: TransportClient) {
+    this._openPromise = new Promise((resolve) => {
+      this._resolveOpen = resolve
+    })
+    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)
+  }
+
+  async waitForOpen() {
+    if (this._isOpen) return Promise.resolve()
+    return this._openPromise
+  }
+
+  async open(clientName: string = DEFAULT_CLIENT_NAME) {
+    // 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,
+  ) {
+    // 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) {
+      this._client.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
+  }
+}

package/src/WalletDirector.ts

@@ -0,0 +1,119 @@
+import { TransportClient } from './transport'
+import { type LogLevel } from './utils/logger'
+import { FederationConfig, JSONValue } from './types'
+import { Transport } from '@fedimint/types'
+import { FedimintWallet } from './FedimintWallet'
+
+export class WalletDirector {
+  // Protected to allow for TestWalletDirector to access the client
+  protected _client: TransportClient
+
+  /**
+   * Creates a new instance of WalletDirector.
+   *
+   * @param {Transport} [transport] - Optional worker client instance. Provide your
+   *                         own to use a custom transport (e.g. React Native).
+   *
+   * @param {boolean} lazy - If true, delays Web Worker and WebAssembly initialization
+   *                         until needed. Default is false.
+   */
+  constructor(transport: Transport, lazy: boolean = false) {
+    if (!transport) {
+      throw new Error('WalletDirector requires a transport implementation')
+    }
+    this._client = new TransportClient(transport)
+    this._client.logger.info('WalletDirector instantiated')
+    if (!lazy) {
+      this.initialize()
+    }
+  }
+
+  async initialize() {
+    this._client.logger.info('Initializing TransportClient')
+    await this._client.initialize()
+    this._client.logger.info('TransportClient initialized')
+  }
+
+  // TODO: Make this stateful... handle listing/joining/opening/closing wallets at this level
+  async createWallet() {
+    await this._client.initialize()
+    return new FedimintWallet(this._client)
+  }
+
+  async previewFederation(inviteCode: string) {
+    await this._client.initialize()
+    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) {
+    this._client.logger.setLevel(level)
+    this._client.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 TransportClient 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 TransportClient 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) {
+    await this._client.initialize()
+    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 TransportClient 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 TransportClient 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) {
+    await this._client.initialize()
+    const response = await this._client.sendSingleMessage<{
+      type: string
+      data: JSONValue
+      requestId: number
+    }>('parseBolt11Invoice', { invoiceStr })
+    return response
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { WalletDirector } from './WalletDirector'
+export { TransportClient } from './transport'
+export type { FedimintWallet } from './FedimintWallet'
+export type * from './types'

package/src/services/BalanceService.test.ts

@@ -0,0 +1,26 @@
+import { expect } from 'vitest'
+import { walletTest } from '../test/fixtures'
+
+walletTest('getBalance should be initially zero', async ({ wallet }) => {
+  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)
+})
+
+walletTest('subscribe balance', async ({ wallet }) => {
+  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 { TransportClient } from '../transport'
+
+/**
+ * Balance Service
+ *
+ * The Balance Service provides methods to interact with the balance of a Fedimint wallet.
+ */
+export class BalanceService {
+  constructor(private client: TransportClient) {}
+
+  /** 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,216 @@
+import type {
+  EcashTransaction,
+  LightningTransaction,
+  LnVariant,
+  MintVariant,
+  OperationKey,
+  OperationLog,
+  Transactions,
+  WalletTransaction,
+  WalletVariant,
+} from '../types'
+import { TransportClient } from '../transport'
+
+export class FederationService {
+  constructor(private client: TransportClient) {}
+
+  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(
+    limit?: number,
+    last_seen?: OperationKey,
+  ): Promise<[OperationKey, OperationLog][]> {
+    return await this.client.rpcSingle<[OperationKey, OperationLog][]>(
+      '',
+      'list_operations',
+      {
+        limit: limit ?? null,
+        last_seen: last_seen ?? null,
+      },
+    )
+  }
+
+  async getOperation(operationId: string) {
+    return await this.client.rpcSingle<OperationLog | null>(
+      '',
+      'get_operation',
+      { operation_id: operationId },
+    )
+  }
+
+  async listTransactions(
+    limit?: number,
+    last_seen?: OperationKey,
+  ): Promise<Transactions[]> {
+    const operations = await this.listOperations(limit, last_seen)
+    return operations
+      .filter(
+        (item): item is [OperationKey, OperationLog] =>
+          Array.isArray(item) && item.length === 2,
+      )
+      .filter(([_, op]) => {
+        const { operation_module_kind, meta } = op
+        const variant = meta.variant
+        return (
+          (operation_module_kind === 'ln' &&
+            ((variant as LnVariant).pay || (variant as LnVariant).receive)) ||
+          (operation_module_kind === 'mint' &&
+            ((variant as MintVariant).spend_o_o_b ||
+              (variant as MintVariant).reissuance)) ||
+          (operation_module_kind === 'wallet' &&
+            ((variant as WalletVariant).deposit ||
+              (variant as WalletVariant).withdraw))
+        )
+      })
+      .map(([key, op]) => {
+        const timestamp = key.creation_time
+          ? Math.round(
+              key.creation_time.secs_since_epoch * 1000 +
+                key.creation_time.nanos_since_epoch / 1_000_000,
+            )
+          : 0
+        const operationId = key.operation_id
+        const kind = op.operation_module_kind as 'ln' | 'mint' | 'wallet'
+        const meta = op.meta
+        const variant = meta.variant
+
+        let outcome: string | undefined
+        if (op.outcome && op.outcome.outcome) {
+          if (typeof op.outcome.outcome === 'string') {
+            outcome = op.outcome.outcome
+          } else if (
+            typeof op.outcome.outcome === 'object' &&
+            op.outcome.outcome !== null
+          ) {
+            if ('success' in op.outcome.outcome) outcome = 'success'
+            else if ('canceled' in op.outcome.outcome) outcome = 'canceled'
+            else if ('claimed' in op.outcome.outcome) outcome = 'claimed'
+            else if ('funded' in op.outcome.outcome) outcome = 'funded'
+            else if ('awaiting_funds' in op.outcome.outcome)
+              outcome = 'awaiting_funds'
+            else if ('unexpected_error' in op.outcome.outcome)
+              outcome = 'unexpected_error'
+            else if ('created' in op.outcome.outcome) outcome = 'created'
+            else if ('waiting_for_refund' in op.outcome.outcome)
+              outcome = 'canceled'
+            else if ('awaiting_change' in op.outcome.outcome)
+              outcome = 'pending'
+            else if ('refunded' in op.outcome.outcome) outcome = 'refunded'
+            else if ('waiting_for_payment' in op.outcome.outcome)
+              outcome = 'awaiting_funds'
+            else if ('Created' in op.outcome.outcome) outcome = 'Created'
+            else if ('Success' in op.outcome.outcome) outcome = 'Success'
+            else if ('Refunded' in op.outcome.outcome) outcome = 'Refunded'
+            else if ('UserCanceledProcessing' in op.outcome.outcome)
+              outcome = 'UserCanceledProcessing'
+            else if ('UserCanceledSuccess' in op.outcome.outcome)
+              outcome = 'UserCanceledSuccess'
+            else if ('UserCanceledFailure' in op.outcome.outcome)
+              outcome = 'UserCanceledFailure'
+            else if ('WaitingForTransaction' in op.outcome.outcome)
+              outcome = 'pending'
+            else if ('WaitingForConfirmation' in op.outcome.outcome)
+              outcome = 'pending'
+            else if ('Confirmed' in op.outcome.outcome) outcome = 'Confirmed'
+            else if ('Claimed' in op.outcome.outcome) outcome = 'Claimed'
+            else if ('Failed' in op.outcome.outcome) outcome = 'Failed'
+          }
+        }
+
+        if (kind === 'ln') {
+          const isPay = !!(variant as LnVariant).pay
+          const txId =
+            (variant as LnVariant).pay?.out_point.txid ||
+            (variant as LnVariant).receive?.out_point.txid ||
+            ''
+          const type = (variant as LnVariant).pay ? 'send' : 'receive'
+          const invoice =
+            (variant as LnVariant).pay?.invoice ||
+            (variant as LnVariant).receive?.invoice ||
+            ''
+          const gateway =
+            (variant as LnVariant).pay?.gateway_id ||
+            (variant as LnVariant).receive?.gateway_id ||
+            ''
+          const fee = (variant as LnVariant).pay?.fee
+          const internalPay = (variant as LnVariant).pay?.is_internal_payment
+          const preimage =
+            isPay &&
+            op.outcome?.outcome &&
+            typeof op.outcome.outcome === 'object' &&
+            'success' in op.outcome.outcome
+              ? op.outcome.outcome.success.preimage
+              : undefined
+
+          return {
+            timestamp,
+            operationId,
+            kind,
+            txId,
+            type,
+            invoice,
+            internalPay,
+            fee,
+            gateway,
+            outcome: outcome as LightningTransaction['outcome'],
+          } as LightningTransaction
+        } else if (kind === 'mint') {
+          const txId = (variant as MintVariant).reissuance?.txid
+          const type = (variant as MintVariant).reissuance
+            ? 'reissue'
+            : 'spend_oob'
+          const amountMsats = meta.amount
+          const notes = (variant as MintVariant).spend_o_o_b?.oob_notes
+
+          return {
+            timestamp,
+            type,
+            txId,
+            outcome: outcome as EcashTransaction['outcome'],
+            operationId,
+            amountMsats,
+            notes,
+            kind,
+          } as EcashTransaction
+        } else if (kind === 'wallet') {
+          const type = (variant as WalletVariant).deposit
+            ? 'deposit'
+            : 'withdraw'
+          const address =
+            (variant as WalletVariant).deposit?.address ||
+            (variant as WalletVariant).withdraw?.address ||
+            ''
+          const feeRate = (variant as WalletVariant).withdraw?.fee.fee_rate
+            .sats_per_kvb
+          const amountMsats =
+            (variant as WalletVariant).withdraw?.amountMsats || 0
+
+          return {
+            timestamp,
+            type,
+            onchainAddress: address,
+            fee: feeRate || 0,
+            amountMsats,
+            outcome,
+            kind,
+            operationId,
+          } as WalletTransaction
+        }
+      })
+      .filter(
+        (transaction): transaction is Transactions => transaction !== undefined,
+      )
+  }
+}