@unicitylabs/bridge-plugin 0.2.0-dev.1

package/lib/tron/TronRpcClient.js

@@ -0,0 +1,100 @@
+function strip0x(h) {
+    return h.startsWith('0x') || h.startsWith('0X') ? h.slice(2) : h;
+}
+export class TronHttpRpcClient {
+    baseUrl;
+    apiKey;
+    fetchFn;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.apiKey = options.apiKey;
+        // Bind to globalThis: native `fetch` is spec'd to require `this` to be the
+        // real global (window/self) — assigning the bare reference and later
+        // calling it as `this.fetchFn(...)` rebinds `this` to the client instance,
+        // which throws "Illegal invocation".
+        const f = options.fetchFn ?? globalThis.fetch?.bind(globalThis);
+        if (!f) {
+            throw new Error('No fetch available; pass fetchFn in TronHttpRpcClientOptions.');
+        }
+        this.fetchFn = f;
+    }
+    async post(path, body) {
+        const headers = { 'content-type': 'application/json' };
+        if (this.apiKey) {
+            headers['TRON-PRO-API-KEY'] = this.apiKey;
+        }
+        const res = await this.fetchFn(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            throw new Error(`Tron RPC ${path} failed: HTTP ${res.status}`);
+        }
+        return (await res.json());
+    }
+    async getTransactionInfo(txidHex) {
+        const info = await this.post('/wallet/gettransactioninfobyid', { value: strip0x(txidHex) });
+        if (!info || Object.keys(info).length === 0 || info.id == null) {
+            return null;
+        }
+        const receipt = (info.receipt ?? {});
+        const rawLogs = Array.isArray(info.log) ? info.log : [];
+        const logs = rawLogs.map((l) => ({
+            address: String(l.address ?? '').toLowerCase(),
+            topics: Array.isArray(l.topics) ? l.topics.map((t) => String(t).toLowerCase()) : [],
+            data: String(l.data ?? '').toLowerCase(),
+        }));
+        return {
+            blockNumber: BigInt(info.blockNumber ?? 0),
+            success: String(receipt.result ?? '') === 'SUCCESS',
+            logs,
+        };
+    }
+    async getNowBlockNumber() {
+        const block = await this.post('/wallet/getnowblock', {});
+        const header = (block.block_header ?? {});
+        const raw = (header.raw_data ?? {});
+        return BigInt(raw.number ?? 0);
+    }
+    /**
+     * Read-only (constant) contract call — used for `allowance(owner, spender)` so
+     * bridge-in can skip a redundant `approve`. Addresses go over the wire in the
+     * hex `41…` form (visible:false). Throws if the node reports the call reverted
+     * or returns no result word.
+     */
+    async constantCall(input) {
+        const res = await this.post('/wallet/triggerconstantcontract', {
+            owner_address: '41' + strip0x(input.ownerHex).toLowerCase(),
+            contract_address: '41' + strip0x(input.contractHex).toLowerCase(),
+            function_selector: input.functionSignature,
+            parameter: strip0x(input.parameterHex ?? ''),
+            visible: false,
+        });
+        const result = (res.result ?? {});
+        // `result.result === true` on success; a revert sets a code/message instead.
+        if (result.result !== true && (result.code != null || result.message != null)) {
+            const msg = typeof result.message === 'string' ? hexMessage(result.message) : String(result.code);
+            throw new Error(`triggerconstantcontract ${input.functionSignature} reverted: ${msg}`);
+        }
+        const cr = res.constant_result;
+        if (!Array.isArray(cr) || cr.length === 0 || typeof cr[0] !== 'string') {
+            throw new Error(`triggerconstantcontract ${input.functionSignature} returned no result`);
+        }
+        return strip0x(cr[0]);
+    }
+}
+/** Decode a possibly-hex Tron revert message into readable text (best effort). */
+function hexMessage(m) {
+    if (!/^[0-9a-fA-F]*$/.test(m) || m.length % 2 !== 0)
+        return m;
+    try {
+        const bytes = new Uint8Array(m.length / 2);
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = parseInt(m.slice(i * 2, i * 2 + 2), 16);
+        return new TextDecoder().decode(bytes).replace(/\0+/g, '').trim() || m;
+    }
+    catch {
+        return m;
+    }
+}

package/lib/tron/config.d.ts

@@ -0,0 +1,11 @@
+import { type BridgeAssetConfig } from '../config.js';
+/** Tron network ids (TronWeb genesis-derived chain ids). */
+export declare const TRON_MAINNET_CHAIN_ID = 728126428;
+export declare const TRON_NILE_CHAIN_ID = 3448148188;
+/** Canonical USDT (TRC20) contract on Tron mainnet. */
+export declare const TRON_MAINNET_USDT = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t";
+/** Canonical USDT (TRC20) contract on the Tron Nile testnet. */
+export declare const TRON_NILE_USDT = "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf";
+export declare const TRON_DEFAULT_CONFIRMATIONS = 20;
+export declare function tronMainnetUsdtConfig(lockContract: string, rpcUrl?: string): BridgeAssetConfig;
+export declare function tronNileUsdtConfig(lockContract: string, rpcUrl?: string): BridgeAssetConfig;

package/lib/tron/config.js

@@ -0,0 +1,31 @@
+import { DEFAULT_DECIMALS } from '../config.js';
+/** Tron network ids (TronWeb genesis-derived chain ids). */
+export const TRON_MAINNET_CHAIN_ID = 728126428; // 0x2b6653dc
+export const TRON_NILE_CHAIN_ID = 3448148188; // 0xcd8690dc
+/** Canonical USDT (TRC20) contract on Tron mainnet. */
+export const TRON_MAINNET_USDT = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t';
+/** Canonical USDT (TRC20) contract on the Tron Nile testnet. */
+export const TRON_NILE_USDT = 'TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf';
+export const TRON_DEFAULT_CONFIRMATIONS = 20;
+export function tronMainnetUsdtConfig(lockContract, rpcUrl = 'https://api.trongrid.io') {
+    return {
+        family: 'tron',
+        chainId: TRON_MAINNET_CHAIN_ID,
+        lockContract,
+        assetContract: TRON_MAINNET_USDT,
+        confirmations: TRON_DEFAULT_CONFIRMATIONS,
+        decimals: DEFAULT_DECIMALS,
+        rpcUrl,
+    };
+}
+export function tronNileUsdtConfig(lockContract, rpcUrl = 'https://nile.trongrid.io') {
+    return {
+        family: 'tron',
+        chainId: TRON_NILE_CHAIN_ID,
+        lockContract,
+        assetContract: TRON_NILE_USDT,
+        confirmations: TRON_DEFAULT_CONFIRMATIONS,
+        decimals: DEFAULT_DECIMALS,
+        rpcUrl,
+    };
+}

package/lib/tron/family.d.ts

@@ -0,0 +1,4 @@
+import type { ChainFamilyAdapter } from '../family.js';
+/** The CAIP-2-style chain reference for a Tron numeric chainId (`tron:0x<hex>`). */
+export declare function tronChainRef(chainId: number): string;
+export declare const tronFamily: ChainFamilyAdapter;

package/lib/tron/family.js

@@ -0,0 +1,18 @@
+import { toEvmAddressHex } from '../address.js';
+import { TRON_DEFAULT_CONFIRMATIONS } from './config.js';
+import { tronPresentation } from './presentation.js';
+import { TronHttpRpcClient } from './TronRpcClient.js';
+/** The CAIP-2-style chain reference for a Tron numeric chainId (`tron:0x<hex>`). */
+export function tronChainRef(chainId) {
+    return `tron:0x${chainId.toString(16)}`;
+}
+export const tronFamily = {
+    family: 'tron',
+    chainName: 'Tron',
+    defaultConfirmations: TRON_DEFAULT_CONFIRMATIONS,
+    blockSeconds: 3,
+    chainRef: tronChainRef,
+    normalizeAddress: toEvmAddressHex,
+    createRpc: ({ rpcUrl, apiKey }) => new TronHttpRpcClient({ baseUrl: rpcUrl ?? 'https://api.trongrid.io', apiKey }),
+    presentation: tronPresentation,
+};

package/lib/tron/presentation.d.ts

@@ -0,0 +1,10 @@
+/**
+ * What the wallet UI shows for a Tron chain without knowing Tron: the
+ * Tronscan link for a transaction and the shape of a valid destination.
+ */
+import type { BridgePresentation } from '@unicitylabs/bridge-core';
+/** Tronscan transaction URL for a Tron chainId (Nile testnet vs mainnet). */
+export declare function explorerTxUrl(chainId: number, txid: string): string;
+/** Structural validity of a Tron base58 (`T…`) address (a bridge-out destination). */
+export declare function isValidTronAddress(addr: string): boolean;
+export declare function tronPresentation(chainId: number): BridgePresentation;

package/lib/tron/presentation.js

@@ -0,0 +1,18 @@
+import { TRON_NILE_CHAIN_ID } from './config.js';
+/** Tronscan transaction URL for a Tron chainId (Nile testnet vs mainnet). */
+export function explorerTxUrl(chainId, txid) {
+    const base = chainId === TRON_NILE_CHAIN_ID
+        ? 'https://nile.tronscan.org/#/transaction/'
+        : 'https://tronscan.org/#/transaction/';
+    return base + txid;
+}
+/** Structural validity of a Tron base58 (`T…`) address (a bridge-out destination). */
+export function isValidTronAddress(addr) {
+    return /^T[1-9A-HJ-NP-Za-km-z]{33}$/.test(addr.trim());
+}
+export function tronPresentation(chainId) {
+    return {
+        explorerTxUrl: (txid) => explorerTxUrl(chainId, txid),
+        validateAddress: (addr) => isValidTronAddress(addr),
+    };
+}

package/lib/tron/providers.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Tron wallet providers (08 Phase 3 — wallet picker, adapter/WalletConnect seam).
+ *
+ * The bridge-in flow needs a {SourceSigner}; *which* wallet supplies it (injected
+ * TronLink, WalletConnect, a managed key) is a user choice. This is the small
+ * registry the picker renders: each {SourceWalletProvider} knows its id/name, whether
+ * it's usable here, and how to `create` a (not-yet-connected) `SourceSigner` for a
+ * given source chain. `runBridgeIn` then drives that signer uniformly — `connect()`
+ * prompts (TronLink authorize, or the WalletConnect QR), the rest is identical.
+ *
+ * TronLink (priority 1) needs no extra dependency and is implemented here.
+ * WalletConnect is wired by **injecting a signer factory** ({TronWalletConfig})
+ * from the app once `@tronweb3/walletconnect-tron` is installed and a `projectId`
+ * is configured — so this module (and everything that typechecks against it) has
+ * **no** dependency on the WalletConnect package. Until the factory is supplied,
+ * only TronLink is offered.
+ */
+import type { SourceSigner, SourceWalletProvider } from '../wallet/signer.js';
+import { type TronLinkWindow } from './signer.js';
+/** Stable ids for the wallets the picker can offer. */
+export type TronWalletId = 'tronlink' | 'walletconnect';
+/**
+ * Factory the app injects once `@tronweb3/walletconnect-tron` v4 is installed and a
+ * WalletConnect `projectId` is configured. Returns a `SourceSigner` that wraps the
+ * adapter (its `connect()` opens the WC modal). Keeping this a callback is what lets
+ * the plugin stay free of any WalletConnect dependency.
+ */
+export type WalletConnectSignerFactory = (chainId: number) => SourceSigner;
+/** App-supplied wallet configuration (which optional wallets to offer + how to build them). */
+export interface TronWalletConfig {
+    /** Present only when WalletConnect is configured (projectId set + factory wired). */
+    readonly walletConnect?: {
+        readonly signerFactory: WalletConnectSignerFactory;
+    };
+}
+/** Injected-TronLink provider (browser extension) — priority 1, no extra deps. */
+export declare function tronLinkProvider(win?: TronLinkWindow): SourceWalletProvider;
+/** WalletConnect provider built from the app-injected signer factory. */
+export declare function walletConnectProvider(factory: WalletConnectSignerFactory): SourceWalletProvider;
+/**
+ * The wallets to offer in the picker: TronLink always, plus WalletConnect when the
+ * app has configured it. Availability (extension present?) is left to the UI via
+ * `isAvailable()` — the list is not pre-filtered, so a missing TronLink can still be
+ * shown with an "install it" hint rather than silently vanishing.
+ */
+export declare function availableTronWallets(config?: TronWalletConfig): SourceWalletProvider[];

package/lib/tron/providers.js

@@ -0,0 +1,32 @@
+import { TronLinkSigner } from './signer.js';
+/** Injected-TronLink provider (browser extension) — priority 1, no extra deps. */
+export function tronLinkProvider(win = globalThis) {
+    return {
+        id: 'tronlink',
+        name: 'TronLink',
+        isAvailable: () => Boolean(win.tronWeb),
+        create: (chainId) => new TronLinkSigner(win, chainId),
+    };
+}
+/** WalletConnect provider built from the app-injected signer factory. */
+export function walletConnectProvider(factory) {
+    return {
+        id: 'walletconnect',
+        name: 'WalletConnect',
+        isAvailable: () => true, // usable on any device once configured (that's the point of WC)
+        create: (chainId) => factory(chainId),
+    };
+}
+/**
+ * The wallets to offer in the picker: TronLink always, plus WalletConnect when the
+ * app has configured it. Availability (extension present?) is left to the UI via
+ * `isAvailable()` — the list is not pre-filtered, so a missing TronLink can still be
+ * shown with an "install it" hint rather than silently vanishing.
+ */
+export function availableTronWallets(config = {}) {
+    const providers = [tronLinkProvider()];
+    if (config.walletConnect) {
+        providers.push(walletConnectProvider(config.walletConnect.signerFactory));
+    }
+    return providers;
+}

package/lib/tron/signer.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Tron signers behind the family-neutral {SourceSigner} (06 §A1.3, §W2; 08
+ * §1.2/§1.3): TronLink first, WalletConnect and a managed key behind the same
+ * surface. `connect()` prompts once; `getNetwork()` derives the wallet node's
+ * real chainId from its genesis block, so the caller can refuse to sign
+ * against the wrong chain.
+ */
+import type { ContractCall } from '../contract-call.js';
+import type { SourceSigner, WalletChange } from '../wallet/signer.js';
+export interface TronSendOptions {
+    /** Energy/bandwidth fee cap in SUN (1 TRX = 1e6 SUN). Default 150 TRX. */
+    readonly feeLimitSun?: number;
+    /** TRX (in SUN) to send with the call. Default 0. */
+    readonly callValueSun?: number;
+}
+/** Minimal shape of the TronWeb instance TronLink injects on `window`. */
+export interface InjectedTronWeb {
+    defaultAddress: {
+        base58: string | false;
+    };
+    fullNode?: {
+        host: string;
+    };
+    transactionBuilder: {
+        triggerSmartContract(contractAddress: string, functionSelector: string, options: Record<string, unknown>, parameters: readonly {
+            type: string;
+            value: string;
+        }[], issuerAddress: string): Promise<{
+            transaction: unknown;
+            result?: {
+                result?: boolean;
+            };
+        }>;
+    };
+    trx: {
+        sign(transaction: unknown): Promise<unknown>;
+        sendRawTransaction(signed: unknown): Promise<{
+            result?: boolean;
+            txid?: string;
+            transaction?: {
+                txID?: string;
+            };
+        }>;
+        getChainParameters?(): Promise<unknown>;
+        /** Genesis-block fetch — the source of the wallet's real chainId (08 §1.3). */
+        getBlockByNumber?(n: number): Promise<{
+            blockID?: string;
+        } | null>;
+    };
+    address: {
+        toHex(addr: string): string;
+    };
+}
+/** The browser injections TronLink exposes. */
+export interface TronLinkWindow {
+    tronLink?: {
+        request(args: {
+            method: string;
+        }): Promise<unknown>;
+    };
+    tronWeb?: InjectedTronWeb & {
+        ready?: boolean;
+    };
+    addEventListener?(type: string, listener: (e: unknown) => void): void;
+    removeEventListener?(type: string, listener: (e: unknown) => void): void;
+}
+/**
+ * Tron's chainId (as used by the bridge config, e.g. Nile `3448148188`) is the
+ * low 4 bytes of the genesis block's `blockID`. Deriving it from the wallet's
+ * connected node is a real network identity — not the manifest echoing itself.
+ */
+export declare function chainIdFromGenesisBlockId(blockId: string): number;
+/**
+ * TronLink-backed signer (priority 1). Uses the injected `window.tronWeb` for
+ * building + broadcasting; `tron_requestAccounts` prompts the connection once.
+ */
+export declare class TronLinkSigner implements SourceSigner {
+    /** The injected window (defaults to the global one in a browser). */
+    private readonly win;
+    /** Expected Tron chainId (from the manifest) — for the caller's wrong-network message. */
+    private readonly expectedChainId?;
+    /** True once `connect()` has prompted; `getAddress()` then reads live silently. */
+    private connected;
+    constructor(
+    /** The injected window (defaults to the global one in a browser). */
+    win?: TronLinkWindow, 
+    /** Expected Tron chainId (from the manifest) — for the caller's wrong-network message. */
+    expectedChainId?: number | undefined);
+    private tronWeb;
+    connect(): Promise<string>;
+    getAddress(): Promise<string>;
+    getNetwork(): Promise<number>;
+    onChange(cb: (e: WalletChange) => void): () => void;
+    /** The manifest's expected chainId, for building a clear wrong-network message. */
+    get expected(): number | undefined;
+    sendCall(call: ContractCall, opts?: TronSendOptions): Promise<string>;
+}
+/** Sign an unsigned Tron transaction, resolving to the signed form. */
+export type TronTxSign = (unsignedTx: unknown) => Promise<unknown>;
+/**
+ * Build → **sign (via `sign`)** → broadcast a call over any {InjectedTronWeb} (the
+ * dApp-broadcast model). The build + broadcast use `tw`; only the signature is the
+ * wallet's concern — so this serves both the injected path (`tw.trx.sign`) and
+ * adapter/WalletConnect (the adapter's `signTransaction`).
+ */
+export declare function sendCallSigned(tw: InjectedTronWeb, issuerBase58: string, call: ContractCall, sign: TronTxSign, opts?: TronSendOptions): Promise<string>;
+/**
+ * Shared build → sign → broadcast over any {InjectedTronWeb} (the dApp-broadcast
+ * model). TronLink prompts on `trx.sign`; a key-bearing TronWeb signs silently.
+ */
+export declare function sendCallVia(tw: InjectedTronWeb, issuerBase58: string, call: ContractCall, opts?: TronSendOptions): Promise<string>;
+/**
+ * A wallet that connects + signs but does **not** build/broadcast (WalletConnect,
+ * or any `@tronweb3/tronwallet-adapters` adapter). The app adapts the concrete
+ * adapter to this shape; {AdapterTronSigner} pairs it with a node TronWeb for the
+ * build/broadcast, so the plugin needs no WalletConnect/tronweb dependency.
+ */
+export interface AdapterWallet {
+    /** Connect (e.g. open the WalletConnect modal); resolve to the base58 address. */
+    connect(): Promise<string>;
+    /** Sign a built Tron transaction; resolve to the signed transaction. */
+    signTransaction(unsignedTx: unknown): Promise<unknown>;
+    /** Optional: subscribe to account/disconnect changes. */
+    onChange?(cb: (e: WalletChange) => void): () => void;
+    /** Optional: tear down the session. */
+    disconnect?(): Promise<void>;
+}
+/**
+ * A {SourceSigner} backed by an {AdapterWallet} (WalletConnect / adapter) for signing,
+ * plus a lazily-provided node TronWeb for build + broadcast. The node builds the tx
+ * against the bridge's chain, so the tx is bound to that chain regardless of what the
+ * remote wallet reports — hence `getNetwork()` returns the configured chainId (as
+ * {ManagedTronSigner} does), and the wrong-network guard is satisfied by construction.
+ */
+export declare class AdapterTronSigner implements SourceSigner {
+    private readonly wallet;
+    /** Lazily builds the node TronWeb (keeps the heavy `tronweb` import off the hot path). */
+    private readonly tronWebProvider;
+    private readonly chainId;
+    private address;
+    private tw;
+    constructor(wallet: AdapterWallet, 
+    /** Lazily builds the node TronWeb (keeps the heavy `tronweb` import off the hot path). */
+    tronWebProvider: () => Promise<InjectedTronWeb>, chainId: number);
+    connect(): Promise<string>;
+    getAddress(): Promise<string>;
+    getNetwork(): Promise<number>;
+    sendCall(call: ContractCall, opts?: TronSendOptions): Promise<string>;
+    onChange(cb: (e: WalletChange) => void): () => void;
+}
+/**
+ * Managed-key / WalletConnect signer (06 §W4): wraps a pre-built `TronWeb`-shaped
+ * object that already holds a key (managed: `new TronWeb({ privateKey })`; the
+ * proven `demo/tron.ts` path) or a WalletConnect-provided signer. No extension,
+ * no flow change — same `SourceSigner` surface, signs silently. Its network is
+ * known from construction (the node it was built against), so it's trusted.
+ */
+export declare class ManagedTronSigner implements SourceSigner {
+    private readonly tw;
+    private readonly chainId;
+    constructor(tw: InjectedTronWeb, chainId: number);
+    connect(): Promise<string>;
+    getAddress(): Promise<string>;
+    getNetwork(): Promise<number>;
+    sendCall(call: ContractCall, opts?: TronSendOptions): Promise<string>;
+}