@mapprotocol/common-contracts 0.3.1 → 0.3.2

package/utils/dist/factory.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evmDeployByFactory = evmDeployByFactory;
+exports.evmGetFactoryAddress = evmGetFactoryAddress;
+exports.tronDeployByFactory = tronDeployByFactory;
+exports.tronGetFactoryAddress = tronGetFactoryAddress;
+/**
+ * Factory deployment — deterministic contract addresses across chains.
+ * EVM: CREATE3 factory at 0x6258e4d2950757A749a4d4683A7342261ce12471
+ * Tron: CREATE2 factory at TJAwD5VfMYMGWwdPi2aVcoQwVBfsuw5wQt
+ */
+const tronHelper_1 = require("./tronHelper");
+// Factory contract addresses
+const EVM_FACTORY = "0x6258e4d2950757A749a4d4683A7342261ce12471";
+const TRON_FACTORY = "TJAwD5VfMYMGWwdPi2aVcoQwVBfsuw5wQt";
+// EVM factory ABI (CREATE3 — getAddress only needs salt)
+// function deploy(bytes32 salt, bytes creationCode, uint256 value)
+// function getAddress(bytes32 salt) view returns (address)
+const EVM_FACTORY_ABI = [
+    {
+        "inputs": [{ "name": "salt", "type": "bytes32" }, { "name": "creationCode", "type": "bytes" }, { "name": "value", "type": "uint256" }],
+        "name": "deploy",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "inputs": [{ "name": "salt", "type": "bytes32" }],
+        "name": "getAddress",
+        "outputs": [{ "name": "", "type": "address" }],
+        "stateMutability": "view",
+        "type": "function"
+    }
+];
+// Tron factory ABI (CREATE2 — getAddress needs salt + codeHash)
+// function deploy(bytes32 salt, bytes creationCode, uint256 value) returns (address)
+// function getAddress(bytes32 salt, bytes32 codeHash) view returns (address)
+// function getAddressTron(bytes32 salt, bytes32 codeHash) view returns (address)
+const TRON_FACTORY_ABI = [
+    {
+        "inputs": [{ "name": "salt", "type": "bytes32" }, { "name": "creationCode", "type": "bytes" }, { "name": "value", "type": "uint256" }],
+        "name": "deploy",
+        "outputs": [{ "name": "addr", "type": "address" }],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    },
+    {
+        "inputs": [{ "name": "salt", "type": "bytes32" }, { "name": "codeHash", "type": "bytes32" }],
+        "name": "getAddressTron",
+        "outputs": [{ "name": "", "type": "address" }],
+        "stateMutability": "view",
+        "type": "function"
+    }
+];
+// ============================================================
+// EVM Factory (CREATE3, ethers.js)
+// ============================================================
+/**
+ * Deploy contract via CREATE3 factory on EVM chains.
+ * Address only depends on salt, not bytecode.
+ * @param ethers - ethers from hardhat runtime (hre.ethers)
+ * @param salt - human-readable salt string
+ * @param bytecode - contract bytecode (artifact.bytecode)
+ * @param constructorArgs - ABI-encoded constructor arguments
+ * @returns deployed contract address
+ */
+async function evmDeployByFactory(ethers, salt, bytecode, constructorArgs = "0x") {
+    const [signer] = await ethers.getSigners();
+    const factory = new ethers.Contract(EVM_FACTORY, EVM_FACTORY_ABI, signer);
+    const code = await ethers.provider.getCode(EVM_FACTORY);
+    if (code === "0x")
+        throw new Error("factory not deployed on this chain");
+    const saltHash = ethers.keccak256(ethers.toUtf8Bytes(salt));
+    const predicted = await factory.getAddress(saltHash);
+    const existingCode = await ethers.provider.getCode(predicted);
+    if (existingCode !== "0x") {
+        console.log(`already deployed at ${predicted}`);
+        return predicted;
+    }
+    const fullBytecode = constructorArgs === "0x"
+        ? bytecode
+        : ethers.concat([bytecode, constructorArgs]);
+    const tx = await factory.deploy(saltHash, fullBytecode, 0);
+    await tx.wait();
+    // Verify contract was actually deployed
+    const deployedCode = await ethers.provider.getCode(predicted);
+    if (deployedCode === "0x") {
+        throw new Error(`factory deploy failed: no contract at predicted address ${predicted}`);
+    }
+    console.log(`deployed via factory at ${predicted}`);
+    return predicted;
+}
+/**
+ * Get predicted factory address for a salt on EVM (CREATE3 — only needs salt).
+ * @param ethers - ethers from hardhat runtime
+ * @param salt - human-readable salt string
+ */
+async function evmGetFactoryAddress(ethers, salt) {
+    const factory = new ethers.Contract(EVM_FACTORY, EVM_FACTORY_ABI, await ethers.provider);
+    const saltHash = ethers.keccak256(ethers.toUtf8Bytes(salt));
+    return factory.getAddress(saltHash);
+}
+// ============================================================
+// Tron Factory (CREATE2, tronweb)
+// ============================================================
+/**
+ * Deploy contract via CREATE2 factory on Tron.
+ * Address depends on salt + creationCode (bytecode + constructor args).
+ * @param tronWeb - initialized tronweb instance
+ * @param artifacts - hardhat artifacts
+ * @param contractName - contract name to deploy
+ * @param salt - human-readable salt string
+ * @param args - constructor arguments array
+ * @param feeLimit - tron fee limit
+ * @returns deployed contract address (0x-prefixed hex)
+ */
+async function tronDeployByFactory(tronWeb, artifacts, contractName, salt, args = [], feeLimit = 15000000000) {
+    const factory = await tronWeb.contract(TRON_FACTORY_ABI, TRON_FACTORY);
+    const saltHash = tronWeb.sha3(salt);
+    // Build creation code with constructor args
+    const artifact = await artifacts.readArtifact(contractName);
+    let creationCode = artifact.bytecode;
+    if (args.length > 0) {
+        const iface = new (require("ethers").Interface)(artifact.abi);
+        const encoded = iface.encodeDeploy(args);
+        creationCode = creationCode + encoded.slice(2);
+    }
+    // Check if already deployed
+    const codeHash = tronWeb.sha3(creationCode);
+    const predicted = await factory.getAddressTron(saltHash, codeHash).call();
+    const predictedHex = predicted.replace(/^41/, "0x");
+    try {
+        const existing = await tronWeb.trx.getContract(tronWeb.address.fromHex(predicted));
+        if (existing && existing.bytecode) {
+            console.log(`already deployed at ${(0, tronHelper_1.tronFromHex)(predicted)}`);
+            return predictedHex;
+        }
+    }
+    catch { }
+    // Deploy
+    console.log(`deploying ${contractName} via factory with salt "${salt}"...`);
+    const { sendAndWait } = require("./tronHelper");
+    const txResult = await sendAndWait(factory.deploy(saltHash, creationCode, 0), tronWeb, { feeLimit });
+    // Read actual address from Deployed event
+    let addrHex = predictedHex; // fallback to predicted
+    if (txResult.log && txResult.log.length > 0) {
+        // Deployed(address indexed addr, bytes32 indexed salt)
+        // First topic = event sig, second topic = addr
+        const addrTopic = txResult.log[0].topics?.[1];
+        if (addrTopic) {
+            addrHex = "0x" + addrTopic.slice(24); // last 20 bytes
+        }
+    }
+    // Verify contract was actually deployed
+    const addrBase58 = (0, tronHelper_1.tronFromHex)(addrHex);
+    try {
+        const deployed = await tronWeb.trx.getContract(addrBase58);
+        if (!deployed || !deployed.bytecode) {
+            throw new Error(`factory deploy failed: no contract at ${addrBase58}`);
+        }
+    }
+    catch (e) {
+        if (e.message?.includes("factory deploy failed"))
+            throw e;
+        // Contract might not be indexed yet, wait and retry
+        await new Promise(r => setTimeout(r, 3000));
+        const deployed = await tronWeb.trx.getContract(addrBase58);
+        if (!deployed || !deployed.bytecode) {
+            throw new Error(`factory deploy failed: no contract at ${addrBase58}`);
+        }
+    }
+    console.log(`${contractName} deployed: ${addrBase58} (${addrHex})`);
+    return addrHex;
+}
+/**
+ * Get predicted factory address for a salt on Tron (CREATE2 — needs salt + codeHash).
+ * @param tronWeb - initialized tronweb instance
+ * @param salt - human-readable salt string
+ * @param codeHash - keccak256 of creationCode (bytecode + constructor args)
+ * @returns address in base58 format
+ */
+async function tronGetFactoryAddress(tronWeb, salt, codeHash) {
+    const factory = await tronWeb.contract(TRON_FACTORY_ABI, TRON_FACTORY);
+    const saltHash = tronWeb.sha3(salt);
+    const addr = await factory.getAddressTron(saltHash, codeHash).call();
+    return (0, tronHelper_1.tronFromHex)(addr);
+}

package/utils/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @mapprotocol/common-contracts/utils
+ *
+ * Shared TypeScript utilities for MAP Protocol contract operations.
+ *
+ * Quick start:
+ *   const deployer = createDeployer(hre, { autoVerify: true });
+ *   await deployer.deploy("MyContract", [arg1], "optional_salt");
+ *   await deployer.deployProxy("MyContract", [initArg], "optional_salt");
+ *   await deployer.upgrade("MyContract", proxyAddr);
+ */
+export { createDeployer, type Deployer, type DeployResult, type DeployProxyResult, type DeployerOptions } from "./deployer";
+export { resolveDeploymentPath, getDeploymentByKey, hasDeployment, saveDeployment, type DeploymentPath, type DeploymentOptions } from "./deployRecord";
+export { verify, type VerifyOptions } from "./verifier";
+export { getCodeHash, getProxyCodeHash, getCustomProxyCodeHash } from "./codeHash";
+export { addressToHex, isBase58, isTronAddress, isSolanaChain } from "./addressCodec";
+export { TronClient, tronFromHex, tronToHex, isTronNetwork, sendAndWait, waitForTx, type TronAddress } from "./tronHelper";

package/utils/dist/index.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * @mapprotocol/common-contracts/utils
+ *
+ * Shared TypeScript utilities for MAP Protocol contract operations.
+ *
+ * Quick start:
+ *   const deployer = createDeployer(hre, { autoVerify: true });
+ *   await deployer.deploy("MyContract", [arg1], "optional_salt");
+ *   await deployer.deployProxy("MyContract", [initArg], "optional_salt");
+ *   await deployer.upgrade("MyContract", proxyAddr);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitForTx = exports.sendAndWait = exports.isTronNetwork = exports.tronToHex = exports.tronFromHex = exports.TronClient = exports.isSolanaChain = exports.isTronAddress = exports.isBase58 = exports.addressToHex = exports.getCustomProxyCodeHash = exports.getProxyCodeHash = exports.getCodeHash = exports.verify = exports.saveDeployment = exports.hasDeployment = exports.getDeploymentByKey = exports.resolveDeploymentPath = exports.createDeployer = void 0;
+// Unified deployer — recommended entry point for deploy/upgrade/verify
+var deployer_1 = require("./deployer");
+Object.defineProperty(exports, "createDeployer", { enumerable: true, get: function () { return deployer_1.createDeployer; } });
+// Deploy record — deploy.json address management
+var deployRecord_1 = require("./deployRecord");
+Object.defineProperty(exports, "resolveDeploymentPath", { enumerable: true, get: function () { return deployRecord_1.resolveDeploymentPath; } });
+Object.defineProperty(exports, "getDeploymentByKey", { enumerable: true, get: function () { return deployRecord_1.getDeploymentByKey; } });
+Object.defineProperty(exports, "hasDeployment", { enumerable: true, get: function () { return deployRecord_1.hasDeployment; } });
+Object.defineProperty(exports, "saveDeployment", { enumerable: true, get: function () { return deployRecord_1.saveDeployment; } });
+// Contract verification
+var verifier_1 = require("./verifier");
+Object.defineProperty(exports, "verify", { enumerable: true, get: function () { return verifier_1.verify; } });
+// Code hash for CREATE2 address prediction
+var codeHash_1 = require("./codeHash");
+Object.defineProperty(exports, "getCodeHash", { enumerable: true, get: function () { return codeHash_1.getCodeHash; } });
+Object.defineProperty(exports, "getProxyCodeHash", { enumerable: true, get: function () { return codeHash_1.getProxyCodeHash; } });
+Object.defineProperty(exports, "getCustomProxyCodeHash", { enumerable: true, get: function () { return codeHash_1.getCustomProxyCodeHash; } });
+// Address encoding
+var addressCodec_1 = require("./addressCodec");
+Object.defineProperty(exports, "addressToHex", { enumerable: true, get: function () { return addressCodec_1.addressToHex; } });
+Object.defineProperty(exports, "isBase58", { enumerable: true, get: function () { return addressCodec_1.isBase58; } });
+Object.defineProperty(exports, "isTronAddress", { enumerable: true, get: function () { return addressCodec_1.isTronAddress; } });
+Object.defineProperty(exports, "isSolanaChain", { enumerable: true, get: function () { return addressCodec_1.isSolanaChain; } });
+// Tron utilities
+var tronHelper_1 = require("./tronHelper");
+Object.defineProperty(exports, "TronClient", { enumerable: true, get: function () { return tronHelper_1.TronClient; } });
+Object.defineProperty(exports, "tronFromHex", { enumerable: true, get: function () { return tronHelper_1.tronFromHex; } });
+Object.defineProperty(exports, "tronToHex", { enumerable: true, get: function () { return tronHelper_1.tronToHex; } });
+Object.defineProperty(exports, "isTronNetwork", { enumerable: true, get: function () { return tronHelper_1.isTronNetwork; } });
+Object.defineProperty(exports, "sendAndWait", { enumerable: true, get: function () { return tronHelper_1.sendAndWait; } });
+Object.defineProperty(exports, "waitForTx", { enumerable: true, get: function () { return tronHelper_1.waitForTx; } });

package/utils/dist/tronHelper.d.ts

@@ -0,0 +1,127 @@
+/** Convert hex address to Tron base58 format. Returns as-is if already base58. */
+export declare function tronFromHex(hex: string): string;
+/** Convert Tron base58 address to 0x-prefixed hex. Returns as-is if already hex. */
+export declare function tronToHex(addr: string): string;
+/** Check if a network name or chainId belongs to Tron (case-insensitive). */
+export declare function isTronNetwork(networkOrChainId: string | number): boolean;
+export interface TronAddress {
+    hex: string;
+    base58: string;
+}
+/**
+ * TronClient — encapsulates tronWeb instance, provides high-level contract operations.
+ *
+ * Usage:
+ *   // From hardhat runtime (recommended in tasks)
+ *   let client = TronClient.fromHre(hre);
+ *
+ *   // Manual — with rpc and private key
+ *   let client = new TronClient("https://api.trongrid.io", "your_private_key");
+ *
+ *   // Read-only — no private key
+ *   let client = new TronClient("https://api.trongrid.io");
+ *
+ *   // Contract interaction
+ *   let gw = await client.getContract(artifacts, "Gateway", addr);
+ *   let wtoken = await gw.wToken().call();                      // read
+ *   await gw.setWtoken(client.toHex(wtoken)).sendAndWait();     // write + wait
+ *
+ *   // Deploy
+ *   let { hex, base58 } = await client.deploy(artifacts, "Gateway");
+ *   let { proxy, implementation } = await client.deployProxy(artifacts, "Gateway", [admin]);
+ *
+ *   // Upgrade
+ *   await client.upgradeProxy(artifacts, "Gateway", proxyAddr);
+ */
+export declare class TronClient {
+    private tronWeb;
+    private connected;
+    /**
+     * Create a TronClient with explicit rpcUrl.
+     * @param rpcUrl - Tron full host URL (e.g. "https://api.trongrid.io")
+     * @param privateKey - optional, omit for read-only operations
+     */
+    constructor(rpcUrl: string, privateKey?: string);
+    /**
+     * Create TronClient from hardhat runtime environment.
+     * Reads rpcUrl and privateKey from hre.network.config. Verifies RPC connectivity.
+     */
+    static fromHre(hre: any): TronClient;
+    /** Verify RPC is reachable. Uses getNowBlock which is widely supported. */
+    private _checkConnection;
+    /** Lazy connection check — called before first contract operation. */
+    private _ensureConnected;
+    /** Get the default operator address in base58 format. */
+    get defaultAddress(): string;
+    /** Convert Tron base58 address to 0x hex. */
+    toHex(addr: string): string;
+    /** Convert 0x hex to Tron base58 address. */
+    fromHex(hex: string): string;
+    /**
+     * Get a contract instance. Write methods have .sendAndWait() attached.
+     * @param artifacts - hardhat artifacts (hre.artifacts)
+     * @param contractName - contract name (e.g. "Gateway")
+     * @param addr - contract address (base58 or hex)
+     */
+    getContract(artifacts: any, contractName: string, addr: string): Promise<any>;
+    /**
+     * Deploy contract. If salt is provided, uses CREATE2 factory.
+     * @param artifacts - hardhat artifacts
+     * @param contractName - contract name to deploy
+     * @param args - constructor arguments
+     * @param salt - optional CREATE2 salt for deterministic address
+     * @param feeLimit - Tron fee limit (default 15 TRX)
+     */
+    deploy(artifacts: any, contractName: string, args?: any[], salt?: string, feeLimit?: number): Promise<TronAddress>;
+    /**
+     * Deploy implementation + ERC1967 proxy. If salt is provided, proxy uses factory.
+     * @param artifacts - hardhat artifacts
+     * @param contractName - implementation contract name
+     * @param initArgs - initialize() function arguments
+     * @param salt - optional CREATE2 salt for proxy
+     * @param feeLimit - Tron fee limit
+     */
+    deployProxy(artifacts: any, contractName: string, initArgs?: any[], salt?: string, feeLimit?: number): Promise<{
+        proxy: TronAddress;
+        implementation: TronAddress;
+    }>;
+    /**
+     * Upgrade a UUPS proxy to a new implementation.
+     * @param artifacts - hardhat artifacts
+     * @param contractName - new implementation contract name
+     * @param proxyAddr - proxy address to upgrade
+     * @param feeLimit - Tron fee limit
+     */
+    upgradeProxy(artifacts: any, contractName: string, proxyAddr: string, feeLimit?: number): Promise<TronAddress>;
+    /**
+     * Wait for a transaction to be confirmed on-chain.
+     * @param txId - transaction hash from .send()
+     */
+    waitForTx(txId: string, retries?: number, interval?: number): Promise<any>;
+    /** Wrap contract methods — adds .sendAndWait() to write methods. */
+    private _wrapContract;
+}
+/** @internal Deploy contract on Tron. If salt is provided, uses CREATE2 factory. */
+export declare function tronDeploy(tronWeb: any, artifacts: any, contractName: string, args?: any[], salt?: string, feeLimit?: number): Promise<TronAddress>;
+/** @internal Deploy implementation + ERC1967 proxy on Tron. */
+export declare function tronDeployProxy(tronWeb: any, artifacts: any, contractName: string, initArgs?: any[], salt?: string, feeLimit?: number): Promise<{
+    proxy: TronAddress;
+    implementation: TronAddress;
+}>;
+/** @internal Upgrade a UUPS proxy to a new implementation on Tron. */
+export declare function tronUpgradeProxy(tronWeb: any, artifacts: any, contractName: string, proxyAddr: string, feeLimit?: number): Promise<TronAddress>;
+/**
+ * Send a tron contract call and wait for on-chain confirmation.
+ * @param methodCall - tronweb contract method call (e.g. contract.setWtoken(addr))
+ * @param tronWeb - tronweb instance for querying tx status
+ * @param opts - send options (feeLimit, callValue, etc.)
+ */
+export declare function sendAndWait(methodCall: any, tronWeb: any, opts?: Record<string, any>): Promise<any>;
+/**
+ * Wait for a Tron transaction to be confirmed on-chain.
+ * @param tronWeb - tronweb instance
+ * @param txId - transaction hash returned by .send()
+ * @param retries - max poll attempts (default 20)
+ * @param interval - poll interval in ms (default 3000)
+ */
+export declare function waitForTx(tronWeb: any, txId: string, retries?: number, interval?: number): Promise<any>;

package/utils/dist/tronHelper.js

@@ -0,0 +1,291 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TronClient = void 0;
+exports.tronFromHex = tronFromHex;
+exports.tronToHex = tronToHex;
+exports.isTronNetwork = isTronNetwork;
+exports.tronDeploy = tronDeploy;
+exports.tronDeployProxy = tronDeployProxy;
+exports.tronUpgradeProxy = tronUpgradeProxy;
+exports.sendAndWait = sendAndWait;
+exports.waitForTx = waitForTx;
+let TronWeb = require("tronweb");
+// ============================================================
+// Pure address conversion — no RPC, no private key needed
+// ============================================================
+/** Convert hex address to Tron base58 format. Returns as-is if already base58. */
+function tronFromHex(hex) {
+    if (hex.startsWith("T") && hex.length === 34)
+        return hex;
+    return TronWeb.address.fromHex(hex);
+}
+/** Convert Tron base58 address to 0x-prefixed hex. Returns as-is if already hex. */
+function tronToHex(addr) {
+    if (addr.startsWith("0x") && addr.length === 42)
+        return addr;
+    return TronWeb.address.toHex(addr).replace(/^(41)/, "0x");
+}
+// Tron chainIds: mainnet 728126428, nile testnet 3448148188
+const TRON_CHAIN_IDS = [728126428, 3448148188];
+/** Check if a network name or chainId belongs to Tron (case-insensitive). */
+function isTronNetwork(networkOrChainId) {
+    if (typeof networkOrChainId === "number") {
+        return TRON_CHAIN_IDS.includes(networkOrChainId);
+    }
+    return networkOrChainId.toLowerCase().startsWith("tron");
+}
+// ============================================================
+// TronClient
+// ============================================================
+/**
+ * TronClient — encapsulates tronWeb instance, provides high-level contract operations.
+ *
+ * Usage:
+ *   // From hardhat runtime (recommended in tasks)
+ *   let client = TronClient.fromHre(hre);
+ *
+ *   // Manual — with rpc and private key
+ *   let client = new TronClient("https://api.trongrid.io", "your_private_key");
+ *
+ *   // Read-only — no private key
+ *   let client = new TronClient("https://api.trongrid.io");
+ *
+ *   // Contract interaction
+ *   let gw = await client.getContract(artifacts, "Gateway", addr);
+ *   let wtoken = await gw.wToken().call();                      // read
+ *   await gw.setWtoken(client.toHex(wtoken)).sendAndWait();     // write + wait
+ *
+ *   // Deploy
+ *   let { hex, base58 } = await client.deploy(artifacts, "Gateway");
+ *   let { proxy, implementation } = await client.deployProxy(artifacts, "Gateway", [admin]);
+ *
+ *   // Upgrade
+ *   await client.upgradeProxy(artifacts, "Gateway", proxyAddr);
+ */
+class TronClient {
+    /**
+     * Create a TronClient with explicit rpcUrl.
+     * @param rpcUrl - Tron full host URL (e.g. "https://api.trongrid.io")
+     * @param privateKey - optional, omit for read-only operations
+     */
+    constructor(rpcUrl, privateKey) {
+        this.connected = false;
+        const opts = { fullHost: rpcUrl };
+        if (privateKey) {
+            // TronWeb doesn't accept 0x prefix on private keys
+            opts.privateKey = privateKey.startsWith("0x") ? privateKey.slice(2) : privateKey;
+        }
+        this.tronWeb = new TronWeb(opts);
+    }
+    /**
+     * Create TronClient from hardhat runtime environment.
+     * Reads rpcUrl and privateKey from hre.network.config. Verifies RPC connectivity.
+     */
+    static fromHre(hre) {
+        const config = hre.network.config;
+        let rpcUrl = config.url;
+        let privateKey = Array.isArray(config.accounts) ? config.accounts[0] : undefined;
+        if (!rpcUrl)
+            throw new Error(`no rpc url configured for network ${hre.network.name}`);
+        // Hardhat config uses JSON-RPC path (e.g. /jsonrpc), TronWeb needs base URL
+        rpcUrl = rpcUrl.replace(/\/(jsonrpc|wallet|solidity)\/?$/i, "");
+        // TronWeb doesn't accept 0x prefix on private keys
+        if (privateKey && privateKey.startsWith("0x")) {
+            privateKey = privateKey.slice(2);
+        }
+        return new TronClient(rpcUrl, privateKey);
+    }
+    /** Verify RPC is reachable. Uses getNowBlock which is widely supported. */
+    async _checkConnection() {
+        if (this.connected)
+            return;
+        try {
+            // getNowBlock calls /wallet/getnowblock — more universally supported than getNodeInfo
+            await this.tronWeb.trx.getCurrentBlock();
+            this.connected = true;
+        }
+        catch (e) {
+            const url = this.tronWeb.fullNode?.host || "unknown";
+            throw new Error(`TronClient: cannot connect to ${url}. ` +
+                `Ensure the URL is a valid TronWeb full host (e.g. "https://api.trongrid.io") and is reachable. ` +
+                `Error: ${e.message || e}`);
+        }
+    }
+    /** Lazy connection check — called before first contract operation. */
+    async _ensureConnected() {
+        if (!this.connected)
+            await this._checkConnection();
+    }
+    /** Get the default operator address in base58 format. */
+    get defaultAddress() {
+        return this.tronWeb.defaultAddress.base58;
+    }
+    /** Convert Tron base58 address to 0x hex. */
+    toHex(addr) {
+        return tronToHex(addr);
+    }
+    /** Convert 0x hex to Tron base58 address. */
+    fromHex(hex) {
+        return tronFromHex(hex);
+    }
+    /**
+     * Get a contract instance. Write methods have .sendAndWait() attached.
+     * @param artifacts - hardhat artifacts (hre.artifacts)
+     * @param contractName - contract name (e.g. "Gateway")
+     * @param addr - contract address (base58 or hex)
+     */
+    async getContract(artifacts, contractName, addr) {
+        await this._ensureConnected();
+        console.log("operator address is:", this.defaultAddress);
+        const artifact = await artifacts.readArtifact(contractName);
+        const contract = await this.tronWeb.contract(artifact.abi, addr);
+        return this._wrapContract(contract);
+    }
+    /**
+     * Deploy contract. If salt is provided, uses CREATE2 factory.
+     * @param artifacts - hardhat artifacts
+     * @param contractName - contract name to deploy
+     * @param args - constructor arguments
+     * @param salt - optional CREATE2 salt for deterministic address
+     * @param feeLimit - Tron fee limit (default 15 TRX)
+     */
+    async deploy(artifacts, contractName, args = [], salt = "", feeLimit = 15000000000) {
+        await this._ensureConnected();
+        return tronDeploy(this.tronWeb, artifacts, contractName, args, salt, feeLimit);
+    }
+    /**
+     * Deploy implementation + ERC1967 proxy. If salt is provided, proxy uses factory.
+     * @param artifacts - hardhat artifacts
+     * @param contractName - implementation contract name
+     * @param initArgs - initialize() function arguments
+     * @param salt - optional CREATE2 salt for proxy
+     * @param feeLimit - Tron fee limit
+     */
+    async deployProxy(artifacts, contractName, initArgs = [], salt = "", feeLimit = 15000000000) {
+        await this._ensureConnected();
+        return tronDeployProxy(this.tronWeb, artifacts, contractName, initArgs, salt, feeLimit);
+    }
+    /**
+     * Upgrade a UUPS proxy to a new implementation.
+     * @param artifacts - hardhat artifacts
+     * @param contractName - new implementation contract name
+     * @param proxyAddr - proxy address to upgrade
+     * @param feeLimit - Tron fee limit
+     */
+    async upgradeProxy(artifacts, contractName, proxyAddr, feeLimit = 15000000000) {
+        await this._ensureConnected();
+        return tronUpgradeProxy(this.tronWeb, artifacts, contractName, proxyAddr, feeLimit);
+    }
+    /**
+     * Wait for a transaction to be confirmed on-chain.
+     * @param txId - transaction hash from .send()
+     */
+    async waitForTx(txId, retries = 20, interval = 3000) {
+        return waitForTx(this.tronWeb, txId, retries, interval);
+    }
+    /** Wrap contract methods — adds .sendAndWait() to write methods. */
+    _wrapContract(contract) {
+        const tronWeb = this.tronWeb;
+        return new Proxy(contract, {
+            get(target, prop) {
+                const original = target[prop];
+                if (typeof original !== "function")
+                    return original;
+                return (...args) => {
+                    const methodCall = original.apply(target, args);
+                    if (methodCall && typeof methodCall.send === "function") {
+                        methodCall.sendAndWait = (opts) => sendAndWait(methodCall, tronWeb, opts);
+                    }
+                    return methodCall;
+                };
+            }
+        });
+    }
+}
+exports.TronClient = TronClient;
+// ============================================================
+// Low-level functions (used internally by TronClient)
+// ============================================================
+/** @internal Deploy contract on Tron. If salt is provided, uses CREATE2 factory. */
+async function tronDeploy(tronWeb, artifacts, contractName, args = [], salt = "", feeLimit = 15000000000) {
+    if (salt) {
+        const { tronDeployByFactory } = require("./factory");
+        const hex = await tronDeployByFactory(tronWeb, artifacts, contractName, salt, args, feeLimit);
+        return { hex, base58: tronFromHex(hex) };
+    }
+    const artifact = await artifacts.readArtifact(contractName);
+    console.log("deploy address is:", tronWeb.defaultAddress.base58);
+    const instance = await tronWeb.contract().new({
+        abi: artifact.abi,
+        bytecode: artifact.bytecode,
+        feeLimit,
+        callValue: 0,
+        parameters: args,
+    });
+    const rawAddress = instance.address; // 41-prefixed hex
+    const hex = rawAddress.replace(/^41/, "0x");
+    const base58 = tronWeb.address.fromHex(rawAddress);
+    console.log(`${contractName} deployed: ${base58} (${hex})`);
+    return { hex, base58 };
+}
+/** @internal Deploy implementation + ERC1967 proxy on Tron. */
+async function tronDeployProxy(tronWeb, artifacts, contractName, initArgs = [], salt = "", feeLimit = 15000000000) {
+    const implementation = await tronDeploy(tronWeb, artifacts, contractName, [], "", feeLimit);
+    console.log(`${contractName} implementation: ${implementation.base58} (${implementation.hex})`);
+    // Wait for implementation to be fully confirmed before deploying proxy
+    if (salt) {
+        console.log("waiting for implementation to be indexed...");
+        await new Promise(r => setTimeout(r, 5000));
+    }
+    const artifact = await artifacts.readArtifact(contractName);
+    const iface = new (require("ethers").Interface)(artifact.abi);
+    const initData = iface.encodeFunctionData("initialize", initArgs);
+    const proxy = await tronDeploy(tronWeb, artifacts, "ERC1967Proxy", [implementation.hex, initData], salt, feeLimit);
+    console.log(`${contractName} proxy: ${proxy.base58} (${proxy.hex})`);
+    return { proxy, implementation };
+}
+/** @internal Upgrade a UUPS proxy to a new implementation on Tron. */
+async function tronUpgradeProxy(tronWeb, artifacts, contractName, proxyAddr, feeLimit = 15000000000) {
+    const impl = await tronDeploy(tronWeb, artifacts, contractName, [], "", feeLimit);
+    console.log(`${contractName} new implementation: ${impl.base58} (${impl.hex})`);
+    const artifact = await artifacts.readArtifact("BaseImplementation");
+    const proxyContract = await tronWeb.contract(artifact.abi, proxyAddr);
+    const oldImpl = await proxyContract.getImplementation().call();
+    console.log(`old implementation: ${tronFromHex(oldImpl)}`);
+    await sendAndWait(proxyContract.upgradeToAndCall(impl.hex, "0x"), tronWeb, { feeLimit });
+    const newImpl = await proxyContract.getImplementation().call();
+    console.log(`${contractName} upgraded: ${tronFromHex(oldImpl)} -> ${tronFromHex(newImpl)}`);
+    return impl;
+}
+/**
+ * Send a tron contract call and wait for on-chain confirmation.
+ * @param methodCall - tronweb contract method call (e.g. contract.setWtoken(addr))
+ * @param tronWeb - tronweb instance for querying tx status
+ * @param opts - send options (feeLimit, callValue, etc.)
+ */
+async function sendAndWait(methodCall, tronWeb, opts = {}) {
+    const txId = await methodCall.send(opts);
+    return waitForTx(tronWeb, txId);
+}
+/**
+ * Wait for a Tron transaction to be confirmed on-chain.
+ * @param tronWeb - tronweb instance
+ * @param txId - transaction hash returned by .send()
+ * @param retries - max poll attempts (default 20)
+ * @param interval - poll interval in ms (default 3000)
+ */
+async function waitForTx(tronWeb, txId, retries = 20, interval = 3000) {
+    console.log(`waiting for tx ${txId}...`);
+    for (let i = 0; i < retries; i++) {
+        const result = await tronWeb.trx.getTransactionInfo(txId);
+        if (result && result.id) {
+            if (result.receipt?.result === "SUCCESS") {
+                console.log(`tx confirmed in block ${result.blockNumber}`);
+                return result;
+            }
+            throw new Error(`tx failed: ${result.receipt?.result || "UNKNOWN"}`);
+        }
+        await new Promise(r => setTimeout(r, interval));
+    }
+    throw new Error(`tx not confirmed after ${retries} retries: ${txId}`);
+}