@mapprotocol/common-contracts 0.3.2 → 0.4.1

package/README.md

@@ -12,7 +12,7 @@ npm install @mapprotocol/common-contracts
 
 ### BaseImplementation
 
-Abstract base for all upgradeable protocol contracts. Combines UUPS proxy, pausable, and access control in one inheritance.
+Abstract base for all upgradeable protocol contracts (UUPS + Pausable + AccessManaged).
 
 ```solidity
 import "@mapprotocol/common-contracts/contracts/base/BaseImplementation.sol";
@@ -24,12 +24,6 @@ contract MyContract is BaseImplementation {
 }
 ```
 
-**Includes:**
-- `UUPSUpgradeable` — proxy upgrade pattern
-- `PausableUpgradeable` — emergency pause via `trigger()`
-- `AccessManagedUpgradeable` — role-based function access
-- `getImplementation()` — read current implementation address
-
 ### AuthorityManager
 
 Extended `AccessManager` with enumerable role members. One instance per chain controls all protocol contracts.
@@ -38,82 +32,49 @@ Extended `AccessManager` with enumerable role members. One instance per chain co
 import "@mapprotocol/common-contracts/contracts/AuthorityManager.sol";
 ```
 
-**Key functions:**
-- `grantRole(roleId, account, delay)` — assign role
-- `revokeRole(roleId, account)` — remove role
-- `setTargetFunctionRole(target, selectors, roleId)` — restrict contract functions to a role
-- `getRoleMembers(roleId)` — list all members of a role
-
 ## TypeScript Utilities
 
-### Deployment
-
 ```typescript
-import { getDeploymentByKey, saveDeployment, resolveDeploymentEnv } from "@mapprotocol/common-contracts/utils/deployment";
-
-// Read deployed address (defaults to <cwd>/deployments/deploy.json)
-const addr = await getDeploymentByKey("Bsc", "Gateway");
-
-// With custom suffix and path
-const addr = await getDeploymentByKey("Bsc", "Gateway", { suffix: "main", basePath: "./my-deployments" });
-
-// Save deployment
-await saveDeployment("Bsc", "Gateway", "0x...");
+import { createDeployer } from "@mapprotocol/common-contracts/utils/deployer";
+import { getDeploymentByKey, saveDeployment } from "@mapprotocol/common-contracts/utils/deployRecord";
+import { TronClient, tronToHex, tronFromHex } from "@mapprotocol/common-contracts/utils/tronHelper";
+import { verify } from "@mapprotocol/common-contracts/utils/verifier";
+import { addressToHex } from "@mapprotocol/common-contracts/utils/addressCodec";
 ```
 
-### Tron Interaction
+### Quick Start
 
 ```typescript
-import { createTronWeb, tronDeploy, getTronContract, tronToHex, tronFromHex } from "@mapprotocol/common-contracts/utils/tronHelper";
-
-// Address conversion (pure, no RPC needed)
-const hex = tronToHex("TXyz...");        // -> "0x..."
-const base58 = tronFromHex("0x...");     // -> "TXyz..."
-
-// Deploy contract on Tron
-const tronWeb = createTronWeb({ rpcUrl: "https://api.trongrid.io", privateKey: "..." });
-const addr = await tronDeploy(tronWeb, artifacts, "MyContract", [arg1, arg2]);
-
-// Read-only (no privateKey needed)
-const readOnly = createTronWeb({ rpcUrl: "https://api.trongrid.io" });
-const contract = await getTronContract(readOnly, artifacts, "MyContract", addr);
+// Unified deployer — auto-routes EVM / Tron
+const deployer = createDeployer(hre, { autoVerify: true });
+let result = await deployer.deploy("Gateway", [bridge, owner, wtoken]);
+let proxy  = await deployer.deployProxy("Gateway", [admin]);
+
+// Deploy record
+const addr = getDeploymentByKey("Bsc", "Gateway", { env: "prod" });
+saveDeployment("Bsc", "Gateway", "0x...", { env: "prod" });
+
+// Tron client
+let client = TronClient.fromHre(hre);
+let gw = await client.getContract(hre.artifacts, "Gateway", addr);
+await gw.setWtoken(client.toHex(wtoken)).sendAndWait();
+let val = await gw.wToken().call();
 ```
 
-### Address Encoding
-
-```typescript
-import { addressToHex, isTronAddress, isSolanaChain } from "@mapprotocol/common-contracts/utils/addressCodec";
-
-// Auto-detect format and convert to hex
-addressToHex("0xAbC...");              // EVM -> lowercase hex
-addressToHex("TXyz...");              // Tron -> extract 20-byte address
-addressToHex("So11111...");           // Solana -> full base58 decode
-
-// Type checks
-isTronAddress("TXyz...");             // true (validates 0x41 prefix byte)
-isSolanaChain("Sol");                 // true
-```
+See JSDoc in each module's source for full API details and edge cases.
 
 ## Forge Script Base
 
-For monorepo projects, `script/Base.s.sol` provides deployment primitives:
-
 ```solidity
-import {BaseScript} from "../../common/script/Base.s.sol";
+import {BaseScript} from "@mapprotocol/common-contracts/script/base/Base.s.sol";
 
 contract MyDeploy is BaseScript {
     function run() public broadcast {
-        // CREATE2 factory deployment (deterministic address)
+        (address proxy, address impl) = deployProxy(type(MyContract).creationCode, initData);
         address addr = deployByFactory("my_salt", type(MyContract).creationCode, abi.encode(arg));
-
-        // Check factory availability
-        require(isFactoryAvailable(), "no factory on this chain");
-
-        // UUPS proxy upgrade
-        upgradeProxy(proxyAddr, newImplAddr);
-
-        // Deploy new impl + upgrade in one step
         deployAndUpgrade(proxyAddr, type(MyContractV2).creationCode);
+        address relay = readDeployment("Relay");
+        saveDeployment("Gateway", addr);
     }
 }
 ```
@@ -121,43 +82,12 @@ contract MyDeploy is BaseScript {
 ## Development
 
 ```bash
-# Build
-forge build                  # Foundry
-npm run build:hardhat        # Hardhat + TypeChain
-
-# Test
-forge test
-forge test --gas-report
-
-# Format
-forge fmt
-
-# Publish
-npm run prepublishOnly       # clean + build + typecheck
-npm publish
+forge build && forge test          # Solidity
+npm run build:hardhat              # Hardhat + TypeChain
+npm run build:utils                # TypeScript utilities
+npm run prepublishOnly && npm publish
 ```
 
-## Package Contents
-
-| Path | Description |
-|------|-------------|
-| `contracts/**/*.sol` | Solidity source files |
-| `artifacts/**/*.json` | Compiled ABI + bytecode |
-| `typechain-types/**/*` | TypeChain generated types |
-| `utils/*.ts` | Shared TypeScript utilities |
-
-## Requirements
-
-- Solidity ^0.8.20
-- Node.js >= 18
-- OpenZeppelin Contracts 5.4.0
-
 ## License
 
 MIT
-
-## Links
-
-- [Repository](https://github.com/mapprotocol/mapo-contracts-v2/tree/main/common)
-- [Issues](https://github.com/mapprotocol/mapo-contracts-v2/issues)
-- [MAP Protocol](https://mapprotocol.io)

package/package.json

@@ -1,9 +1,21 @@
 {
   "name": "@mapprotocol/common-contracts",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Common contracts for MAP Protocol",
   "main": "typechain-types/index.js",
   "types": "typechain-types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./typechain-types/index.d.ts",
+      "default": "./typechain-types/index.js"
+    },
+    "./utils/*": {
+      "types": "./utils/dist/*.d.ts",
+      "default": "./utils/dist/*.js"
+    },
+    "./contracts/*": "./contracts/*",
+    "./script/*": "./script/*"
+  },
   "files": [
     "contracts/**/*.sol",
     "artifacts/contracts/**/*.json",
@@ -11,6 +23,7 @@
     "typechain-types/**/*",
     "utils/**/*.ts",
     "utils/dist/**/*",
+    "script/base/**/*.sol",
     "README.md"
   ],
   "repository": {

package/script/base/Base.s.sol

@@ -0,0 +1,231 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Script, stdJson, console} from "forge-std/Script.sol";
+import {ERC1967Proxy} from "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";
+import {IFactory} from "./interfaces/IFactory.sol";
+
+/**
+ * @title BaseScript
+ * @notice Base contract for deployment scripts with full lifecycle support
+ * @dev Inherit this in your deployment scripts.
+ *
+ * Features:
+ *   - Private key management (mainnet / testnet)
+ *   - Direct deployment and CREATE2 factory deployment
+ *   - Proxy deployment (implementation + ERC1967Proxy)
+ *   - UUPS proxy upgrade
+ *   - deploy.json record read/write
+ *
+ * Usage:
+ *   contract MyDeploy is BaseScript {
+ *       function run() public broadcast {
+ *           // Direct deploy
+ *           address impl = deployDirect(type(MyContract).creationCode, abi.encode(arg));
+ *
+ *           // Factory deploy (deterministic address)
+ *           address addr = deployByFactory("my_salt", type(MyContract).creationCode, abi.encode(arg));
+ *
+ *           // Proxy deploy (impl + proxy)
+ *           (address proxy, address impl) = deployProxy(type(MyContract).creationCode, initData);
+ *           (address proxy, address impl) = deployProxyByFactory("my_salt", type(MyContract).creationCode, initData);
+ *
+ *           // Upgrade
+ *           upgradeProxy(proxy, newImplAddr);
+ *           address newImpl = deployAndUpgrade(proxy, type(MyContractV2).creationCode);
+ *
+ *           // Deploy record
+ *           address relay = readDeployment("Relay");
+ *           saveDeployment("Gateway", addr);
+ *       }
+ *   }
+ */
+abstract contract BaseScript is Script {
+    IFactory constant private FACTORY = IFactory(0x6258e4d2950757A749a4d4683A7342261ce12471);
+    using stdJson for string;
+
+    address internal broadcaster;
+    uint256 private broadcasterPK;
+
+    constructor() {
+        uint256 privateKey;
+        if (block.chainid == 212) {
+            privateKey = vm.envUint("TESTNET_PRIVATE_KEY");
+        } else {
+            privateKey = vm.envUint("PRIVATE_KEY");
+        }
+        broadcaster = vm.addr(privateKey);
+        broadcasterPK = privateKey;
+    }
+
+    modifier broadcast() {
+        vm.startBroadcast(broadcasterPK);
+        _;
+        vm.stopBroadcast();
+    }
+
+    // ============================================================
+    // Factory (CREATE2) deployment
+    // ============================================================
+
+    /// @notice Deploy contract via CREATE2 factory with deterministic address
+    function deployByFactory(
+        string memory salt,
+        bytes memory creationCode,
+        bytes memory constructorArgs
+    ) internal returns (address addr) {
+        require(address(FACTORY).code.length > 0, "factory not deployed on this chain");
+        bytes32 saltHash = keccak256(bytes(salt));
+        addr = FACTORY.getAddress(saltHash);
+        if (addr.code.length > 0) revert("already deployed");
+        bytes memory code = abi.encodePacked(creationCode, constructorArgs);
+        FACTORY.deploy(saltHash, code, 0);
+    }
+
+    /// @notice Deploy implementation + proxy via CREATE2 factory
+    function deployProxyByFactory(
+        string memory salt,
+        bytes memory implCreationCode,
+        bytes memory initData
+    ) internal returns (address proxy, address impl) {
+        impl = deployDirect(implCreationCode, bytes(""));
+        proxy = deployByFactory(salt, type(ERC1967Proxy).creationCode, abi.encode(impl, initData));
+        console.log("Proxy:", proxy);
+        console.log("Implementation:", impl);
+    }
+
+    /// @notice Check if the CREATE2 factory is available on this chain
+    function isFactoryAvailable() internal view returns (bool) {
+        return address(FACTORY).code.length > 0;
+    }
+
+    /// @notice Get the predicted address for a given salt
+    function getFactoryAddress(string memory salt) internal view returns (address) {
+        require(isFactoryAvailable(), "factory not deployed on this chain");
+        return FACTORY.getAddress(keccak256(bytes(salt)));
+    }
+
+    /// @notice Check if a contract is already deployed at the factory address
+    function isFactoryDeployed(string memory salt) internal view returns (bool) {
+        if (!isFactoryAvailable()) return false;
+        return FACTORY.getAddress(keccak256(bytes(salt))).code.length > 0;
+    }
+
+    // ============================================================
+    // Direct deployment
+    // ============================================================
+
+    /// @notice Deploy a new contract directly (non-deterministic address)
+    function deployDirect(
+        bytes memory creationCode,
+        bytes memory constructorArgs
+    ) internal returns (address addr) {
+        bytes memory code = abi.encodePacked(creationCode, constructorArgs);
+        assembly {
+            addr := create(0, add(code, 0x20), mload(code))
+        }
+        require(addr != address(0), "deploy failed");
+    }
+
+    /// @notice Deploy implementation + proxy directly
+    function deployProxy(
+        bytes memory implCreationCode,
+        bytes memory initData
+    ) internal returns (address proxy, address impl) {
+        impl = deployDirect(implCreationCode, bytes(""));
+        ERC1967Proxy p = new ERC1967Proxy(impl, initData);
+        proxy = address(p);
+        console.log("Proxy:", proxy);
+        console.log("Implementation:", impl);
+    }
+
+    // ============================================================
+    // Upgrade
+    // ============================================================
+
+    /// @notice Upgrade a UUPS proxy to a new implementation
+    function upgradeProxy(address proxy, address newImpl) internal {
+        address oldImpl = _getImplementation(proxy);
+        (bool success,) = proxy.call(
+            abi.encodeWithSignature("upgradeToAndCall(address,bytes)", newImpl, bytes(""))
+        );
+        require(success, "upgrade failed");
+        console.log("Upgraded:", oldImpl, "->", newImpl);
+    }
+
+    /// @notice Deploy new implementation and upgrade proxy in one step
+    function deployAndUpgrade(address proxy, bytes memory implCreationCode) internal returns (address newImpl) {
+        newImpl = deployDirect(implCreationCode, bytes(""));
+        upgradeProxy(proxy, newImpl);
+    }
+
+    // ============================================================
+    // Deploy record (deploy.json) read/write
+    // ============================================================
+
+    /// @notice Read a deployed address from deployments/deploy.json
+    function readDeployment(string memory key) internal view returns (address) {
+        (string memory env, string memory chain) = _resolveDeploymentPath();
+        return _readDeploymentByPath(env, chain, key);
+    }
+
+    /// @notice Read a deployed address for a specific env and chain
+    function _readDeploymentByPath(string memory env, string memory chain, string memory key) internal view returns (address addr) {
+        string memory filePath = "deployments/deploy.json";
+        if (!vm.exists(filePath)) {
+            revert(string(abi.encodePacked("deploy.json not found: ", filePath)));
+        }
+        string memory json = vm.readFile(filePath);
+        // JSON path: .prod.Bsc.Gateway
+        string memory jsonPath = string(abi.encodePacked(".", env, ".", chain, ".", key));
+        addr = json.readAddress(jsonPath);
+    }
+
+    /// @notice Save a deployed address to deployments/deploy.json
+    function saveDeployment(string memory key, address addr) internal {
+        (string memory env, string memory chain) = _resolveDeploymentPath();
+        string memory filePath = "deployments/deploy.json";
+        // JSON path: .prod.Bsc.Gateway
+        string memory jsonPath = string(abi.encodePacked(".", env, ".", chain, ".", key));
+        string memory json = vm.readFile(filePath);
+        bool exists = vm.keyExistsJson(json, jsonPath);
+        if (!exists) {
+            revert(string(abi.encodePacked("key not found: ", env, ".", chain, ".", key)));
+        }
+        vm.writeJson(vm.toString(addr), filePath, jsonPath);
+    }
+
+    // ============================================================
+    // Internal helpers
+    // ============================================================
+
+    /// @notice Resolve deployment path (env, chain) based on chainId and NETWORK_ENV
+    /// @return env "prod", "main", or "test"
+    /// @return chain "Mapo", "Bsc", etc.
+    function _resolveDeploymentPath() internal view returns (string memory env, string memory chain) {
+        uint256 chainId = block.chainid;
+        env = vm.envString("NETWORK_ENV"); // required: test/prod/main
+
+        if (chainId == 212 || chainId == 22776) chain = "Mapo";
+        else if (chainId == 11155111 || chainId == 1) chain = "Eth";
+        else if (chainId == 97 || chainId == 56) chain = "Bsc";
+        else if (chainId == 8453) chain = "Base";
+        else if (chainId == 42161) chain = "Arb";
+        else if (chainId == 10) chain = "Op";
+        else if (chainId == 130) chain = "Uni";
+        else if (chainId == 137) chain = "Pol";
+        else if (chainId == 196) chain = "Xlayer";
+        else revert("unknown chain");
+    }
+
+    /// @notice Read current implementation address from a UUPS proxy
+    function _getImplementation(address proxy) internal view returns (address) {
+        (bool success, bytes memory data) = proxy.staticcall(
+            abi.encodeWithSignature("getImplementation()")
+        );
+        if (success && data.length == 32) {
+            return abi.decode(data, (address));
+        }
+        return address(0);
+    }
+}

package/script/base/interfaces/IFactory.sol

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+interface IFactory {
+    function getAddress(bytes32 salt) external view returns (address);
+    function deploy(bytes32 salt, bytes memory creationCode, uint256 value) external;
+}

package/utils/deployer.ts

@@ -13,12 +13,17 @@ import { verify as _verify } from "./verifier";
  */
 
 export interface DeployerOptions {
-    autoVerify?: boolean;   // auto verify after deploy/upgrade, defaults to false
+    /**
+     * Auto-verify contracts after deploy/upgrade.
+     * Failures are logged as warnings, never thrown — call deployer.verify() for explicit error handling.
+     * Defaults to false.
+     */
+    autoVerify?: boolean;
 }
 
 export interface DeployResult {
-    address: string;       // primary address (0x hex for EVM, base58 for Tron)
-    hex?: string;          // 0x hex (Tron only, EVM same as address)
+    address: string;       // EVM: 0x hex address. Tron: base58 (T...) address.
+    hex?: string;          // Tron only: 0x hex address. Undefined on EVM.
 }
 
 export interface DeployProxyResult {
@@ -29,9 +34,16 @@ export interface DeployProxyResult {
 }
 
 export interface Deployer {
+    /**
+     * Deploy a contract.
+     * @param contractName - artifact name
+     * @param args - constructor arguments as raw values
+     * @param salt - "" or omitted = direct deploy; non-empty string = CREATE2 factory (deterministic address)
+     */
     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 explicitly (throws on failure, unlike autoVerify which only warns). */
     verify(contractName: string, address: string, constructorArgs?: any[], contractPath?: string): Promise<void>;
     isTron: boolean;
     network: string;

package/utils/dist/deployer.d.ts

@@ -8,6 +8,11 @@
  *   let newImpl = await deployer.upgrade("Gateway", proxyAddr);
  */
 export interface DeployerOptions {
+    /**
+     * Auto-verify contracts after deploy/upgrade.
+     * Failures are logged as warnings, never thrown — call deployer.verify() for explicit error handling.
+     * Defaults to false.
+     */
     autoVerify?: boolean;
 }
 export interface DeployResult {
@@ -21,9 +26,16 @@ export interface DeployProxyResult {
     implementationHex?: string;
 }
 export interface Deployer {
+    /**
+     * Deploy a contract.
+     * @param contractName - artifact name
+     * @param args - constructor arguments as raw values
+     * @param salt - "" or omitted = direct deploy; non-empty string = CREATE2 factory (deterministic address)
+     */
     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 explicitly (throws on failure, unlike autoVerify which only warns). */
     verify(contractName: string, address: string, constructorArgs?: any[], contractPath?: string): Promise<void>;
     isTron: boolean;
     network: string;

package/utils/dist/verifier.d.ts

@@ -2,7 +2,17 @@ export interface VerifyOptions {
     address: string;
     contractName: string;
     contractPath?: string;
+    /**
+     * Constructor arguments as raw values — auto-encoded via ethers `encodeDeploy`.
+     * Example: ["0xAbC123...", "0xDeF456...", 200]
+     * Use this for most cases. Mutually exclusive with constructorParams.
+     */
     constructorArgs?: any[];
+    /**
+     * Pre-encoded constructor params as hex string (without 0x prefix).
+     * Use this when you already have the ABI-encoded bytes, e.g. from `cast abi-encode`.
+     * Takes priority over constructorArgs if both are provided.
+     */
     constructorParams?: string;
     compiler?: string;
     optimizer?: boolean;

package/utils/dist/verifier.js

@@ -27,7 +27,17 @@ async function verify(hre, opts) {
 // EVM verification via hardhat-verify
 // ============================================================
 async function verifyEvm(hre, opts) {
-    const contractPath = opts.contractPath || `contracts/${opts.contractName}.sol:${opts.contractName}`;
+    // Resolve contractPath from hardhat artifact (authoritative) instead of guessing
+    let contractPath = opts.contractPath;
+    if (!contractPath) {
+        try {
+            const artifact = await hre.artifacts.readArtifact(opts.contractName);
+            contractPath = `${artifact.sourceName}:${opts.contractName}`;
+        }
+        catch {
+            contractPath = `contracts/${opts.contractName}.sol:${opts.contractName}`;
+        }
+    }
     console.log(`verifying ${opts.contractName} at ${opts.address} ...`);
     try {
         await hre.run("verify:verify", {
@@ -56,13 +66,13 @@ async function verifyTron(hre, opts) {
     const chainId = hre.network.config.chainId;
     const fs = require("fs");
     const path = require("path");
-    // Auto-read compiler settings from hardhat config
+    // Compiler settings: opts > build-info > hardhat config (no hardcoded defaults)
     const solcConfig = hre.config?.solidity?.compilers?.[0] || hre.config?.solidity || {};
-    const compiler = opts.compiler || solcConfig.version || "0.8.25";
-    const optimizer = opts.optimizer ?? solcConfig.settings?.optimizer?.enabled ?? true;
-    const optimizerRuns = opts.optimizerRuns ?? solcConfig.settings?.optimizer?.runs ?? 200;
-    const evmVersion = solcConfig.settings?.evmVersion || "london";
-    const viaIR = solcConfig.settings?.viaIR ? "1" : "0";
+    let compiler = opts.compiler || solcConfig.version || "";
+    let optimizer = opts.optimizer ?? solcConfig.settings?.optimizer?.enabled;
+    let optimizerRuns = opts.optimizerRuns ?? solcConfig.settings?.optimizer?.runs;
+    let evmVersion = solcConfig.settings?.evmVersion || "";
+    let viaIR = solcConfig.settings?.viaIR ? "1" : "0";
     // Convert address to Tron format
     let address = opts.address;
     if (address.startsWith("0x")) {
@@ -71,25 +81,26 @@ async function verifyTron(hre, opts) {
     // Generate flattened source
     const outputDir = path.join(process.cwd(), "verify-output");
     const flattenPath = path.join(outputDir, `${opts.contractName}_flatten.sol`);
-    console.log(`generating flatten for ${opts.contractName}...`);
-    try {
-        // Find actual source path from artifact
-        const artifact = await hre.artifacts.readArtifact(opts.contractName);
-        const sourcePath = artifact.sourceName; // e.g. "contracts/factory/Create2Factory.sol"
-        let flattenedSource = await hre.run("flatten:get-flattened-sources", {
-            files: [sourcePath],
-        });
-        flattenedSource = removeDuplicateSPDX(flattenedSource);
-        fs.mkdirSync(outputDir, { recursive: true });
-        fs.writeFileSync(flattenPath, flattenedSource);
-        console.log(`flatten saved to: ${flattenPath}`);
+    if (fs.existsSync(flattenPath)) {
+        console.log(`using existing flatten: ${flattenPath}`);
     }
-    catch (e) {
-        if (fs.existsSync(flattenPath)) {
-            console.log(`using existing flatten: ${flattenPath}`);
+    else {
+        console.log(`generating flatten for ${opts.contractName}...`);
+        let sourcePath = "";
+        try {
+            const artifact = await hre.artifacts.readArtifact(opts.contractName);
+            sourcePath = artifact.sourceName;
+            let flattenedSource = await hre.run("flatten:get-flattened-sources", {
+                files: [sourcePath],
+            });
+            flattenedSource = removeDuplicateSPDX(flattenedSource);
+            fs.mkdirSync(outputDir, { recursive: true });
+            fs.writeFileSync(flattenPath, flattenedSource);
+            console.log(`flatten saved to: ${flattenPath}`);
         }
-        else {
-            console.log(`flatten failed, generate manually: forge flatten contracts/${opts.contractName}.sol`);
+        catch (e) {
+            const hint = sourcePath || `contracts/${opts.contractName}.sol`;
+            console.log(`flatten failed, generate manually: npx hardhat flatten ${hint} > ${flattenPath}`);
             return;
         }
     }
@@ -106,27 +117,49 @@ async function verifyTron(hre, opts) {
         const form = new FormData();
         form.append("contractAddress", address);
         form.append("contractName", opts.contractName);
-        // Read full compiler version from build-info (includes commit hash)
+        // Read compiler settings from build-info that contains this contract
         let fullCompiler = `v${compiler}`;
         try {
             const buildInfoDir = path.join(process.cwd(), "artifacts/build-info");
-            const buildInfoFiles = fs.readdirSync(buildInfoDir);
-            if (buildInfoFiles.length > 0) {
-                const buildInfo = JSON.parse(fs.readFileSync(path.join(buildInfoDir, buildInfoFiles[0]), "utf-8"));
-                if (buildInfo.solcLongVersion) {
-                    fullCompiler = `v${buildInfo.solcLongVersion}`;
+            const buildInfoFiles = fs.readdirSync(buildInfoDir).filter((f) => f.endsWith(".json"));
+            const artifact = await hre.artifacts.readArtifact(opts.contractName);
+            const sourceName = artifact.sourceName;
+            for (const file of buildInfoFiles) {
+                const buildInfo = JSON.parse(fs.readFileSync(path.join(buildInfoDir, file), "utf-8"));
+                if (buildInfo.output?.contracts?.[sourceName]?.[opts.contractName]) {
+                    if (buildInfo.solcLongVersion) {
+                        fullCompiler = `v${buildInfo.solcLongVersion}`;
+                    }
+                    // Override settings from actual build-info input
+                    const settings = buildInfo.input?.settings;
+                    if (settings) {
+                        if (settings.evmVersion)
+                            evmVersion = settings.evmVersion;
+                        if (settings.optimizer != null) {
+                            optimizer = settings.optimizer.enabled ?? optimizer;
+                            optimizerRuns = settings.optimizer.runs ?? optimizerRuns;
+                        }
+                        if (settings.viaIR != null)
+                            viaIR = settings.viaIR ? "1" : "0";
+                    }
+                    break;
                 }
             }
         }
         catch (e) {
             console.log(`[warn] could not read build-info: ${e.message}`);
         }
+        if (!fullCompiler.includes("+commit.")) {
+            console.log(`[error] could not determine full compiler version (got: ${fullCompiler}). Run 'npx hardhat compile' to generate build-info.`);
+            printTronVerifyInfo(address, opts.contractName, fullCompiler, !!optimizer, optimizerRuns || 200, evmVersion || "london", flattenPath, chainId);
+            return;
+        }
         form.append("compiler", fullCompiler);
         form.append("license", "3"); // MIT
         form.append("optimizer", optimizer ? "1" : "0");
-        form.append("runs", String(optimizerRuns));
+        form.append("runs", String(optimizerRuns ?? 200));
         form.append("viaIR", viaIR);
-        form.append("evmVersion", evmVersion);
+        form.append("evmVersion", evmVersion || "london");
         // Encode constructor params from ABI if not pre-encoded
         let constructorParams = opts.constructorParams || "";
         if (!constructorParams && opts.constructorArgs && opts.constructorArgs.length > 0) {
@@ -164,11 +197,14 @@ async function verifyTron(hre, opts) {
             req.on("error", reject);
             form.pipe(req);
         });
-        if (result.code === 200 || result.success) {
-            console.log(`${opts.contractName} verified on TronScan: ${result.data?.message || "success"}`);
+        console.log(`TronScan raw response:`, JSON.stringify(result, null, 2));
+        const status = result.data?.status;
+        if ((result.code === 200 && (status === 200 || status === 2006)) || result.success) {
+            console.log(`${opts.contractName} verified on TronScan`);
         }
         else {
-            console.log(`TronScan response:`, JSON.stringify(result, null, 2));
+            console.log(`verification failed (status: ${status}): ${result.data?.message || "unknown"}`);
+            console.log(`  compiler: ${fullCompiler}, evmVersion: ${evmVersion}, optimizer: ${optimizer}, runs: ${optimizerRuns}, viaIR: ${viaIR}`);
             printTronVerifyInfo(address, opts.contractName, fullCompiler, optimizer, optimizerRuns, evmVersion, flattenPath, chainId);
         }
     }

package/utils/verifier.ts

@@ -11,14 +11,24 @@ const TRONSCAN_API: Record<number, string> = {
 };
 
 export interface VerifyOptions {
-    address: string;             // contract address
+    address: string;             // contract address (0x hex or Tron base58)
     contractName: string;        // e.g. "AuthorityManager"
     contractPath?: string;       // e.g. "contracts/AuthorityManager.sol:AuthorityManager"
-    constructorArgs?: any[];     // constructor arguments (raw values)
-    constructorParams?: string;  // pre-encoded constructor params hex (without 0x), overrides constructorArgs
-    compiler?: string;           // solc version, defaults to "0.8.25"
-    optimizer?: boolean;         // defaults to true
-    optimizerRuns?: number;      // defaults to 200
+    /**
+     * Constructor arguments as raw values — auto-encoded via ethers `encodeDeploy`.
+     * Example: ["0xAbC123...", "0xDeF456...", 200]
+     * Use this for most cases. Mutually exclusive with constructorParams.
+     */
+    constructorArgs?: any[];
+    /**
+     * Pre-encoded constructor params as hex string (without 0x prefix).
+     * Use this when you already have the ABI-encoded bytes, e.g. from `cast abi-encode`.
+     * Takes priority over constructorArgs if both are provided.
+     */
+    constructorParams?: string;
+    compiler?: string;           // override solc version (auto-read from build-info if omitted)
+    optimizer?: boolean;         // override optimizer enabled (auto-read from build-info if omitted)
+    optimizerRuns?: number;      // override optimizer runs (auto-read from build-info if omitted)
 }
 
 /**
@@ -39,7 +49,16 @@ export async function verify(hre: any, opts: VerifyOptions): Promise<void> {
 // ============================================================
 
 async function verifyEvm(hre: any, opts: VerifyOptions): Promise<void> {
-    const contractPath = opts.contractPath || `contracts/${opts.contractName}.sol:${opts.contractName}`;
+    // Resolve contractPath from hardhat artifact (authoritative) instead of guessing
+    let contractPath = opts.contractPath;
+    if (!contractPath) {
+        try {
+            const artifact = await hre.artifacts.readArtifact(opts.contractName);
+            contractPath = `${artifact.sourceName}:${opts.contractName}`;
+        } catch {
+            contractPath = `contracts/${opts.contractName}.sol:${opts.contractName}`;
+        }
+    }
 
     console.log(`verifying ${opts.contractName} at ${opts.address} ...`);
 
@@ -71,13 +90,13 @@ async function verifyTron(hre: any, opts: VerifyOptions): Promise<void> {
     const fs = require("fs");
     const path = require("path");
 
-    // Auto-read compiler settings from hardhat config
+    // Compiler settings: opts > build-info > hardhat config (no hardcoded defaults)
     const solcConfig = hre.config?.solidity?.compilers?.[0] || hre.config?.solidity || {};
-    const compiler = opts.compiler || solcConfig.version || "0.8.25";
-    const optimizer = opts.optimizer ?? solcConfig.settings?.optimizer?.enabled ?? true;
-    const optimizerRuns = opts.optimizerRuns ?? solcConfig.settings?.optimizer?.runs ?? 200;
-    const evmVersion = solcConfig.settings?.evmVersion || "london";
-    const viaIR = solcConfig.settings?.viaIR ? "1" : "0";
+    let compiler = opts.compiler || solcConfig.version || "";
+    let optimizer = opts.optimizer ?? solcConfig.settings?.optimizer?.enabled;
+    let optimizerRuns = opts.optimizerRuns ?? solcConfig.settings?.optimizer?.runs;
+    let evmVersion = solcConfig.settings?.evmVersion || "";
+    let viaIR = solcConfig.settings?.viaIR ? "1" : "0";
 
     // Convert address to Tron format
     let address = opts.address;
@@ -89,23 +108,24 @@ async function verifyTron(hre: any, opts: VerifyOptions): Promise<void> {
     const outputDir = path.join(process.cwd(), "verify-output");
     const flattenPath = path.join(outputDir, `${opts.contractName}_flatten.sol`);
 
-    console.log(`generating flatten for ${opts.contractName}...`);
-    try {
-        // Find actual source path from artifact
-        const artifact = await hre.artifacts.readArtifact(opts.contractName);
-        const sourcePath = artifact.sourceName; // e.g. "contracts/factory/Create2Factory.sol"
-        let flattenedSource = await hre.run("flatten:get-flattened-sources", {
-            files: [sourcePath],
-        });
-        flattenedSource = removeDuplicateSPDX(flattenedSource);
-        fs.mkdirSync(outputDir, { recursive: true });
-        fs.writeFileSync(flattenPath, flattenedSource);
-        console.log(`flatten saved to: ${flattenPath}`);
-    } catch (e) {
-        if (fs.existsSync(flattenPath)) {
-            console.log(`using existing flatten: ${flattenPath}`);
-        } else {
-            console.log(`flatten failed, generate manually: forge flatten contracts/${opts.contractName}.sol`);
+    if (fs.existsSync(flattenPath)) {
+        console.log(`using existing flatten: ${flattenPath}`);
+    } else {
+        console.log(`generating flatten for ${opts.contractName}...`);
+        let sourcePath = "";
+        try {
+            const artifact = await hre.artifacts.readArtifact(opts.contractName);
+            sourcePath = artifact.sourceName;
+            let flattenedSource = await hre.run("flatten:get-flattened-sources", {
+                files: [sourcePath],
+            });
+            flattenedSource = removeDuplicateSPDX(flattenedSource);
+            fs.mkdirSync(outputDir, { recursive: true });
+            fs.writeFileSync(flattenPath, flattenedSource);
+            console.log(`flatten saved to: ${flattenPath}`);
+        } catch (e) {
+            const hint = sourcePath || `contracts/${opts.contractName}.sol`;
+            console.log(`flatten failed, generate manually: npx hardhat flatten ${hint} > ${flattenPath}`);
             return;
         }
     }
@@ -124,28 +144,47 @@ async function verifyTron(hre: any, opts: VerifyOptions): Promise<void> {
         const form = new FormData();
         form.append("contractAddress", address);
         form.append("contractName", opts.contractName);
-        // Read full compiler version from build-info (includes commit hash)
+        // Read compiler settings from build-info that contains this contract
         let fullCompiler = `v${compiler}`;
         try {
             const buildInfoDir = path.join(process.cwd(), "artifacts/build-info");
-            const buildInfoFiles = fs.readdirSync(buildInfoDir);
-            if (buildInfoFiles.length > 0) {
-                const buildInfo = JSON.parse(fs.readFileSync(
-                    path.join(buildInfoDir, buildInfoFiles[0]), "utf-8"
-                ));
-                if (buildInfo.solcLongVersion) {
-                    fullCompiler = `v${buildInfo.solcLongVersion}`;
+            const buildInfoFiles = fs.readdirSync(buildInfoDir).filter((f: string) => f.endsWith(".json"));
+            const artifact = await hre.artifacts.readArtifact(opts.contractName);
+            const sourceName = artifact.sourceName;
+
+            for (const file of buildInfoFiles) {
+                const buildInfo = JSON.parse(fs.readFileSync(path.join(buildInfoDir, file), "utf-8"));
+                if (buildInfo.output?.contracts?.[sourceName]?.[opts.contractName]) {
+                    if (buildInfo.solcLongVersion) {
+                        fullCompiler = `v${buildInfo.solcLongVersion}`;
+                    }
+                    // Override settings from actual build-info input
+                    const settings = buildInfo.input?.settings;
+                    if (settings) {
+                        if (settings.evmVersion) evmVersion = settings.evmVersion;
+                        if (settings.optimizer != null) {
+                            optimizer = settings.optimizer.enabled ?? optimizer;
+                            optimizerRuns = settings.optimizer.runs ?? optimizerRuns;
+                        }
+                        if (settings.viaIR != null) viaIR = settings.viaIR ? "1" : "0";
+                    }
+                    break;
                 }
             }
         } catch (e: any) {
             console.log(`[warn] could not read build-info: ${e.message}`);
         }
+        if (!fullCompiler.includes("+commit.")) {
+            console.log(`[error] could not determine full compiler version (got: ${fullCompiler}). Run 'npx hardhat compile' to generate build-info.`);
+            printTronVerifyInfo(address, opts.contractName, fullCompiler, !!optimizer, optimizerRuns || 200, evmVersion || "london", flattenPath, chainId);
+            return;
+        }
         form.append("compiler", fullCompiler);
         form.append("license", "3"); // MIT
         form.append("optimizer", optimizer ? "1" : "0");
-        form.append("runs", String(optimizerRuns));
+        form.append("runs", String(optimizerRuns ?? 200));
         form.append("viaIR", viaIR);
-        form.append("evmVersion", evmVersion);
+        form.append("evmVersion", evmVersion || "london");
         // Encode constructor params from ABI if not pre-encoded
         let constructorParams = opts.constructorParams || "";
         if (!constructorParams && opts.constructorArgs && opts.constructorArgs.length > 0) {
@@ -180,10 +219,13 @@ async function verifyTron(hre: any, opts: VerifyOptions): Promise<void> {
             form.pipe(req);
         });
 
-        if (result.code === 200 || result.success) {
-            console.log(`${opts.contractName} verified on TronScan: ${result.data?.message || "success"}`);
+        console.log(`TronScan raw response:`, JSON.stringify(result, null, 2));
+        const status = result.data?.status;
+        if ((result.code === 200 && (status === 200 || status === 2006)) || result.success) {
+            console.log(`${opts.contractName} verified on TronScan`);
         } else {
-            console.log(`TronScan response:`, JSON.stringify(result, null, 2));
+            console.log(`verification failed (status: ${status}): ${result.data?.message || "unknown"}`);
+            console.log(`  compiler: ${fullCompiler}, evmVersion: ${evmVersion}, optimizer: ${optimizer}, runs: ${optimizerRuns}, viaIR: ${viaIR}`);
             printTronVerifyInfo(address, opts.contractName, fullCompiler, optimizer, optimizerRuns, evmVersion, flattenPath, chainId);
         }
     } catch (e: any) {