@fedimint/core-web 0.0.11 → 0.1.0

package/src/test/fixtures.ts

@@ -1,17 +1,26 @@
 import { expect, test } from 'vitest'
 import { TestFedimintWallet } from './TestFedimintWallet'
-import { WorkerClient } from '../worker/WorkerClient'
+import { TransportClient } from '../transport/TransportClient'
+import { WasmWorkerTransport } from '../transport/wasmTransport/WasmWorkerTransport'
+import { TestWalletDirector } from './TestWalletDirector'
 
 /**
- * Adds Fixtures for setting up and tearing down a test FedimintWallet instance
+ * Adds Fixtures for setting up and tearing down test FedimintWallet/WalletDirector instances
  */
 export const walletTest = test.extend<{
+  walletDirector: TestWalletDirector
   wallet: TestFedimintWallet
   fundedWallet: TestFedimintWallet
+  fundedWalletBeefy: TestFedimintWallet
+  unopenedWallet: TestFedimintWallet
 }>({
-  wallet: async ({}, use) => {
+  walletDirector: async ({}, use) => {
+    const walletDirector = new TestWalletDirector()
+    await use(walletDirector)
+  },
+  wallet: async ({ walletDirector }, use) => {
     const randomTestingId = Math.random().toString(36).substring(2, 15)
-    const wallet = new TestFedimintWallet()
+    const wallet = await walletDirector.createTestWallet()
     expect(wallet).toBeDefined()
     const inviteCode = await wallet.testing.getInviteCode()
     await expect(
@@ -33,9 +42,19 @@ export const walletTest = test.extend<{
   },
 
   fundedWallet: async ({ wallet }, use) => {
+    // 10K MSats
     await wallet.fundWallet(10_000)
     await use(wallet)
   },
+  fundedWalletBeefy: async ({ wallet }, use) => {
+    // 1M MSats
+    await wallet.fundWallet(1_000_000)
+    await use(wallet)
+  },
+  unopenedWallet: async ({ walletDirector }, use) => {
+    const wallet = await walletDirector.createTestWallet()
+    await use(wallet)
+  },
 })
 
 /**
@@ -44,12 +63,15 @@ export const walletTest = test.extend<{
 export const workerTest = test.extend<{
   worker: Worker
   clientName: string
-  workerClient: WorkerClient
+  transportClient: TransportClient
 }>({
   worker: async ({}, use) => {
-    const worker = new Worker(new URL('../worker/worker.js', import.meta.url), {
-      type: 'module',
-    })
+    const worker = new Worker(
+      new URL('../transport/wasmTransport/worker.js', import.meta.url),
+      {
+        type: 'module',
+      },
+    )
     await use(worker)
     worker.terminate()
   },
@@ -57,8 +79,10 @@ export const workerTest = test.extend<{
     const randomTestingId = Math.random().toString(36).substring(2, 15)
     await use(randomTestingId)
   },
-  workerClient: async ({}, use) => {
-    const workerClient = new WorkerClient()
-    await use(workerClient)
+  transportClient: async ({}, use) => {
+    // TODO: figure out how to use a different transport in runtime depending on the test
+    // Ideally, we don't want to create separate fixtures for each transport
+    const transportClient = new TransportClient(new WasmWorkerTransport())
+    await use(transportClient)
   },
 })

package/src/transport/TransportClient.test.ts

@@ -0,0 +1,6 @@
+import { expect } from 'vitest'
+import { workerTest } from '../test/fixtures'
+
+workerTest('should initialize', async ({ transportClient }) => {
+  expect(transportClient).toBeDefined()
+})

package/src/{worker/WorkerClient.ts → transport/TransportClient.ts}

@@ -4,27 +4,34 @@ import type {
   ModuleKind,
   StreamError,
   StreamResult,
-  WorkerMessageType,
+  TransportMessageType,
 } from '../types'
-import { logger } from '../utils/logger'
-
-// Handles communication with the wasm worker
-// TODO: Move rpc stream management to a separate "SubscriptionManager" class
-export class WorkerClient {
-  private worker: Worker
+import { Logger } from '../utils/logger'
+import type { Transport, TransportMessage } from '../types/transport'
+
+/**
+ * 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
 
-  constructor() {
-    // Must create the URL inside the constructor for vite
-    this.worker = new Worker(new URL('./worker.js', import.meta.url), {
-      type: 'module',
-    })
-    this.worker.onmessage = this.handleWorkerMessage.bind(this)
-    this.worker.onerror = this.handleWorkerError.bind(this)
-    logger.info('WorkerClient instantiated')
-    logger.debug('WorkerClient', this.worker)
+  /**
+   * @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
@@ -34,30 +41,31 @@ export class WorkerClient {
     return this.initPromise
   }
 
-  private handleWorkerLogs(event: MessageEvent) {
-    const { type, level, message, ...data } = event.data
-    logger.log(level, message, ...data)
+  private handleLogMessage(message: TransportMessage) {
+    const { type, level, message: logMessage, ...data } = message
+    this.logger.info(String(level), String(logMessage), data)
   }
 
-  private handleWorkerError(event: ErrorEvent) {
-    logger.error('Worker error', event)
+  private handleTransportError = (error: unknown) => {
+    this.logger.error('TransportClient error', error)
   }
 
-  private handleWorkerMessage(event: MessageEvent) {
-    const { type, requestId, ...data } = event.data
+  private handleTransportMessage = (message: TransportMessage) => {
+    const { type, requestId, ...data } = message
     if (type === 'log') {
-      this.handleWorkerLogs(event.data)
+      this.handleLogMessage(message)
     }
-    const streamCallback = this.requestCallbacks.get(requestId)
+    const streamCallback =
+      requestId !== undefined ? this.requestCallbacks.get(requestId) : undefined
     // TODO: Handle errors... maybe have another callbacks list for errors?
-    logger.debug('WorkerClient - handleWorkerMessage', event.data)
+    this.logger.debug('TransportClient - handleTransportMessage', message)
     if (streamCallback) {
       streamCallback(data) // {data: something} OR {error: something}
-    } else {
-      logger.warn(
-        'WorkerClient - handleWorkerMessage - received message with no callback',
+    } else if (requestId !== undefined) {
+      this.logger.warn(
+        'TransportClient - handleTransportMessage - received message with no callback',
         requestId,
-        event.data,
+        message,
       )
     }
   }
@@ -69,30 +77,35 @@ export class WorkerClient {
   sendSingleMessage<
     Response extends JSONValue = JSONValue,
     Payload extends JSONValue = JSONValue,
-  >(type: WorkerMessageType, payload?: Payload) {
+  >(type: TransportMessageType, payload?: Payload) {
     return new Promise<Response>((resolve, reject) => {
       const requestId = ++this.requestCounter
-      logger.debug('WorkerClient - sendSingleMessage', requestId, type, payload)
+      this.logger.debug(
+        'TransportClient - sendSingleMessage',
+        requestId,
+        type,
+        payload,
+      )
       this.requestCallbacks.set(
         requestId,
         (response: StreamResult<Response>) => {
           this.requestCallbacks.delete(requestId)
-          logger.debug(
-            'WorkerClient - sendSingleMessage - response',
+          this.logger.debug(
+            'TransportClient - sendSingleMessage - response',
             requestId,
             response,
           )
           if (response.data) resolve(response.data)
           else if (response.error) reject(response.error)
           else
-            logger.warn(
-              'WorkerClient - sendSingleMessage - malformed response',
+            this.logger.warn(
+              'TransportClient - sendSingleMessage - malformed response',
               requestId,
               response,
             )
         },
       )
-      this.worker.postMessage({ type, payload, requestId })
+      this.transport.postMessage({ type, payload, requestId })
     })
   }
 
@@ -132,7 +145,13 @@ export class WorkerClient {
     onEnd: () => void = () => {},
   ): CancelFunction {
     const requestId = ++this.requestCounter
-    logger.debug('WorkerClient - rpcStream', requestId, module, method, body)
+    this.logger.debug(
+      'TransportClient - rpcStream',
+      requestId,
+      module,
+      method,
+      body,
+    )
     let unsubscribe: (value: void) => void = () => {}
     let isSubscribed = false
 
@@ -180,10 +199,6 @@ export class WorkerClient {
     unsubscribePromise: Promise<void>,
     // Unsubscribe function
   ) {
-    // await this.openPromise
-    // if (!this.worker || !this._isOpen)
-    //   throw new Error('FedimintWallet is not open')
-
     this.requestCallbacks.set(requestId, (response: StreamResult<Response>) => {
       if (response.error !== undefined) {
         onError(response.error)
@@ -194,14 +209,14 @@ export class WorkerClient {
         onEnd()
       }
     })
-    this.worker.postMessage({
+    this.transport.postMessage({
       type: 'rpc',
       payload: { module, method, body },
       requestId,
     })
 
     unsubscribePromise.then(() => {
-      this.worker?.postMessage({
+      this.transport.postMessage({
         type: 'unsubscribe',
         requestId,
       })
@@ -213,7 +228,7 @@ export class WorkerClient {
     Response extends JSONValue = JSONValue,
     Error extends string = string,
   >(module: ModuleKind, method: string, body: JSONValue) {
-    logger.debug('WorkerClient - rpcSingle', module, method, body)
+    this.logger.debug('TransportClient - rpcSingle', module, method, body)
     return new Promise<Response>((resolve, reject) => {
       this.rpcStream<Response>(module, method, body, resolve, reject)
     })

package/src/transport/index.ts

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

package/src/transport/wasmTransport/WasmWorkerTransport.ts

@@ -0,0 +1,39 @@
+import type {
+  Transport,
+  TransportErrorHandler,
+  TransportLogger,
+  TransportMessageHandler,
+  TransportRequest,
+} from '../../types/transport'
+
+export class WasmWorkerTransport implements Transport {
+  private messageHandler: TransportMessageHandler = () => {}
+  private errorHandler: TransportErrorHandler = () => {}
+  private readonly worker: Worker
+
+  logger: TransportLogger = console
+
+  constructor() {
+    this.worker = new Worker(new URL('./worker.js', import.meta.url), {
+      type: 'module',
+    })
+    this.worker.onmessage = (event: MessageEvent) => {
+      this.messageHandler(event.data)
+    }
+    this.worker.onerror = (event: ErrorEvent) => {
+      this.errorHandler(event)
+    }
+  }
+
+  postMessage(message: TransportRequest) {
+    this.worker.postMessage(message)
+  }
+
+  setMessageHandler(handler: TransportMessageHandler) {
+    this.messageHandler = handler
+  }
+
+  setErrorHandler(handler: TransportErrorHandler) {
+    this.errorHandler = handler
+  }
+}

package/src/{worker → transport/wasmTransport}/worker.js

@@ -17,6 +17,17 @@ const handleFree = (requestId) => {
 
 console.log('Worker - init')
 
+/**
+ * Type definitions for the worker messages
+ *
+ * @typedef {import('../../types/transport').TransportMessageType} WorkerMessageType
+ * @typedef {{
+ *  type: WorkerMessageType
+ *  payload: any
+ *  requestId: number
+ * }} WorkerMessage
+ * @param {{data: WorkerMessage}} event
+ */
 self.onmessage = async (event) => {
   const { type, payload, requestId } = event.data
 
@@ -45,6 +56,23 @@ self.onmessage = async (event) => {
       } catch (e) {
         self.postMessage({ type: 'error', error: e.message, requestId })
       }
+    } else if (type === 'previewFederation') {
+      const { inviteCode } = payload
+      try {
+        client = await WasmClient.preview_federation(inviteCode)
+        const parsed = JSON.parse(client)
+        self.postMessage({
+          type: 'previewFederation',
+          data: {
+            success: !!client,
+            config: parsed.config,
+            federation_id: parsed.federation_id,
+          },
+          requestId,
+        })
+      } catch (e) {
+        self.postMessage({ type: 'error', error: e.message, requestId })
+      }
     } else if (type === 'rpc') {
       const { module, method, body } = payload
       console.log('RPC received', module, method, body)

package/src/{worker → transport/wasmTransport}/worker.test.ts

@@ -1,7 +1,7 @@
 import { expect } from 'vitest'
-import { TESTING_INVITE } from '../test/TestingService'
-import { JSONObject } from '../types'
-import { workerTest } from '../test/fixtures'
+import { TESTING_INVITE } from '../../test/TestingService'
+import { JSONObject } from '../../types'
+import { workerTest } from '../../test/fixtures'
 
 // Waits for a message of a given type from the worker
 const waitForWorkerResponse = (

package/src/types/index.ts

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

package/src/types/transport.ts

@@ -0,0 +1,54 @@
+import type { JSONValue } from './utils'
+
+const TransportMessageTypes = [
+  'init',
+  'initialized',
+  'rpc',
+  'log',
+  'open',
+  'join',
+  'error',
+  'unsubscribe',
+  'cleanup',
+  'parseInviteCode',
+  'parseBolt11Invoice',
+  'previewFederation',
+] as const
+
+export type TransportMessageType = (typeof TransportMessageTypes)[number]
+
+export type TransportRequest = {
+  type: TransportMessageType
+  requestId?: number
+  payload?: JSONValue
+}
+
+export type TransportMessage = {
+  type: TransportMessageType | string
+  requestId?: number
+} & Record<string, unknown>
+
+export type TransportMessageHandler = (message: TransportMessage) => void
+
+export type TransportErrorHandler = (error: unknown) => void
+
+/**
+ * Generic Transport interface for communicating with a specific
+ * target of the FedimintClient. Can be Wasm, React Native, Node, etc.
+ */
+export interface Transport {
+  postMessage(message: TransportRequest): void
+  setMessageHandler(handler: TransportMessageHandler): void
+  setErrorHandler(handler: TransportErrorHandler): void
+  logger: TransportLogger
+}
+
+/**
+ * Generic logger interface based on browser console.log
+ */
+export type TransportLogger = {
+  debug(message: string, ...args: any[]): void
+  info(message: string, ...args: any[]): void
+  warn(message: string, ...args: any[]): void
+  error(message: string, ...args: any[]): void
+}

package/src/types/wallet.ts

@@ -1,7 +1,11 @@
-import { MSats, Duration, JSONValue } from './utils'
+import { MSats, Duration, JSONValue, JSONObject } from './utils'
 
-const MODULE_KINDS = ['', 'ln', 'mint'] as const
+const MODULE_KINDS = ['', 'ln', 'mint', 'wallet'] as const
 type ModuleKind = (typeof MODULE_KINDS)[number]
+
+// TODO: Define the structure of FederationConfig
+type FederationConfig = JSONObject
+
 type GatewayInfo = {
   gateway_id: string
   api: string
@@ -50,6 +54,14 @@ type LnReceiveState =
   | 'awaiting_funds'
   | 'claimed'
 
+type LnInternalPayState =
+  | 'funding'
+  | { preimage: string }
+  | { refund_success: { out_points: BtcOutPoint[]; error: string } }
+  | { refund_error: { error_message: string; error: string } }
+  | { funding_failed: { error: string } }
+  | { unexpected_error: string }
+
 type CreateBolt11Response = {
   operation_id: string
   invoice: string
@@ -93,8 +105,165 @@ type SpendNotesState =
   | 'Success'
   | 'Refunded'
 
+type TxOutputSummary = {
+  outpoint: {
+    txid: string
+    vout: number
+  }
+  amount: number
+}
+
+type BtcOutPoint = {
+  txid: string
+  vout: number
+}
+
+type WalletDepositState =
+  | 'WaitingForTransaction'
+  | {
+      WaitingForConfirmation: {
+        btc_deposited: number
+        btc_out_point: BtcOutPoint
+      }
+    }
+  | { Confirmed: { btc_deposited: number; btc_out_point: BtcOutPoint } }
+  | { Claimed: { btc_deposited: number; btc_out_point: BtcOutPoint } }
+  | { Failed: string }
+
+type WalletSummary = {
+  spendable_utxos: TxOutputSummary[]
+  unsigned_peg_out_txos: TxOutputSummary[]
+  unsigned_change_utxos: TxOutputSummary[]
+  // TODO: fix typo in rust
+  unconfirmed_peg_out_txos: TxOutputSummary[]
+  unconfirmed_change_utxos: TxOutputSummary[]
+}
+
+type LnVariant = {
+  pay?: {
+    gateway_id: string
+    invoice: string
+    fee: number
+    is_internal_payment: boolean
+    out_point: {
+      out_idx: number
+      txid: string
+    }
+  }
+  receive?: {
+    gateway_id: string
+    invoice: string
+    out_point: {
+      out_idx: number
+      txid: string
+    }
+  }
+}
+
+type MintVariant = {
+  spend_o_o_b?: {
+    requested_amount: number
+    oob_notes: string
+  }
+  reissuance?: {
+    txid: string
+  }
+}
+
+type WalletVariant = {
+  deposit?: {
+    address: string
+    tweak_idx: number
+  }
+  withdraw?: {
+    address: string
+    amountMsats: number
+    fee: {
+      fee_rate: {
+        sats_per_kvb: number
+      }
+      total_weight: number
+    }
+  }
+}
+
+type OperationKey = {
+  creation_time: { nanos_since_epoch: number; secs_since_epoch: number }
+  operation_id: string
+}
+type OperationMeta = {
+  amount: number
+  extra_meta: JSONObject
+  variant: LnVariant | MintVariant | WalletVariant
+}
+
+type OperationLog = {
+  meta: OperationMeta
+  operation_module_kind: string
+  outcome: {
+    outcome: LnPayState | LnReceiveState | SpendNotesState | WalletDepositState
+  }
+}
+
+type BaseTransactions = {
+  timestamp: number
+  operationId: string
+  kind: 'ln' | 'mint' | 'wallet'
+}
+
+type LightningTransaction = BaseTransactions & {
+  type: 'send' | 'receive'
+  invoice: string
+  outcome:
+    | 'created'
+    | 'canceled'
+    | 'claimed'
+    | 'pending'
+    | 'success'
+    | 'funded'
+    | 'awaiting_funds'
+    | 'unexpected_error'
+  gateway: string
+  fee?: number
+  internalPay?: boolean
+  preimage?: string
+  txId: string
+}
+
+type EcashTransaction = BaseTransactions & {
+  type: 'spend_oob' | 'reissue'
+  amountMsats: number
+  outcome?: SpendNotesState | ReissueExternalNotesState
+  notes?: string
+  txId?: string
+}
+
+type WalletTransaction = BaseTransactions & {
+  type: 'withdraw' | 'deposit'
+  onchainAddress: string
+  amountMsats: number
+  fee: number
+  outcome?:
+    | 'WaitingForTransaction'
+    | 'WaitingForConfirmation'
+    | 'Confirmed'
+    | 'Claimed'
+    | 'Failed'
+}
+
+type Transactions = LightningTransaction | EcashTransaction | WalletTransaction
+
+/** Keys are powers of 2 */
+type NoteCountByDenomination = Record<number, number>
+
+type GenerateAddressResponse = {
+  deposit_address: string
+  operation_id: string
+}
+
 export {
   LightningGateway,
+  FederationConfig,
   RouteHint,
   FeeToAmount,
   OutgoingLightningPayment,
@@ -108,7 +277,22 @@ export {
   StreamResult,
   ModuleKind,
   CancelFunction,
+  LnInternalPayState,
   ReissueExternalNotesState,
   MintSpendNotesResponse,
   SpendNotesState,
+  WalletSummary,
+  TxOutputSummary,
+  NoteCountByDenomination,
+  GenerateAddressResponse,
+  OperationKey,
+  OperationLog,
+  LnVariant,
+  MintVariant,
+  WalletVariant,
+  LightningTransaction,
+  EcashTransaction,
+  WalletTransaction,
+  Transactions,
+  WalletDepositState,
 }