@meshconnect/uwc-core 1.0.3 → 1.1.0

package/src/services/transaction-service.ts

@@ -1,89 +1,112 @@
 import type {
   ConnectionMode,
   Connector,
-  ExtensionInjectedProvider,
-  IntegratedBrowserInjectedProvider,
-  WalletConnectProvider,
-  SupportedProvider,
   TransactionRequest,
   TransactionResult
 } from '@meshconnect/uwc-types'
 import type { SessionManager } from '../managers/session-manager'
+import type { EventManager } from '../managers/event-manager'
 import type { ServiceOptions } from './connection-service'
+import {
+  instrumentHandoff,
+  sessionHandoffContext
+} from '../observability/instrument-handoff'
+import { resolveSessionProvider } from '../utils/resolve-session-provider'
+import {
+  validateWalletSession,
+  getSessionConnector
+} from '../utils/validate-wallet-session'
 
 /**
- * Service for handling transaction operations across different connector types
+ * Service for handling transaction operations across different connector types.
+ *
+ * Owns the WHOLE wallet-boundary op — validation (session guards, connector
+ * capability, provider resolution) BEFORE the funnel, then the instrumented
+ * connector call — the same layering as ConnectionService / NetworkSwitchService,
+ * so a pre-wallet failure never emits an `awaitingWallet`/terminal pair.
  */
 export class TransactionService {
   constructor(
     private sessionManager: SessionManager,
-    private connectors: Map<ConnectionMode, Connector>
+    private connectors: Map<ConnectionMode, Connector>,
+    private usingIntegratedBrowser: boolean,
+    private eventManager: EventManager,
+    // Observational wallet-response deadline for the handoff timeout marker.
+    private walletResponseTimeoutMs: number
   ) {}
 
   /**
    * Send a transaction with the currently connected wallet
    * @param request The transaction request parameters
-   * @param provider The wallet provider to use for sending (required for injected connector)
    * @param options Optional cancellation signal
    * @returns A promise that resolves to the transaction result
    */
   async sendTransaction(
     request: TransactionRequest,
-    provider?: SupportedProvider,
     options?: ServiceOptions
   ): Promise<TransactionResult> {
     options?.signal?.throwIfAborted()
-    const session = this.sessionManager.getSession()
+    const session = validateWalletSession(this.sessionManager, {
+      requireAddress: true
+    })
 
-    if (!session.connectionMode) {
-      throw new Error('No active connection')
+    const connector = getSessionConnector(this.connectors, session)
+    if (!connector.sendTransaction) {
+      throw new Error(`Connector does not support transactions`)
     }
 
-    if (!session.activeAddress) {
-      throw new Error('No active wallet address')
-    }
+    // Validation, not wallet work — a missing provider must not enter the funnel.
+    // undefined only for tonConnect, whose connector resolves its own provider.
+    const provider = resolveSessionProvider(
+      session,
+      this.usingIntegratedBrowser
+    )
 
-    // Get the appropriate connector
-    const connector = this.connectors.get(session.connectionMode)
-    if (!connector) {
-      throw new Error(
-        `No connector found for connection mode: ${session.connectionMode}`
-      )
-    }
+    const result = await instrumentHandoff(
+      {
+        eventManager: this.eventManager,
+        timeoutMs: this.walletResponseTimeoutMs,
+        signal: options?.signal
+      },
+      sessionHandoffContext('sendTransaction', session),
+      // tonConnect resolves undefined and keeps its request-only call shape.
+      () =>
+        provider === undefined
+          ? connector.sendTransaction!(request)
+          : connector.sendTransaction!(request, provider)
+    )
+    // AFTER the funnel: the tx already broadcast, so its truthful terminal is
+    // recorded; an abort that raced completion still rejects the caller here.
+    options?.signal?.throwIfAborted()
+    return result
+  }
 
-    // Check if the connector supports transactions
-    if (!connector.sendTransaction) {
-      throw new Error(`Connector does not support transactions`)
-    }
+  /**
+   * Sign a Solana tx without broadcasting (raw bytes in/out). Routes to the
+   * active connector's optional `signSolanaTransactionBytes`; the capability
+   * check is validation and stays OUTSIDE the funnel.
+   */
+  async signSolanaTransactionBytes(
+    serializedTx: Uint8Array
+  ): Promise<Uint8Array> {
+    const session = validateWalletSession(this.sessionManager, {
+      requireAddress: false
+    })
 
-    // Call the connector's sendTransaction method with the appropriate provider
-    let result: TransactionResult
-    if (session.connectionMode === 'injected') {
-      if (!provider) {
-        throw new Error('Provider is required for injected connector')
-      }
-      result = await connector.sendTransaction(
-        request,
-        provider as
-          | ExtensionInjectedProvider
-          | IntegratedBrowserInjectedProvider
-      )
-    } else if (session.connectionMode === 'tonConnect') {
-      result = await connector.sendTransaction(request)
-    } else if (session.connectionMode === 'walletConnect') {
-      if (!provider) {
-        throw new Error('Provider is required for WalletConnect connector')
-      }
-      result = await connector.sendTransaction(
-        request,
-        provider as WalletConnectProvider
+    const connector = this.connectors.get(session.connectionMode!)
+    if (!connector?.signSolanaTransactionBytes) {
+      throw new Error(
+        `signSolanaTransaction is not supported for connection mode "${session.connectionMode}"`
       )
-    } else {
-      // For other connectors that might not need the provider
-      result = await connector.sendTransaction(request)
     }
 
-    options?.signal?.throwIfAborted()
-    return result
+    return await instrumentHandoff(
+      {
+        eventManager: this.eventManager,
+        timeoutMs: this.walletResponseTimeoutMs
+      },
+      sessionHandoffContext('signSolanaTransaction', session),
+      () => connector.signSolanaTransactionBytes!(serializedTx)
+    )
   }
 }

package/src/universal-wallet-connector.instrumentation-guard.test.ts

@@ -0,0 +1,199 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import type { Network, WalletMetadata, Session } from '@meshconnect/uwc-types'
+import { UniversalWalletConnector } from './universal-wallet-connector'
+import { UWC_OPERATIONS } from './events'
+import type { UWCObserver, UWCTelemetryEvent } from './observability/telemetry'
+
+// Guardrail: every wallet-boundary op reachable through the public API MUST go
+// through `instrumentHandoff` — i.e. emit exactly one `awaitingWallet` and
+// exactly one terminal. A new `UWCOperation` wired up without `instrumentHandoff`
+// (the easy mistake when adding a sign/send method) fails this test.
+//
+// Every instrumented op lives INSIDE its service (validation first, then the
+// funnel at the real wallet boundary) — one layering for connect, switch, sign
+// and send. The sign/send ops below run END-TO-END through the REAL
+// SignatureService / TransactionService against mocked connectors; connect and
+// switchNetwork services are mocked here, with their handoff coverage in
+// connection-service.test.ts / network-switch-service.test.ts.
+
+const signMessageMock = vi.fn()
+const signTypedDataMock = vi.fn()
+const sendTransactionMock = vi.fn()
+const signSolanaTransactionBytesMock = vi.fn()
+
+const connectedSession: Session = {
+  connectionMode: 'injected',
+  activeNetwork: {
+    internalId: 1,
+    id: 'eip155:1',
+    namespace: 'eip155',
+    name: 'Ethereum',
+    logoUrl: '',
+    nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    networkType: 'evm'
+  },
+  activeWalletCapabilities: null,
+  activeNetworkWalletCapabilities: null,
+  activeAddress: '0xabc',
+  publicKey: null,
+  availableNetworks: [],
+  activeWallet: {
+    id: 'metamask',
+    name: 'MetaMask',
+    extensionInjectedProvider: {}
+  } as unknown as WalletMetadata,
+  availableAddresses: []
+}
+
+vi.mock('@meshconnect/uwc-injected-connector', () => ({
+  InjectedConnector: vi.fn().mockImplementation(function () {
+    return {
+      getAvailableWallets: vi.fn().mockResolvedValue([]),
+      // The REAL services route the session's connectionMode ('injected') to
+      // this connector — these are the instrumented wallet boundaries.
+      signMessage: signMessageMock,
+      signTypedData: signTypedDataMock,
+      sendTransaction: sendTransactionMock,
+      signSolanaTransactionBytes: signSolanaTransactionBytesMock
+    }
+  })
+}))
+vi.mock('@meshconnect/uwc-wallet-connect-connector', () => ({
+  WalletConnectConnector: vi.fn().mockImplementation(function () {
+    return { getAvailableWallets: vi.fn().mockResolvedValue([]) }
+  })
+}))
+vi.mock('@meshconnect/uwc-ton-connector', () => ({
+  TonConnectConnector: vi.fn().mockImplementation(function () {
+    return { getAvailableWallets: vi.fn().mockResolvedValue([]) }
+  })
+}))
+vi.mock('./managers/session-manager', () => ({
+  SessionManager: vi.fn().mockImplementation(function () {
+    return { getSession: () => connectedSession, updateSession: vi.fn() }
+  })
+}))
+vi.mock('./services/connection-service', () => ({
+  ConnectionService: vi.fn().mockImplementation(function () {
+    return {
+      connect: vi.fn().mockResolvedValue(undefined),
+      disconnect: vi.fn().mockResolvedValue(undefined),
+      getWallets: vi.fn().mockReturnValue([]),
+      getNetworks: vi.fn().mockReturnValue([]),
+      getConnectionURI: vi.fn(),
+      updateWallets: vi.fn(),
+      teardownLifecycle: vi.fn()
+    }
+  })
+}))
+vi.mock('./services/network-switch-service', () => ({
+  NetworkSwitchService: vi.fn().mockImplementation(function () {
+    return { switchNetwork: vi.fn(), getLoadingState: vi.fn() }
+  })
+}))
+vi.mock('./services/wallet-capabilities-service', () => ({
+  WalletCapabilitiesService: vi.fn().mockImplementation(function () {
+    return { getWalletCapabilities: vi.fn() }
+  })
+}))
+
+const networks = [
+  {
+    internalId: 1,
+    id: 'eip155:1',
+    namespace: 'eip155',
+    name: 'Ethereum',
+    logoUrl: '',
+    nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+    networkType: 'evm'
+  }
+] as unknown as Network[]
+
+const wallets = [
+  { id: 'metamask', name: 'MetaMask' }
+] as unknown as WalletMetadata[]
+
+const TERMINALS = ['walletSucceeded', 'walletRejected', 'walletFailed'] as const
+
+type OpRunner = (uwc: UniversalWalletConnector) => Promise<unknown>
+
+const OPS: Array<{ op: string; run: OpRunner }> = [
+  { op: 'signMessage', run: uwc => uwc.signMessage('hello') },
+  {
+    op: 'signTypedData',
+    run: uwc =>
+      uwc.signTypedData({
+        domain: {},
+        types: {},
+        primaryType: 'x',
+        message: {}
+      } as never)
+  },
+  {
+    op: 'sendTransaction',
+    run: uwc => uwc.sendTransaction({ to: '0xabc' } as never)
+  },
+  {
+    op: 'signSolanaTransaction',
+    run: uwc => uwc.signSolanaTransaction(new Uint8Array([1, 2, 3]))
+  }
+]
+
+describe('UniversalWalletConnector — instrumentation guard', () => {
+  beforeEach(() => {
+    UniversalWalletConnector.resetInstance()
+    signMessageMock.mockReset().mockResolvedValue({
+      type: 'standard',
+      signature: '0xsig'
+    })
+    signTypedDataMock.mockReset().mockResolvedValue('0xsig')
+    sendTransactionMock.mockReset().mockResolvedValue({ hash: '0xtx' })
+    signSolanaTransactionBytesMock
+      .mockReset()
+      .mockResolvedValue(new Uint8Array([9]))
+  })
+
+  for (const { op, run } of OPS) {
+    it(`${op} emits awaitingWallet and exactly one terminal`, async () => {
+      const events: UWCTelemetryEvent[] = []
+      const observer: UWCObserver = { onEvent: e => events.push(e) }
+      const uwc = new UniversalWalletConnector({ networks, wallets, observer })
+
+      await run(uwc)
+
+      const awaiting = events.filter(e => e.name === 'awaitingWallet')
+      const terminals = events.filter(e =>
+        TERMINALS.includes(e.name as (typeof TERMINALS)[number])
+      )
+      expect(awaiting).toHaveLength(1)
+      expect(awaiting[0].operation).toBe(op)
+      expect(terminals).toHaveLength(1)
+      expect(terminals[0].handoffId).toBe(awaiting[0].handoffId)
+    })
+  }
+
+  // A new UWCOperation MUST be categorized here — instrumented inside a service
+  // (the OPS above run end-to-end through the real sign/send services; connect /
+  // switchNetwork are covered in their service tests) or deliberately
+  // uninstrumented (read-only / housekeeping). This partition fails on an
+  // UNcategorized addition, so a new sign/send op can't silently skip the
+  // handoff funnel just because the author forgot to extend OPS — the gap the
+  // hardcoded list alone couldn't catch.
+  it('every UWCOperation is categorized (none escapes the funnel decision)', () => {
+    const serviceInstrumented = [
+      ...OPS.map(o => o.op),
+      'connect',
+      'switchNetwork'
+    ]
+    const deliberatelyUninstrumented = [
+      'disconnect',
+      'initialize',
+      'getWalletCapabilities'
+    ]
+    const categorized = [
+      ...serviceInstrumented,
+      ...deliberatelyUninstrumented
+    ].sort()
+    expect(categorized).toEqual([...UWC_OPERATIONS].sort())
+  })
+})