@meshconnect/uwc-tron-connector 0.1.0

package/src/rest/address.ts

@@ -0,0 +1,140 @@
+/**
+ * Tron address utilities — base58check ↔ hex, dependency-free.
+ *
+ * A Tron address has two on-the-wire forms:
+ *   - base58check (`T...`): Base58Check of `0x41 ‖ <20-byte body> ‖ <4-byte checksum>`.
+ *   - hex (`41` + 40 hex chars): the 21-byte payload (`0x41` prefix + 20-byte body).
+ *
+ * The full-node HTTP API accepts base58 directly when `visible: true` is set, so
+ * build/broadcast never needs conversion. The one place we DO need it is the
+ * TRC20 ABI parameter, which encodes the recipient as the bare 20-byte body.
+ *
+ * Decoding base58 is pure bigint math (no hashing), so the conversion helpers
+ * (`tronAddressToHex` / `tronAddressToEvmHex`) stay synchronous and do NOT
+ * verify the 4-byte checksum — that's the hot path used for already-validated
+ * addresses. Checksum verification is provided separately by the async
+ * `assertValidTronChecksum` (SubtleCrypto), which the connector calls on the
+ * TRC20 recipient — the one case the node never validates (it's encoded as raw
+ * hex, not sent as base58).
+ */
+
+const BASE58_ALPHABET =
+  '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+
+/** Decode a Base58 string to bytes (big-endian). Throws on invalid characters. */
+function base58Decode(input: string): Uint8Array {
+  if (input.length === 0) throw new Error('tron address: empty base58 string')
+
+  let value = 0n
+  for (const char of input) {
+    const index = BASE58_ALPHABET.indexOf(char)
+    if (index === -1) {
+      throw new Error(`tron address: invalid base58 character "${char}"`)
+    }
+    value = value * 58n + BigInt(index)
+  }
+
+  const bytes: number[] = []
+  while (value > 0n) {
+    bytes.unshift(Number(value & 0xffn))
+    value >>= 8n
+  }
+
+  // Each leading '1' in base58 represents a leading zero byte.
+  for (const char of input) {
+    if (char !== '1') break
+    bytes.unshift(0)
+  }
+
+  return Uint8Array.from(bytes)
+}
+
+function toHex(bytes: Uint8Array): string {
+  let out = ''
+  for (const byte of bytes) {
+    out += byte.toString(16).padStart(2, '0')
+  }
+  return out
+}
+
+/**
+ * Convert a base58 Tron address (`T...`) to its 21-byte hex form
+ * (`41` + 40 hex chars). Already-hex input (with or without `0x`) is normalised
+ * and returned as-is.
+ */
+export function tronAddressToHex(address: string): string {
+  // Accept hex passthrough so callers can mix forms.
+  const stripped = address.startsWith('0x') ? address.slice(2) : address
+  if (/^41[0-9a-fA-F]{40}$/.test(stripped)) {
+    return stripped.toLowerCase()
+  }
+
+  const decoded = base58Decode(address)
+  // 25 bytes = 21-byte payload (0x41 + 20-byte body) + 4-byte checksum.
+  if (decoded.length !== 25) {
+    throw new Error(
+      `tron address: expected 25 bytes after base58 decode, got ${decoded.length}`
+    )
+  }
+  const payload = decoded.subarray(0, 21)
+  if (payload[0] !== 0x41) {
+    throw new Error('tron address: missing 0x41 Tron address prefix')
+  }
+  return toHex(payload)
+}
+
+/**
+ * Convert a Tron address to its bare 20-byte EVM-style hex body (no `0x41`
+ * prefix, no `0x`). This is the form used inside TRC20 ABI parameters.
+ */
+export function tronAddressToEvmHex(address: string): string {
+  return tronAddressToHex(address).slice(2)
+}
+
+/**
+ * SHA-256 via SubtleCrypto. Re-wraps the input with `Uint8Array.from` so it is
+ * an ArrayBuffer-backed view (satisfies `digest`'s `BufferSource` param without
+ * naming the DOM type, which our lint's `no-undef` doesn't recognize).
+ */
+async function sha256(bytes: Uint8Array): Promise<Uint8Array> {
+  const digest = await crypto.subtle.digest('SHA-256', Uint8Array.from(bytes))
+  return new Uint8Array(digest)
+}
+
+/**
+ * Validate a base58 Tron address's 0x41 prefix and 4-byte Base58Check checksum
+ * (first 4 bytes of `sha256(sha256(payload))`). Throws on mismatch.
+ *
+ * This matters for the TRC20 recipient: native transfers send the address as
+ * base58 with `visible:true`, so the node validates it — but TRC20 encodes the
+ * recipient as a raw 20-byte hex word, so the node never sees the base58 form.
+ * Without this check a typo'd-but-structurally-valid address would silently
+ * send funds to the wrong, unrecoverable destination.
+ *
+ * Hex inputs carry no base58 checksum, so they pass through unchecked.
+ * Async because it uses SubtleCrypto for SHA-256 (no hashing dependency).
+ */
+export async function assertValidTronChecksum(address: string): Promise<void> {
+  const stripped = address.startsWith('0x') ? address.slice(2) : address
+  if (/^41[0-9a-fA-F]{40}$/.test(stripped)) return // hex form: no checksum to verify
+
+  const decoded = base58Decode(address)
+  if (decoded.length !== 25) {
+    throw new Error(
+      `tron address: expected 25 bytes after base58 decode, got ${decoded.length}`
+    )
+  }
+  const payload = decoded.subarray(0, 21)
+  if (payload[0] !== 0x41) {
+    throw new Error('tron address: missing 0x41 Tron address prefix')
+  }
+  const expected = decoded.subarray(21, 25)
+  const round2 = await sha256(await sha256(payload))
+  for (let i = 0; i < 4; i++) {
+    if (round2[i] !== expected[i]) {
+      throw new Error(
+        'tron address: base58 checksum mismatch (possible typo in recipient address)'
+      )
+    }
+  }
+}

package/src/rest/trongrid-client.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { TronGridClient, decodeHexMessage } from './trongrid-client'
+
+const MAINNET = 'tron:0x2b6653dc' as const
+
+function mockFetch(responses: unknown[]): ReturnType<typeof vi.fn> {
+  const fn = vi.fn()
+  for (const body of responses) {
+    fn.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      json: async () => body
+    })
+  }
+  return fn
+}
+
+describe('TronGridClient', () => {
+  let fetchMock: ReturnType<typeof vi.fn>
+
+  beforeEach(() => {
+    fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+  })
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('throws when no endpoint is configured for the network', () => {
+    expect(() => new TronGridClient('eip155:1' as never)).toThrow(
+      /no full-node endpoint/
+    )
+  })
+
+  it('strips trailing slashes from a configured endpoint (no double slash)', async () => {
+    fetchMock = mockFetch([{ txID: 'a', raw_data: {} }])
+    vi.stubGlobal('fetch', fetchMock)
+    const client = new TronGridClient('tron:0x2b6653dc', {
+      endpoints: { 'tron:0x2b6653dc': 'https://node.example.com///' }
+    })
+    await client.createTransaction({ from: 'a', to: 'b', amount: 1 })
+    expect(fetchMock.mock.calls[0][0]).toBe(
+      'https://node.example.com/wallet/createtransaction'
+    )
+  })
+
+  it('createTransaction posts visible base58 fields and returns the unsigned tx', async () => {
+    fetchMock = mockFetch([{ txID: 'abc123', raw_data: {}, visible: true }])
+    vi.stubGlobal('fetch', fetchMock)
+    const client = new TronGridClient(MAINNET, { apiKey: 'KEY' })
+
+    const tx = await client.createTransaction({
+      from: 'TFrom',
+      to: 'TTo',
+      amount: 5
+    })
+
+    expect(tx.txID).toBe('abc123')
+    const [url, init] = fetchMock.mock.calls[0]
+    expect(url).toBe('https://api.trongrid.io/wallet/createtransaction')
+    expect(JSON.parse(init.body)).toEqual({
+      owner_address: 'TFrom',
+      to_address: 'TTo',
+      amount: 5,
+      visible: true
+    })
+    expect(init.headers['TRON-PRO-API-KEY']).toBe('KEY')
+  })
+
+  it('createTransaction surfaces a node-side Error field', async () => {
+    fetchMock = mockFetch([{ Error: 'bad address' }])
+    vi.stubGlobal('fetch', fetchMock)
+    const client = new TronGridClient(MAINNET)
+    await expect(
+      client.createTransaction({ from: 'a', to: 'b', amount: 1 })
+    ).rejects.toThrow(/bad address/)
+  })
+
+  it('createTrc20Transfer requires result.result and a transaction', async () => {
+    fetchMock = mockFetch([
+      {
+        result: { result: true },
+        transaction: { txID: 'def456', raw_data: {} }
+      }
+    ])
+    vi.stubGlobal('fetch', fetchMock)
+    const client = new TronGridClient(MAINNET)
+    const tx = await client.createTrc20Transfer({
+      from: 'TFrom',
+      to: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+      amount: 1_000_000,
+      contractAddress: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'
+    })
+    expect(tx.txID).toBe('def456')
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body)
+    expect(body.function_selector).toBe('transfer(address,uint256)')
+    expect(body.fee_limit).toBe(100_000_000)
+    expect(body.parameter).toHaveLength(128)
+  })
+
+  it('createTrc20Transfer throws a decoded message on a failed estimate', async () => {
+    // "REVERT" in hex ASCII.
+    fetchMock = mockFetch([
+      { result: { result: false, message: '524556455254' } }
+    ])
+    vi.stubGlobal('fetch', fetchMock)
+    const client = new TronGridClient(MAINNET)
+    await expect(
+      client.createTrc20Transfer({
+        from: 'a',
+        to: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
+        amount: 1,
+        contractAddress: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'
+      })
+    ).rejects.toThrow(/REVERT/)
+  })
+
+  it('broadcastTransaction returns the txid on result:true', async () => {
+    fetchMock = mockFetch([{ result: true, txid: 'tx789' }])
+    vi.stubGlobal('fetch', fetchMock)
+    const client = new TronGridClient(MAINNET)
+    const txid = await client.broadcastTransaction({ txID: 'tx789' })
+    expect(txid).toBe('tx789')
+  })
+
+  it('broadcastTransaction throws a decoded message on result:false', async () => {
+    fetchMock = mockFetch([
+      { result: false, message: '434f4e54524143545f56414c4944415445' }
+    ])
+    vi.stubGlobal('fetch', fetchMock)
+    const client = new TronGridClient(MAINNET)
+    await expect(client.broadcastTransaction({ txID: 'x' })).rejects.toThrow(
+      /CONTRACT_VALIDATE/
+    )
+  })
+
+  it('throws on a non-ok HTTP response', async () => {
+    fetchMock.mockResolvedValueOnce({
+      ok: false,
+      status: 503,
+      statusText: 'Service Unavailable',
+      json: async () => ({})
+    })
+    const client = new TronGridClient(MAINNET)
+    await expect(
+      client.createTransaction({ from: 'a', to: 'b', amount: 1 })
+    ).rejects.toThrow(/503/)
+  })
+})
+
+describe('decodeHexMessage', () => {
+  it('decodes even-length hex ASCII', () => {
+    expect(decodeHexMessage('524556455254')).toBe('REVERT')
+  })
+  it('passes through non-hex strings', () => {
+    expect(decodeHexMessage('already readable')).toBe('already readable')
+  })
+  it('does not mangle an all-hex word that decodes to non-printable bytes', () => {
+    // "deadbeef" is valid even-length hex but decodes to non-printable bytes.
+    expect(decodeHexMessage('deadbeef')).toBe('deadbeef')
+  })
+  it('passes through odd-length strings unchanged', () => {
+    expect(decodeHexMessage('abc')).toBe('abc')
+  })
+  it('returns empty string for undefined', () => {
+    expect(decodeHexMessage(undefined)).toBe('')
+  })
+})

package/src/rest/trongrid-client.ts

@@ -0,0 +1,205 @@
+import type { NetworkId, TronGridConfig } from '@meshconnect/uwc-types'
+import { encodeTrc20TransferParams, TRC20_TRANSFER_SELECTOR } from './abi'
+
+/**
+ * The minimal shape of an unsigned Tron transaction returned by
+ * `/wallet/createtransaction` and `/wallet/triggersmartcontract`.
+ *
+ * Only `txID` + `raw_data*` are load-bearing for sign/broadcast; the struct
+ * carries more fields that pass through opaquely. Typed loosely on purpose so
+ * a node-version change to the surrounding shape doesn't break the contract.
+ */
+export interface UnsignedTronTransaction {
+  txID?: string
+  raw_data?: unknown
+  raw_data_hex?: string
+  visible?: boolean
+  [key: string]: unknown
+}
+
+/** A transaction with the wallet's signature appended, ready to broadcast. */
+export interface SignedTronTransaction extends UnsignedTronTransaction {
+  signature?: string[]
+}
+
+/** Broadcast response from `/wallet/broadcasttransaction`. */
+interface BroadcastResponse {
+  result?: boolean
+  txid?: string
+  code?: string
+  message?: string
+  transaction?: { txID?: string }
+}
+
+const DEFAULT_ENDPOINTS: Partial<Record<NetworkId, string>> = {
+  'tron:0x2b6653dc': 'https://api.trongrid.io', // Mainnet
+  'tron:0x94a9059e': 'https://api.shasta.trongrid.io', // Shasta testnet
+  'tron:0xcd8690dc': 'https://nile.trongrid.io' // Nile testnet
+}
+
+const DEFAULT_FEE_LIMIT_SUN = 100_000_000 // 100 TRX
+
+/**
+ * Thin `fetch` wrapper over the three Tron full-node HTTP endpoints this
+ * connector needs. No SDK, no `tronweb` — the `/wallet/*` paths are the Tron
+ * full-node API standard, identical across TronGrid and any full node.
+ */
+export class TronGridClient {
+  private readonly baseUrl: string
+  private readonly apiKey: string | undefined
+  private readonly feeLimitSun: number
+
+  constructor(networkId: NetworkId, config: TronGridConfig = {}) {
+    const url = config.endpoints?.[networkId] ?? DEFAULT_ENDPOINTS[networkId]
+    if (!url) {
+      throw new Error(
+        `tron-connector: no full-node endpoint configured for network "${networkId}". ` +
+          `Pass one via TronConnectorConfig.tronGrid.endpoints.`
+      )
+    }
+    // Reject plaintext endpoints: we send the TRON-PRO-API-KEY header and the
+    // unsigned tx in the body, so an `http://` host would leak both. Allow
+    // loopback http for local dev nodes (e.g. a tron-quickstart container).
+    if (
+      /^http:\/\//i.test(url) &&
+      !/^http:\/\/(localhost|127\.0\.0\.1)/i.test(url)
+    ) {
+      throw new Error(
+        `tron-connector: refusing non-https endpoint "${url}" (would send the API key + tx in cleartext)`
+      )
+    }
+    // Normalise away trailing slashes so path concatenation is predictable.
+    // Done with a plain loop (no regex) to avoid any backtracking concern.
+    let base = url
+    while (base.endsWith('/')) base = base.slice(0, -1)
+    this.baseUrl = base
+    this.apiKey = config.apiKey
+
+    const feeLimit = config.feeLimitSun ?? DEFAULT_FEE_LIMIT_SUN
+    if (!Number.isInteger(feeLimit) || feeLimit <= 0) {
+      throw new Error(
+        `tron-connector: feeLimitSun must be a positive integer (SUN), got ${feeLimit}`
+      )
+    }
+    this.feeLimitSun = feeLimit
+  }
+
+  /** Build an unsigned native TRX transfer. Amounts are in SUN. */
+  async createTransaction(params: {
+    from: string
+    to: string
+    amount: number
+  }): Promise<UnsignedTronTransaction> {
+    const tx = await this.post<UnsignedTronTransaction & { Error?: string }>(
+      '/wallet/createtransaction',
+      {
+        owner_address: params.from,
+        to_address: params.to,
+        amount: params.amount,
+        visible: true
+      }
+    )
+    if (tx.Error) {
+      throw new Error(`tron-connector: createtransaction failed — ${tx.Error}`)
+    }
+    if (!tx.txID) {
+      throw new Error('tron-connector: createtransaction returned no txID')
+    }
+    return tx
+  }
+
+  /** Build an unsigned TRC20 `transfer(address,uint256)` transaction. */
+  async createTrc20Transfer(params: {
+    from: string
+    to: string
+    amount: number
+    contractAddress: string
+  }): Promise<UnsignedTronTransaction> {
+    const response = await this.post<{
+      result?: { result?: boolean; code?: string; message?: string }
+      transaction?: UnsignedTronTransaction
+    }>('/wallet/triggersmartcontract', {
+      owner_address: params.from,
+      contract_address: params.contractAddress,
+      function_selector: TRC20_TRANSFER_SELECTOR,
+      parameter: encodeTrc20TransferParams(params.to, params.amount),
+      fee_limit: this.feeLimitSun,
+      call_value: 0,
+      visible: true
+    })
+    if (!response.result?.result || !response.transaction?.txID) {
+      throw new Error(
+        `tron-connector: triggersmartcontract failed — ${
+          decodeHexMessage(response.result?.message) ||
+          response.result?.code ||
+          'unknown error'
+        }`
+      )
+    }
+    return response.transaction
+  }
+
+  /** Broadcast a signed transaction. Returns the on-chain txid. */
+  async broadcastTransaction(signed: SignedTronTransaction): Promise<string> {
+    const response = await this.post<BroadcastResponse>(
+      '/wallet/broadcasttransaction',
+      signed
+    )
+    // The node returns `{ result: false, message: <hex> }` on rejection even
+    // when a txid is echoed back — treat anything other than `result: true` as
+    // failure.
+    if (response.result !== true) {
+      throw new Error(
+        decodeHexMessage(response.message) ||
+          response.code ||
+          'tron-connector: broadcast rejected by node'
+      )
+    }
+    const txid = response.txid ?? response.transaction?.txID ?? signed.txID
+    if (!txid) {
+      throw new Error('tron-connector: broadcast returned no txid')
+    }
+    return txid
+  }
+
+  private async post<T>(path: string, body: unknown): Promise<T> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json'
+    }
+    if (this.apiKey) headers['TRON-PRO-API-KEY'] = this.apiKey
+
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body)
+    })
+    if (!response.ok) {
+      throw new Error(
+        `tron-connector: ${path} responded ${response.status} ${response.statusText}`
+      )
+    }
+    return (await response.json()) as T
+  }
+}
+
+/**
+ * Full nodes often return `message` as hex-encoded ASCII
+ * (e.g. `"434f4e54524143545f56414c4944415445..."`). Decode when it looks like
+ * hex AND the result is printable ASCII; otherwise pass the string through
+ * unchanged. The printable check avoids mangling a message that happens to be
+ * an all-hex, even-length word (e.g. `"deadbeef"`), which would decode to
+ * non-printable bytes.
+ */
+export function decodeHexMessage(message: string | undefined): string {
+  if (!message) return ''
+  if (!/^[0-9a-fA-F]+$/.test(message) || message.length % 2 !== 0) {
+    return message
+  }
+  let decoded = ''
+  for (let i = 0; i < message.length; i += 2) {
+    decoded += String.fromCharCode(parseInt(message.slice(i, i + 2), 16))
+  }
+  // Printable ASCII (incl. common whitespace) → it was hex-encoded text.
+  // Anything else → the input was more likely a literal string; keep it.
+  return /^[\x20-\x7e\t\n\r]*$/.test(decoded) ? decoded : message
+}

package/src/shared/error-utils.ts

@@ -0,0 +1,60 @@
+import type { WalletError } from '@meshconnect/uwc-types'
+import { WalletConnectorError } from '@meshconnect/uwc-types'
+
+const REJECTION_PATTERNS = [
+  'user rejected',
+  'user denied',
+  'user cancelled',
+  'user canceled',
+  'rejected by user',
+  'denied by user',
+  'cancelled by user',
+  'canceled by user',
+  'user disapproved',
+  'user declined',
+  'action_rejected',
+  'reject request',
+  'user rejects',
+  'wallet rejected',
+  'confirmation declined'
+]
+
+/**
+ * Translate an unknown error (from a wallet `request`/`sign` call or a node
+ * response) into a `WalletConnectorError`. User-rejection signals are tagged
+ * `type: 'rejected'`; everything else is `type: 'unknown'`.
+ *
+ * Throws — never returns.
+ */
+export function parseError(error: unknown): never {
+  if (error instanceof WalletConnectorError) throw error
+
+  let message = ''
+  let isRejected = false
+
+  if (error && typeof error === 'object') {
+    const errObj = error as {
+      code?: number | string
+      message?: string
+      error?: { message?: string }
+    }
+    // 4001 is the de-facto user-rejected code across injected wallets.
+    if (errObj.code === 4001 || errObj.code === 'ACTION_REJECTED') {
+      isRejected = true
+    }
+    message = errObj.message ?? errObj.error?.message ?? String(error)
+  } else {
+    message = String(error)
+  }
+
+  if (!isRejected) {
+    const lower = message.toLowerCase()
+    isRejected = REJECTION_PATTERNS.some(pattern => lower.includes(pattern))
+  }
+
+  const walletError: WalletError = {
+    type: isRejected ? 'rejected' : 'unknown',
+    message
+  }
+  throw new WalletConnectorError(walletError)
+}