@multiplatform.one/web3 8.3.0 → 8.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/web3",
-  "version": "8.3.0",
+  "version": "8.4.0",
   "description": "Web3 wallet integration for multiplatform.one ecosystem with ConnectKit and wagmi",
   "keywords": [
     "connectkit",
@@ -105,6 +105,12 @@
       "import": "./dist/esm/solana.mjs",
       "require": "./dist/cjs/solana.cjs"
     },
+    "./tron": {
+      "source": "./src/tron.ts",
+      "types": "./types/tron.d.ts",
+      "import": "./dist/esm/tron.mjs",
+      "require": "./dist/cjs/tron.cjs"
+    },
     "./phantom": {
       "source": "./src/phantom/index.ts",
       "types": "./types/phantom/index.d.ts",
@@ -120,10 +126,10 @@
     "@aave/account": "^0.2.1",
     "@coinbase/wallet-sdk": "^4.4.0",
     "@metamask/connect-evm": "^2.1.1",
-    "@multiplatform.one/connectkit": "^8.3.0",
-    "@multiplatform.one/gpg": "^8.3.0",
-    "@multiplatform.one/platform": "^8.3.0",
-    "@multiplatform.one/theme": "^8.3.0",
+    "@multiplatform.one/connectkit": "^8.4.0",
+    "@multiplatform.one/gpg": "^8.4.0",
+    "@multiplatform.one/platform": "^8.4.0",
+    "@multiplatform.one/theme": "^8.4.0",
     "@noble/ciphers": "^1.3.0",
     "@noble/curves": "^1.9.7",
     "@phosphor-icons/react": "^2.1.10",
@@ -147,8 +153,8 @@
     "wagmi": "^3.7.1"
   },
   "devDependencies": {
-    "@multiplatform.one/config": "8.3.0",
-    "@multiplatform.one/test-utils": "8.3.0",
+    "@multiplatform.one/config": "8.4.0",
+    "@multiplatform.one/test-utils": "8.4.0",
     "@tamagui/build": "2.7.6",
     "@tanstack/react-query": "^5.104.3",
     "@testing-library/jest-dom": "^7.0.1",

package/src/clients/tron.spec.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  isTronAddress,
+  readTrc20Balance,
+  toTronBase58,
+  toTronHex,
+  tronClient,
+  TronGridError,
+} from "./tron";
+
+const usdt = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t";
+const usdtHex = "41a614f803b6fd780986a42c78ec9c7f77e6ded13c";
+const holder = "TKHuVq1oKVruCGLvqVexFs6dawKv6fQgFs";
+
+function answering(body: unknown, status = 200) {
+  return vi.fn(async (_url: string | URL | Request, _init?: RequestInit) => {
+    return new Response(JSON.stringify(body), { status });
+  });
+}
+
+describe("Tron addresses", () => {
+  it("converts between base58, 41 hex and bare 20-byte hex", () => {
+    expect(toTronHex(usdt)).toBe(usdtHex);
+    expect(toTronBase58(usdtHex)).toBe(usdt);
+    expect(toTronBase58(`0x${usdtHex.slice(2)}`)).toBe(usdt);
+    expect(toTronBase58("0x52842189638234da1c683e278d4a07d7ea76fcbb")).toBe(
+      "THVWhQra6ziciHXtxzdzUKt2fzCPEvLM4F",
+    );
+  });
+
+  it("refuses a bad checksum, a wrong version byte and a wrong length", () => {
+    expect(() => toTronHex(`${usdt.slice(0, -1)}u`)).toThrow(/checksum|not a Tron/);
+    expect(isTronAddress("1BoatSLRHtKNngkdXEeobR76b53LETtpyT")).toBe(false);
+    expect(isTronAddress("0x1234")).toBe(false);
+    expect(isTronAddress("not an address")).toBe(false);
+    expect(isTronAddress(usdt)).toBe(true);
+  });
+});
+
+describe("readTrc20Balance", () => {
+  it("posts balanceOf(owner) to TronGrid and reads the word back", async () => {
+    const fetch = answering({
+      result: { result: true },
+      constant_result: [`${"0".repeat(56)}0001e240`],
+    });
+    const balance = await readTrc20Balance({ token: usdt, owner: holder, network: "nile", fetch });
+    expect(balance).toBe(123456n);
+    const [url, init] = fetch.mock.calls[0];
+    expect(url).toBe("https://nile.trongrid.io/wallet/triggerconstantcontract");
+    expect(init?.method).toBe("POST");
+    const body = JSON.parse(String(init?.body));
+    expect(body).toEqual({
+      owner_address: holder,
+      contract_address: usdt,
+      function_selector: "balanceOf(address)",
+      parameter: `${"0".repeat(24)}${toTronHex(holder).slice(2)}`,
+      visible: true,
+    });
+    expect(init?.headers).not.toHaveProperty("TRON-PRO-API-KEY");
+  });
+
+  it("defaults to mainnet, takes an API key and an API URL of the app's own", async () => {
+    const fetch = answering({ result: { result: true }, constant_result: [""] });
+    await expect(
+      readTrc20Balance({ token: usdt, owner: holder, fetch, apiKey: "k" }),
+    ).resolves.toBe(0n);
+    expect(fetch.mock.calls[0][0]).toBe("https://api.trongrid.io/wallet/triggerconstantcontract");
+    expect(fetch.mock.calls[0][1]?.headers).toHaveProperty("TRON-PRO-API-KEY", "k");
+    await readTrc20Balance({ token: usdt, owner: holder, fetch, apiUrl: "https://node.example/" });
+    expect(fetch.mock.calls[1][0]).toBe("https://node.example/wallet/triggerconstantcontract");
+  });
+
+  it("names TronGrid's reason when the call fails", async () => {
+    const reason = Buffer.from("REVERT opcode executed").toString("hex");
+    const fetch = answering({ result: { code: "CONTRACT_EXE_ERROR", message: reason } });
+    await expect(readTrc20Balance({ token: usdt, owner: holder, fetch })).rejects.toThrow(
+      "TronGrid balanceOf failed: REVERT opcode executed",
+    );
+  });
+
+  it("rejects on an HTTP error with its status", async () => {
+    const fetch = answering({}, 429);
+    const failure = readTrc20Balance({ token: usdt, owner: holder, fetch });
+    await expect(failure).rejects.toBeInstanceOf(TronGridError);
+    await expect(failure).rejects.toMatchObject({ status: 429 });
+  });
+
+  it("refuses a malformed owner before any request", async () => {
+    const fetch = answering({});
+    await expect(readTrc20Balance({ token: usdt, owner: "nope", fetch })).rejects.toThrow(
+      /not a Tron address/,
+    );
+    expect(fetch).not.toHaveBeenCalled();
+  });
+});
+
+describe("tronClient", () => {
+  it("signs through the adapter and reads the connected account's balance on its network", async () => {
+    const signMessage = vi.fn(async () => "0xsig");
+    const fetch = answering({ result: { result: true }, constant_result: ["0a"] });
+    const client = tronClient({ address: holder, signMessage }, { network: "nile", fetch });
+    expect(client).toMatchObject({
+      family: "tron",
+      address: holder,
+      chainId: "tron",
+      network: "nile",
+      capabilities: ["signMessage"],
+    });
+    await expect(client.signMessage("hi")).resolves.toBe("0xsig");
+    await expect(client.trc20Balance(usdt)).resolves.toBe(10n);
+    expect(JSON.parse(String(fetch.mock.calls[0][1]?.body)).owner_address).toBe(holder);
+    expect(fetch.mock.calls[0][0]).toContain("nile.trongrid.io");
+  });
+
+  it("needs a connected adapter", () => {
+    expect(() => tronClient({ address: null, signMessage: vi.fn() })).toThrow(/connect a Tron/);
+  });
+});

package/src/clients/tron.ts

@@ -0,0 +1,186 @@
+import bs58 from "bs58";
+import { bytesToHex, hexToBytes, hexToString, sha256 } from "viem";
+import type { WalletAdapter } from "../connectkit/adapters/types";
+import type { ChainClient, ClientCapability } from "./types";
+
+/** The Tron networks TronGrid serves. */
+export type TronNetwork = "mainnet" | "nile" | "shasta";
+
+/** TronGrid's HTTP API per network. */
+export const tronGridUrls: Readonly<Record<TronNetwork, string>> = Object.freeze({
+  mainnet: "https://api.trongrid.io",
+  nile: "https://nile.trongrid.io",
+  shasta: "https://api.shasta.trongrid.io",
+});
+
+const tronPrefix = 0x41;
+
+const checksumOf = (payload: Uint8Array) => sha256(sha256(payload, "bytes"), "bytes").slice(0, 4);
+
+/**
+ * A Tron address as its 21 bytes, version byte 0x41 first. Takes base58
+ * (`T…`), 41-prefixed hex, or a bare 20-byte EVM-style hex. Throws on a bad
+ * checksum or length.
+ */
+export function tronAddressBytes(address: string): Uint8Array {
+  const value = address.trim();
+  if (/^(0x)?[0-9a-fA-F]+$/.test(value)) {
+    const bytes = hexToBytes(value.startsWith("0x") ? (value as `0x${string}`) : `0x${value}`);
+    if (bytes.length === 20) return Uint8Array.of(tronPrefix, ...bytes);
+    if (bytes.length === 21 && bytes[0] === tronPrefix) return bytes;
+    throw new Error(`not a Tron address: ${address}`);
+  }
+  let decoded: Uint8Array;
+  try {
+    decoded = bs58.decode(value);
+  } catch {
+    throw new Error(`not a Tron address: ${address}`);
+  }
+  if (decoded.length !== 25 || decoded[0] !== tronPrefix) {
+    throw new Error(`not a Tron address: ${address}`);
+  }
+  const payload = decoded.slice(0, 21);
+  const checksum = checksumOf(payload);
+  if (!checksum.every((byte, index) => byte === decoded[21 + index])) {
+    throw new Error(`Tron address checksum mismatch: ${address}`);
+  }
+  return payload;
+}
+
+/** The base58 form TronLink shows (`T…`), from any form tronAddressBytes takes. */
+export function toTronBase58(address: string): string {
+  const payload = tronAddressBytes(address);
+  return bs58.encode(Uint8Array.of(...payload, ...checksumOf(payload)));
+}
+
+/** The 41-prefixed hex form TronGrid takes when `visible` is false. */
+export function toTronHex(address: string): string {
+  return bytesToHex(tronAddressBytes(address)).slice(2);
+}
+
+/** Whether `address` is a well-formed Tron address in any form tronAddressBytes takes. */
+export function isTronAddress(address: string): boolean {
+  try {
+    tronAddressBytes(address);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Where a TronGrid read goes: a network, or an API URL of the app's own. */
+export interface TronGridOptions {
+  /** Defaults to `mainnet`. Ignored when `apiUrl` is given. */
+  network?: TronNetwork;
+  /** A TronGrid-compatible full node, in place of the network's TronGrid URL. */
+  apiUrl?: string;
+  /** Sent as `TRON-PRO-API-KEY`. TronGrid serves keyless reads at a lower rate. */
+  apiKey?: string;
+  fetch?: typeof fetch;
+  signal?: AbortSignal;
+}
+
+export interface Trc20BalanceParameters extends TronGridOptions {
+  /** The TRC-20 contract. */
+  token: string;
+  /** The account whose balance is read. */
+  owner: string;
+}
+
+/** A TronGrid call that answered without a result. */
+export class TronGridError extends Error {
+  readonly status?: number;
+  constructor(message: string, status?: number) {
+    super(message);
+    this.name = "TronGridError";
+    this.status = status;
+  }
+}
+
+function decodeMessage(message: string | undefined): string | undefined {
+  if (!message) return undefined;
+  if (!/^[0-9a-fA-F]+$/.test(message) || message.length % 2) return message;
+  try {
+    return hexToString(`0x${message}`);
+  } catch {
+    return message;
+  }
+}
+
+/**
+ * A TRC-20 `balanceOf(owner)` in the token's smallest unit, read through
+ * TronGrid's `triggerconstantcontract`. No wallet and no tronweb: one POST.
+ */
+export async function readTrc20Balance(parameters: Trc20BalanceParameters): Promise<bigint> {
+  const { token, owner, network = "mainnet", apiUrl, apiKey, signal } = parameters;
+  const request = parameters.fetch ?? globalThis.fetch;
+  const ownerBytes = tronAddressBytes(owner);
+  const base = (apiUrl ?? tronGridUrls[network]).replace(/\/+$/, "");
+  const response = await request(`${base}/wallet/triggerconstantcontract`, {
+    method: "POST",
+    headers: {
+      accept: "application/json",
+      "content-type": "application/json",
+      ...(apiKey ? { "TRON-PRO-API-KEY": apiKey } : {}),
+    },
+    body: JSON.stringify({
+      owner_address: toTronBase58(owner),
+      contract_address: toTronBase58(token),
+      function_selector: "balanceOf(address)",
+      parameter: bytesToHex(ownerBytes.slice(1)).slice(2).padStart(64, "0"),
+      visible: true,
+    }),
+    ...(signal ? { signal } : {}),
+  });
+  if (!response.ok) {
+    throw new TronGridError(`TronGrid answered ${response.status} for balanceOf`, response.status);
+  }
+  const body = (await response.json()) as {
+    result?: { result?: boolean; code?: string; message?: string };
+    constant_result?: string[];
+    Error?: string;
+  };
+  const word = body.constant_result?.[0];
+  if (!body.result?.result || word === undefined) {
+    const reason = decodeMessage(body.result?.message) ?? body.Error ?? body.result?.code;
+    throw new TronGridError(`TronGrid balanceOf failed${reason ? `: ${reason}` : ""}`);
+  }
+  return word === "" ? 0n : BigInt(`0x${word}`);
+}
+
+type MessageAdapter = Pick<WalletAdapter, "address" | "signMessage">;
+
+export interface TronClientOptions extends Omit<TronGridOptions, "signal"> {}
+
+/**
+ * The connected Tron wallet: message signing through TronLink and TRC-20
+ * reads through TronGrid on the wallet's network.
+ */
+export interface TronClient extends ChainClient<"tron"> {
+  readonly address: string;
+  readonly chainId: "tron";
+  /** The network TronLink's node is on, which `trc20Balance` reads. */
+  readonly network: TronNetwork;
+  /** TronLink's `signMessageV2`, 0x hex. */
+  signMessage(message: string): Promise<string>;
+  /** A TRC-20 balance in the token's smallest unit, for the connected account unless `owner` is given. */
+  trc20Balance(token: string, owner?: string, signal?: AbortSignal): Promise<bigint>;
+}
+
+const capabilities: readonly ClientCapability[] = ["signMessage"];
+
+export function tronClient(adapter: MessageAdapter, options: TronClientOptions = {}): TronClient {
+  if (!adapter.address) throw new Error("tronClient: connect a Tron wallet first");
+  const address = adapter.address;
+  const network = options.network ?? "mainnet";
+  return {
+    family: "tron",
+    address,
+    chainId: "tron",
+    network,
+    capabilities,
+    signMessage: (message) => adapter.signMessage(message),
+    trc20Balance: (token, owner = address, signal) =>
+      readTrc20Balance({ ...options, network, token, owner, ...(signal ? { signal } : {}) }),
+  };
+}

package/src/clients/useTronClient.ts

@@ -0,0 +1,26 @@
+import { useMemo } from "react";
+import { useAccount } from "wagmi";
+import { connectorAdapter } from "./adapter";
+import { useOptionalConnection } from "../core/react";
+import { TronAdapter } from "../connectkit/adapters/TronAdapter";
+import { tronClient, type TronClient } from "./tron";
+
+/**
+ * The connected TronLink wallet: the connection store's client when one is
+ * mounted, else wagmi's shim connector's. Undefined while no Tron wallet
+ * holds the connection.
+ */
+export function useTronClient(): TronClient | undefined {
+  const connection = useOptionalConnection();
+  const { connector, address } = useAccount();
+  return useMemo(() => {
+    if (connection) {
+      return connection.family === "tron"
+        ? ((connection.client as TronClient | null) ?? undefined)
+        : undefined;
+    }
+    const adapter = connectorAdapter(connector, "tron");
+    if (!adapter?.address) return undefined;
+    return tronClient(adapter, adapter instanceof TronAdapter ? { network: adapter.network } : {});
+  }, [connection, connector, address]);
+}

package/src/connectkit/adapters/TronAdapter.spec.ts

@@ -0,0 +1,155 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { discoverTronWallets, hasTronWallet, TronAdapter, tronNetworkOf } from "./TronAdapter";
+
+const address = "TKHuVq1oKVruCGLvqVexFs6dawKv6fQgFs";
+const globals: string[] = [];
+const install = (name: string, value: unknown) => {
+  globals.push(name);
+  (window as unknown as Record<string, unknown>)[name] = value;
+};
+
+afterEach(() => {
+  for (const name of globals.splice(0)) Reflect.deleteProperty(window, name);
+});
+
+function tronWeb(host = "https://api.trongrid.io") {
+  return {
+    ready: true,
+    defaultAddress: { base58: false as string | false },
+    fullNode: { host },
+    trx: { signMessageV2: vi.fn(async (message: string) => `0xsigned:${message}`) },
+  };
+}
+
+function tronLink(answer: unknown = { code: 200, message: "ok" }, host?: string) {
+  const web = tronWeb(host);
+  const link = {
+    ready: true,
+    tronWeb: web,
+    request: vi.fn(async () => {
+      if (answer && typeof answer === "object" && (answer as { code?: number }).code === 200) {
+        web.defaultAddress.base58 = address;
+      }
+      return answer;
+    }),
+  };
+  install("tronLink", link);
+  install("tronWeb", web);
+  return { link, web };
+}
+
+describe("discoverTronWallets", () => {
+  it("lists TronLink only when it is injected", () => {
+    expect(hasTronWallet()).toBe(false);
+    expect(discoverTronWallets()).toEqual([]);
+    tronLink();
+    const [entry] = discoverTronWallets();
+    expect(entry).toMatchObject({
+      id: "wallet:tron:tronlink",
+      name: "TronLink",
+      ecosystem: "tron",
+    });
+    expect(entry.adapter).toBeInstanceOf(TronAdapter);
+  });
+});
+
+describe("TronAdapter", () => {
+  it("connects through tron_requestAccounts and takes tronWeb's base58 account", async () => {
+    const { link } = tronLink();
+    const adapter = new TronAdapter();
+    await adapter.connect();
+    expect(link.request).toHaveBeenCalledWith({ method: "tron_requestAccounts" });
+    expect(adapter.address).toBe(address);
+    expect(adapter.isConnected).toBe(true);
+    expect(adapter.networkId).toBe("tron:mainnet");
+  });
+
+  it("reports the network TronLink's node is on", () => {
+    tronLink(undefined, "https://nile.trongrid.io");
+    expect(new TronAdapter().network).toBe("nile");
+    expect(tronNetworkOf("https://api.shasta.trongrid.io")).toBe("shasta");
+    expect(tronNetworkOf(undefined)).toBe("mainnet");
+  });
+
+  it("rejects when TronLink is locked, refuses, or is missing", async () => {
+    tronLink("");
+    await expect(new TronAdapter().connect()).rejects.toThrow(/locked/);
+    for (const name of globals.splice(0)) Reflect.deleteProperty(window, name);
+    tronLink({ code: 4001, message: "User rejected" });
+    await expect(new TronAdapter().connect()).rejects.toThrow("User rejected");
+    for (const name of globals.splice(0)) Reflect.deleteProperty(window, name);
+    await expect(new TronAdapter().connect()).rejects.toThrow(/Install TronLink/);
+  });
+
+  it("connects through the TIP-1193 provider when TronLink exposes window.tron", async () => {
+    const web = tronWeb();
+    const listeners = new Set<(accounts: string[]) => void>();
+    const provider = {
+      tronWeb: web,
+      request: vi.fn(async () => {
+        web.defaultAddress.base58 = address;
+        return [address];
+      }),
+      on: (_event: string, listener: (accounts: string[]) => void) => listeners.add(listener),
+      removeListener: (_event: string, listener: (accounts: string[]) => void) =>
+        listeners.delete(listener),
+    };
+    install("tron", provider);
+    const adapter = new TronAdapter();
+    await adapter.connect();
+    expect(provider.request).toHaveBeenCalledWith({ method: "eth_requestAccounts" });
+    const changed = vi.fn();
+    const unsubscribe = adapter.subscribe(changed);
+    web.defaultAddress.base58 = false;
+    for (const listener of listeners) listener([]);
+    expect(changed).toHaveBeenCalledTimes(1);
+    expect(adapter.address).toBeNull();
+    unsubscribe();
+    expect(listeners.size).toBe(0);
+  });
+
+  it("restores the account TronLink already shares, and says false when it shares none", async () => {
+    const { web } = tronLink();
+    const adapter = new TronAdapter();
+    await expect(adapter.restore()).resolves.toBe(false);
+    web.defaultAddress.base58 = address;
+    await expect(adapter.restore()).resolves.toBe(true);
+    expect(adapter.address).toBe(address);
+    for (const name of globals.splice(0)) Reflect.deleteProperty(window, name);
+    await expect(new TronAdapter().restore()).rejects.toThrow(/not.*yet|yet/);
+  });
+
+  it("follows TronLink's account messages", async () => {
+    const { web } = tronLink();
+    const adapter = new TronAdapter();
+    await adapter.connect();
+    const changed = vi.fn();
+    const unsubscribe = adapter.subscribe(changed);
+    web.defaultAddress.base58 = "TJCo98saj6WND61g1uuKwJ9GMWMT9WkJFo";
+    window.dispatchEvent(
+      new MessageEvent("message", { data: { message: { action: "accountsChanged" } } }),
+    );
+    expect(changed).toHaveBeenCalledTimes(1);
+    expect(adapter.address).toBe("TJCo98saj6WND61g1uuKwJ9GMWMT9WkJFo");
+    window.dispatchEvent(new MessageEvent("message", { data: { message: { action: "other" } } }));
+    expect(changed).toHaveBeenCalledTimes(1);
+    unsubscribe();
+    window.dispatchEvent(
+      new MessageEvent("message", { data: { message: { action: "disconnect" } } }),
+    );
+    expect(changed).toHaveBeenCalledTimes(1);
+  });
+
+  it("signs with signMessageV2 once connected, and builds no sign-in message", async () => {
+    const { web } = tronLink();
+    const adapter = new TronAdapter();
+    await expect(adapter.signMessage("hi")).rejects.toThrow(/connect a Tron wallet/);
+    await adapter.connect();
+    await expect(adapter.signMessage("hi")).resolves.toBe("0xsigned:hi");
+    expect(web.trx.signMessageV2).toHaveBeenCalledWith("hi");
+    await expect(adapter.buildMessage({ nonce: "n" })).rejects.toThrow(/not supported yet/);
+    await adapter.disconnect();
+    expect(adapter.address).toBeNull();
+  });
+});