@meshconnect/uwc-tron-connector 0.1.0

package/src/wallets/base.ts

@@ -0,0 +1,184 @@
+import type { SignedTronTransaction } from '../rest/trongrid-client'
+
+/**
+ * The subset of an injected wallet's `tronWeb` we rely on. Each wallet ships
+ * its own `tronWeb` (with the user's keys wired in) inside its provider; the
+ * crypto runs there, at zero bundle cost to us.
+ */
+export interface InjectedTronWeb {
+  defaultAddress?: {
+    base58?: string | false
+    hex?: string | false
+  }
+  trx: {
+    /** Sign an unsigned transaction object. Returns the signed transaction. */
+    sign(transaction: unknown): Promise<SignedTronTransaction>
+    /** Sign a plain string message (TIP-191). Present on all 5 target wallets. */
+    signMessageV2?(message: string): Promise<string>
+  }
+}
+
+/**
+ * The shape every supported wallet exposes at its window namespace. Wallets
+ * differ in where this object lives (see each wrapper), not in its surface.
+ */
+export interface InjectedTronProvider {
+  tronWeb?: InjectedTronWeb
+  /** Account-request entry point (`tron_requestAccounts`). */
+  request?(args: { method: string; params?: unknown }): Promise<unknown>
+  on?(event: string, handler: (...args: unknown[]) => void): void
+  removeListener?(event: string, handler: (...args: unknown[]) => void): void
+}
+
+/**
+ * One wrapper per wallet. Keeps every per-wallet quirk — namespace path, ready
+ * signal — isolated to a single ~30-line file, so a wallet change is a local
+ * patch (and a single wallet can be flag-disabled without touching the rest).
+ */
+export interface TronWalletWrapper {
+  /** Stable id; matches `WalletMetadata.id` callers pass in. */
+  id: string
+  /** Human-readable name; surfaced via `getAvailableWallets`. */
+  displayName: string
+  /** Read the provider from its window namespace, or undefined if absent. */
+  resolveProvider(): InjectedTronProvider | undefined
+  /**
+   * Window event that fires when the wallet finishes injecting, if it has one.
+   * Lets detection resolve immediately instead of waiting on the poll tick.
+   * TronLink is currently the only target wallet that emits one.
+   */
+  readyEventName?: string
+}
+
+/** Safely walk `window` down a path of keys (e.g. ['okxwallet','tronLink']). */
+export function readWindowPath(
+  path: readonly string[]
+): InjectedTronProvider | undefined {
+  if (typeof window === 'undefined') return undefined
+  let node: unknown = window
+  for (const key of path) {
+    if (node == null || typeof node !== 'object') return undefined
+    node = (node as Record<string, unknown>)[key]
+  }
+  if (node == null || typeof node !== 'object') return undefined
+  return node as InjectedTronProvider
+}
+
+/**
+ * A provider counts as present/detectable once it exposes a `request` method
+ * (the connect entry point) or already carries a `tronWeb` instance.
+ *
+ * Important: we must NOT require `tronWeb` here. Wallets like TronLink inject
+ * `window.tronLink` with `request` immediately but only populate `tronWeb`
+ * (and the account) AFTER the user approves `tron_requestAccounts`. Requiring
+ * `tronWeb` for detection would make the wallet un-discoverable until it's
+ * connected — a chicken-and-egg that hides it from the wallet list entirely.
+ */
+export function isProviderReady(
+  provider: InjectedTronProvider | undefined
+): provider is InjectedTronProvider {
+  return (
+    !!provider && (typeof provider.request === 'function' || !!provider.tronWeb)
+  )
+}
+
+/**
+ * After `connect`, poll briefly for the wallet's account address. TronLink (and
+ * the TronLink-compatible wallets) populate `tronWeb.defaultAddress.base58` a
+ * tick or two after `tron_requestAccounts` resolves, so a single synchronous
+ * read can miss it. Resolves the base58 address, or `undefined` on timeout.
+ */
+export function waitForWalletAddress(
+  provider: InjectedTronProvider,
+  timeoutMs = 3000,
+  pollIntervalMs = 50
+): Promise<string | undefined> {
+  const read = (): string | undefined => {
+    const base58 = provider.tronWeb?.defaultAddress?.base58
+    return typeof base58 === 'string' && base58.length > 0 ? base58 : undefined
+  }
+  const immediate = read()
+  if (immediate) return Promise.resolve(immediate)
+
+  return new Promise(resolve => {
+    let settled = false
+    const finish = (value: string | undefined) => {
+      if (settled) return
+      settled = true
+      clearInterval(timer)
+      clearTimeout(deadline)
+      resolve(value)
+    }
+    const timer = setInterval(() => {
+      const address = read()
+      if (address) finish(address)
+    }, pollIntervalMs)
+    const deadline = setTimeout(() => finish(undefined), timeoutMs)
+  })
+}
+
+/**
+ * Pick the first *ready* provider among the candidates (in preference order).
+ * If none is ready yet, return the first one that merely exists, so
+ * `detectProvider` keeps polling it — re-evaluated each tick, so a path that
+ * becomes ready later still wins. Used by wallets exposed at more than one
+ * window namespace (casing/legacy variants).
+ */
+export function firstReadyOf(
+  ...candidates: Array<InjectedTronProvider | undefined>
+): InjectedTronProvider | undefined {
+  for (const candidate of candidates) {
+    if (isProviderReady(candidate)) return candidate
+  }
+  return candidates.find(candidate => candidate != null)
+}
+
+/**
+ * Resolve a wallet's provider, waiting up to `timeoutMs` for it to finish
+ * injecting. Polling covers all wallets; an optional `readyEventName` provides
+ * a fast path for wallets that announce readiness (TronLink's TIP-6963-style
+ * signal). Resolves `undefined` if the wallet never appears.
+ */
+export function detectProvider(
+  wrapper: TronWalletWrapper,
+  timeoutMs = 3000,
+  pollIntervalMs = 50
+): Promise<InjectedTronProvider | undefined> {
+  const immediate = wrapper.resolveProvider()
+  if (isProviderReady(immediate)) return Promise.resolve(immediate)
+
+  // No browser context (SSR/non-browser): no wallet can ever appear, so resolve
+  // immediately instead of polling out the full timeout.
+  if (typeof window === 'undefined') return Promise.resolve(undefined)
+
+  return new Promise(resolve => {
+    let settled = false
+    // Declared up front (not `const` after `finish`) so `finish` never
+    // forward-references an uninitialized binding, even under future refactors.
+    let timer: ReturnType<typeof setInterval>
+    let deadline: ReturnType<typeof setTimeout>
+
+    const onReady = () => tryResolve()
+    const finish = (result: InjectedTronProvider | undefined) => {
+      if (settled) return
+      settled = true
+      clearInterval(timer)
+      clearTimeout(deadline)
+      if (wrapper.readyEventName && typeof window !== 'undefined') {
+        window.removeEventListener(wrapper.readyEventName, onReady)
+      }
+      resolve(result)
+    }
+
+    function tryResolve() {
+      const provider = wrapper.resolveProvider()
+      if (isProviderReady(provider)) finish(provider)
+    }
+
+    if (wrapper.readyEventName && typeof window !== 'undefined') {
+      window.addEventListener(wrapper.readyEventName, onReady)
+    }
+    timer = setInterval(tryResolve, pollIntervalMs)
+    deadline = setTimeout(() => finish(undefined), timeoutMs)
+  })
+}

package/src/wallets/bitget.ts

@@ -0,0 +1,17 @@
+import { readWindowPath, firstReadyOf, type TronWalletWrapper } from './base'
+
+/**
+ * Bitget Wallet (formerly BitKeep) — injects at `window.bitkeep`. The Tron
+ * provider lives under `window.bitkeep.tronLink`; older builds exposed it on
+ * `window.bitkeep` directly, so we fall back to that.
+ */
+export const bitget: TronWalletWrapper = {
+  id: 'bitget',
+  displayName: 'Bitget Wallet',
+  resolveProvider() {
+    return firstReadyOf(
+      readWindowPath(['bitkeep', 'tronLink']),
+      readWindowPath(['bitkeep'])
+    )
+  }
+}

package/src/wallets/okx.ts

@@ -0,0 +1,10 @@
+import { readWindowPath, type TronWalletWrapper } from './base'
+
+/** OKX Wallet — exposes a TronLink-compatible provider at `window.okxwallet.tronLink`. */
+export const okx: TronWalletWrapper = {
+  id: 'okx',
+  displayName: 'OKX Wallet',
+  resolveProvider() {
+    return readWindowPath(['okxwallet', 'tronLink'])
+  }
+}

package/src/wallets/registry.ts

@@ -0,0 +1,26 @@
+import type { TronWalletId } from '@meshconnect/uwc-types'
+import type { TronWalletWrapper } from './base'
+import { tronlink } from './tronlink'
+import { okx } from './okx'
+import { trust } from './trust'
+import { bitget } from './bitget'
+import { tokenpocket } from './tokenpocket'
+
+export type { TronWalletId } from '@meshconnect/uwc-types'
+
+/** All supported wallet wrappers, keyed by id. */
+export const TRON_WALLET_REGISTRY: Record<TronWalletId, TronWalletWrapper> = {
+  tronlink,
+  bitget,
+  okx,
+  tokenpocket,
+  trust
+}
+
+export const ALL_TRON_WALLET_IDS: readonly TronWalletId[] = Object.freeze(
+  Object.keys(TRON_WALLET_REGISTRY) as TronWalletId[]
+)
+
+export function isTronWalletId(value: string): value is TronWalletId {
+  return (ALL_TRON_WALLET_IDS as readonly string[]).includes(value)
+}

package/src/wallets/tokenpocket.ts

@@ -0,0 +1,15 @@
+import { readWindowPath, type TronWalletWrapper } from './base'
+
+/**
+ * TokenPocket — injects at `window.tokenpocket`, exposing its Tron provider at
+ * `window.tokenpocket.tron`. We target that nested path specifically rather
+ * than the shared `window.tronLink` global TokenPocket also populates, so it is
+ * never mis-detected as TronLink.
+ */
+export const tokenpocket: TronWalletWrapper = {
+  id: 'tokenpocket',
+  displayName: 'TokenPocket',
+  resolveProvider() {
+    return readWindowPath(['tokenpocket', 'tron'])
+  }
+}

package/src/wallets/tronlink.ts

@@ -0,0 +1,15 @@
+import { readWindowPath, firstReadyOf, type TronWalletWrapper } from './base'
+
+/**
+ * TronLink — `window.tronLink` (legacy) or `window.tron` (TIP-1193).
+ * The only target wallet that announces readiness, via the
+ * `tronLink#initialized` window event.
+ */
+export const tronlink: TronWalletWrapper = {
+  id: 'tronlink',
+  displayName: 'TronLink',
+  readyEventName: 'tronLink#initialized',
+  resolveProvider() {
+    return firstReadyOf(readWindowPath(['tronLink']), readWindowPath(['tron']))
+  }
+}

package/src/wallets/trust.ts

@@ -0,0 +1,18 @@
+import { readWindowPath, firstReadyOf, type TronWalletWrapper } from './base'
+
+/**
+ * Trust Wallet — TronLink-compatible provider. The repo's existing wallet
+ * metadata uses `window.trustWallet.tronLink` (capital W), so we prefer that,
+ * then the all-lowercase `window.trustwallet.tronLink` that some extension
+ * versions expose, to avoid casing-related false negatives.
+ */
+export const trust: TronWalletWrapper = {
+  id: 'trust',
+  displayName: 'Trust Wallet',
+  resolveProvider() {
+    return firstReadyOf(
+      readWindowPath(['trustWallet', 'tronLink']),
+      readWindowPath(['trustwallet', 'tronLink'])
+    )
+  }
+}