@mapprotocol/common-contracts 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapprotocol/common-contracts",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Common contracts for MAP Protocol",
   "main": "typechain-types/index.js",
   "types": "typechain-types/index.d.ts",
@@ -10,6 +10,7 @@
     "!artifacts/contracts/**/*.dbg.json",
     "typechain-types/**/*",
     "utils/**/*.ts",
+    "utils/dist/**/*",
     "README.md"
   ],
   "repository": {
@@ -31,12 +32,13 @@
     "test": "forge test",
     "test:hardhat": "hardhat test",
     "format": "forge fmt",
-    "clean": "forge clean && hardhat clean && rm -rf typechain-types",
+    "build:utils": "cd utils && tsc",
+    "clean": "forge clean && hardhat clean && rm -rf typechain-types utils/dist",
     "compile": "hardhat compile",
     "typecheck": "tsc --noEmit",
     "gas-report": "forge test --gas-report",
     "coverage": "forge coverage",
-    "prepublishOnly": "npm run clean && npm run build:hardhat && npm run typecheck"
+    "prepublishOnly": "npm run clean && npm run build:hardhat && npm run build:utils && npm run typecheck"
   },
   "keywords": [
     "solidity",

package/utils/dist/addressCodec.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Convert any address format to hex bytes.
+ * - EVM address (0x prefix): return as-is lowercase
+ * - Tron address (T prefix, 34 chars, 0x41 byte): convert via tronToHex
+ * - Solana/other base58 address: base58 decode to full bytes
+ * @param addr - address in any supported format
+ */
+export declare function addressToHex(addr: string): string;
+/** Check if a string is valid base58 encoding. */
+export declare function isBase58(addr: string): boolean;
+/** Check if address is Tron format (T prefix, 34 chars, 0x41 first byte after decode). */
+export declare function isTronAddress(addr: string): boolean;
+/** Check if chain name is Solana. */
+export declare function isSolanaChain(chainName: string): boolean;

package/utils/dist/addressCodec.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addressToHex = addressToHex;
+exports.isBase58 = isBase58;
+exports.isTronAddress = isTronAddress;
+exports.isSolanaChain = isSolanaChain;
+/**
+ * Multi-chain address encoding — converts EVM, Tron, and Solana addresses to hex bytes.
+ */
+const bs58_1 = __importDefault(require("bs58"));
+const tronHelper_1 = require("./tronHelper");
+/**
+ * Convert any address format to hex bytes.
+ * - EVM address (0x prefix): return as-is lowercase
+ * - Tron address (T prefix, 34 chars, 0x41 byte): convert via tronToHex
+ * - Solana/other base58 address: base58 decode to full bytes
+ * @param addr - address in any supported format
+ */
+function addressToHex(addr) {
+    if (addr.startsWith("0x")) {
+        return addr.toLowerCase();
+    }
+    if (isTronAddress(addr)) {
+        return (0, tronHelper_1.tronToHex)(addr);
+    }
+    if (isBase58(addr)) {
+        const decoded = bs58_1.default.decode(addr);
+        return "0x" + Buffer.from(decoded).toString("hex");
+    }
+    throw new Error(`Unknown address format: ${addr}`);
+}
+/** Check if a string is valid base58 encoding. */
+function isBase58(addr) {
+    const base58Chars = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    for (const char of addr) {
+        if (!base58Chars.includes(char)) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Check if address is Tron format (T prefix, 34 chars, 0x41 first byte after decode). */
+function isTronAddress(addr) {
+    if (!addr.startsWith("T") || addr.length !== 34 || !isBase58(addr))
+        return false;
+    try {
+        const decoded = bs58_1.default.decode(addr);
+        // Tron: 0x41 (1 byte) + address (20 bytes) + checksum (4 bytes) = 25 bytes
+        return decoded.length === 25 && decoded[0] === 0x41;
+    }
+    catch {
+        return false;
+    }
+}
+/** Check if chain name is Solana. */
+function isSolanaChain(chainName) {
+    return chainName === "Sol" || chainName === "sol_test";
+}

package/utils/dist/codeHash.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Get codeHash for a contract deployment.
+ * @param artifacts - hardhat artifacts (hre.artifacts)
+ * @param contractName - contract name (e.g. "Gateway", "AuthorityManager")
+ * @param args - constructor arguments array
+ */
+export declare function getCodeHash(artifacts: any, contractName: string, args?: any[]): Promise<string>;
+/**
+ * Get codeHash for an ERC1967Proxy deployment.
+ * @param artifacts - hardhat artifacts (hre.artifacts)
+ * @param implAddress - implementation address
+ * @param implName - implementation contract name (for encoding initData)
+ * @param initArgs - arguments for initialize() function
+ */
+export declare function getProxyCodeHash(artifacts: any, implAddress: string, implName: string, initArgs?: any[]): Promise<string>;
+/**
+ * Get codeHash for a custom proxy deployment.
+ * @param artifacts - hardhat artifacts (hre.artifacts)
+ * @param proxyName - proxy contract name (e.g. "MyCustomProxy")
+ * @param implAddress - implementation address
+ * @param implName - implementation contract name (for encoding initData)
+ * @param initArgs - arguments for initialize() function
+ */
+export declare function getCustomProxyCodeHash(artifacts: any, proxyName: string, implAddress: string, implName: string, initArgs?: any[]): Promise<string>;

package/utils/dist/codeHash.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCodeHash = getCodeHash;
+exports.getProxyCodeHash = getProxyCodeHash;
+exports.getCustomProxyCodeHash = getCustomProxyCodeHash;
+/**
+ * Calculate creationCode hash for CREATE2 address prediction.
+ */
+const { keccak256, Interface } = require("ethers");
+/**
+ * Get codeHash for a contract deployment.
+ * @param artifacts - hardhat artifacts (hre.artifacts)
+ * @param contractName - contract name (e.g. "Gateway", "AuthorityManager")
+ * @param args - constructor arguments array
+ */
+async function getCodeHash(artifacts, contractName, args = []) {
+    const artifact = await artifacts.readArtifact(contractName);
+    let bytecode = artifact.bytecode;
+    if (!bytecode.startsWith("0x"))
+        bytecode = "0x" + bytecode;
+    if (args.length > 0) {
+        const iface = new Interface(artifact.abi);
+        const encoded = iface.encodeDeploy(args);
+        return keccak256(bytecode + encoded.slice(2));
+    }
+    return keccak256(bytecode);
+}
+/**
+ * Get codeHash for an ERC1967Proxy deployment.
+ * @param artifacts - hardhat artifacts (hre.artifacts)
+ * @param implAddress - implementation address
+ * @param implName - implementation contract name (for encoding initData)
+ * @param initArgs - arguments for initialize() function
+ */
+async function getProxyCodeHash(artifacts, implAddress, implName, initArgs = []) {
+    return getCustomProxyCodeHash(artifacts, "ERC1967Proxy", implAddress, implName, initArgs);
+}
+/**
+ * Get codeHash for a custom proxy deployment.
+ * @param artifacts - hardhat artifacts (hre.artifacts)
+ * @param proxyName - proxy contract name (e.g. "MyCustomProxy")
+ * @param implAddress - implementation address
+ * @param implName - implementation contract name (for encoding initData)
+ * @param initArgs - arguments for initialize() function
+ */
+async function getCustomProxyCodeHash(artifacts, proxyName, implAddress, implName, initArgs = []) {
+    const proxyArtifact = await artifacts.readArtifact(proxyName);
+    let bytecode = proxyArtifact.bytecode;
+    if (!bytecode.startsWith("0x"))
+        bytecode = "0x" + bytecode;
+    let initData = "0x";
+    if (initArgs.length > 0) {
+        const implArtifact = await artifacts.readArtifact(implName);
+        const iface = new Interface(implArtifact.abi);
+        initData = iface.encodeFunctionData("initialize", initArgs);
+    }
+    const { AbiCoder } = require("ethers");
+    const constructorArgs = AbiCoder.defaultAbiCoder().encode(["address", "bytes"], [implAddress, initData]);
+    return keccak256(bytecode + constructorArgs.slice(2));
+}

package/utils/dist/deployRecord.d.ts

@@ -0,0 +1,37 @@
+export interface DeploymentPath {
+    env: string;
+    chain: string;
+}
+export interface DeploymentOptions {
+    basePath?: string;
+    env: string;
+}
+/**
+ * Resolve deployment path from network name and env.
+ * @param network - hardhat network name (e.g. "Bsc", "Mapo_test", "Tron")
+ * @param env - deployment environment: "prod", "main", "test"
+ * @returns { env, chain } for deploy.json lookup
+ */
+export declare function resolveDeploymentPath(network: string, env: string): DeploymentPath;
+/**
+ * Read a deployed contract address from deploy.json.
+ * @param network - hardhat network name
+ * @param key - contract key (e.g. "Gateway", "Authority")
+ * @param opts - optional basePath and env overrides
+ */
+export declare function getDeploymentByKey(network: string, key: string, opts: DeploymentOptions): Promise<string>;
+/**
+ * Check if a contract address exists and is valid in deploy.json.
+ * @param network - hardhat network name
+ * @param key - contract key
+ * @param opts - optional basePath and env overrides
+ */
+export declare function hasDeployment(network: string, key: string, opts: DeploymentOptions): Promise<boolean>;
+/**
+ * Save a deployed contract address to deploy.json.
+ * @param network - hardhat network name
+ * @param key - contract key (e.g. "Gateway")
+ * @param addr - deployed address
+ * @param opts - optional basePath and env overrides
+ */
+export declare function saveDeployment(network: string, key: string, addr: string, opts: DeploymentOptions): Promise<void>;

package/utils/dist/deployRecord.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDeploymentPath = resolveDeploymentPath;
+exports.getDeploymentByKey = getDeploymentByKey;
+exports.hasDeployment = hasDeployment;
+exports.saveDeployment = saveDeployment;
+/**
+ * Deploy record — read/write deployed contract addresses from deploy.json
+ *
+ * Structure:
+ *   {
+ *     "prod": { "Mapo": { "Relay": "0x..." }, "Bsc": { "Gateway": "0x..." } },
+ *     "main": { "Mapo": { "Relay": "0x..." } },
+ *     "test": { "Mapo": { "Relay": "0x..." } }
+ *   }
+ */
+let fs = require("fs");
+let path = require("path");
+function defaultDeployPath() {
+    return path.join(process.cwd(), "deployments");
+}
+/**
+ * Resolve deployment path from network name and env.
+ * @param network - hardhat network name (e.g. "Bsc", "Mapo_test", "Tron")
+ * @param env - deployment environment: "prod", "main", "test"
+ * @returns { env, chain } for deploy.json lookup
+ */
+function resolveDeploymentPath(network, env) {
+    // Strip _test suffix from network name to get chain name
+    const chain = network.replace(/_?test$/i, "");
+    return { env, chain: chain.charAt(0).toUpperCase() + chain.slice(1) };
+}
+/**
+ * Read a deployed contract address from deploy.json.
+ * @param network - hardhat network name
+ * @param key - contract key (e.g. "Gateway", "Authority")
+ * @param opts - optional basePath and env overrides
+ */
+async function getDeploymentByKey(network, key, opts) {
+    const deployPath = opts.basePath || defaultDeployPath();
+    const { env, chain } = resolveDeploymentPath(network, opts.env);
+    const data = await readDeployFile(deployPath);
+    const addr = data[env]?.[chain]?.[key];
+    if (!addr)
+        throw new Error(`no ${key} deployment in ${env}.${chain}`);
+    return addr;
+}
+/**
+ * Check if a contract address exists and is valid in deploy.json.
+ * @param network - hardhat network name
+ * @param key - contract key
+ * @param opts - optional basePath and env overrides
+ */
+async function hasDeployment(network, key, opts) {
+    try {
+        const deployPath = opts.basePath || defaultDeployPath();
+        const { env, chain } = resolveDeploymentPath(network, opts.env);
+        const data = await readDeployFile(deployPath);
+        const addr = data[env]?.[chain]?.[key];
+        return !!addr && addr.length > 2 && addr !== "0x";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Save a deployed contract address to deploy.json.
+ * @param network - hardhat network name
+ * @param key - contract key (e.g. "Gateway")
+ * @param addr - deployed address
+ * @param opts - optional basePath and env overrides
+ */
+async function saveDeployment(network, key, addr, opts) {
+    const deployPath = opts.basePath || defaultDeployPath();
+    const { env, chain } = resolveDeploymentPath(network, opts.env);
+    const data = await readDeployFile(deployPath);
+    if (!data[env])
+        data[env] = {};
+    if (!data[env][chain])
+        data[env][chain] = {};
+    data[env][chain][key] = addr;
+    const filePath = path.resolve(deployPath, "deploy.json");
+    await ensureDir(deployPath);
+    await fs.promises.writeFile(filePath, JSON.stringify(data, null, "\t"));
+}
+async function readDeployFile(basePath) {
+    const filePath = path.resolve(basePath, "deploy.json");
+    try {
+        const rawdata = await fs.promises.readFile(filePath, "utf-8");
+        return JSON.parse(rawdata);
+    }
+    catch {
+        return {};
+    }
+}
+async function ensureDir(dirPath) {
+    const absPath = path.resolve(dirPath);
+    try {
+        await fs.promises.stat(absPath);
+    }
+    catch {
+        await fs.promises.mkdir(absPath, { recursive: true });
+    }
+}

package/utils/dist/deployer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Unified deployer — auto-routes to EVM or Tron based on network name.
+ *
+ * Usage in hardhat tasks:
+ *   const deployer = createDeployer(hre, { autoVerify: true });
+ *   let addr = await deployer.deploy("Gateway", [admin], salt);
+ *   let { proxy, implementation } = await deployer.deployProxy("Gateway", [admin], salt);
+ *   let newImpl = await deployer.upgrade("Gateway", proxyAddr);
+ */
+export interface DeployerOptions {
+    autoVerify?: boolean;
+}
+export interface DeployResult {
+    address: string;
+    hex?: string;
+}
+export interface DeployProxyResult {
+    proxy: string;
+    implementation: string;
+    proxyHex?: string;
+    implementationHex?: string;
+}
+export interface Deployer {
+    deploy(contractName: string, args?: any[], salt?: string): Promise<DeployResult>;
+    deployProxy(contractName: string, initArgs?: any[], salt?: string): Promise<DeployProxyResult>;
+    upgrade(contractName: string, proxyAddr: string): Promise<DeployResult>;
+    verify(contractName: string, address: string, constructorArgs?: any[], contractPath?: string): Promise<void>;
+    isTron: boolean;
+    network: string;
+}
+/**
+ * Create a unified deployer that auto-routes to EVM or Tron based on network.
+ * @param hre - hardhat runtime environment
+ * @param opts - options (autoVerify: auto-verify after deploy, defaults to false)
+ */
+export declare function createDeployer(hre: any, opts?: DeployerOptions): Deployer;

package/utils/dist/deployer.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDeployer = createDeployer;
+const tronHelper_1 = require("./tronHelper");
+const evmHelper_1 = require("./evmHelper");
+const verifier_1 = require("./verifier");
+/**
+ * Create a unified deployer that auto-routes to EVM or Tron based on network.
+ * @param hre - hardhat runtime environment
+ * @param opts - options (autoVerify: auto-verify after deploy, defaults to false)
+ */
+function createDeployer(hre, opts = {}) {
+    const network = hre.network.name;
+    const isTron = (0, tronHelper_1.isTronNetwork)(network);
+    const autoVerify = opts.autoVerify || false;
+    async function tryVerify(contractName, address, constructorArgs, contractPath) {
+        if (!autoVerify)
+            return;
+        try {
+            await (0, verifier_1.verify)(hre, { contractName, address, constructorArgs, contractPath });
+        }
+        catch (e) {
+            console.log(`[warn] auto-verify failed: ${e.message || e}`);
+        }
+    }
+    if (isTron) {
+        const client = tronHelper_1.TronClient.fromHre(hre);
+        return {
+            isTron: true,
+            network,
+            async deploy(contractName, args = [], salt = "") {
+                let result = await client.deploy(hre.artifacts, contractName, args, salt);
+                await tryVerify(contractName, result.base58, args);
+                return { address: result.base58, hex: result.hex };
+            },
+            async deployProxy(contractName, initArgs = [], salt = "") {
+                let result = await client.deployProxy(hre.artifacts, contractName, initArgs, salt);
+                await tryVerify(contractName, result.implementation.base58);
+                return {
+                    proxy: result.proxy.base58,
+                    implementation: result.implementation.base58,
+                    proxyHex: result.proxy.hex,
+                    implementationHex: result.implementation.hex,
+                };
+            },
+            async upgrade(contractName, proxyAddr) {
+                let result = await client.upgradeProxy(hre.artifacts, contractName, proxyAddr);
+                await tryVerify(contractName, result.base58);
+                return { address: result.base58, hex: result.hex };
+            },
+            async verify(contractName, address, constructorArgs, contractPath) {
+                await (0, verifier_1.verify)(hre, { contractName, address, constructorArgs, contractPath });
+            },
+        };
+    }
+    // EVM
+    const { ethers, artifacts } = hre;
+    return {
+        isTron: false,
+        network,
+        async deploy(contractName, args = [], salt = "") {
+            let addr = await (0, evmHelper_1.evmDeploy)(ethers, artifacts, contractName, args, salt);
+            await tryVerify(contractName, addr, args);
+            return { address: addr };
+        },
+        async deployProxy(contractName, initArgs = [], salt = "") {
+            let result = await (0, evmHelper_1.evmDeployProxy)(ethers, artifacts, contractName, initArgs, salt);
+            await tryVerify(contractName, result.implementation);
+            return { proxy: result.proxy, implementation: result.implementation };
+        },
+        async upgrade(contractName, proxyAddr) {
+            let addr = await (0, evmHelper_1.evmUpgradeProxy)(ethers, contractName, proxyAddr);
+            await tryVerify(contractName, addr);
+            return { address: addr };
+        },
+        async verify(contractName, address, constructorArgs, contractPath) {
+            await (0, verifier_1.verify)(hre, { contractName, address, constructorArgs, contractPath });
+        },
+    };
+}

package/utils/dist/evmHelper.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Deploy contract on EVM. If salt is provided, uses CREATE2 factory for deterministic address.
+ * @param ethers - ethers from hardhat runtime (hre.ethers)
+ * @param artifacts - hardhat artifacts (hre.artifacts)
+ * @param contractName - contract name to deploy
+ * @param args - constructor arguments array
+ * @param salt - optional CREATE2 salt for deterministic address
+ * @returns deployed contract address (0x hex)
+ */
+export declare function evmDeploy(ethers: any, artifacts: any, contractName: string, args?: any[], salt?: string): Promise<string>;
+/**
+ * Deploy implementation + ERC1967 proxy in one step.
+ * If salt is provided, proxy is deployed via factory.
+ * @param ethers - ethers from hardhat runtime (hre.ethers)
+ * @param artifacts - hardhat artifacts (hre.artifacts)
+ * @param contractName - implementation contract name
+ * @param initArgs - initialize() function arguments
+ * @param salt - optional CREATE2 salt for proxy
+ * @returns { proxy, implementation } addresses
+ */
+export declare function evmDeployProxy(ethers: any, artifacts: any, contractName: string, initArgs?: any[], salt?: string): Promise<{
+    proxy: string;
+    implementation: string;
+}>;
+/**
+ * Upgrade a UUPS proxy to a new implementation.
+ * Deploys new implementation, then calls upgradeToAndCall on the proxy.
+ * @param ethers - ethers from hardhat runtime (hre.ethers)
+ * @param contractName - new implementation contract name
+ * @param proxyAddr - proxy address to upgrade
+ * @returns new implementation address
+ */
+export declare function evmUpgradeProxy(ethers: any, contractName: string, proxyAddr: string): Promise<string>;

package/utils/dist/evmHelper.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evmDeploy = evmDeploy;
+exports.evmDeployProxy = evmDeployProxy;
+exports.evmUpgradeProxy = evmUpgradeProxy;
+/**
+ * Deploy contract on EVM. If salt is provided, uses CREATE2 factory for deterministic address.
+ * @param ethers - ethers from hardhat runtime (hre.ethers)
+ * @param artifacts - hardhat artifacts (hre.artifacts)
+ * @param contractName - contract name to deploy
+ * @param args - constructor arguments array
+ * @param salt - optional CREATE2 salt for deterministic address
+ * @returns deployed contract address (0x hex)
+ */
+async function evmDeploy(ethers, artifacts, contractName, args = [], salt = "") {
+    if (salt) {
+        const { evmDeployByFactory } = require("./factory");
+        const artifact = await artifacts.readArtifact(contractName);
+        const constructorArgs = args.length > 0
+            ? ethers.AbiCoder.defaultAbiCoder().encode(artifact.abi
+                .find((x) => x.type === "constructor")
+                ?.inputs.map((i) => i.type) || [], args)
+            : "0x";
+        return evmDeployByFactory(ethers, salt, artifact.bytecode, constructorArgs);
+    }
+    const [deployer] = await ethers.getSigners();
+    console.log("deploy address is:", deployer.address);
+    const ContractFactory = await ethers.getContractFactory(contractName);
+    const contract = await (await ContractFactory.deploy(...args)).waitForDeployment();
+    const addr = await contract.getAddress();
+    console.log(`${contractName} deployed: ${addr}`);
+    return addr;
+}
+/**
+ * Deploy implementation + ERC1967 proxy in one step.
+ * If salt is provided, proxy is deployed via factory.
+ * @param ethers - ethers from hardhat runtime (hre.ethers)
+ * @param artifacts - hardhat artifacts (hre.artifacts)
+ * @param contractName - implementation contract name
+ * @param initArgs - initialize() function arguments
+ * @param salt - optional CREATE2 salt for proxy
+ * @returns { proxy, implementation } addresses
+ */
+async function evmDeployProxy(ethers, artifacts, contractName, initArgs = [], salt = "") {
+    const ImplFactory = await ethers.getContractFactory(contractName);
+    const impl = await (await ImplFactory.deploy()).waitForDeployment();
+    const implAddr = await impl.getAddress();
+    console.log(`${contractName} implementation: ${implAddr}`);
+    const initData = ImplFactory.interface.encodeFunctionData("initialize", initArgs);
+    let proxyAddr;
+    if (salt) {
+        const { evmDeployByFactory } = require("./factory");
+        const proxyArtifact = await artifacts.readArtifact("ERC1967Proxy");
+        const constructorArgs = ethers.AbiCoder.defaultAbiCoder().encode(["address", "bytes"], [implAddr, initData]);
+        proxyAddr = await evmDeployByFactory(ethers, salt, proxyArtifact.bytecode, constructorArgs);
+    }
+    else {
+        const ProxyFactory = await ethers.getContractFactory("ERC1967Proxy");
+        const proxy = await (await ProxyFactory.deploy(implAddr, initData)).waitForDeployment();
+        proxyAddr = await proxy.getAddress();
+    }
+    console.log(`${contractName} proxy: ${proxyAddr}`);
+    return { proxy: proxyAddr, implementation: implAddr };
+}
+/**
+ * Upgrade a UUPS proxy to a new implementation.
+ * Deploys new implementation, then calls upgradeToAndCall on the proxy.
+ * @param ethers - ethers from hardhat runtime (hre.ethers)
+ * @param contractName - new implementation contract name
+ * @param proxyAddr - proxy address to upgrade
+ * @returns new implementation address
+ */
+async function evmUpgradeProxy(ethers, contractName, proxyAddr) {
+    const [deployer] = await ethers.getSigners();
+    const ImplFactory = await ethers.getContractFactory(contractName);
+    const impl = await (await ImplFactory.deploy()).waitForDeployment();
+    const implAddr = await impl.getAddress();
+    const proxy = await ethers.getContractAt("BaseImplementation", proxyAddr, deployer);
+    const oldImpl = await proxy.getImplementation();
+    await (await proxy.upgradeToAndCall(implAddr, "0x")).wait();
+    console.log(`${contractName} upgraded: ${oldImpl} -> ${implAddr}`);
+    return implAddr;
+}

package/utils/dist/factory.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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
+ */
+export declare function evmDeployByFactory(ethers: any, salt: string, bytecode: string, constructorArgs?: string): Promise<string>;
+/**
+ * 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
+ */
+export declare function evmGetFactoryAddress(ethers: any, salt: string): Promise<string>;
+/**
+ * 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)
+ */
+export declare function tronDeployByFactory(tronWeb: any, artifacts: any, contractName: string, salt: string, args?: any[], feeLimit?: number): Promise<string>;
+/**
+ * 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
+ */
+export declare function tronGetFactoryAddress(tronWeb: any, salt: string, codeHash: string): Promise<string>;