@meshconnect/uwc-core 0.10.1 → 1.0.0

package/src/universal-wallet-connector.ts

@@ -18,11 +18,13 @@ import type {
   EVMCapabilities,
   SignatureType,
   EIP712TypedData,
-  TronConnectorConfig
+  WalletError
 } from '@meshconnect/uwc-types'
+import { WalletConnectorError } from '@meshconnect/uwc-types'
 import { InjectedConnector } from '@meshconnect/uwc-injected-connector'
 import { WalletConnectConnector } from '@meshconnect/uwc-wallet-connect-connector'
 import { TonConnectConnector } from '@meshconnect/uwc-ton-connector'
+import type { TronConnectorConfig } from '@meshconnect/uwc-tron-connector'
 import { SessionManager } from './managers/session-manager'
 import { EventManager } from './managers/event-manager'
 import { ConnectionService } from './services/connection-service'
@@ -31,8 +33,32 @@ import { SignatureService } from './services/signature-service'
 import { TransactionService } from './services/transaction-service'
 import { WalletCapabilitiesService } from './services/wallet-capabilities-service'
 import { createNetworkRpcMap } from './utils/network-rpc-utils'
+import type { UWCEventName, UWCEventListener, UWCOperation } from './events'
+
+/**
+ * Configuration object form of the UniversalWalletConnector constructor.
+ * Prefer this over the positional constructor in new code.
+ */
+export interface UWCConfig {
+  networks: Network[]
+  // Required: the constructor throws on an empty/missing wallet list. Keeping
+  // this required (not `wallets?`) makes the type match the runtime contract
+  // so consumers get a compile error instead of a runtime throw.
+  wallets: WalletMetadata[]
+  usingIntegratedBrowser?: boolean
+  walletConnectConfig?: WalletConnectConfig
+  tonConnectConfig?: TonConnectConfig
+  tronConnectorConfig?: TronConnectorConfig
+}
+
+/** Common options for user-initiated async operations. */
+export interface OperationOptions {
+  /** Abort the operation if the signal fires. State mutations are skipped after abort. */
+  signal?: AbortSignal
+}
 
 export class UniversalWalletConnector {
+  private static instance: UniversalWalletConnector | null = null
   private static instanceCount = 0
   private static hasWarnedAboutMultipleInstances = false
 
@@ -50,18 +76,84 @@ export class UniversalWalletConnector {
   private detectionComplete = false
   private networkRpcMap: NetworkRpcMap
 
+  /**
+   * Recommended entry point: returns the shared instance, creating it on the
+   * first call. Subsequent calls ignore the `config` argument — use
+   * `resetInstance()` first if you need to reinitialise (e.g. in tests).
+   */
+  static getInstance(config?: UWCConfig): UniversalWalletConnector {
+    if (UniversalWalletConnector.instance) {
+      return UniversalWalletConnector.instance
+    }
+    if (!config) {
+      throw new Error(
+        'UniversalWalletConnector.getInstance() was called before an instance existed. Pass a config on the first call.'
+      )
+    }
+    return new UniversalWalletConnector(config)
+  }
+
+  /** Clear the shared instance reference. Primarily for tests and full-logout flows. */
+  static resetInstance(): void {
+    UniversalWalletConnector.instance = null
+    UniversalWalletConnector.instanceCount = 0
+    UniversalWalletConnector.hasWarnedAboutMultipleInstances = false
+  }
+
+  constructor(config: UWCConfig)
   constructor(
     networks: Network[],
+    wallets: WalletMetadata[],
+    usingIntegratedBrowser?: boolean,
+    walletConnectConfig?: WalletConnectConfig,
+    tonConnectConfig?: TonConnectConfig,
+    tronConnectorConfig?: TronConnectorConfig
+  )
+  constructor(
+    networksOrConfig: Network[] | UWCConfig,
     wallets: WalletMetadata[] = [],
     usingIntegratedBrowser = false,
     walletConnectConfig?: WalletConnectConfig,
     tonConnectConfig?: TonConnectConfig,
     tronConnectorConfig?: TronConnectorConfig
   ) {
-    // Track instance creation
-    UniversalWalletConnector.instanceCount++
+    if (!networksOrConfig) {
+      throw new Error(
+        'Universal Wallet Connector must be initialized with at least one network'
+      )
+    }
 
-    // Warn about multiple instances
+    let config: UWCConfig
+    if (Array.isArray(networksOrConfig)) {
+      config = {
+        networks: networksOrConfig,
+        wallets,
+        usingIntegratedBrowser
+      }
+      if (walletConnectConfig) {
+        config.walletConnectConfig = walletConnectConfig
+      }
+      if (tonConnectConfig) {
+        config.tonConnectConfig = tonConnectConfig
+      }
+      if (tronConnectorConfig) {
+        config.tronConnectorConfig = tronConnectorConfig
+      }
+    } else {
+      config = networksOrConfig
+    }
+
+    const {
+      networks,
+      wallets: configuredWallets = [],
+      usingIntegratedBrowser: configuredUsingIntegratedBrowser = false,
+      walletConnectConfig: configuredWalletConnectConfig,
+      tonConnectConfig: configuredTonConnectConfig,
+      tronConnectorConfig: configuredTronConnectorConfig
+    } = config
+
+    // Track instance creation and warn on duplicates
+    UniversalWalletConnector.instanceCount++
     if (
       UniversalWalletConnector.instanceCount > 1 &&
       !UniversalWalletConnector.hasWarnedAboutMultipleInstances
@@ -71,25 +163,29 @@ export class UniversalWalletConnector {
         `⚠️ WARNING: Multiple instances of UniversalWalletConnector detected (${UniversalWalletConnector.instanceCount} instances). ` +
           'This can lead to state inconsistencies and unexpected behavior. ' +
           'Please ensure you create only one instance and reuse it throughout your application. ' +
-          'Consider using a singleton pattern or a context provider. ' +
+          'Use UniversalWalletConnector.getInstance(config) instead of `new` to guarantee a single instance. ' +
           'You can ignore this warning if you are using React Strict Mode, which intentionally mounts components twice in development to help identify side effects.'
       )
       UniversalWalletConnector.hasWarnedAboutMultipleInstances = true
     }
 
-    if (!networks) {
+    // Reject empty arrays as well as null/undefined to honour the error
+    // messages below. The companion type `UWCConfig.wallets` is required, so
+    // TypeScript callers get a compile error for the missing-wallets case;
+    // this runtime guard catches the empty-array case the type can't express.
+    if (!networks || networks.length === 0) {
       throw new Error(
         'Universal Wallet Connector must be initialized with at least one network'
       )
     }
-    if (!wallets) {
+    if (!configuredWallets || configuredWallets.length === 0) {
       throw new Error(
         'Universal Wallet Connector must be initialized with at least one wallet'
       )
     }
 
-    this.wallets = wallets
-    this.usingIntegratedBrowser = usingIntegratedBrowser
+    this.wallets = configuredWallets
+    this.usingIntegratedBrowser = configuredUsingIntegratedBrowser
 
     // Create RPC map from networks
     this.networkRpcMap = createNetworkRpcMap(networks)
@@ -99,24 +195,27 @@ export class UniversalWalletConnector {
     this.injectedConnector = new InjectedConnector(
       this.networkRpcMap,
       this.wallets,
-      tonConnectConfig,
-      tronConnectorConfig,
+      configuredTonConnectConfig,
+      configuredTronConnectorConfig,
       networks
     )
     this.connectors.set('injected', this.injectedConnector)
 
-    if (tonConnectConfig) {
+    if (configuredTonConnectConfig) {
       this.connectors.set(
         'tonConnect',
-        new TonConnectConnector(tonConnectConfig)
+        new TonConnectConnector(configuredTonConnectConfig)
       )
     }
 
     // Only add WalletConnect connector if config is provided
-    if (walletConnectConfig) {
+    if (configuredWalletConnectConfig) {
       this.connectors.set(
         'walletConnect',
-        new WalletConnectConnector(walletConnectConfig, this.networkRpcMap)
+        new WalletConnectConnector(
+          configuredWalletConnectConfig,
+          this.networkRpcMap
+        )
       )
     }
 
@@ -127,14 +226,14 @@ export class UniversalWalletConnector {
       this.wallets,
       this.sessionManager,
       this.connectors,
-      usingIntegratedBrowser,
+      configuredUsingIntegratedBrowser,
       this.eventManager
     )
     this.networkSwitchService = new NetworkSwitchService(
       networks,
       this.sessionManager,
       this.connectors,
-      usingIntegratedBrowser,
+      configuredUsingIntegratedBrowser,
       this.eventManager
     )
     this.signatureService = new SignatureService(
@@ -152,6 +251,12 @@ export class UniversalWalletConnector {
       this.eventManager
     )
 
+    // Register as the shared instance so getInstance() works
+    // (only set if no instance exists, to avoid overwriting an earlier one)
+    if (!UniversalWalletConnector.instance) {
+      UniversalWalletConnector.instance = this
+    }
+
     // Initialize detected wallets after services are created
     this.initializeDetectedWallets()
   }
@@ -176,167 +281,35 @@ export class UniversalWalletConnector {
         }
       })
 
-      // Check available wallets for each namespace across all connectors
+      // Run every namespace × connector detection concurrently.
+      // The namespace loop used to be sequential and `await`-ed each call,
+      // which meant a 100ms EIP-6963 native timeout + any bridge polling
+      // added up. With Promise.all the total time is the slowest single
+      // call, not the sum.
+      const detectionTasks: Promise<void>[] = []
       for (const namespace of namespaces) {
         for (const [, connector] of this.connectors) {
-          // Check if connector supports getAvailableWallets
-          if (typeof connector.getAvailableWallets === 'function') {
-            try {
-              const detectedWallets = await connector.getAvailableWallets(
-                namespace as Namespace,
-                this.wallets
+          if (typeof connector.getAvailableWallets !== 'function') continue
+          detectionTasks.push(
+            Promise.resolve()
+              .then(() =>
+                connector.getAvailableWallets!(
+                  namespace as Namespace,
+                  this.wallets
+                )
               )
-
-              // Update wallets with detected information
-              detectedWallets.forEach(detected => {
-                // Find matching wallet based on namespace-specific naming
-                let wallet: WalletMetadata | undefined
-
-                if (namespace === 'eip155') {
-                  // For EIP155, match by eip155Name
-                  wallet = this.wallets.find(w => {
-                    const provider = this.usingIntegratedBrowser
-                      ? w.integratedBrowserInjectedProvider
-                      : w.extensionInjectedProvider
-                    return (
-                      provider?.namespaceMetaData?.eip155?.eip155Name?.toLowerCase() ===
-                      detected.name.toLowerCase()
-                    )
-                  })
-                } else if (namespace === 'solana') {
-                  // For Solana, match by walletStandardName
-                  wallet = this.wallets.find(w => {
-                    const provider = this.usingIntegratedBrowser
-                      ? w.integratedBrowserInjectedProvider
-                      : w.extensionInjectedProvider
-                    return (
-                      provider?.namespaceMetaData?.solana?.walletStandardName?.toLowerCase() ===
-                      detected.name.toLowerCase()
-                    )
-                  })
-                } else if (namespace === 'tron') {
-                  // Two id schemes can appear here:
-                  //  - Mesh-owned TronConnector: uuid === WalletMetadata.id
-                  //    (a stable TronWalletId like 'tronlink').
-                  //  - Legacy window-global discovery: uuid === `tron-${injectedId}`
-                  //    (e.g. 'tron-tronlink'), derived from the injection path.
-                  const tronDetected = detected as DetectedTronWalletInfo
-                  wallet = this.wallets.find(w => {
-                    if (tronDetected.uuid === w.id) return true
-                    const provider = this.usingIntegratedBrowser
-                      ? w.integratedBrowserInjectedProvider
-                      : w.extensionInjectedProvider
-                    const injectedId =
-                      provider?.namespaceMetaData?.tron?.injectedId
-                    if (!injectedId) return false
-                    // Mesh-owned connector reports the canonical injectedId —
-                    // match it directly so catalog-driven wallets (whose `id`
-                    // is a backend GUID, not a TronWalletId) are recognized.
-                    if (
-                      tronDetected.injectedId &&
-                      injectedId.toLowerCase() ===
-                        tronDetected.injectedId.toLowerCase()
-                    ) {
-                      return true
-                    }
-                    // Legacy window-global discovery scheme: `tron-${injectedId}`.
-                    return (
-                      tronDetected.uuid ===
-                      `tron-${injectedId}`.toLowerCase().replace(/\./g, '-')
-                    )
-                  })
-                } else if (namespace === 'tvm') {
-                  // For TON, match by jsBridgeKey
-                  const tonDetected = detected as DetectedTonWalletInfo
-                  wallet = this.wallets.find(w => {
-                    const provider = this.usingIntegratedBrowser
-                      ? w.integratedBrowserInjectedProvider
-                      : w.extensionInjectedProvider
-                    return (
-                      provider?.namespaceMetaData?.tvm?.jsBridgeKey ===
-                      tonDetected.jsBridgeKey
-                    )
-                  })
-                } else {
-                  // For other namespaces, fall back to wallet name
-                  wallet = this.wallets.find(
-                    w => w.name.toLowerCase() === detected.name.toLowerCase()
-                  )
-                }
-
-                if (wallet) {
-                  // Determine which provider to update based on usingIntegratedBrowser
-                  const provider = this.usingIntegratedBrowser
-                    ? wallet.integratedBrowserInjectedProvider
-                    : wallet.extensionInjectedProvider
-
-                  // Update the appropriate namespace metadata
-                  if (provider?.namespaceMetaData) {
-                    const nsMetadata =
-                      provider.namespaceMetaData[namespace as Namespace]
-                    if (nsMetadata && namespace === 'eip155') {
-                      // For EIP155, we have specific fields
-                      const eip155Metadata = nsMetadata as {
-                        installed?: boolean
-                        detectedWallet?: DetectedEIP6963WalletInfo
-                      }
-                      eip155Metadata.installed = true
-                      const eip155Detected =
-                        detected as DetectedEIP6963WalletInfo
-                      eip155Metadata.detectedWallet = {
-                        uuid: eip155Detected.uuid,
-                        name: eip155Detected.name,
-                        icon: eip155Detected.icon,
-                        rdns: eip155Detected.rdns
-                      }
-                    } else if (namespace === 'solana') {
-                      // For Solana, we have different fields
-                      const solanaMetadata = nsMetadata as {
-                        installed?: boolean
-                        detectedWallet?: DetectedSolanaWalletInfo
-                      }
-                      solanaMetadata.installed = true
-                      const solanaDetected =
-                        detected as DetectedSolanaWalletInfo
-                      solanaMetadata.detectedWallet = {
-                        uuid: solanaDetected.uuid,
-                        name: solanaDetected.name,
-                        features: solanaDetected.features
-                      }
-                    } else if (namespace === 'tron') {
-                      const tronMetadata = nsMetadata as {
-                        installed?: boolean
-                        detectedWallet?: DetectedTronWalletInfo
-                      }
-                      tronMetadata.installed = true
-                      const tronDetected = detected as DetectedTronWalletInfo
-                      tronMetadata.detectedWallet = {
-                        uuid: tronDetected.uuid,
-                        name: tronDetected.name
-                      }
-                    } else if (namespace === 'tvm') {
-                      const tonMetadata = nsMetadata as {
-                        installed?: boolean
-                        detectedWallet?: DetectedTonWalletInfo
-                      }
-                      tonMetadata.installed = true
-                      const tonDetected = detected as DetectedTonWalletInfo
-                      tonMetadata.detectedWallet = {
-                        uuid: tonDetected.uuid,
-                        name: tonDetected.name,
-                        icon: tonDetected.icon,
-                        jsBridgeKey: tonDetected.jsBridgeKey
-                      }
-                    }
-                  }
+              .then(detected => {
+                for (const d of detected) {
+                  this.applyDetectedWallet(namespace as Namespace, d)
                 }
               })
-            } catch {
-              // Silently handle errors for individual connector/namespace combinations
-            }
-          }
+              .catch(() => {
+                // Silently handle errors for individual connector/namespace combinations
+              })
+          )
         }
       }
+      await Promise.all(detectionTasks)
 
       // Notify the connection service to update its internal wallets reference
       this.connectionService.updateWallets(this.wallets)
@@ -344,12 +317,145 @@ export class UniversalWalletConnector {
       // Mark detection as complete
       this.detectionComplete = true
 
-      // Notify listeners about the update
-      this.eventManager.notify()
-    } catch {
-      // Silently handle error during initialization
+      this.eventManager.emit('walletsDetected', { wallets: this.wallets })
+      this.eventManager.emit('ready', undefined)
+    } catch (error) {
       this.detectionComplete = true
-      this.eventManager.notify()
+      this.emitError(error, 'initialize')
+      this.eventManager.emit('ready', undefined)
+    }
+  }
+
+  /**
+   * Merge a single detected wallet (from one namespace × connector run) into
+   * the configured wallet metadata. Factored out so detection tasks can run
+   * in parallel without racing on the merge logic.
+   */
+  private applyDetectedWallet(
+    namespace: Namespace,
+    detected: {
+      uuid: string
+      name: string
+      icon?: string
+      rdns?: string
+      features?: string[]
+      jsBridgeKey?: string
+    }
+  ): void {
+    let wallet: WalletMetadata | undefined
+
+    const pickProvider = (w: WalletMetadata) =>
+      this.usingIntegratedBrowser
+        ? w.integratedBrowserInjectedProvider
+        : w.extensionInjectedProvider
+
+    if (namespace === 'eip155') {
+      wallet = this.wallets.find(
+        w =>
+          pickProvider(
+            w
+          )?.namespaceMetaData?.eip155?.eip155Name?.toLowerCase() ===
+          detected.name.toLowerCase()
+      )
+    } else if (namespace === 'solana') {
+      wallet = this.wallets.find(
+        w =>
+          pickProvider(
+            w
+          )?.namespaceMetaData?.solana?.walletStandardName?.toLowerCase() ===
+          detected.name.toLowerCase()
+      )
+    } else if (namespace === 'tron') {
+      // Three id schemes can appear here:
+      //  - Mesh-owned TronConnector reports the canonical `injectedId` directly
+      //    (added in #174) — match catalog wallets whose `id` is a backend GUID.
+      //  - Mesh-owned TronConnector: uuid === WalletMetadata.id
+      //    (a stable TronWalletId like 'tronlink').
+      //  - Legacy window-global discovery: uuid === `tron-${injectedId}`
+      //    (e.g. 'tron-tronlink'), derived from the injection path.
+      const tronDetected = detected as DetectedTronWalletInfo
+      wallet = this.wallets.find(w => {
+        if (tronDetected.uuid === w.id) return true
+        const injectedId = pickProvider(w)?.namespaceMetaData?.tron?.injectedId
+        if (!injectedId) return false
+        if (
+          tronDetected.injectedId &&
+          injectedId.toLowerCase() === tronDetected.injectedId.toLowerCase()
+        ) {
+          return true
+        }
+        return (
+          tronDetected.uuid ===
+          `tron-${injectedId}`.toLowerCase().replace(/\./g, '-')
+        )
+      })
+    } else if (namespace === 'tvm') {
+      const tonDetected = detected as DetectedTonWalletInfo
+      wallet = this.wallets.find(
+        w =>
+          pickProvider(w)?.namespaceMetaData?.tvm?.jsBridgeKey ===
+          tonDetected.jsBridgeKey
+      )
+    } else {
+      wallet = this.wallets.find(
+        w => w.name.toLowerCase() === detected.name.toLowerCase()
+      )
+    }
+
+    if (!wallet) return
+
+    const provider = pickProvider(wallet)
+    if (!provider?.namespaceMetaData) return
+
+    const nsMetadata = provider.namespaceMetaData[namespace]
+    if (!nsMetadata) return
+
+    if (namespace === 'eip155') {
+      const m = nsMetadata as {
+        installed?: boolean
+        detectedWallet?: DetectedEIP6963WalletInfo
+      }
+      const d = detected as DetectedEIP6963WalletInfo
+      m.installed = true
+      m.detectedWallet = {
+        uuid: d.uuid,
+        name: d.name,
+        icon: d.icon,
+        rdns: d.rdns
+      }
+    } else if (namespace === 'solana') {
+      const m = nsMetadata as {
+        installed?: boolean
+        detectedWallet?: DetectedSolanaWalletInfo
+      }
+      const d = detected as DetectedSolanaWalletInfo
+      m.installed = true
+      m.detectedWallet = {
+        uuid: d.uuid,
+        name: d.name,
+        features: d.features
+      }
+    } else if (namespace === 'tron') {
+      const m = nsMetadata as {
+        installed?: boolean
+        detectedWallet?: DetectedTronWalletInfo
+      }
+      const d = detected as DetectedTronWalletInfo
+      m.installed = true
+      m.detectedWallet = { uuid: d.uuid, name: d.name }
+    } else if (namespace === 'tvm') {
+      const m = nsMetadata as {
+        installed?: boolean
+        detectedWallet?: DetectedTonWalletInfo
+      }
+      const d = detected as DetectedTonWalletInfo
+      m.installed = true
+      m.detectedWallet = {
+        uuid: d.uuid,
+        name: d.name,
+        icon: d.icon,
+        jsBridgeKey: d.jsBridgeKey
+      }
     }
   }
 
@@ -361,6 +467,32 @@ export class UniversalWalletConnector {
     return this.detectionComplete
   }
 
+  // ---- Event subscription ----
+
+  /** Subscribe to a typed event. Returns an unsubscribe function. */
+  on<K extends UWCEventName>(
+    event: K,
+    listener: UWCEventListener<K>
+  ): () => void {
+    return this.eventManager.on(event, listener)
+  }
+
+  /** Subscribe once; the listener is removed after the first dispatch. */
+  once<K extends UWCEventName>(
+    event: K,
+    listener: UWCEventListener<K>
+  ): () => void {
+    return this.eventManager.once(event, listener)
+  }
+
+  off<K extends UWCEventName>(event: K, listener: UWCEventListener<K>): void {
+    this.eventManager.off(event, listener)
+  }
+
+  /**
+   * @deprecated Prefer `on(eventName, listener)` for targeted updates.
+   * Subscribes to the catch-all `change` event.
+   */
   subscribe(listener: () => void): () => void {
     return this.eventManager.subscribe(listener)
   }
@@ -382,24 +514,45 @@ export class UniversalWalletConnector {
   async connect(
     connectionMode: ConnectionMode,
     walletId: string,
-    networkId?: NetworkId
+    networkId?: NetworkId,
+    options?: OperationOptions
   ): Promise<void> {
-    await this.connectionService.connect(connectionMode, walletId, networkId)
-    this.eventManager.notify()
+    try {
+      await this.connectionService.connect(
+        connectionMode,
+        walletId,
+        networkId,
+        options
+      )
+    } catch (error) {
+      this.emitError(error, 'connect')
+      throw error
+    }
   }
 
   getConnectionURI(): string | undefined {
     return this.connectionService.getConnectionURI()
   }
 
-  async disconnect(): Promise<void> {
-    await this.connectionService.disconnect()
-    this.eventManager.notify()
+  async disconnect(options?: OperationOptions): Promise<void> {
+    try {
+      await this.connectionService.disconnect(options)
+    } catch (error) {
+      this.emitError(error, 'disconnect')
+      throw error
+    }
   }
 
-  async switchNetwork(networkId: NetworkId): Promise<void> {
-    await this.networkSwitchService.switchNetwork(networkId)
-    this.eventManager.notify()
+  async switchNetwork(
+    networkId: NetworkId,
+    options?: OperationOptions
+  ): Promise<void> {
+    try {
+      await this.networkSwitchService.switchNetwork(networkId, options)
+    } catch (error) {
+      this.emitError(error, 'switchNetwork')
+      throw error
+    }
   }
 
   getNetworkSwitchLoadingState() {
@@ -409,9 +562,13 @@ export class UniversalWalletConnector {
   /**
    * Sign a message with the connected wallet
    * @param message The message to sign
+   * @param options Optional cancellation signal
    * @returns A promise that resolves to the signature
    */
-  async signMessage(message: string): Promise<SignatureType> {
+  async signMessage(
+    message: string,
+    options?: OperationOptions
+  ): Promise<SignatureType> {
     const session = this.sessionManager.getSession()
 
     if (!session.activeWallet) {
@@ -422,23 +579,32 @@ export class UniversalWalletConnector {
       throw new Error('No active connection')
     }
 
-    // Get the provider from the active wallet based on connection mode
-    let provider
-    if (session.connectionMode === 'injected') {
-      provider = this.usingIntegratedBrowser
-        ? session.activeWallet.integratedBrowserInjectedProvider
-        : session.activeWallet.extensionInjectedProvider
-    } else if (session.connectionMode === 'walletConnect') {
-      provider = session.activeWallet.walletConnectProvider
-    } else if (session.connectionMode === 'tonConnect') {
-      return await this.signatureService.signMessage(message)
-    }
+    try {
+      // Get the provider from the active wallet based on connection mode
+      let provider
+      if (session.connectionMode === 'injected') {
+        provider = this.usingIntegratedBrowser
+          ? session.activeWallet.integratedBrowserInjectedProvider
+          : session.activeWallet.extensionInjectedProvider
+      } else if (session.connectionMode === 'walletConnect') {
+        provider = session.activeWallet.walletConnectProvider
+      } else if (session.connectionMode === 'tonConnect') {
+        return await this.signatureService.signMessage(
+          message,
+          undefined,
+          options
+        )
+      }
 
-    if (!provider) {
-      throw new Error('No provider available for the active wallet')
-    }
+      if (!provider) {
+        throw new Error('No provider available for the active wallet')
+      }
 
-    return await this.signatureService.signMessage(message, provider)
+      return await this.signatureService.signMessage(message, provider, options)
+    } catch (error) {
+      this.emitError(error, 'signMessage')
+      throw error
+    }
   }
 
   /**
@@ -483,10 +649,12 @@ export class UniversalWalletConnector {
   /**
    * Send a transaction with the connected wallet
    * @param request The transaction request parameters
+   * @param options Optional cancellation signal
    * @returns A promise that resolves to the transaction result
    */
   async sendTransaction(
-    request: TransactionRequest
+    request: TransactionRequest,
+    options?: OperationOptions
   ): Promise<TransactionResult> {
     const session = this.sessionManager.getSession()
 
@@ -498,23 +666,36 @@ export class UniversalWalletConnector {
       throw new Error('No active connection')
     }
 
-    // Get the provider from the active wallet based on connection mode
-    let provider
-    if (session.connectionMode === 'injected') {
-      provider = this.usingIntegratedBrowser
-        ? session.activeWallet.integratedBrowserInjectedProvider
-        : session.activeWallet.extensionInjectedProvider
-    } else if (session.connectionMode === 'walletConnect') {
-      provider = session.activeWallet.walletConnectProvider
-    } else if (session.connectionMode === 'tonConnect') {
-      return await this.transactionService.sendTransaction(request)
-    }
+    try {
+      // Get the provider from the active wallet based on connection mode
+      let provider
+      if (session.connectionMode === 'injected') {
+        provider = this.usingIntegratedBrowser
+          ? session.activeWallet.integratedBrowserInjectedProvider
+          : session.activeWallet.extensionInjectedProvider
+      } else if (session.connectionMode === 'walletConnect') {
+        provider = session.activeWallet.walletConnectProvider
+      } else if (session.connectionMode === 'tonConnect') {
+        return await this.transactionService.sendTransaction(
+          request,
+          undefined,
+          options
+        )
+      }
 
-    if (!provider) {
-      throw new Error('No provider available for the active wallet')
-    }
+      if (!provider) {
+        throw new Error('No provider available for the active wallet')
+      }
 
-    return await this.transactionService.sendTransaction(request, provider)
+      return await this.transactionService.sendTransaction(
+        request,
+        provider,
+        options
+      )
+    } catch (error) {
+      this.emitError(error, 'sendTransaction')
+      throw error
+    }
   }
 
   /**
@@ -548,16 +729,24 @@ export class UniversalWalletConnector {
    * Fetch wallet capabilities for the connected wallet
    * @param address The wallet address to fetch capabilities for
    * @param activeNetwork Optional network to set as the active network for capabilities
+   * @param options Optional cancellation signal
    * @returns A promise that resolves when capabilities are fetched and updated
    */
   async getWalletCapabilities(
     address: string,
-    activeNetwork?: Network
+    activeNetwork?: Network,
+    options?: OperationOptions
   ): Promise<void> {
-    return await this.walletCapabilitiesService.getWalletCapabilities(
-      address,
-      activeNetwork
-    )
+    try {
+      return await this.walletCapabilitiesService.getWalletCapabilities(
+        address,
+        activeNetwork,
+        options
+      )
+    } catch (error) {
+      this.emitError(error, 'getWalletCapabilities')
+      throw error
+    }
   }
 
   /**
@@ -619,4 +808,23 @@ export class UniversalWalletConnector {
     const session = this.sessionManager.getSession()
     return session.activeWalletCapabilities
   }
+
+  // ---- private helpers ----
+
+  private emitError(error: unknown, operation: UWCOperation): void {
+    // Intentional cancellations (AbortSignal.throwIfAborted, fetch abort,
+    // DOMException) should NOT surface as wallet errors — the caller already
+    // knows it asked to abort. Skip emission so error telemetry stays clean.
+    if (error instanceof Error && error.name === 'AbortError') {
+      return
+    }
+    const walletError: WalletError =
+      error instanceof WalletConnectorError
+        ? { type: error.type, message: error.message }
+        : {
+            type: 'unknown',
+            message: error instanceof Error ? error.message : String(error)
+          }
+    this.eventManager.emit('error', { error: walletError, operation })
+  }
 }