clutch-hub-sdk-js 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [4.4.0](https://github.com/clutchprotocol/clutch-hub/compare/v4.3.0...v4.4.0) (2026-10-06)
+
+
+### Features
+
+* **sdk:** sign with TronLink (signMessageV2, TIP-191), and the demo app connects it ([#32](https://github.com/clutchprotocol/clutch-hub/issues/32)) ([57fdd06](https://github.com/clutchprotocol/clutch-hub/commit/57fdd06297ff0b1f434d4b27d4941777772baeec))
+
 ## [4.3.0](https://github.com/clutchprotocol/clutch-hub/compare/v4.2.1...v4.3.0) (2026-10-06)
 
 

package/README.md

@@ -41,14 +41,14 @@ await sdk.submitTransaction(signed.rawTransaction);
 
 Hash arguments (`listRideOffers`, `subscribeRideOffers`) accept the `0x`-prefixed form that `signTransaction` returns; the SDK normalizes them to the form the hub matches on.
 
-## Wallets: MetaMask, Trust Wallet
+## Wallets: MetaMask, Trust Wallet, TronLink
 
-A wallet keeps the key and signs a short text with `personal_sign`. Use a signer where you used a key:
+A wallet keeps the key and signs a short text. MetaMask and Trust Wallet sign it with `personal_sign` (EIP-191). TronLink signs it with `signMessageV2` (TIP-191), which is the same with the prefix `\x19TRON Signed Message:\n`. A TronLink account is the same kind of key as a Clutch account, so its `T…` address is the Clutch address `0x…` of the same key. Use a signer where you used a key:
 
 ```javascript
 import { ClutchHubSdk, discoverInjectedWallets, connectWallet } from 'clutch-hub-sdk-js';
 
-const [wallet] = await discoverInjectedWallets();   // EIP-6963, then window.ethereum
+const [wallet] = await discoverInjectedWallets();   // EIP-6963 and TIP-6963 (TronLink), then window.ethereum / window.tron
 const signer = await connectWallet(wallet);          // the wallet asks the user to share an account
 
 const sdk = new ClutchHubSdk('http://localhost:3000', signer.address, signer, 2077);
@@ -56,11 +56,11 @@ const sdk = new ClutchHubSdk('http://localhost:3000', signer.address, signer, 20
 const signed = await sdk.signTransaction(unsigned, signer, { type: 'RideRequest', fare: 5_000_000n });
 ```
 
-Each `signTransaction` and each login opens a prompt in the wallet. The text the wallet shows is `clutch-tx:{chainId}:{hash}` for a transaction and `clutch-auth:{chainId}:{address}:{timestamp}` for the login. The node and the Hub API accept this signature next to the signature of a private key. `createWalletSigner(provider, address)` builds a signer for a provider you already have, and `createLocalSigner(privateKey)` wraps a key. A user who says no in the wallet gives a rejection with `code: 4001`.
+Each `signTransaction` and each login opens a prompt in the wallet. The text the wallet shows is `clutch-tx:{chainId}:{hash}` for a transaction and `clutch-auth:{chainId}:{address}:{timestamp}` for the login. The node and the Hub API accept this signature next to the signature of a private key. `wallet.kind` is `'evm'` (MetaMask, Trust Wallet) or `'tron'` (TronLink), and `connectWallet`, `createSignerFor(wallet, account)`, `sharedWalletAccount(wallet)` (the account a wallet already shares, with no prompt) and `watchWalletAccounts(wallet, listener)` work for both. `createWalletSigner(provider, address)` and `createTronLinkSigner(provider, address)` build a signer for a provider you already have, and `createLocalSigner(privateKey)` wraps a key. A user who says no in a wallet gives a rejection (MetaMask and Trust Wallet: `code: 4001`; TronLink: an error with the message `user rejected request`).
 
 ## Features
 
-- Client-side signing (private keys never sent to server), or a wallet that keeps the key (MetaMask, Trust Wallet)
+- Client-side signing (private keys never sent to server), or a wallet that keeps the key (MetaMask, Trust Wallet, TronLink)
 - Full ride lifecycle: request, offer, accept, pay, cancel
 - GraphQL queries and WebSocket subscriptions
 - TypeScript types
@@ -70,7 +70,7 @@ Each `signTransaction` and each login opens a prompt in the wallet. The text the
 | Category | Methods |
 |----------|---------|
 | Auth | Auto `generateToken` via `ensureAuth()` (signed challenge; needs a private key or a signer), `setPrivateKey`, `setSigner`, `signAuthChallenge` |
-| Signers | `createLocalSigner`, `createWalletSigner`, `discoverInjectedWallets`, `connectWallet`, `addressFromPrivateKey` |
+| Signers | `createLocalSigner`, `createWalletSigner`, `createTronLinkSigner`, `createSignerFor`, `discoverInjectedWallets`, `connectWallet`, `sharedWalletAccount`, `watchWalletAccounts`, `tronAddressToHex`, `addressFromPrivateKey` |
 | Write | `createUnsignedRide*`, `signTransaction`, `submitTransaction` |
 | Read | `listRideRequests`, `listRideOffers`, `listActiveTrips`, `getAccountBalance`, … |
 | Live | `subscribeRideRequests`, `subscribeRideOffers`, `subscribeActiveTrips`, … |

package/dist/signers.d.ts

@@ -44,6 +44,8 @@ export interface Eip1193Provider {
 export declare function walletTransactionText(chainId: number, hashHex: string): string;
 /** What `personal_sign` hashes and signs: `Keccak256("\x19Ethereum Signed Message:\n" + length + text)`. */
 export declare function personalSignDigest(text: string): Uint8Array;
+/** What TronLink's `signMessageV2` (TIP-191) hashes and signs: `Keccak256("\x19TRON Signed Message:\n" + length + text)`. */
+export declare function tronSignDigest(text: string): Uint8Array;
 /**
  * A signer that asks a wallet to sign with `personal_sign`. The wallet shows the user the text,
  * and keeps the key. `address` is the account to sign for; it is lowercased, because the hash of a
@@ -54,28 +56,75 @@ export declare function personalSignDigest(text: string): Uint8Array;
  * that does not say why.
  */
 export declare function createWalletSigner(provider: Eip1193Provider, address: string): Signer;
+/**
+ * A TRON address as the Clutch address of the same key: `0x` and 40 lowercase hex characters.
+ *
+ * A TRON account is an Ethereum-type key (the same curve, the same Keccak-256, the same 20 address
+ * bytes). TRON writes those bytes in base58 (`T…`): `0x41`, the 20 bytes, and 4 bytes of checksum,
+ * and the checksum is checked here. A `0x` address and the `41…` hex form are accepted as they are.
+ */
+export declare function tronAddressToHex(address: string): string;
+/** The part of the `tronWeb` that TronLink puts on its provider that the SDK uses. */
+export interface TronWebLike {
+    ready?: boolean;
+    defaultAddress?: {
+        base58?: string | false;
+    };
+    trx?: {
+        signMessageV2?(message: string): Promise<unknown>;
+    };
+}
+/**
+ * TronLink's provider (`window.tron`, or the one it announces with TIP-6963): EIP-1193 plus a
+ * `tronWeb`, which is `false` until the person lets this site use TronLink.
+ */
+export interface TronLinkProvider extends Eip1193Provider {
+    tronWeb?: TronWebLike | false;
+}
+/**
+ * A signer that asks TronLink to sign with `signMessageV2` (TIP-191). TronLink shows the person the
+ * text and keeps the key. `address` is the account to sign for (a `0x` address, or the base58 one
+ * TronLink shows). It is checked the same way `createWalletSigner` checks: the signature is
+ * recovered here, and one from another account is refused before it leaves the SDK.
+ *
+ * TronLink's documentation is not clear on what `signMessageV2` takes: one page says a hex string
+ * and another says plain text or hex. So the text goes in plain first. A TronLink that takes only
+ * hex answers "Invalid transaction provided" before it opens a prompt, and then the text goes in
+ * again as `0x` hex of its UTF-8 bytes. Any other answer ends the call, because a second try would
+ * open a second prompt.
+ */
+export declare function createTronLinkSigner(provider: TronLinkProvider, address: string): Signer;
 /** A wallet found in the page. */
 export interface InjectedWallet {
-    /** The EIP-6963 `rdns` (for example `io.metamask`), or `injected-0` for a bare `window.ethereum`. */
+    /** The EIP-6963 or TIP-6963 `rdns` (for example `io.metamask`), or `injected-0` for a bare `window.ethereum`. */
     id: string;
     name: string;
     /** A `data:` image address from the wallet, when it announced one. */
     icon?: string;
+    /**
+     * `evm` (MetaMask, Trust Wallet: signs with `personal_sign`) or `tron` (TronLink: signs with
+     * `signMessageV2`). Default `evm`.
+     */
+    kind?: 'evm' | 'tron';
+    /** For a `tron` wallet this is a {@link TronLinkProvider}. */
     provider: Eip1193Provider;
 }
 export interface WalletDiscoveryOptions {
     /** Where to look. Default: `window`. */
     host?: EventTarget & {
         ethereum?: unknown;
+        tron?: unknown;
+        tronLink?: unknown;
     };
-    /** How long to listen for EIP-6963 announcements, in milliseconds. Default: 300. */
+    /** How long to listen for EIP-6963 and TIP-6963 announcements, in milliseconds. Default: 300. */
     timeoutMs?: number;
 }
 /**
- * The wallets in this page. A wallet that follows EIP-6963 announces itself, so several can be
- * listed side by side; one that only sets `window.ethereum` (older wallets, some in-app browsers)
- * is added when no announced wallet is that same provider. Returns an empty list when there is no
- * wallet, or when there is no page (Node).
+ * The wallets in this page. A wallet that follows EIP-6963 (MetaMask, Trust Wallet) or TIP-6963
+ * (TronLink, the same idea for TRON) announces itself, so several can be listed side by side. One
+ * that only sets a global is added when no announced wallet is that same provider: `window.ethereum`
+ * (older wallets, some in-app browsers), or `window.tron` / `window.tronLink` for TronLink. Returns
+ * an empty list when there is no wallet, or when there is no page (Node).
  */
 export declare function discoverInjectedWallets(options?: WalletDiscoveryOptions): Promise<InjectedWallet[]>;
 /**
@@ -83,3 +132,20 @@ export declare function discoverInjectedWallets(options?: WalletDiscoveryOptions
  * Rejects when the user says no (the provider's error, code 4001) or when no account is shared.
  */
 export declare function connectWallet(wallet: InjectedWallet): Promise<Signer>;
+/** A signer for `account` on `wallet`: `personal_sign` for MetaMask and Trust Wallet, `signMessageV2` for TronLink. */
+export declare function createSignerFor(wallet: InjectedWallet, account: string): Signer;
+/** The first account in an answer of this wallet (`accountsChanged`), as a Clutch address; `null` when there is none. */
+export declare function walletAccountFrom(wallet: InjectedWallet, accounts: unknown): string | null;
+/**
+ * The account a wallet already shares with this page, as a Clutch address. It never opens a
+ * prompt, so an app can use it to connect again by itself on the next visit. `null` when the wallet
+ * shares none (locked, or the site was never allowed). A TronLink that allowed the site earlier has
+ * its `tronWeb` ready; one that did not has `tronWeb` `false`.
+ */
+export declare function sharedWalletAccount(wallet: InjectedWallet): Promise<string | null>;
+/**
+ * Call `listener` with the new account (a Clutch address) when the person switches account in the
+ * wallet, and with `null` when the wallet stops sharing this site (locked, or disconnected).
+ * Returns a function that stops listening.
+ */
+export declare function watchWalletAccounts(wallet: InjectedWallet, listener: (account: string | null) => void): () => void;

package/dist/signers.js

@@ -1,17 +1,21 @@
 import { Buffer } from 'buffer';
 import { keccak_256 } from '@noble/hashes/sha3';
+import { sha256 } from '@noble/hashes/sha256';
 import * as secp from '@noble/secp256k1';
 /*
  * Who signs a transaction.
  *
- * The SDK used to take a private key string and sign with it. A wallet (MetaMask, Trust Wallet)
- * never gives its key to a page, so the SDK now takes a `Signer`: an object that can be asked for
- * a signature. A key in memory is one kind of signer (`createLocalSigner`, in sdk.ts); a wallet is
- * another (`createWalletSigner`, here). Everywhere the SDK took a key it still takes a key string.
+ * The SDK used to take a private key string and sign with it. A wallet (MetaMask, Trust Wallet,
+ * TronLink) never gives its key to a page, so the SDK now takes a `Signer`: an object that can be
+ * asked for a signature. A key in memory is one kind of signer (`createLocalSigner`, in sdk.ts); a
+ * wallet is another (`createWalletSigner` and `createTronLinkSigner`, here). Everywhere the SDK
+ * took a key it still takes a key string.
  *
- * A wallet will not sign a bare hash, so it signs a short readable text with `personal_sign`
- * (EIP-191), which hashes `"\x19Ethereum Signed Message:\n" + length + text`. The node and the Hub
- * API accept that signature next to the old one. The texts below are the contract with them:
+ * A wallet will not sign a bare hash, so it signs a short readable text. MetaMask and Trust Wallet
+ * use `personal_sign` (EIP-191), which hashes `"\x19Ethereum Signed Message:\n" + length + text`.
+ * TronLink uses `signMessageV2` (TIP-191), which hashes `"\x19TRON Signed Message:\n" + length +
+ * text`: the same key and the same 20-byte address, with another prefix. The node and the Hub API
+ * accept both signatures next to the old one. The texts below are the contract with them:
  *
  *   transaction  clutch-tx:{chainId}:{hash}              hash = 64 lowercase hex, no 0x
  *   login        clutch-auth:{chainId}:{publicKey}:{timestamp}
@@ -30,6 +34,12 @@ export function personalSignDigest(text) {
     const prefix = Buffer.from(`\x19Ethereum Signed Message:\n${body.length}`, 'utf8');
     return keccak_256(Buffer.concat([prefix, body]));
 }
+/** What TronLink's `signMessageV2` (TIP-191) hashes and signs: `Keccak256("\x19TRON Signed Message:\n" + length + text)`. */
+export function tronSignDigest(text) {
+    const body = Buffer.from(text, 'utf8');
+    const prefix = Buffer.from(`\x19TRON Signed Message:\n${body.length}`, 'utf8');
+    return keccak_256(Buffer.concat([prefix, body]));
+}
 /**
  * `r`, `s` and `v` from a wallet's answer: `0x` and 130 hex characters (65 bytes). Some wallets
  * answer with a recovery id of 0 or 1 instead of 27 or 28; the node reads only 27 and 28.
@@ -90,6 +100,114 @@ export function createWalletSigner(provider, address) {
         signAuthChallenge: ({ message }) => personalSign(message),
     };
 }
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+function base58Decode(text) {
+    const digits = []; // base 256, least significant first
+    for (const char of text) {
+        let carry = BASE58_ALPHABET.indexOf(char);
+        if (carry < 0) {
+            throw new Error(`"${char}" is not a base58 character`);
+        }
+        for (let i = 0; i < digits.length; i++) {
+            carry += digits[i] * 58;
+            digits[i] = carry & 0xff;
+            carry >>= 8;
+        }
+        while (carry > 0) {
+            digits.push(carry & 0xff);
+            carry >>= 8;
+        }
+    }
+    for (const char of text) {
+        if (char !== '1')
+            break;
+        digits.push(0); // each leading "1" is a zero byte
+    }
+    return Uint8Array.from(digits.reverse());
+}
+/**
+ * A TRON address as the Clutch address of the same key: `0x` and 40 lowercase hex characters.
+ *
+ * A TRON account is an Ethereum-type key (the same curve, the same Keccak-256, the same 20 address
+ * bytes). TRON writes those bytes in base58 (`T…`): `0x41`, the 20 bytes, and 4 bytes of checksum,
+ * and the checksum is checked here. A `0x` address and the `41…` hex form are accepted as they are.
+ */
+export function tronAddressToHex(address) {
+    if (/^0x[0-9a-fA-F]{40}$/.test(address)) {
+        return address.toLowerCase();
+    }
+    if (/^41[0-9a-fA-F]{40}$/.test(address)) {
+        return '0x' + address.slice(2).toLowerCase();
+    }
+    const bytes = base58Decode(address);
+    if (bytes.length !== 25 || bytes[0] !== 0x41) {
+        throw new Error(`"${address}" is not a TRON address`);
+    }
+    const checksum = sha256(sha256(bytes.slice(0, 21))).slice(0, 4);
+    if (!checksum.every((byte, index) => byte === bytes[21 + index])) {
+        throw new Error(`"${address}" is not a TRON address: its checksum is wrong`);
+    }
+    return '0x' + Buffer.from(bytes.slice(1, 21)).toString('hex');
+}
+/** A TRON address from a wallet's answer as a Clutch address, or `null` when it is not one. */
+function tronAccountOf(raw) {
+    try {
+        return typeof raw === 'string' ? tronAddressToHex(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+const INVALID_INPUT = /invalid transaction provided/i;
+/**
+ * A signer that asks TronLink to sign with `signMessageV2` (TIP-191). TronLink shows the person the
+ * text and keeps the key. `address` is the account to sign for (a `0x` address, or the base58 one
+ * TronLink shows). It is checked the same way `createWalletSigner` checks: the signature is
+ * recovered here, and one from another account is refused before it leaves the SDK.
+ *
+ * TronLink's documentation is not clear on what `signMessageV2` takes: one page says a hex string
+ * and another says plain text or hex. So the text goes in plain first. A TronLink that takes only
+ * hex answers "Invalid transaction provided" before it opens a prompt, and then the text goes in
+ * again as `0x` hex of its UTF-8 bytes. Any other answer ends the call, because a second try would
+ * open a second prompt.
+ */
+export function createTronLinkSigner(provider, address) {
+    const account = tronAddressToHex(address);
+    async function tronSign(text) {
+        const trx = provider.tronWeb ? provider.tronWeb.trx : undefined;
+        if (!trx || typeof trx.signMessageV2 !== 'function') {
+            throw new Error('TronLink is locked, or has not shared this site: open TronLink and connect again');
+        }
+        const hexText = '0x' + Buffer.from(text, 'utf8').toString('hex');
+        let raw;
+        try {
+            raw = await trx.signMessageV2(text);
+        }
+        catch (error) {
+            if (!INVALID_INPUT.test(error instanceof Error ? error.message : String(error))) {
+                throw error;
+            }
+            raw = await trx.signMessageV2(hexText);
+        }
+        const signature = parseWalletSignature(raw);
+        const signedBy = recoverAddress(tronSignDigest(text), signature);
+        if (signedBy !== account) {
+            // A TronLink that read the hex as text would sign the text of the hex. Say so, because that
+            // is not the person's fault and switching accounts would not help.
+            if (recoverAddress(tronSignDigest(hexText), signature) === account) {
+                throw new Error('this TronLink signed the hex text, not the message, so the signature is not valid for Clutch: update TronLink');
+            }
+            throw new Error(`TronLink signed with ${signedBy ?? 'an account that cannot be read'}, not ${account}: switch to ${account} in TronLink and try again`);
+        }
+        return signature;
+    }
+    return {
+        address: account,
+        interactive: true,
+        signTransaction: ({ hashHex, chainId }) => tronSign(walletTransactionText(chainId, hashHex)),
+        signAuthChallenge: ({ message }) => tronSign(message),
+    };
+}
 function isProvider(value) {
     return !!value && typeof value.request === 'function';
 }
@@ -105,18 +223,20 @@ function legacyName(provider) {
     return 'Browser wallet';
 }
 /**
- * The wallets in this page. A wallet that follows EIP-6963 announces itself, so several can be
- * listed side by side; one that only sets `window.ethereum` (older wallets, some in-app browsers)
- * is added when no announced wallet is that same provider. Returns an empty list when there is no
- * wallet, or when there is no page (Node).
+ * The wallets in this page. A wallet that follows EIP-6963 (MetaMask, Trust Wallet) or TIP-6963
+ * (TronLink, the same idea for TRON) announces itself, so several can be listed side by side. One
+ * that only sets a global is added when no announced wallet is that same provider: `window.ethereum`
+ * (older wallets, some in-app browsers), or `window.tron` / `window.tronLink` for TronLink. Returns
+ * an empty list when there is no wallet, or when there is no page (Node).
  */
 export async function discoverInjectedWallets(options = {}) {
     const host = options.host ?? (typeof window !== 'undefined' ? window : undefined);
     if (!host) {
         return [];
     }
-    const found = new Map();
-    const onAnnounce = (event) => {
+    const announcedEvm = new Map();
+    const announcedTron = new Map();
+    const onAnnounce = (found, kind) => (event) => {
         const detail = event.detail;
         if (!detail || !isProvider(detail.provider)) {
             return;
@@ -124,38 +244,132 @@ export async function discoverInjectedWallets(options = {}) {
         const info = detail.info ?? {};
         const id = info.rdns || info.uuid || info.name || `announced-${found.size}`;
         if (!found.has(id)) {
-            found.set(id, { id, name: info.name || id, icon: info.icon, provider: detail.provider });
+            found.set(id, { id, name: info.name || id, icon: info.icon, kind, provider: detail.provider });
         }
     };
-    host.addEventListener('eip6963:announceProvider', onAnnounce);
+    const onEvm = onAnnounce(announcedEvm, 'evm');
+    const onTron = onAnnounce(announcedTron, 'tron');
+    host.addEventListener('eip6963:announceProvider', onEvm);
+    host.addEventListener('TIP6963:announceProvider', onTron);
     try {
         host.dispatchEvent(new Event('eip6963:requestProvider'));
+        host.dispatchEvent(new Event('TIP6963:requestProvider'));
         await new Promise((resolve) => setTimeout(resolve, options.timeoutMs ?? 300));
     }
     finally {
-        host.removeEventListener('eip6963:announceProvider', onAnnounce);
+        host.removeEventListener('eip6963:announceProvider', onEvm);
+        host.removeEventListener('TIP6963:announceProvider', onTron);
+    }
+    const tronWallets = [...announcedTron.values()];
+    if (tronWallets.length === 0) {
+        // `window.tronLink` is the older name of `window.tron`; the two are the same wallet.
+        const bare = [host.tron, host.tronLink].find(isProvider);
+        if (bare) {
+            tronWallets.push({ id: 'injected-tron', name: 'TronLink', kind: 'tron', provider: bare });
+        }
     }
-    const wallets = [...found.values()];
+    // A provider that is TronLink's must not be listed again as an Ethereum wallet.
+    const wallets = [...announcedEvm.values()].filter((wallet) => !tronWallets.some((tron) => tron.provider === wallet.provider));
     const ethereum = host.ethereum;
     if (isProvider(ethereum)) {
         const list = Array.isArray(ethereum.providers) && ethereum.providers.length > 0 ? ethereum.providers : [ethereum];
         list.filter(isProvider).forEach((provider, index) => {
-            if (!wallets.some((wallet) => wallet.provider === provider)) {
-                wallets.push({ id: `injected-${index}`, name: legacyName(provider), provider });
+            const known = [...wallets, ...tronWallets].some((wallet) => wallet.provider === provider);
+            if (!known) {
+                wallets.push({ id: `injected-${index}`, name: legacyName(provider), kind: 'evm', provider });
             }
         });
     }
-    return wallets;
+    return [...wallets, ...tronWallets];
+}
+/** An account from an `eth_accounts`-style answer, as `0x` and 40 lowercase hex characters. */
+function evmAccountOf(raw) {
+    return typeof raw === 'string' && /^0x[0-9a-fA-F]{40}$/.test(raw) ? raw.toLowerCase() : null;
+}
+/**
+ * Ask TronLink to share its account. TronLink answers `['T…']` (base58). An older TronLink does not
+ * know `eth_requestAccounts` (error 4200): it has its own `tron_requestAccounts`, which answers
+ * `{ code, message }` and puts the account in `tronWeb`.
+ */
+async function requestTronAccount(provider) {
+    let accounts;
+    try {
+        accounts = await provider.request({ method: 'eth_requestAccounts' });
+    }
+    catch (error) {
+        if (error?.code !== 4200) {
+            throw error;
+        }
+        const answer = (await provider.request({ method: 'tron_requestAccounts' }));
+        if (!answer) {
+            throw new Error('TronLink is locked: unlock it and try again');
+        }
+        if (answer.code === 4001) {
+            throw Object.assign(new Error('You said no in TronLink.'), { code: 4001 });
+        }
+        if (answer.code !== 200) {
+            throw new Error(answer.message || 'TronLink did not connect');
+        }
+        accounts = [provider.tronWeb ? provider.tronWeb.defaultAddress?.base58 : undefined];
+    }
+    return tronAccountOf(Array.isArray(accounts) ? accounts[0] : undefined);
 }
 /**
  * Ask a wallet to share its account (the wallet shows its own prompt) and return a signer for it.
  * Rejects when the user says no (the provider's error, code 4001) or when no account is shared.
  */
 export async function connectWallet(wallet) {
+    if (wallet.kind === 'tron') {
+        const account = await requestTronAccount(wallet.provider);
+        if (!account) {
+            throw new Error('the wallet did not share an account');
+        }
+        return createTronLinkSigner(wallet.provider, account);
+    }
     const accounts = await wallet.provider.request({ method: 'eth_requestAccounts' });
-    const first = Array.isArray(accounts) ? accounts[0] : undefined;
-    if (typeof first !== 'string' || !/^0x[0-9a-fA-F]{40}$/.test(first)) {
+    const account = evmAccountOf(Array.isArray(accounts) ? accounts[0] : undefined);
+    if (!account) {
         throw new Error('the wallet did not share an account');
     }
-    return createWalletSigner(wallet.provider, first);
+    return createWalletSigner(wallet.provider, account);
+}
+/** A signer for `account` on `wallet`: `personal_sign` for MetaMask and Trust Wallet, `signMessageV2` for TronLink. */
+export function createSignerFor(wallet, account) {
+    return wallet.kind === 'tron'
+        ? createTronLinkSigner(wallet.provider, account)
+        : createWalletSigner(wallet.provider, account);
+}
+/** The first account in an answer of this wallet (`accountsChanged`), as a Clutch address; `null` when there is none. */
+export function walletAccountFrom(wallet, accounts) {
+    const first = Array.isArray(accounts) ? accounts[0] : undefined;
+    return wallet.kind === 'tron' ? tronAccountOf(first) : evmAccountOf(first);
+}
+/**
+ * The account a wallet already shares with this page, as a Clutch address. It never opens a
+ * prompt, so an app can use it to connect again by itself on the next visit. `null` when the wallet
+ * shares none (locked, or the site was never allowed). A TronLink that allowed the site earlier has
+ * its `tronWeb` ready; one that did not has `tronWeb` `false`.
+ */
+export async function sharedWalletAccount(wallet) {
+    if (wallet.kind === 'tron') {
+        const tronWeb = wallet.provider.tronWeb;
+        return !tronWeb || tronWeb.ready === false ? null : tronAccountOf(tronWeb.defaultAddress?.base58);
+    }
+    return walletAccountFrom(wallet, await wallet.provider.request({ method: 'eth_accounts' }));
+}
+/**
+ * Call `listener` with the new account (a Clutch address) when the person switches account in the
+ * wallet, and with `null` when the wallet stops sharing this site (locked, or disconnected).
+ * Returns a function that stops listening.
+ */
+export function watchWalletAccounts(wallet, listener) {
+    const provider = wallet.provider;
+    if (!provider.on) {
+        return () => { };
+    }
+    const onAccountsChanged = (accounts) => listener(walletAccountFrom(wallet, accounts));
+    provider.on('accountsChanged', onAccountsChanged);
+    return () => {
+        provider.removeListener?.('accountsChanged', onAccountsChanged);
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clutch-hub-sdk-js",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "JavaScript SDK for interacting with the clutch-hub-api",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/signers.ts

@@ -1,19 +1,23 @@
 import { Buffer } from 'buffer';
 import { keccak_256 } from '@noble/hashes/sha3';
+import { sha256 } from '@noble/hashes/sha256';
 import * as secp from '@noble/secp256k1';
 import type { Signature } from './types.js';
 
 /*
  * Who signs a transaction.
  *
- * The SDK used to take a private key string and sign with it. A wallet (MetaMask, Trust Wallet)
- * never gives its key to a page, so the SDK now takes a `Signer`: an object that can be asked for
- * a signature. A key in memory is one kind of signer (`createLocalSigner`, in sdk.ts); a wallet is
- * another (`createWalletSigner`, here). Everywhere the SDK took a key it still takes a key string.
+ * The SDK used to take a private key string and sign with it. A wallet (MetaMask, Trust Wallet,
+ * TronLink) never gives its key to a page, so the SDK now takes a `Signer`: an object that can be
+ * asked for a signature. A key in memory is one kind of signer (`createLocalSigner`, in sdk.ts); a
+ * wallet is another (`createWalletSigner` and `createTronLinkSigner`, here). Everywhere the SDK
+ * took a key it still takes a key string.
  *
- * A wallet will not sign a bare hash, so it signs a short readable text with `personal_sign`
- * (EIP-191), which hashes `"\x19Ethereum Signed Message:\n" + length + text`. The node and the Hub
- * API accept that signature next to the old one. The texts below are the contract with them:
+ * A wallet will not sign a bare hash, so it signs a short readable text. MetaMask and Trust Wallet
+ * use `personal_sign` (EIP-191), which hashes `"\x19Ethereum Signed Message:\n" + length + text`.
+ * TronLink uses `signMessageV2` (TIP-191), which hashes `"\x19TRON Signed Message:\n" + length +
+ * text`: the same key and the same 20-byte address, with another prefix. The node and the Hub API
+ * accept both signatures next to the old one. The texts below are the contract with them:
  *
  *   transaction  clutch-tx:{chainId}:{hash}              hash = 64 lowercase hex, no 0x
  *   login        clutch-auth:{chainId}:{publicKey}:{timestamp}
@@ -78,6 +82,13 @@ export function personalSignDigest(text: string): Uint8Array {
   return keccak_256(Buffer.concat([prefix, body]));
 }
 
+/** What TronLink's `signMessageV2` (TIP-191) hashes and signs: `Keccak256("\x19TRON Signed Message:\n" + length + text)`. */
+export function tronSignDigest(text: string): Uint8Array {
+  const body = Buffer.from(text, 'utf8');
+  const prefix = Buffer.from(`\x19TRON Signed Message:\n${body.length}`, 'utf8');
+  return keccak_256(Buffer.concat([prefix, body]));
+}
+
 /**
  * `r`, `s` and `v` from a wallet's answer: `0x` and 130 hex characters (65 bytes). Some wallets
  * answer with a recovery id of 0 or 1 instead of 27 or 28; the node reads only 27 and 28.
@@ -144,20 +155,156 @@ export function createWalletSigner(provider: Eip1193Provider, address: string):
   };
 }
 
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+
+function base58Decode(text: string): Uint8Array {
+  const digits: number[] = []; // base 256, least significant first
+  for (const char of text) {
+    let carry = BASE58_ALPHABET.indexOf(char);
+    if (carry < 0) {
+      throw new Error(`"${char}" is not a base58 character`);
+    }
+    for (let i = 0; i < digits.length; i++) {
+      carry += digits[i] * 58;
+      digits[i] = carry & 0xff;
+      carry >>= 8;
+    }
+    while (carry > 0) {
+      digits.push(carry & 0xff);
+      carry >>= 8;
+    }
+  }
+  for (const char of text) {
+    if (char !== '1') break;
+    digits.push(0); // each leading "1" is a zero byte
+  }
+  return Uint8Array.from(digits.reverse());
+}
+
+/**
+ * A TRON address as the Clutch address of the same key: `0x` and 40 lowercase hex characters.
+ *
+ * A TRON account is an Ethereum-type key (the same curve, the same Keccak-256, the same 20 address
+ * bytes). TRON writes those bytes in base58 (`T…`): `0x41`, the 20 bytes, and 4 bytes of checksum,
+ * and the checksum is checked here. A `0x` address and the `41…` hex form are accepted as they are.
+ */
+export function tronAddressToHex(address: string): string {
+  if (/^0x[0-9a-fA-F]{40}$/.test(address)) {
+    return address.toLowerCase();
+  }
+  if (/^41[0-9a-fA-F]{40}$/.test(address)) {
+    return '0x' + address.slice(2).toLowerCase();
+  }
+  const bytes = base58Decode(address);
+  if (bytes.length !== 25 || bytes[0] !== 0x41) {
+    throw new Error(`"${address}" is not a TRON address`);
+  }
+  const checksum = sha256(sha256(bytes.slice(0, 21))).slice(0, 4);
+  if (!checksum.every((byte, index) => byte === bytes[21 + index])) {
+    throw new Error(`"${address}" is not a TRON address: its checksum is wrong`);
+  }
+  return '0x' + Buffer.from(bytes.slice(1, 21)).toString('hex');
+}
+
+/** The part of the `tronWeb` that TronLink puts on its provider that the SDK uses. */
+export interface TronWebLike {
+  ready?: boolean;
+  defaultAddress?: { base58?: string | false };
+  trx?: { signMessageV2?(message: string): Promise<unknown> };
+}
+
+/**
+ * TronLink's provider (`window.tron`, or the one it announces with TIP-6963): EIP-1193 plus a
+ * `tronWeb`, which is `false` until the person lets this site use TronLink.
+ */
+export interface TronLinkProvider extends Eip1193Provider {
+  tronWeb?: TronWebLike | false;
+}
+
+/** A TRON address from a wallet's answer as a Clutch address, or `null` when it is not one. */
+function tronAccountOf(raw: unknown): string | null {
+  try {
+    return typeof raw === 'string' ? tronAddressToHex(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+const INVALID_INPUT = /invalid transaction provided/i;
+
+/**
+ * A signer that asks TronLink to sign with `signMessageV2` (TIP-191). TronLink shows the person the
+ * text and keeps the key. `address` is the account to sign for (a `0x` address, or the base58 one
+ * TronLink shows). It is checked the same way `createWalletSigner` checks: the signature is
+ * recovered here, and one from another account is refused before it leaves the SDK.
+ *
+ * TronLink's documentation is not clear on what `signMessageV2` takes: one page says a hex string
+ * and another says plain text or hex. So the text goes in plain first. A TronLink that takes only
+ * hex answers "Invalid transaction provided" before it opens a prompt, and then the text goes in
+ * again as `0x` hex of its UTF-8 bytes. Any other answer ends the call, because a second try would
+ * open a second prompt.
+ */
+export function createTronLinkSigner(provider: TronLinkProvider, address: string): Signer {
+  const account = tronAddressToHex(address);
+
+  async function tronSign(text: string): Promise<Signature> {
+    const trx = provider.tronWeb ? provider.tronWeb.trx : undefined;
+    if (!trx || typeof trx.signMessageV2 !== 'function') {
+      throw new Error('TronLink is locked, or has not shared this site: open TronLink and connect again');
+    }
+    const hexText = '0x' + Buffer.from(text, 'utf8').toString('hex');
+    let raw: unknown;
+    try {
+      raw = await trx.signMessageV2(text);
+    } catch (error) {
+      if (!INVALID_INPUT.test(error instanceof Error ? error.message : String(error))) {
+        throw error;
+      }
+      raw = await trx.signMessageV2(hexText);
+    }
+    const signature = parseWalletSignature(raw);
+    const signedBy = recoverAddress(tronSignDigest(text), signature);
+    if (signedBy !== account) {
+      // A TronLink that read the hex as text would sign the text of the hex. Say so, because that
+      // is not the person's fault and switching accounts would not help.
+      if (recoverAddress(tronSignDigest(hexText), signature) === account) {
+        throw new Error('this TronLink signed the hex text, not the message, so the signature is not valid for Clutch: update TronLink');
+      }
+      throw new Error(
+        `TronLink signed with ${signedBy ?? 'an account that cannot be read'}, not ${account}: switch to ${account} in TronLink and try again`
+      );
+    }
+    return signature;
+  }
+
+  return {
+    address: account,
+    interactive: true,
+    signTransaction: ({ hashHex, chainId }) => tronSign(walletTransactionText(chainId, hashHex)),
+    signAuthChallenge: ({ message }) => tronSign(message),
+  };
+}
+
 /** A wallet found in the page. */
 export interface InjectedWallet {
-  /** The EIP-6963 `rdns` (for example `io.metamask`), or `injected-0` for a bare `window.ethereum`. */
+  /** The EIP-6963 or TIP-6963 `rdns` (for example `io.metamask`), or `injected-0` for a bare `window.ethereum`. */
   id: string;
   name: string;
   /** A `data:` image address from the wallet, when it announced one. */
   icon?: string;
+  /**
+   * `evm` (MetaMask, Trust Wallet: signs with `personal_sign`) or `tron` (TronLink: signs with
+   * `signMessageV2`). Default `evm`.
+   */
+  kind?: 'evm' | 'tron';
+  /** For a `tron` wallet this is a {@link TronLinkProvider}. */
   provider: Eip1193Provider;
 }
 
 export interface WalletDiscoveryOptions {
   /** Where to look. Default: `window`. */
-  host?: EventTarget & { ethereum?: unknown };
-  /** How long to listen for EIP-6963 announcements, in milliseconds. Default: 300. */
+  host?: EventTarget & { ethereum?: unknown; tron?: unknown; tronLink?: unknown };
+  /** How long to listen for EIP-6963 and TIP-6963 announcements, in milliseconds. Default: 300. */
   timeoutMs?: number;
 }
 
@@ -175,19 +322,21 @@ function legacyName(provider: Eip1193Provider): string {
 }
 
 /**
- * The wallets in this page. A wallet that follows EIP-6963 announces itself, so several can be
- * listed side by side; one that only sets `window.ethereum` (older wallets, some in-app browsers)
- * is added when no announced wallet is that same provider. Returns an empty list when there is no
- * wallet, or when there is no page (Node).
+ * The wallets in this page. A wallet that follows EIP-6963 (MetaMask, Trust Wallet) or TIP-6963
+ * (TronLink, the same idea for TRON) announces itself, so several can be listed side by side. One
+ * that only sets a global is added when no announced wallet is that same provider: `window.ethereum`
+ * (older wallets, some in-app browsers), or `window.tron` / `window.tronLink` for TronLink. Returns
+ * an empty list when there is no wallet, or when there is no page (Node).
  */
 export async function discoverInjectedWallets(options: WalletDiscoveryOptions = {}): Promise<InjectedWallet[]> {
   const host = options.host ?? (typeof window !== 'undefined' ? (window as unknown as WalletDiscoveryOptions['host']) : undefined);
   if (!host) {
     return [];
   }
-  const found = new Map<string, InjectedWallet>();
+  const announcedEvm = new Map<string, InjectedWallet>();
+  const announcedTron = new Map<string, InjectedWallet>();
 
-  const onAnnounce = (event: Event): void => {
+  const onAnnounce = (found: Map<string, InjectedWallet>, kind: 'evm' | 'tron') => (event: Event): void => {
     const detail = (event as Event & { detail?: { info?: Record<string, string>; provider?: unknown } }).detail;
     if (!detail || !isProvider(detail.provider)) {
       return;
@@ -195,30 +344,81 @@ export async function discoverInjectedWallets(options: WalletDiscoveryOptions =
     const info = detail.info ?? {};
     const id = info.rdns || info.uuid || info.name || `announced-${found.size}`;
     if (!found.has(id)) {
-      found.set(id, { id, name: info.name || id, icon: info.icon, provider: detail.provider });
+      found.set(id, { id, name: info.name || id, icon: info.icon, kind, provider: detail.provider });
     }
   };
+  const onEvm = onAnnounce(announcedEvm, 'evm');
+  const onTron = onAnnounce(announcedTron, 'tron');
 
-  host.addEventListener('eip6963:announceProvider', onAnnounce);
+  host.addEventListener('eip6963:announceProvider', onEvm);
+  host.addEventListener('TIP6963:announceProvider', onTron);
   try {
     host.dispatchEvent(new Event('eip6963:requestProvider'));
+    host.dispatchEvent(new Event('TIP6963:requestProvider'));
     await new Promise<void>((resolve) => setTimeout(resolve, options.timeoutMs ?? 300));
   } finally {
-    host.removeEventListener('eip6963:announceProvider', onAnnounce);
+    host.removeEventListener('eip6963:announceProvider', onEvm);
+    host.removeEventListener('TIP6963:announceProvider', onTron);
   }
 
-  const wallets = [...found.values()];
+  const tronWallets = [...announcedTron.values()];
+  if (tronWallets.length === 0) {
+    // `window.tronLink` is the older name of `window.tron`; the two are the same wallet.
+    const bare = [host.tron, host.tronLink].find(isProvider);
+    if (bare) {
+      tronWallets.push({ id: 'injected-tron', name: 'TronLink', kind: 'tron', provider: bare });
+    }
+  }
+
+  // A provider that is TronLink's must not be listed again as an Ethereum wallet.
+  const wallets = [...announcedEvm.values()].filter(
+    (wallet) => !tronWallets.some((tron) => tron.provider === wallet.provider)
+  );
   const ethereum = host.ethereum as (Eip1193Provider & { providers?: unknown }) | undefined;
   if (isProvider(ethereum)) {
     const list: unknown[] =
       Array.isArray(ethereum.providers) && ethereum.providers.length > 0 ? ethereum.providers : [ethereum];
     list.filter(isProvider).forEach((provider, index) => {
-      if (!wallets.some((wallet) => wallet.provider === provider)) {
-        wallets.push({ id: `injected-${index}`, name: legacyName(provider), provider });
+      const known = [...wallets, ...tronWallets].some((wallet) => wallet.provider === provider);
+      if (!known) {
+        wallets.push({ id: `injected-${index}`, name: legacyName(provider), kind: 'evm', provider });
       }
     });
   }
-  return wallets;
+  return [...wallets, ...tronWallets];
+}
+
+/** An account from an `eth_accounts`-style answer, as `0x` and 40 lowercase hex characters. */
+function evmAccountOf(raw: unknown): string | null {
+  return typeof raw === 'string' && /^0x[0-9a-fA-F]{40}$/.test(raw) ? raw.toLowerCase() : null;
+}
+
+/**
+ * Ask TronLink to share its account. TronLink answers `['T…']` (base58). An older TronLink does not
+ * know `eth_requestAccounts` (error 4200): it has its own `tron_requestAccounts`, which answers
+ * `{ code, message }` and puts the account in `tronWeb`.
+ */
+async function requestTronAccount(provider: TronLinkProvider): Promise<string | null> {
+  let accounts: unknown;
+  try {
+    accounts = await provider.request({ method: 'eth_requestAccounts' });
+  } catch (error) {
+    if ((error as { code?: number } | null)?.code !== 4200) {
+      throw error;
+    }
+    const answer = (await provider.request({ method: 'tron_requestAccounts' })) as { code?: number; message?: string } | '' | null;
+    if (!answer) {
+      throw new Error('TronLink is locked: unlock it and try again');
+    }
+    if (answer.code === 4001) {
+      throw Object.assign(new Error('You said no in TronLink.'), { code: 4001 });
+    }
+    if (answer.code !== 200) {
+      throw new Error(answer.message || 'TronLink did not connect');
+    }
+    accounts = [provider.tronWeb ? provider.tronWeb.defaultAddress?.base58 : undefined];
+  }
+  return tronAccountOf(Array.isArray(accounts) ? accounts[0] : undefined);
 }
 
 /**
@@ -226,10 +426,61 @@ export async function discoverInjectedWallets(options: WalletDiscoveryOptions =
  * Rejects when the user says no (the provider's error, code 4001) or when no account is shared.
  */
 export async function connectWallet(wallet: InjectedWallet): Promise<Signer> {
+  if (wallet.kind === 'tron') {
+    const account = await requestTronAccount(wallet.provider as TronLinkProvider);
+    if (!account) {
+      throw new Error('the wallet did not share an account');
+    }
+    return createTronLinkSigner(wallet.provider as TronLinkProvider, account);
+  }
   const accounts = await wallet.provider.request({ method: 'eth_requestAccounts' });
-  const first = Array.isArray(accounts) ? accounts[0] : undefined;
-  if (typeof first !== 'string' || !/^0x[0-9a-fA-F]{40}$/.test(first)) {
+  const account = evmAccountOf(Array.isArray(accounts) ? accounts[0] : undefined);
+  if (!account) {
     throw new Error('the wallet did not share an account');
   }
-  return createWalletSigner(wallet.provider, first);
+  return createWalletSigner(wallet.provider, account);
+}
+
+/** A signer for `account` on `wallet`: `personal_sign` for MetaMask and Trust Wallet, `signMessageV2` for TronLink. */
+export function createSignerFor(wallet: InjectedWallet, account: string): Signer {
+  return wallet.kind === 'tron'
+    ? createTronLinkSigner(wallet.provider as TronLinkProvider, account)
+    : createWalletSigner(wallet.provider, account);
+}
+
+/** The first account in an answer of this wallet (`accountsChanged`), as a Clutch address; `null` when there is none. */
+export function walletAccountFrom(wallet: InjectedWallet, accounts: unknown): string | null {
+  const first = Array.isArray(accounts) ? accounts[0] : undefined;
+  return wallet.kind === 'tron' ? tronAccountOf(first) : evmAccountOf(first);
+}
+
+/**
+ * The account a wallet already shares with this page, as a Clutch address. It never opens a
+ * prompt, so an app can use it to connect again by itself on the next visit. `null` when the wallet
+ * shares none (locked, or the site was never allowed). A TronLink that allowed the site earlier has
+ * its `tronWeb` ready; one that did not has `tronWeb` `false`.
+ */
+export async function sharedWalletAccount(wallet: InjectedWallet): Promise<string | null> {
+  if (wallet.kind === 'tron') {
+    const tronWeb = (wallet.provider as TronLinkProvider).tronWeb;
+    return !tronWeb || tronWeb.ready === false ? null : tronAccountOf(tronWeb.defaultAddress?.base58);
+  }
+  return walletAccountFrom(wallet, await wallet.provider.request({ method: 'eth_accounts' }));
+}
+
+/**
+ * Call `listener` with the new account (a Clutch address) when the person switches account in the
+ * wallet, and with `null` when the wallet stops sharing this site (locked, or disconnected).
+ * Returns a function that stops listening.
+ */
+export function watchWalletAccounts(wallet: InjectedWallet, listener: (account: string | null) => void): () => void {
+  const provider = wallet.provider;
+  if (!provider.on) {
+    return () => {};
+  }
+  const onAccountsChanged = (accounts: unknown): void => listener(walletAccountFrom(wallet, accounts));
+  provider.on('accountsChanged', onAccountsChanged);
+  return () => {
+    provider.removeListener?.('accountsChanged', onAccountsChanged);
+  };
 }