@fedimint/core 0.1.0

package/src/services/MintService.ts

@@ -0,0 +1,129 @@
+import { TransportClient } from '../transport'
+import type {
+  Duration,
+  JSONObject,
+  JSONValue,
+  MintSpendNotesResponse,
+  MSats,
+  NoteCountByDenomination,
+  ReissueExternalNotesState,
+  SpendNotesState,
+} from '../types'
+
+export class MintService {
+  constructor(private client: TransportClient) {}
+
+  /** 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 { TransportClient } from '../transport'
+
+export class RecoveryService {
+  constructor(private client: TransportClient) {}
+
+  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,59 @@
+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))
+  },
+)
+
+walletTest(
+  'generateAddress should always return an address',
+  async ({ wallet }) => {
+    expect(wallet).toBeDefined()
+    expect(wallet.isOpen()).toBe(true)
+    const response = await wallet.wallet.generateAddress()
+
+    expect(response, 'generateAddress').toEqual({
+      deposit_address: expect.any(String),
+      operation_id: expect.any(String),
+    })
+  },
+)
+
+walletTest(
+  'sendOnchain should return an operation ID after sending funds',
+  async ({ fundedWalletBeefy }) => {
+    expect(fundedWalletBeefy).toBeDefined()
+    expect(fundedWalletBeefy.isOpen()).toBe(true)
+
+    const amountSat = 100
+    const address =
+      'bcrt1qphk8q2v8he2autevdcefnnwjl4yc2hm74uuvhaa6nhrnkd3gfrwq6mnr76'
+
+    const response = await fundedWalletBeefy.wallet.sendOnchain(
+      amountSat,
+      address,
+    )
+
+    expect(response, 'send onchain').toEqual({
+      operation_id: expect.any(String),
+    })
+  },
+)

package/src/services/WalletService.ts

@@ -0,0 +1,50 @@
+import {
+  JSONValue,
+  WalletSummary,
+  GenerateAddressResponse,
+  WalletDepositState,
+} from '../types'
+import { TransportClient } from '../transport'
+
+export class WalletService {
+  constructor(private client: TransportClient) {}
+
+  async getWalletSummary(): Promise<WalletSummary> {
+    return await this.client.rpcSingle('wallet', 'get_wallet_summary', {})
+  }
+
+  async generateAddress(extraMeta: JSONValue = {}) {
+    return await this.client.rpcSingle<GenerateAddressResponse>(
+      'wallet',
+      'peg_in',
+      {
+        extra_meta: extraMeta,
+      },
+    )
+  }
+
+  async sendOnchain(
+    amountSat: number,
+    address: string,
+    extraMeta: JSONValue = {},
+  ): Promise<{ operation_id: string }> {
+    return await this.client.rpcSingle('wallet', 'peg_out', {
+      amount_sat: amountSat,
+      destination_address: address,
+      extra_meta: extraMeta,
+    })
+  }
+  subscribeDeposit(
+    operation_id: string,
+    onSuccess: (state: WalletDepositState) => void = () => {},
+    onError: (error: string) => void = () => {},
+  ) {
+    return this.client.rpcStream(
+      'ln',
+      'subscribe_deposit',
+      { operation_id: operation_id },
+      onSuccess,
+      onError,
+    )
+  }
+}

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/transport/TransportClient.ts

@@ -0,0 +1,254 @@
+import type {
+  CancelFunction,
+  JSONValue,
+  ModuleKind,
+  StreamError,
+  StreamResult,
+} from '../types'
+import { Logger } from '../utils/logger'
+import type {
+  Transport,
+  TransportMessage,
+  TransportMessageType,
+} from '@fedimint/types'
+
+/**
+ * Handles communication with a generic transport.
+ * Must be instantiated with a platform-specific transport. (wasm for web, react native, etc.)
+ */
+export class TransportClient {
+  // Generic Transport. Can be wasm, react native, node, etc.
+  private readonly transport: Transport
+  private requestCounter = 0
+  private requestCallbacks = new Map<number, (value: any) => void>()
+  private initPromise: Promise<boolean> | undefined = undefined
+  logger: Logger
+
+  /**
+   * @summary Constructor for the TransportClient
+   * @param transport - The platform-specific transport to use. (wasm for web, react native, etc.)
+   */
+  constructor(transport: Transport) {
+    this.transport = transport
+    this.logger = new Logger(transport.logger)
+    this.transport.setMessageHandler(this.handleTransportMessage)
+    this.transport.setErrorHandler(this.handleTransportError)
+    this.logger.info('TransportClient instantiated')
+    this.logger.debug('TransportClient transport', transport)
+  }
+
+  // Idempotent setup - Loads the wasm module
+  initialize() {
+    if (this.initPromise) return this.initPromise
+    this.initPromise = this.sendSingleMessage('init')
+    return this.initPromise
+  }
+
+  private handleLogMessage(message: TransportMessage) {
+    const { type, level, message: logMessage, ...data } = message
+    this.logger.info(String(level), String(logMessage), data)
+  }
+
+  private handleTransportError = (error: unknown) => {
+    this.logger.error('TransportClient error', error)
+  }
+
+  private handleTransportMessage = (message: TransportMessage) => {
+    const { type, requestId, ...data } = message
+    if (type === 'log') {
+      this.handleLogMessage(message)
+    }
+    const streamCallback =
+      requestId !== undefined ? this.requestCallbacks.get(requestId) : undefined
+    // TODO: Handle errors... maybe have another callbacks list for errors?
+    this.logger.debug('TransportClient - handleTransportMessage', message)
+    if (streamCallback) {
+      streamCallback(data) // {data: something} OR {error: something}
+    } else if (requestId !== undefined) {
+      this.logger.warn(
+        'TransportClient - handleTransportMessage - received message with no callback',
+        requestId,
+        message,
+      )
+    }
+  }
+
+  // TODO: Handle errors... maybe have another callbacks list for errors?
+  // TODO: Handle timeouts
+  // TODO: Handle multiple errors
+
+  sendSingleMessage<
+    Response extends JSONValue = JSONValue,
+    Payload extends JSONValue = JSONValue,
+  >(type: TransportMessageType, payload?: Payload) {
+    return new Promise<Response>((resolve, reject) => {
+      const requestId = ++this.requestCounter
+      this.logger.debug(
+        'TransportClient - sendSingleMessage',
+        requestId,
+        type,
+        payload,
+      )
+      this.requestCallbacks.set(
+        requestId,
+        (response: StreamResult<Response>) => {
+          this.requestCallbacks.delete(requestId)
+          this.logger.debug(
+            'TransportClient - sendSingleMessage - response',
+            requestId,
+            response,
+          )
+          if (response.data) resolve(response.data)
+          else if (response.error) reject(response.error)
+          else
+            this.logger.warn(
+              'TransportClient - sendSingleMessage - malformed response',
+              requestId,
+              response,
+            )
+        },
+      )
+      this.transport.postMessage({ type, payload, requestId })
+    })
+  }
+
+  /**
+   * @summary Initiates an RPC stream with the specified module and method.
+   *
+   * @description
+   * This function sets up an RPC stream by sending a request to a worker and
+   * handling responses asynchronously. It ensures that unsubscription is handled
+   * correctly, even if the unsubscribe function is called before the subscription
+   * is fully established, by deferring the unsubscription attempt using `setTimeout`.
+   *
+   * The function operates in a non-blocking manner, leveraging Promises to manage
+   * asynchronous operations and callbacks to handle responses.
+   *
+   *
+   * @template Response - The expected type of the successful response.
+   * @template Body - The type of the request body.
+   * @param module - The module kind to interact with.
+   * @param method - The method name to invoke on the module.
+   * @param body - The request payload.
+   * @param onSuccess - Callback invoked with the response data on success.
+   * @param onError - Callback invoked with error information if an error occurs.
+   * @param onEnd - Optional callback invoked when the stream ends.
+   * @returns A function that can be called to cancel the subscription.
+   *
+   */
+  rpcStream<
+    Response extends JSONValue = JSONValue,
+    Body extends JSONValue = JSONValue,
+  >(
+    module: ModuleKind,
+    method: string,
+    body: Body,
+    onSuccess: (res: Response) => void,
+    onError: (res: StreamError['error']) => void,
+    onEnd: () => void = () => {},
+  ): CancelFunction {
+    const requestId = ++this.requestCounter
+    this.logger.debug(
+      'TransportClient - rpcStream',
+      requestId,
+      module,
+      method,
+      body,
+    )
+    let unsubscribe: (value: void) => void = () => {}
+    let isSubscribed = false
+
+    const unsubscribePromise = new Promise<void>((resolve) => {
+      unsubscribe = () => {
+        if (isSubscribed) {
+          // If already subscribed, resolve immediately to trigger unsubscription
+          resolve()
+        } else {
+          // If not yet subscribed, defer the unsubscribe attempt to the next event loop tick
+          // This ensures that subscription setup has time to complete
+          setTimeout(() => unsubscribe(), 0)
+        }
+      }
+    })
+
+    // Initiate the inner RPC stream setup asynchronously
+    this._rpcStreamInner(
+      requestId,
+      module,
+      method,
+      body,
+      onSuccess,
+      onError,
+      onEnd,
+      unsubscribePromise,
+    ).then(() => {
+      isSubscribed = true
+    })
+
+    return unsubscribe
+  }
+
+  private async _rpcStreamInner<
+    Response extends JSONValue = JSONValue,
+    Body extends JSONValue = JSONValue,
+  >(
+    requestId: number,
+    module: ModuleKind,
+    method: string,
+    body: Body,
+    onSuccess: (res: Response) => void,
+    onError: (res: StreamError['error']) => void,
+    onEnd: () => void = () => {},
+    unsubscribePromise: Promise<void>,
+    // Unsubscribe function
+  ) {
+    this.requestCallbacks.set(requestId, (response: StreamResult<Response>) => {
+      if (response.error !== undefined) {
+        onError(response.error)
+      } else if (response.data !== undefined) {
+        onSuccess(response.data)
+      } else if (response.end !== undefined) {
+        this.requestCallbacks.delete(requestId)
+        onEnd()
+      }
+    })
+    this.transport.postMessage({
+      type: 'rpc',
+      payload: { module, method, body },
+      requestId,
+    })
+
+    unsubscribePromise.then(() => {
+      this.transport.postMessage({
+        type: 'unsubscribe',
+        requestId,
+      })
+      this.requestCallbacks.delete(requestId)
+    })
+  }
+
+  rpcSingle<
+    Response extends JSONValue = JSONValue,
+    Error extends string = string,
+  >(module: ModuleKind, method: string, body: JSONValue) {
+    this.logger.debug('TransportClient - rpcSingle', module, method, body)
+    return new Promise<Response>((resolve, reject) => {
+      this.rpcStream<Response>(module, method, body, resolve, reject)
+    })
+  }
+
+  async cleanup() {
+    await this.sendSingleMessage('cleanup')
+    this.requestCounter = 0
+    this.initPromise = undefined
+    this.requestCallbacks.clear()
+  }
+
+  // For Testing
+  _getRequestCounter() {
+    return this.requestCounter
+  }
+  _getRequestCallbackMap() {
+    return this.requestCallbacks
+  }
+}

package/src/transport/index.ts

@@ -0,0 +1 @@
+export { TransportClient } from './TransportClient'

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export * from './wallet'
+export * from './utils'
+export * from './transport'

package/src/types/transport.ts

@@ -0,0 +1 @@
+export * from '@fedimint/types'

package/src/types/utils.ts

@@ -0,0 +1,23 @@
+import type { JSONValue } from '@fedimint/types'
+
+type Alias<T> = T & {}
+type Resolve<T> = T & unknown
+
+type Seconds = Alias<number>
+type Nanos = Alias<number>
+
+type Duration = {
+  nanos: Nanos
+  secs: Seconds
+}
+
+type MSats = Alias<number>
+type Sats = Alias<number>
+
+type JSONObject = Record<string, JSONValue>
+
+type Result<T, U = string> =
+  | { success: true; data?: T }
+  | { success: false; error: U }
+
+export { Alias, Resolve, Duration, MSats, Sats, JSONValue, JSONObject, Result }