@meshconnect/uwc-tron-connector 0.1.0

package/src/tron-connector.ts

@@ -0,0 +1,568 @@
+import type {
+  AvailableAddress,
+  ConnectorResult,
+  DetectedTronWalletInfo,
+  Namespace,
+  Network,
+  NetworkId,
+  SignatureType,
+  SwitchNetworkResult,
+  TransactionRequest,
+  TronNativeTransferRequest,
+  TronTRC20TransferRequest,
+  WalletMetadata
+} from '@meshconnect/uwc-types'
+import { WalletConnectorError } from '@meshconnect/uwc-types'
+import { parseError } from './shared/error-utils'
+import {
+  TronStateMachine,
+  type TronStateListener
+} from './events/state-machine'
+import {
+  TronGridClient,
+  type UnsignedTronTransaction
+} from './rest/trongrid-client'
+import { assertValidTronChecksum, tronAddressToHex } from './rest/address'
+import {
+  encodeTrc20TransferParams,
+  TRC20_TRANSFER_SELECTOR_HASH
+} from './rest/abi'
+import {
+  detectProvider,
+  waitForWalletAddress,
+  type InjectedTronProvider
+} from './wallets/base'
+import {
+  ALL_TRON_WALLET_IDS,
+  TRON_WALLET_REGISTRY,
+  isTronWalletId,
+  type TronWalletId
+} from './wallets/registry'
+import type { TronConnectorConfig } from './types'
+
+/** Wallet events we mirror into the state machine while connected. */
+const WALLET_EVENTS = ['accountsChanged', 'disconnect'] as const
+
+/**
+ * Default probe window for `getAvailableWallets`. Short on purpose — see the
+ * rationale in that method. Override via `TronConnectorConfig.discoveryTimeoutMs`.
+ */
+const DEFAULT_DISCOVERY_TIMEOUT_MS = 300
+
+interface ActiveTronConnection {
+  walletId: TronWalletId
+  provider: InjectedTronProvider
+  address: string
+}
+
+/**
+ * Mesh-owned Tron wallet connector. Zero third-party Tron runtime deps.
+ *
+ * One instance fronts all 5 supported wallets — TronLink, Bitget, OKX,
+ * TokenPocket, Trust — selected per-connect by the wallet id. Per-wallet
+ * enablement is controlled by `config.enabledWallets`.
+ *
+ * Transactions are built and broadcast against the Tron full-node HTTP API
+ * (`/wallet/*`); signing goes through the wallet's own injected
+ * `provider.tronWeb.trx.sign(unsigned)`, so the crypto stays in the wallet and
+ * costs us no bundle.
+ */
+export class TronConnector {
+  private readonly config: TronConnectorConfig
+  private readonly enabled: ReadonlySet<TronWalletId>
+  private readonly clientByNetwork = new Map<NetworkId, TronGridClient>()
+  private readonly state = new TronStateMachine()
+
+  private active: ActiveTronConnection | null = null
+  private activeNetworkId: NetworkId | null = null
+  /** Listeners attached to the active provider, kept so we can detach on cleanup. */
+  private boundListeners: Array<{
+    event: string
+    handler: (...args: unknown[]) => void
+  }> = []
+
+  constructor(config: TronConnectorConfig) {
+    this.config = config
+    this.enabled = new Set(Array.from(config.enabledWallets))
+  }
+
+  /** Subscribe to connection-state transitions (decision D3). */
+  subscribe(listener: TronStateListener): () => void {
+    return this.state.subscribe(listener)
+  }
+
+  /**
+   * Returns the wallets that are (a) enabled in config and (b) currently
+   * injected into the page. Conforms to `Connector.getAvailableWallets` for
+   * namespace `'tron'`.
+   */
+  async getAvailableWallets(
+    namespace: Namespace,
+    expectedWallets?: WalletMetadata[]
+  ): Promise<DetectedTronWalletInfo[]> {
+    if (namespace !== 'tron') return []
+
+    // Discovery uses a deliberately SHORT timeout, distinct from connect()'s
+    // longer `readyStateTimeoutMs`. `detectProvider` only resolves early when a
+    // wallet *appears* — an absent wallet always waits out the full timeout. In
+    // discovery every enabled-but-not-installed wallet is probed in parallel, so
+    // a 3s timeout would make a user who has only TronLink installed wait ~3s
+    // for the wallet list on every call. A short window still catches wallets
+    // that inject slightly after page load (injection is async) without
+    // stalling the UI; connect(), which targets one already-chosen wallet and
+    // can afford to wait, keeps the longer timeout.
+    const timeout =
+      this.config.discoveryTimeoutMs ?? DEFAULT_DISCOVERY_TIMEOUT_MS
+    const interval = this.config.readyStatePollIntervalMs ?? 50
+    const allowedIds = this.resolveAllowedIds(expectedWallets)
+
+    // Probe in parallel but place each result by its index, so the returned
+    // order is stable (matches resolveAllowedIds) regardless of which wallet's
+    // probe resolves first.
+    const detected = await Promise.all(
+      allowedIds.map(async (id): Promise<DetectedTronWalletInfo | null> => {
+        const wrapper = TRON_WALLET_REGISTRY[id]
+        const provider = await detectProvider(wrapper, timeout, interval)
+        return provider ? { uuid: id, name: wrapper.displayName } : null
+      })
+    )
+    return detected.filter((w): w is DetectedTronWalletInfo => w !== null)
+  }
+
+  /**
+   * Connect to a Tron wallet on the given network. The wallet is identified by
+   * `walletProvider.uuid` (or `.walletId`), which must be an enabled
+   * `TronWalletId`. On success this connector holds the active provider until
+   * `disconnect()` or the next `connect()`.
+   */
+  async connect(
+    network: Network,
+    walletProvider?: { uuid?: string } | { walletId?: string }
+  ): Promise<ConnectorResult> {
+    this.assertTronNetwork(network, 'connect')
+    const walletId = this.requireWalletId(walletProvider)
+    const wrapper = TRON_WALLET_REGISTRY[walletId]
+
+    this.state.set({ status: 'connecting', walletId })
+
+    const provider = await detectProvider(
+      wrapper,
+      this.config.readyStateTimeoutMs ?? 3000,
+      this.config.readyStatePollIntervalMs ?? 50
+    )
+    if (!provider) {
+      // Same consistency guard as the catch below: a failed reconnect (target
+      // not installed) must not leave `active` pointing at the prior wallet.
+      this.cleanupActive()
+      this.state.set({ status: 'disconnected' })
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message: `Tron wallet "${wrapper.displayName}" is not installed`
+      })
+    }
+
+    try {
+      // Prompts the wallet to expose the account. The wallet populates its
+      // `tronWeb` + account a tick after this resolves, so poll briefly.
+      await provider.request?.({ method: 'tron_requestAccounts' })
+      const address = await waitForWalletAddress(
+        provider,
+        this.config.readyStateTimeoutMs ?? 3000,
+        this.config.readyStatePollIntervalMs ?? 50
+      )
+      if (!address) {
+        throw new WalletConnectorError({
+          type: 'unknown',
+          message: `Tron wallet "${wrapper.displayName}" connected but exposed no address`
+        })
+      }
+
+      // Pre-warm the per-network client so the first send doesn't pay the cost.
+      this.getClient(network.id)
+      this.cleanupActive()
+      this.active = { walletId, provider, address }
+      this.activeNetworkId = network.id
+      this.bindWalletEvents(provider)
+      this.state.set({ status: 'connected', walletId, address })
+
+      const availableAddresses: AvailableAddress[] = [
+        { networkId: network.id, address }
+      ]
+      return { networkId: network.id, address, availableAddresses }
+    } catch (error) {
+      // Clear any prior/partial connection so `active` can't be left pointing
+      // at a stale wallet while we report 'disconnected' (e.g. a failed
+      // reconnect after a previous connect succeeded).
+      this.cleanupActive()
+      this.state.set({ status: 'disconnected' })
+      parseError(error)
+    }
+  }
+
+  /**
+   * Tron network selection is wallet-driven (the user picks the chain in the
+   * wallet UI); there is no standardised programmatic switch across these
+   * injected providers. We repoint the build/broadcast endpoint to the target
+   * network and report the current address.
+   */
+  async switchNetwork(network: Network): Promise<SwitchNetworkResult> {
+    this.assertTronNetwork(network, 'switchNetwork')
+    if (!this.active) {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message: 'TronConnector.switchNetwork called before connect()'
+      })
+    }
+    try {
+      this.getClient(network.id)
+    } catch (error) {
+      // Surface a missing-endpoint (or similar) failure as a WalletConnectorError,
+      // consistent with connect/sendTransaction/signMessage.
+      parseError(error)
+    }
+    this.activeNetworkId = network.id
+    return { networkId: network.id, address: this.active.address }
+  }
+
+  async disconnect(): Promise<void> {
+    this.cleanupActive()
+    this.state.set({ status: 'disconnected' })
+  }
+
+  async signMessage(message: string): Promise<SignatureType> {
+    const active = this.requireActive('signMessage')
+    const tronWeb = active.provider.tronWeb
+    const signMessageV2 = tronWeb?.trx.signMessageV2
+    if (!tronWeb || !signMessageV2) {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message: 'Active Tron wallet does not support message signing'
+      })
+    }
+    try {
+      const signature = await signMessageV2.call(tronWeb.trx, message)
+      // Match the existing injected-connector tron path, which wraps the
+      // signature as a StandardSignature rather than the TronSignature variant.
+      return { type: 'standard', signature }
+    } catch (error) {
+      parseError(error)
+    }
+  }
+
+  async sendTransaction(request: TransactionRequest): Promise<string> {
+    const active = this.requireActive('sendTransaction')
+    if (!this.activeNetworkId) {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message: 'TronConnector.sendTransaction: no active network'
+      })
+    }
+    const client = this.getClient(this.activeNetworkId)
+
+    // Build, sign, and broadcast all run inside the try so node/network errors
+    // from the build step surface as WalletConnectorError (via parseError),
+    // consistent with the sign/broadcast path; the validation/guard throws below
+    // are already WalletConnectorError and pass through parseError unchanged.
+    try {
+      let unsigned: UnsignedTronTransaction
+      if (isTronTRC20(request)) {
+        this.assertValidAmount(request.amount)
+        this.assertFromMatchesActive(request.from, active.address)
+        // TRC20 encodes `to`/`contract` as raw hex, so the node never sees (or
+        // checksum-validates) the base58 forms — verify both here so a typo'd
+        // recipient or contract can't silently misdirect funds.
+        await this.assertValidRecipient(request.to)
+        await this.assertValidRecipient(request.contractAddress)
+        unsigned = await client.createTrc20Transfer({
+          from: request.from,
+          to: request.to,
+          amount: request.amount,
+          contractAddress: request.contractAddress
+        })
+      } else if (isTronNative(request)) {
+        // The node validates `to` (sent as base58 with visible:true), so no
+        // checksum check is needed on this path.
+        this.assertValidAmount(request.amount)
+        this.assertFromMatchesActive(request.from, active.address)
+        unsigned = await client.createTransaction({
+          from: request.from,
+          to: request.to,
+          amount: request.amount
+        })
+      } else {
+        throw new WalletConnectorError({
+          type: 'unknown',
+          message: 'TronConnector.sendTransaction: unsupported request shape'
+        })
+      }
+
+      // Don't blindly sign what the node returned: confirm the built tx encodes
+      // the requested recipient/amount/contract. A compromised or MITM'd
+      // endpoint could otherwise swap the destination, with the wallet's confirm
+      // UI as the only backstop.
+      this.assertBuiltTxMatchesRequest(unsigned, request)
+
+      // A wallet can lock/disconnect without firing an event, dropping
+      // `tronWeb`. Guard so we surface a clear error, not a raw TypeError.
+      const tronWeb = active.provider.tronWeb
+      if (!tronWeb) {
+        throw new WalletConnectorError({
+          type: 'unknown',
+          message: 'Active Tron wallet is unavailable; reconnect and try again'
+        })
+      }
+
+      const signed = await tronWeb.trx.sign(unsigned)
+      return await client.broadcastTransaction(signed)
+    } catch (error) {
+      parseError(error)
+    }
+  }
+
+  /**
+   * Verify the node-built transaction encodes exactly what we asked for, before
+   * handing it to the wallet to sign. Reads `raw_data.contract[0].parameter.value`:
+   * native → owner/to/amount; TRC20 → owner/contract + the full `transfer` call
+   * data. Addresses are compared hex-normalized (base58/hex agnostic), falling
+   * back to exact string match for non-decodable placeholders.
+   */
+  private assertBuiltTxMatchesRequest(
+    unsigned: UnsignedTronTransaction,
+    request: TronNativeTransferRequest | TronTRC20TransferRequest
+  ): void {
+    const mismatch = (): never => {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message:
+          'TronConnector.sendTransaction: the node-built transaction does not match the request (possible tampered/MITM endpoint)'
+      })
+    }
+    const value = (
+      unsigned.raw_data as
+        | {
+            contract?: Array<{
+              parameter?: { value?: Record<string, unknown> }
+            }>
+          }
+        | undefined
+    )?.contract?.[0]?.parameter?.value
+    if (!value) {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message:
+          'TronConnector.sendTransaction: the node-built transaction does not match the request (possible tampered/MITM endpoint)'
+      })
+    }
+
+    const sameAddress = (built: unknown, requested: string): boolean => {
+      const a = String(built ?? '')
+      if (a === requested) return true
+      try {
+        return tronAddressToHex(a) === tronAddressToHex(requested)
+      } catch {
+        return false
+      }
+    }
+
+    if (!sameAddress(value['owner_address'], request.from)) mismatch()
+    if (isTronTRC20(request)) {
+      if (!sameAddress(value['contract_address'], request.contractAddress)) {
+        mismatch()
+      }
+      const expectedData = (
+        TRC20_TRANSFER_SELECTOR_HASH +
+        encodeTrc20TransferParams(request.to, request.amount)
+      ).toLowerCase()
+      if (String(value['data'] ?? '').toLowerCase() !== expectedData) mismatch()
+    } else {
+      if (!sameAddress(value['to_address'], request.to)) mismatch()
+      if (Number(value['amount']) !== request.amount) mismatch()
+    }
+  }
+
+  /** The wallet only signs for its own key — reject a mismatched `from` early. */
+  private assertFromMatchesActive(from: string, activeAddress: string): void {
+    if (from !== activeAddress) {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message: `TronConnector.sendTransaction: "from" (${from}) does not match the connected address (${activeAddress})`
+      })
+    }
+  }
+
+  // ---- internals -----------------------------------------------------------
+
+  private assertTronNetwork(network: Network, method: string): void {
+    if (network.namespace !== 'tron') {
+      throw new Error(
+        `TronConnector.${method}: expected a 'tron' network, got '${network.namespace}'`
+      )
+    }
+  }
+
+  private requireActive(method: string): ActiveTronConnection {
+    if (!this.active) {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message: `TronConnector.${method} called before connect()`
+      })
+    }
+    return this.active
+  }
+
+  /**
+   * Reject amounts that aren't safe non-negative integers. Two reasons, both on
+   * the money path: a fractional value makes `BigInt(amount)` throw a raw
+   * `RangeError` (and the build runs outside the sign/broadcast try/catch, so it
+   * would escape unwrapped); and a value beyond `Number.MAX_SAFE_INTEGER` can't
+   * be represented exactly, so it would silently transfer the wrong amount.
+   * `Number.isSafeInteger` covers both.
+   */
+  private assertValidAmount(amount: number): void {
+    if (!Number.isSafeInteger(amount) || amount < 0) {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message: `TronConnector.sendTransaction: amount must be a non-negative integer within the safe range, got ${amount}`
+      })
+    }
+  }
+
+  /** Verify a TRC20 recipient's base58 checksum, surfaced as a typed error. */
+  private async assertValidRecipient(to: string): Promise<void> {
+    try {
+      await assertValidTronChecksum(to)
+    } catch (error) {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message:
+          error instanceof Error
+            ? error.message
+            : 'TronConnector.sendTransaction: invalid recipient address'
+      })
+    }
+  }
+
+  private resolveAllowedIds(
+    expectedWallets?: WalletMetadata[]
+  ): TronWalletId[] {
+    if (!expectedWallets || expectedWallets.length === 0) {
+      return ALL_TRON_WALLET_IDS.filter(id => this.enabled.has(id))
+    }
+    const expectedIds = new Set(expectedWallets.map(wallet => wallet.id))
+    return ALL_TRON_WALLET_IDS.filter(
+      id => this.enabled.has(id) && expectedIds.has(id)
+    )
+  }
+
+  private requireWalletId(
+    provider: { uuid?: string } | { walletId?: string } | undefined
+  ): TronWalletId {
+    const raw =
+      (provider as { uuid?: string } | undefined)?.uuid ??
+      (provider as { walletId?: string } | undefined)?.walletId
+    if (!raw) {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message: 'TronConnector.connect: missing wallet identifier'
+      })
+    }
+    if (!isTronWalletId(raw)) {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message: `TronConnector.connect: unknown wallet "${raw}"`
+      })
+    }
+    if (!this.enabled.has(raw)) {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message: `TronConnector.connect: wallet "${raw}" is not enabled in config`
+      })
+    }
+    return raw
+  }
+
+  private getClient(networkId: NetworkId): TronGridClient {
+    let client = this.clientByNetwork.get(networkId)
+    if (!client) {
+      client = new TronGridClient(networkId, this.config.tronGrid)
+      this.clientByNetwork.set(networkId, client)
+    }
+    return client
+  }
+
+  private bindWalletEvents(provider: InjectedTronProvider): void {
+    if (!provider.on) return
+    for (const event of WALLET_EVENTS) {
+      const handler = (...args: unknown[]) => this.onWalletEvent(event, args[0])
+      provider.on(event, handler)
+      this.boundListeners.push({ event, handler })
+    }
+  }
+
+  private onWalletEvent(event: string, payload: unknown): void {
+    if (!this.active) return
+    if (event === 'disconnect') {
+      this.cleanupActive()
+      this.state.set({ status: 'disconnected' })
+      return
+    }
+    // accountsChanged payload shape varies by wallet: TronLink/TIP-1193 emit a
+    // bare address string, while the EIP-1193-style providers (OKX, Trust,
+    // Bitget) emit an array. An empty array is the logout signal. We normalise
+    // both, falling back to the wallet's current default address only when the
+    // payload carries nothing usable.
+    let nextAddress: string | undefined
+    if (typeof payload === 'string') {
+      nextAddress = payload
+    } else if (Array.isArray(payload)) {
+      nextAddress = payload[0] as string | undefined
+    } else {
+      nextAddress =
+        this.active.provider.tronWeb?.defaultAddress?.base58 || undefined
+    }
+    if (!nextAddress) {
+      this.cleanupActive()
+      this.state.set({ status: 'disconnected' })
+      return
+    }
+    this.active = { ...this.active, address: nextAddress }
+    this.state.set({
+      status: 'connected',
+      walletId: this.active.walletId,
+      address: nextAddress
+    })
+  }
+
+  private cleanupActive(): void {
+    if (this.active?.provider.removeListener) {
+      for (const { event, handler } of this.boundListeners) {
+        this.active.provider.removeListener(event, handler)
+      }
+    }
+    this.boundListeners = []
+    this.active = null
+    this.activeNetworkId = null
+  }
+}
+
+function isTronNative(
+  request: TransactionRequest
+): request is TronNativeTransferRequest {
+  return (
+    'from' in request &&
+    'to' in request &&
+    typeof (request as TronNativeTransferRequest).amount === 'number' &&
+    !('contractAddress' in request)
+  )
+}
+
+function isTronTRC20(
+  request: TransactionRequest
+): request is TronTRC20TransferRequest {
+  return (
+    'from' in request &&
+    'to' in request &&
+    'contractAddress' in request &&
+    typeof (request as TronTRC20TransferRequest).amount === 'number'
+  )
+}

package/src/types.ts

@@ -0,0 +1,11 @@
+/**
+ * Public configuration types for the Tron connector now live in
+ * `@meshconnect/uwc-types` (alongside `TonConnectConfig` / `WalletConnectConfig`)
+ * so they can thread through `UniversalWalletConnector`. Re-exported here for
+ * convenience and backward compatibility.
+ */
+export type {
+  TronConnectorConfig,
+  TronGridConfig,
+  TronWalletId
+} from '@meshconnect/uwc-types'