@meshconnect/uwc-core 0.7.4 → 0.7.5-snapshot.3e19fe0

package/README.md

@@ -0,0 +1,924 @@
+# @meshconnect/uwc-core
+
+Framework-agnostic wallet connection manager for Web3 applications. Single API
+for **injected** wallets (MetaMask, Phantom, Tonkeeper extension, …),
+**WalletConnect** (EVM + Solana mobile wallets), and **TON Connect** (TON
+wallets via the JS Bridge).
+
+If you are building a React app, reach for
+[`@meshconnect/uwc-react`](../uwc-react) instead — it wraps this package with
+hooks and a context provider. This document is for everyone else: vanilla JS
+apps, Svelte, Vue, Solid, or any non-React runtime.
+
+---
+
+## Table of contents
+
+1. [Install](#install)
+2. [Quick start](#quick-start)
+3. [Core concepts](#core-concepts)
+4. [Configuration](#configuration)
+5. [Creating the instance](#creating-the-instance)
+6. [Reading state](#reading-state)
+7. [Events](#events)
+8. [Connecting a wallet](#connecting-a-wallet)
+9. [Disconnecting](#disconnecting)
+10. [Switching networks](#switching-networks)
+11. [Signing messages](#signing-messages)
+12. [Sending transactions](#sending-transactions)
+13. [Wallet capabilities](#wallet-capabilities)
+14. [Cancelling in-flight operations](#cancelling-in-flight-operations)
+15. [Error handling](#error-handling)
+16. [Testing](#testing)
+17. [Recipes](#recipes)
+18. [API reference](#api-reference)
+
+---
+
+## Install
+
+```bash
+npm install @meshconnect/uwc-core @meshconnect/uwc-types @meshconnect/uwc-constants
+```
+
+The `types` package provides the `WalletMetadata`, `Network`,
+`TransactionRequest`, … definitions used throughout the API. The `constants`
+package ships ready-to-use `Network` objects (`mainnetNetwork`, `baseNetwork`,
+`solanaNetwork`, …) so you don't have to hand-roll chain configs.
+
+---
+
+## Quick start
+
+```ts
+import { UniversalWalletConnector } from '@meshconnect/uwc-core'
+import {
+  mainnetNetwork,
+  baseNetwork,
+  solanaNetwork
+} from '@meshconnect/uwc-constants'
+import type { WalletMetadata } from '@meshconnect/uwc-types'
+
+const metamask: WalletMetadata = {
+  id: 'metamask',
+  name: 'MetaMask',
+  metadata: { icon: 'https://example.com/metamask.png' },
+  extensionInjectedProvider: {
+    supportedNetworkIds: ['eip155:1', 'eip155:8453'],
+    namespaceMetaData: {
+      eip155: {
+        eip155Name: 'metamask',
+        injectedId: 'isMetamask',
+        supportsAddingNetworks: true,
+        requiresUserApprovalOnNetworkSwitch: false
+      }
+    },
+    requiresUserApprovalOnNamespaceSwitch: false
+  },
+  walletConnectProvider: {
+    supportedNetworkIds: ['eip155:1', 'eip155:8453'],
+    deeplinks: {
+      universal: 'https://metamask.app.link',
+      native: 'metamask://'
+    }
+  }
+}
+
+const connector = UniversalWalletConnector.getInstance({
+  networks: [mainnetNetwork, baseNetwork, solanaNetwork],
+  wallets: [metamask],
+  walletConnectConfig: {
+    projectId: 'YOUR_WC_PROJECT_ID',
+    metadata: {
+      name: 'My dApp',
+      description: 'Does Web3 things',
+      url: 'https://my-dapp.xyz',
+      icons: ['https://my-dapp.xyz/icon.png']
+    }
+  }
+})
+
+// React to state changes
+connector.on('connected', ({ session }) => {
+  console.log('connected as', session.activeAddress)
+})
+connector.on('connectionUri', ({ uri }) => {
+  console.log('show QR code for:', uri)
+})
+connector.on('error', ({ error, operation }) => {
+  console.error(`${operation} failed:`, error.type, error.message)
+})
+
+// Connect
+await connector.connect('injected', 'metamask', 'eip155:1')
+```
+
+---
+
+## Core concepts
+
+### ConnectionMode
+
+Three mutually exclusive ways a user can connect:
+
+| Mode            | Description                                                        | Typical wallets                  |
+| --------------- | ------------------------------------------------------------------ | -------------------------------- |
+| `injected`      | Browser-extension or in-app injected provider (EIP-6963, Solana Wallet Standard, Tron, TON JS Bridge) | MetaMask, Phantom, Tonkeeper extension |
+| `walletConnect` | WalletConnect v2 relay + QR code / deeplink                        | Any WC-compatible mobile wallet  |
+| `tonConnect`    | TON Connect JS Bridge + QR code / universal link                   | Tonkeeper, OKX TON Wallet        |
+
+A wallet can support multiple modes. `isConnectionModeAvailable(mode, walletId)`
+tells you which ones are actually viable in the current runtime.
+
+### Session
+
+One opaque object describes "what's connected right now":
+
+```ts
+interface Session {
+  connectionMode: ConnectionMode | null
+  activeWallet: WalletMetadata | null
+  activeNetwork: Network | null
+  activeAddress: string | null
+  publicKey: string | null
+  availableNetworks: Network[]          // networks the current wallet supports
+  availableAddresses: AvailableAddress[] // one per chain the wallet exposed
+  activeWalletCapabilities: Record<string, EVMCapabilities> | null
+  activeNetworkWalletCapabilities: EVMCapabilities | null
+}
+```
+
+`getSession()` always returns the current snapshot. When any field changes,
+a `sessionChanged` event fires.
+
+### Observer / event model
+
+The connector is an event emitter. There are twelve typed events:
+
+| Event                   | When it fires                                                |
+| ----------------------- | ------------------------------------------------------------ |
+| `ready`                 | Initial wallet detection has completed                       |
+| `walletsDetected`       | Detection completed, payload is the enriched wallet list     |
+| `connecting`            | `connect()` started                                          |
+| `connectionUri`         | A WC/TonConnect pairing URI is now available                 |
+| `connected`             | `connect()` finished successfully                            |
+| `disconnected`          | `disconnect()` finished (session cleared)                    |
+| `sessionChanged`        | Any session field changed                                    |
+| `networkSwitching`      | Network switch started or ended                              |
+| `networkSwitched`       | Network switch finished successfully                         |
+| `capabilitiesUpdated`   | `getWalletCapabilities()` refreshed data                     |
+| `error`                 | A user-initiated op threw                                    |
+| `change`                | Catch-all — fires after every other event                    |
+
+Use `on(eventName, listener)` for targeted updates. Every typed event also
+cascades to `change`, so the legacy `subscribe(listener)` pattern still works.
+
+### AbortSignal
+
+Every async operation accepts an optional `{ signal }`. If the signal aborts,
+the operation rejects with an `AbortError` and no session mutations happen
+after the abort, even if the wallet prompt has already returned. Wallet
+prompts themselves cannot usually be cancelled — the signal protects your app
+from acting on stale results.
+
+---
+
+## Configuration
+
+### Networks
+
+A `Network` describes a chain. `@meshconnect/uwc-constants` ships the common
+ones; you only need to hand-write one if you're adding a chain the library
+doesn't know about. The **only required contract** is: every `networkId` your
+wallets claim to support must have a matching `Network` in this array —
+otherwise the connector will refuse to pick that network.
+
+### Wallets
+
+Each `WalletMetadata` entry declares **which connection modes the wallet can
+use** and the per-mode provider config. Provide only the providers that apply:
+
+```ts
+const phantom: WalletMetadata = {
+  id: 'phantom',
+  name: 'Phantom',
+  metadata: { icon: '…' },
+
+  // Extension / in-browser injection (EIP-6963 + Solana Wallet Standard)
+  extensionInjectedProvider: {
+    supportedNetworkIds: ['eip155:1', 'solana:5eykt4UsFv8P…'],
+    namespaceMetaData: {
+      eip155: {
+        eip155Name: 'phantom',
+        injectedId: 'isPhantom',
+        supportsAddingNetworks: true,
+        requiresUserApprovalOnNetworkSwitch: false
+      },
+      solana: { walletStandardName: 'Phantom', injectedId: 'isPhantom' }
+    },
+    requiresUserApprovalOnNamespaceSwitch: false
+  }
+
+  // Omit walletConnectProvider / tonConnectProvider if unsupported
+}
+```
+
+`usingIntegratedBrowser: true` switches the injected path to use
+`integratedBrowserInjectedProvider` instead of `extensionInjectedProvider` —
+use it when your app runs inside a wallet's built-in browser (e.g. Trust
+Wallet DApp browser).
+
+### WalletConnect / TON Connect
+
+Only required if at least one wallet advertises that mode:
+
+```ts
+walletConnectConfig: {
+  projectId: 'YOUR_WC_PROJECT_ID',
+  metadata: { name, description, url, icons }
+}
+
+tonConnectConfig: {
+  manifestUrl: 'https://my-dapp.xyz/tonconnect-manifest.json'
+}
+```
+
+Omit a config and the corresponding connector simply isn't instantiated —
+`isConnectionModeAvailable('walletConnect', …)` will return `false`.
+
+---
+
+## Creating the instance
+
+The library enforces a single instance per page. There are three ways to
+create it; pick one and stick with it.
+
+### Recommended — `getInstance()`
+
+```ts
+const connector = UniversalWalletConnector.getInstance({
+  networks,
+  wallets,
+  walletConnectConfig // optional
+})
+
+// Anywhere else in your app, call it again without config:
+const same = UniversalWalletConnector.getInstance()
+// → same === connector
+```
+
+`getInstance()` builds the instance on the first call and returns the cached
+one afterwards. Calling it without config **before** any instance exists
+throws.
+
+### Config-object constructor
+
+```ts
+const connector = new UniversalWalletConnector({
+  networks,
+  wallets,
+  walletConnectConfig
+})
+```
+
+The first `new` call is auto-registered as the singleton, so
+`UniversalWalletConnector.getInstance()` later returns the same reference.
+
+### Positional constructor (legacy)
+
+```ts
+const connector = new UniversalWalletConnector(
+  networks,
+  wallets,
+  /* usingIntegratedBrowser */ false,
+  walletConnectConfig,
+  tonConnectConfig
+)
+```
+
+Constructing a **second** instance logs a `console.error` warning — it's
+almost always a mistake. For tests and full-logout flows, call
+`UniversalWalletConnector.resetInstance()` to clear the cached reference.
+
+---
+
+## Reading state
+
+All reads are synchronous and cheap. Call them any time.
+
+```ts
+connector.getSession()                 // current Session
+connector.getState()                   // { session } — parity with older API
+connector.isReady()                    // true once detection completed
+connector.getWallets()                 // wallets with `installed` flags set
+connector.getNetworks()                // the configured networks array
+connector.isConnectionModeAvailable('walletConnect', 'metamask')
+connector.getConnectionURI()           // WC/TonConnect pairing URI, if any
+connector.getNetworkSwitchLoadingState()
+  // { isLoading, isWaitingForUserApproval }
+connector.getActiveWalletCapabilities() // Record<NetworkId, EVMCapabilities> | null
+```
+
+Prefer subscribing to events over polling — see the next section.
+
+---
+
+## Events
+
+### `on(event, listener)`
+
+```ts
+const unsubscribe = connector.on('sessionChanged', ({ session }) => {
+  render(session)
+})
+
+// Clean up when no longer needed
+unsubscribe()
+```
+
+### `once(event, listener)`
+
+Fires at most once, then auto-removes:
+
+```ts
+connector.once('ready', () => {
+  console.log('wallet detection done')
+})
+```
+
+### `off(event, listener)`
+
+Manual removal if you didn't keep the `on()` return value:
+
+```ts
+function handler({ uri }) { … }
+connector.on('connectionUri', handler)
+// …later
+connector.off('connectionUri', handler)
+```
+
+### Event payloads
+
+```ts
+import type { UWCEventMap } from '@meshconnect/uwc-core'
+
+// Narrowed per event:
+connector.on('connecting',    ({ connectionMode, walletId }) => {})
+connector.on('connected',     ({ session }) => {})
+connector.on('disconnected',  () => {})
+connector.on('connectionUri', ({ uri, connectionMode }) => {})
+connector.on('networkSwitching', ({ isLoading, isWaitingForUserApproval }) => {})
+connector.on('networkSwitched',  ({ network }) => {})
+connector.on('sessionChanged',   ({ session }) => {})
+connector.on('capabilitiesUpdated', ({ capabilities }) => {})
+connector.on('walletsDetected',  ({ wallets }) => {})
+connector.on('ready', () => {})
+connector.on('error', ({ error, operation }) => {})
+connector.on('change', () => {})  // catch-all; no payload
+```
+
+### Legacy `subscribe()`
+
+Still supported; subscribes to the catch-all `change` event:
+
+```ts
+const unsubscribe = connector.subscribe(() => {
+  // anything changed — re-read getSession() etc.
+})
+```
+
+Prefer the typed events for new code.
+
+---
+
+## Connecting a wallet
+
+```ts
+try {
+  await connector.connect('injected', 'metamask')
+  // or pick a specific chain:
+  await connector.connect('injected', 'metamask', 'eip155:8453')
+} catch (error) {
+  // see "Error handling" below
+}
+```
+
+### Displaying a WalletConnect / TonConnect QR
+
+The pairing URI appears asynchronously. Listen for `connectionUri` and display
+the QR as soon as it fires:
+
+```ts
+connector.on('connectionUri', async ({ uri, connectionMode }) => {
+  if (connectionMode === 'walletConnect') {
+    await renderQRCode(uri)
+  }
+})
+
+await connector.connect('walletConnect', 'metamask')
+// connect() resolves only once the user has scanned + approved.
+// The promise can reject if the user cancels or the proposal expires.
+```
+
+### WalletConnect proposal-expiry retry
+
+WalletConnect pairings time out if the user doesn't scan within ~5 minutes.
+The error's `type` is `'expired'`. Retry with a fresh call:
+
+```ts
+async function connectWithRetry(walletId: string, networkId?: NetworkId) {
+  for (;;) {
+    try {
+      await connector.connect('walletConnect', walletId, networkId)
+      return
+    } catch (error) {
+      if ((error as WalletError).type === 'expired') continue
+      throw error
+    }
+  }
+}
+```
+
+### What `connect()` does internally
+
+1. Resolves the wallet + provider + target network.
+2. Fires `connecting`.
+3. Starts the underlying wallet flow (extension RPC call, WC pairing, TON JS
+   bridge). For QR-based flows, polls for the pairing URI and fires
+   `connectionUri` as soon as it appears.
+4. On success, updates the session and fires `connected` + `sessionChanged`.
+5. On failure, resets the active connector and rethrows. `error` fires with
+   `operation: 'connect'`.
+
+---
+
+## Disconnecting
+
+```ts
+await connector.disconnect()
+```
+
+Always resolves (even if the underlying connector errors out), then clears
+the session and fires `disconnected` + `sessionChanged`. Call it as part of
+app-level "sign out" flows.
+
+---
+
+## Switching networks
+
+```ts
+await connector.switchNetwork('eip155:8453') // Base
+
+// Track loading for UI
+connector.on('networkSwitching', ({ isLoading, isWaitingForUserApproval }) => {
+  if (isWaitingForUserApproval) showBanner('Approve in your wallet…')
+  else if (isLoading)          showBanner('Switching network…')
+  else                         hideBanner()
+})
+```
+
+**Prerequisites**: an active session, the target `networkId` must be in the
+connector's configured networks, and the active wallet must list it in
+`supportedNetworkIds`. Otherwise `switchNetwork` throws before prompting the
+wallet.
+
+Switching across namespaces (e.g. EVM → Solana) works when the wallet's
+`requiresUserApprovalOnNamespaceSwitch` metadata is set correctly — the user
+may see an extra prompt.
+
+---
+
+## Signing messages
+
+```ts
+import type { SignatureType } from '@meshconnect/uwc-types'
+
+const signature: SignatureType = await connector.signMessage('Hello, world')
+
+switch (signature.type) {
+  case 'standard': // EVM, Solana
+    console.log(signature.signature)
+    break
+  case 'tron':
+    console.log(signature.txID, signature.signature)
+    break
+  case 'tvm': // TON Connect signData
+    console.log(signature.signature, signature.domain, signature.timestamp)
+    // MUST verify domain + timestamp before trusting this signature.
+    break
+}
+```
+
+Throws if no wallet is connected, the connector doesn't support signing, or
+the user rejects the prompt (`error.type === 'rejected'`).
+
+---
+
+## Sending transactions
+
+`sendTransaction` takes a namespace-specific request object and returns a
+`TransactionResult` (chain-dependent hash / signature).
+
+### EVM — native transfer (ETH, MATIC, …)
+
+```ts
+import type { EVMNativeTransferRequest } from '@meshconnect/uwc-types'
+
+const req: EVMNativeTransferRequest = {
+  from: session.activeAddress!,
+  to: '0xRecipient…',
+  amount: 1_000_000_000_000_000_000n, // 1 ETH in wei
+  gasConfig: { gasLimit: 21_000 }
+}
+const hash = await connector.sendTransaction(req)
+```
+
+### EVM — contract call (e.g. ERC-20 transfer)
+
+```ts
+import type { EVMContractCallRequest } from '@meshconnect/uwc-types'
+import { erc20ABI } from './abi/erc20ABI'
+
+const req: EVMContractCallRequest = {
+  contractAddress: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC on Base
+  abi: erc20ABI,
+  functionName: 'transfer',
+  args: [recipient, amountInSmallestUnit],
+  from: session.activeAddress!
+}
+const hash = await connector.sendTransaction(req)
+```
+
+### Solana — native transfer
+
+```ts
+import type { SolanaNativeTransferRequest } from '@meshconnect/uwc-types'
+
+// Fetch a recent blockhash first (RPC call you own)
+const blockhash = await fetchLatestBlockhash()
+
+const req: SolanaNativeTransferRequest = {
+  from: session.activeAddress!,
+  to: recipient,
+  amount: 1_000_000_000n, // 1 SOL in lamports
+  blockhash
+}
+const signature = await connector.sendTransaction(req)
+```
+
+### TON Jetton (USDT on TON, etc.)
+
+Use the helpers in `@meshconnect/uwc-ton-connector` to build the BOC payload,
+then pass the resulting `TonNativeTransferRequest` to `sendTransaction`. See
+the project root README for details.
+
+---
+
+## Wallet capabilities
+
+For EVM wallets supporting EIP-5792 (`wallet_getCapabilities`), the connector
+can fetch capability metadata — atomic batching, paymaster support, etc.
+
+```ts
+await connector.getWalletCapabilities(
+  session.activeAddress!,
+  session.activeNetwork ?? undefined
+)
+
+const caps = connector.getActiveWalletCapabilities()
+if (caps?.['eip155:8453']?.atomic?.status === 'supported') {
+  // wallet can atomically batch on Base
+}
+```
+
+`capabilitiesUpdated` fires with the new map when the call succeeds. Capability
+data is written into the session, so you can also read it from `getSession()`
+as `activeWalletCapabilities` / `activeNetworkWalletCapabilities`.
+
+---
+
+## Cancelling in-flight operations
+
+Every async operation accepts `{ signal }`:
+
+```ts
+const controller = new AbortController()
+
+connectButton.addEventListener('click', () => {
+  connector.connect('walletConnect', 'metamask', undefined, {
+    signal: controller.signal
+  })
+})
+
+cancelButton.addEventListener('click', () => controller.abort())
+```
+
+When the signal aborts, the in-flight promise rejects with an `AbortError`.
+Session state is **not** mutated after the abort, even if the wallet prompt
+later returns a result. This is especially useful in component lifecycles:
+
+```ts
+// Single-page app: abort on route change
+const controller = new AbortController()
+router.once('beforeLeave', () => controller.abort())
+await connector.signMessage('Log in', { signal: controller.signal })
+```
+
+Note: wallet extensions and mobile wallets don't expose a way to dismiss an
+open prompt from the dApp side — the abort protects **your** state, but the
+user may still see the prompt until they dismiss it.
+
+---
+
+## Error handling
+
+All operations throw either a plain `Error` (validation / setup issues) or a
+`WalletConnectorError` (wallet-side failures). The connector also emits a
+typed `error` event for every throw, so you can centralise logging.
+
+### The `WalletError` shape
+
+```ts
+interface WalletError {
+  type: 'unknown' | 'rejected' | 'expired'
+  message: string
+}
+```
+
+- `rejected` — user dismissed the prompt.
+- `expired`  — WalletConnect pairing proposal timed out.
+- `unknown`  — everything else (network errors, bad wallet state, …).
+
+### Per-call handling
+
+```ts
+try {
+  await connector.connect('injected', 'metamask')
+} catch (error) {
+  const walletError = error as WalletError
+  if (walletError.type === 'rejected') {
+    toast('You cancelled the connection')
+  } else {
+    toast(`Connect failed: ${walletError.message}`)
+  }
+}
+```
+
+### Centralised logging via events
+
+```ts
+import type { UWCOperation } from '@meshconnect/uwc-core'
+
+connector.on('error', ({ error, operation }: {
+  error: WalletError
+  operation: UWCOperation
+}) => {
+  analytics.track('wallet.error', {
+    operation,
+    type: error.type,
+    message: error.message
+  })
+})
+```
+
+`operation` is one of:
+`'connect' | 'disconnect' | 'switchNetwork' | 'signMessage' | 'sendTransaction' | 'getWalletCapabilities' | 'initialize'`.
+
+### AbortError
+
+Aborted operations reject with a `DOMException` whose `.name === 'AbortError'`.
+They are **not** routed through the `error` event — aborts are not wallet
+failures.
+
+```ts
+try {
+  await connector.connect(..., { signal })
+} catch (error) {
+  if ((error as { name?: string }).name === 'AbortError') {
+    // silent: user navigated away
+    return
+  }
+  throw error
+}
+```
+
+---
+
+## Testing
+
+The shared singleton can leak state between tests. Reset it in `beforeEach`:
+
+```ts
+import { UniversalWalletConnector } from '@meshconnect/uwc-core'
+
+beforeEach(() => {
+  UniversalWalletConnector.resetInstance()
+})
+```
+
+`resetInstance()` also clears the instance-count and duplicate-warning flags,
+so each test starts from a clean slate.
+
+When unit-testing consumer code, mock the whole module:
+
+```ts
+vi.mock('@meshconnect/uwc-core', () => ({
+  UniversalWalletConnector: class {
+    static getInstance = () => new this()
+    getSession = () => ({ /* fixture */ })
+    on = () => () => {}
+    once = () => () => {}
+    off = () => {}
+    subscribe = () => () => {}
+    connect = vi.fn()
+    disconnect = vi.fn()
+    signMessage = vi.fn()
+    sendTransaction = vi.fn()
+    // …whichever methods your code exercises
+  }
+}))
+```
+
+---
+
+## Recipes
+
+### Minimal vanilla app — connect, display address, disconnect
+
+```ts
+const connector = UniversalWalletConnector.getInstance({
+  networks: [mainnetNetwork],
+  wallets: [metamask]
+})
+
+connector.on('sessionChanged', ({ session }) => {
+  document.querySelector('#addr')!.textContent =
+    session.activeAddress ?? 'not connected'
+})
+
+document.querySelector('#connect')!.addEventListener('click', () =>
+  connector.connect('injected', 'metamask')
+)
+document.querySelector('#disconnect')!.addEventListener('click', () =>
+  connector.disconnect()
+)
+```
+
+### Show QR and auto-close modal on pair
+
+```ts
+connector.on('connectionUri', async ({ uri, connectionMode }) => {
+  if (connectionMode !== 'walletConnect') return
+  qrModal.show(await QRCode.toDataURL(uri))
+})
+
+connector.on('connected', () => qrModal.hide())
+connector.on('error', ({ operation }) => {
+  if (operation === 'connect') qrModal.hide()
+})
+
+await connector.connect('walletConnect', 'metamask')
+```
+
+### Network switcher with per-state UI
+
+```ts
+connector.on('networkSwitching', ({ isLoading, isWaitingForUserApproval }) => {
+  switchBtn.disabled = isLoading
+  switchBtn.textContent = isWaitingForUserApproval
+    ? 'Approve in wallet…'
+    : isLoading
+      ? 'Switching…'
+      : 'Switch network'
+})
+
+switchBtn.addEventListener('click', () =>
+  connector.switchNetwork('eip155:8453')
+)
+```
+
+### Abort a pending sign when the user navigates away
+
+```ts
+const controller = new AbortController()
+window.addEventListener('beforeunload', () => controller.abort())
+
+try {
+  const sig = await connector.signMessage('Sign in', { signal: controller.signal })
+  submitLogin(sig)
+} catch (error) {
+  if ((error as { name?: string }).name === 'AbortError') return
+  throw error
+}
+```
+
+---
+
+## API reference
+
+### Types
+
+```ts
+export interface UWCConfig {
+  networks: Network[]
+  wallets?: WalletMetadata[]
+  usingIntegratedBrowser?: boolean
+  walletConnectConfig?: WalletConnectConfig
+  tonConnectConfig?: TonConnectConfig
+}
+
+export interface OperationOptions {
+  signal?: AbortSignal
+}
+
+export type UWCEventName = keyof UWCEventMap
+export type UWCOperation =
+  | 'connect' | 'disconnect' | 'switchNetwork'
+  | 'signMessage' | 'sendTransaction'
+  | 'getWalletCapabilities' | 'initialize'
+```
+
+### Static methods
+
+```ts
+UniversalWalletConnector.getInstance(config?: UWCConfig): UniversalWalletConnector
+UniversalWalletConnector.resetInstance(): void
+```
+
+### Constructors
+
+```ts
+new UniversalWalletConnector(config: UWCConfig)
+new UniversalWalletConnector(
+  networks: Network[],
+  wallets?: WalletMetadata[],
+  usingIntegratedBrowser?: boolean,
+  walletConnectConfig?: WalletConnectConfig,
+  tonConnectConfig?: TonConnectConfig
+)
+```
+
+### Instance methods
+
+```ts
+// State
+getSession(): Session
+getState(): { session: Session }
+isReady(): boolean
+getWallets(): WalletMetadata[]
+getNetworks(): Network[]
+getConnectionURI(): string | undefined
+getNetworkSwitchLoadingState(): {
+  isLoading: boolean
+  isWaitingForUserApproval: boolean
+}
+getActiveWalletCapabilities(): Record<string, EVMCapabilities> | null
+isConnectionModeAvailable(mode: ConnectionMode, walletId: string): boolean
+
+// Events
+on<K extends UWCEventName>(event: K, listener: UWCEventListener<K>): () => void
+once<K extends UWCEventName>(event: K, listener: UWCEventListener<K>): () => void
+off<K extends UWCEventName>(event: K, listener: UWCEventListener<K>): void
+subscribe(listener: () => void): () => void  // legacy; maps to `change`
+
+// Async ops — all accept an optional OperationOptions argument
+connect(
+  mode: ConnectionMode,
+  walletId: string,
+  networkId?: NetworkId,
+  options?: OperationOptions
+): Promise<void>
+
+disconnect(options?: OperationOptions): Promise<void>
+
+switchNetwork(
+  networkId: NetworkId,
+  options?: OperationOptions
+): Promise<void>
+
+signMessage(
+  message: string,
+  options?: OperationOptions
+): Promise<SignatureType>
+
+sendTransaction(
+  request: TransactionRequest,
+  options?: OperationOptions
+): Promise<TransactionResult>
+
+getWalletCapabilities(
+  address: string,
+  activeNetwork?: Network,
+  options?: OperationOptions
+): Promise<void>
+```
+
+---
+
+## Further reading
+
+- [`@meshconnect/uwc-react`](../uwc-react) — React bindings (hooks + provider)
+- [`@meshconnect/uwc-types`](../types) — all request/response/session types
+- [`@meshconnect/uwc-constants`](../constants) — ready-made `Network` objects
+- [`apps/vanilla-example`](../../apps/vanilla-example) — complete
+  vanilla-TypeScript reference app using this package directly