gate-evm-tools 1.0.27 → 1.0.28

package/docs/workflow-runtime-acceptance.md

@@ -0,0 +1,17 @@
+# Local workflow extraction acceptance — 2026-09-09
+
+Implemented in EvmGateTools and EvmHardhatCli. SmartFlowAI required no source changes because legacy script entrypoints and project-owned state remain intact.
+
+- GateTool build and tests: 123 passed, including historical proxy-artifact compatibility, runtime binding mismatch/unversioned resume rejection, and migration custom/symlink refusal.
+- Template build and full suite: 370 passed. Existing source fixture coverage now consumes TypeScript from the installed package, including deployment, UUPS preparation/retry, external reconciliation and reporter concurrency.
+- GateFlow existing full-template integrity and rpc.env suites: 19 passed. This is adapter regression coverage, not a complete UI SuperTask run.
+- Installed tarball in an isolated generated full project, updated package.json/package-lock.json and completed `npm ci --ignore-scripts`.
+- Compiled-package integration: 9 Hardhat tests passed; direct `npx --no-install gate-workflow` two-custom-step local simulation succeeded; invocation outside the project with `--project-root` resolved the correct project and custom scripts.
+- Baseline migration: 70 files replaced with compatibility exports, every backup compared byte-for-byte, repeat apply performed no changes. Custom/missing/symlinked paths are refused.
+- `git diff --check` passed in both modified repositories.
+
+Local artifact and durable logs: `/Users/vector/gate/local-packages/workflow-extraction/`. `acceptance.json` records the tarball SHA256 and installed runtime digest. The fixture is `full-runtime-check`. The runtime loaded by this fixture was compared with the built runtime identity.
+
+No npm publication, git commit/push, live SuperTask modification or remote transaction broadcast occurred. Solidity/compiler settings and implementation/proxy salt policy were preserved. Local Hardhat tests use the in-process chain; zkSync and UUPS retry coverage uses existing test fixtures, not live-network acceptance.
+
+The template dependency is intentionally the unpublished `1.1.0-local.0` preview. Before publication or distribution, choose a released exact version and regenerate dependency locks. Existing projects require one migration of compatible script exports plus dependency/lockfile installation; subsequent compatible runtime updates use the package. Customized workflows and already-started unversioned executions require the documented manual transition.

package/docs/workflow-runtime.md

@@ -0,0 +1,56 @@
+# Packaged workflow runtime (local preview)
+
+GateTool owns the full-template workflow implementation. New templates have no `scripts/workflow` or `scripts/config` forwarding directory: npm scripts call `gate-workflow`, and Hardhat/tests import package exports directly. Existing npm command names remain supported. Contracts, config.yaml/config.json, rpc.env, task YAML, salts, business scripts and result files remain project-owned. Compiler settings and deployment/vanity behavior are unchanged.
+
+The release version is `1.0.27`. Publish GateTool before distributing a template that depends on it. Install the built tarball with `npm install --save-dev --save-exact /path/to/gate-evm-tools-1.0.27.tgz`. Commit the resulting dependency and existing lockfile together when ready; do not change lockfile formats. Keep the tarball accessible for `npm ci`. Before npm publication, use the explicit local tarball installation above for validation; after publication, install the exact registry version and refresh the lockfile.
+
+Commands run from the project root:
+
+```sh
+npx --no-install gate-workflow --help
+npx --no-install gate-workflow static-validate --task TASK
+npx --no-install gate-workflow run --task TASK --network hardhat --target hardhat --mode simulate --executionId NEW_ID --no-compile
+npx --no-install gate-workflow migrate
+npx --no-install gate-workflow migrate --apply
+```
+
+`--project-root /absolute/project` selects another project explicitly. No manual `--require ts-node/register` is needed for the packaged CLI. Hardhat and its configuration are loaded from the selected project. The workflow runtime requires the full-template Hardhat 2 / ethers 6 plugin setup; the existing GateTool core ethers 5 support does not imply workflow support for ethers 5.
+
+Migration defaults to a reviewable JSON plan. Apply removes recognized baseline files or exact compatibility shims, rewrites recognized npm commands and static imports to package exports, and backs up all changed files in `.gate-workflow-backup-*`. Missing helpers are already migrated. Customized files, symlinks and unresolved executable references block the entire operation before writing. The installed package exports, declared version and npm lock version are checked first. Dependency/lockfile installation is a separate explicit npm step above. Custom workflows require a manual merge. This utility does not migrate live execution state or generate project config. To roll back, restore the backup scripts and the prior package/lockfile pair, then reinstall from that lockfile.
+
+Simulate/execute binds each target and execution ID to the package version and build digest (runtime and GateTool code). A changed build or unversioned existing execution is rejected. Finish existing tasks with their original scripts/package, or reconcile confirmed transactions and prepare a new execution. Do not delete binding records to bypass this check.
+
+Custom steps remain in the project and export default/main/run. Migration rewrites recognized imports through project shims to package exports. Type-only imports may use `gate-evm-tools/runtime/run` (`WorkflowContext`) and `gate-evm-tools/runtime/lib/parameters` (`WorkflowStep`). Modules under runtime/lib are compatibility surfaces tied to the pinned package; upgrade them together. Runtime TypeScript sources ship for source-level regression fixtures; production invokes compiled JavaScript.
+
+Validation is local and without broadcast. This preview is not an npm release and does not switch an active SuperTask automatically.
+
+## Network and Hardhat adapters
+
+The project owns its complete network list in `hardhat.config.ts`. `createNetworkHelpers({ accounts, env? })` supplies RPC routing, account injection and validated fork inputs without choosing remote networks. `env` defaults to process.env; load rpc.env/.env before calling the helper. Edit the existing `networks` entries to override fields or add a network. Keep one network list during migration, preserving confirmed custom fields and the original compiler settings.
+
+```ts
+import { createNetworkHelpers } from 'gate-evm-tools/runtime-config/networks';
+// After rpc.env/.env loading and project account resolution:
+const { remoteNetwork } = createNetworkHelpers({ accounts });
+const config = {
+  // Keep compiler settings and other network entries from your project.
+  networks: {
+    bscDev: {
+      ...remoteNetwork({
+        route: 'bsc', publicFallback: 'https://bsc.drpc.org',
+        useBaseRpc: true, chainId: 56,
+        rpcUrl: process.env.BSC_DEV_RPC_URL,
+      }),
+      timeout: 60_000,
+    },
+  },
+};
+```
+
+The deprecated `createTemplateNetworks` export retains historical defaults only for compatibility with already-generated projects. New templates do not load it; updating GateTool does not replace their inline network declarations.
+
+Register `registerZkSyncSolcAdapter(subtask, TASK_COMPILE_SOLIDITY_RUN_SOLC)` with the project's Hardhat API; the package must not initialize an HRE during config loading. `withTemplateArtifactPaths(config)` selects EVM or zkSync artifact/cache directories and leaves compiler configuration unchanged. Manifest environment binding still precedes loading the upgrades plugin; rpc.env and credential resolution remain explicit in the project. Neither helper reads project env files or changes compiler versions.
+
+The RPC resolver and zkSync solc PATH adapter are also exported under `runtime-config/rpc` and `runtime-config/zksyncSolcPath`; new templates import these exports directly. Migration now recognizes 72 baseline helper/workflow files. Migration rewrites recognized Hardhat imports but preserves compiler/settings/overrides. Merge new helper calls into older inline configs separately while retaining the old toolchain for overlay projects. Network infrastructure/config.yaml profiles and business data stay project-owned.
+
+After this one-time migration, compatible runtime upgrades require updating the exact GateTool dependency and existing lockfile, without copying workflow scripts. Breaking configuration/API changes still require their documented migration. Finish active execution bindings on their original build before upgrading.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gate-evm-tools",
-  "version": "1.0.27",
+  "version": "1.0.28",
   "description": "Gate 智能合约工具集 - 字节码检查、合约升级验证、合约状态同步",
   "type": "module",
   "exports": {
@@ -67,7 +67,8 @@
     "README.md",
     "contractInfo.example.json",
     "dist-runtime/",
-    "runtime/"
+    "runtime/",
+    "docs/"
   ],
   "scripts": {
     "build": "tsc && tsc -p tsconfig.custody-cjs.json && node scripts/write-cjs-package.mjs && tsc -p tsconfig.runtime.json && node scripts/write-runtime-package.mjs",

package/runtime/config/hardhatAdapters.ts

@@ -48,3 +48,11 @@ export function withTemplateArtifactPaths(config: HardhatUserConfig, argv: strin
     },
   };
 }
+
+/** Include the canonical dependency in the project compilation graph without a local Solidity shim. */
+export function registerWorkflowDependencyCompiler(subtask: typeof import("hardhat/config").subtask, taskName: string): void {
+  subtask(taskName).setAction(async (args, _hre, runSuper) => {
+    const sourceNames: string[] = await runSuper(args);
+    return [...new Set([...sourceNames, "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol"])];
+  });
+}

package/runtime/config/networks.ts

@@ -7,8 +7,18 @@ export interface TemplateNetworkOptions {
   overrides?: NonNullable<HardhatUserConfig["networks"]>;
 }
 
-/** Creates fresh network objects; caller-owned compiler configuration is never touched. */
-export function createTemplateNetworks({ accounts, env = process.env, overrides = {} }: TemplateNetworkOptions): NonNullable<HardhatUserConfig["networks"]> {
+export interface RemoteNetworkOptions {
+  route: string;
+  publicFallback: string;
+  useBaseRpc: boolean;
+  chainId: number;
+  ethNetwork?: string;
+  zksync?: boolean;
+  rpcUrl?: string;
+}
+
+/** Generic loaders only: network names and chain declarations belong to the project. */
+export function createNetworkHelpers({ accounts, env = process.env }: Omit<TemplateNetworkOptions, "overrides">) {
   const hardhatForking = env.HARDHAT_FORK_RPC_URL
     ? { url: env.HARDHAT_FORK_RPC_URL }
     : undefined;
@@ -23,15 +33,7 @@ export function createTemplateNetworks({ accounts, env = process.env, overrides
     throw new Error("HARDHAT_FORK_CHAIN_ID must be a positive safe integer");
   }
 
-  interface RemoteNetworkOptions {
-    route: string;
-    publicFallback: string;
-    useBaseRpc: boolean;
-    chainId: number;
-    ethNetwork?: string;
-    zksync?: boolean;
-    rpcUrl?: string;
-  }
+
 
   const remoteNetwork = ({
     route,
@@ -66,6 +68,13 @@ export function createTemplateNetworks({ accounts, env = process.env, overrides
     }
   }
 
+  return { remoteNetwork, hardhatForking, hardhatForkChainId, zkSyncForkRpcUrl };
+}
+
+/** @deprecated Compatibility defaults for older generated projects only. New templates declare networks in hardhat.config.ts. */
+export function createTemplateNetworks({ accounts, env = process.env, overrides = {} }: TemplateNetworkOptions): NonNullable<HardhatUserConfig["networks"]> {
+  const { remoteNetwork, hardhatForking, hardhatForkChainId, zkSyncForkRpcUrl } = createNetworkHelpers({ accounts, env });
+
   const networks = {
     hardhat: {
       allowUnlimitedContractSize: false,

package/runtime/workflow/lib/controlledMulticallAbi.ts

@@ -0,0 +1,6 @@
+/** ABI for querying deployed controlled Multicall authority; no project artifact required. */
+export const CONTROLLED_MULTICALL_AUTHORITY_ABI = [
+  "function callers(address caller) view returns (bool)",
+  "function factoryCallers(address factory, address caller) view returns (bool)",
+  "function owner() view returns (address)",
+];

package/runtime/workflow/lib/parameters.ts

@@ -266,9 +266,10 @@ export const validateDeployCreate2Strategy = (steps: WorkflowStep[]): void => {
       if (step.upgradeableStrategy !== "uups-placeholder-proxy") {
         throw new Error(`Deploy step ${step.id} requires upgradeableStrategy: uups-placeholder-proxy`);
       }
-      if (String(step.contract) !== "contracts/workflow/UUPSPlaceholder.sol:UUPSPlaceholder") {
+      if (String(step.contract) !== "contracts/workflow/UUPSPlaceholder.sol:UUPSPlaceholder"
+        && step.contract !== asObject(step.firstUpgrade).contract) {
         throw new Error(
-          `Deploy step ${step.id} must create UUPS proxies with contracts/workflow/UUPSPlaceholder.sol:UUPSPlaceholder`,
+          `Deploy step ${step.id} must use the same business implementation in contract and firstUpgrade.contract`,
         );
       }
       if (!asObject(step.firstUpgrade).contract) {

package/runtime/workflow/steps/deploy.ts

@@ -1,3 +1,4 @@
+import { CONTROLLED_MULTICALL_AUTHORITY_ABI } from "../lib/controlledMulticallAbi";
 import path from "path";
 import { ethers, network } from "../../projectHardhat";
 import type {
@@ -286,7 +287,7 @@ const runGateToolControlledMulticall = async (
     create2.scheme,
   );
   const multicall = await ethers.getContractAt(
-    "Multicall3",
+    CONTROLLED_MULTICALL_AUTHORITY_ABI,
     create2.controlledMulticall,
     context.signer,
   );

package/runtime/workflow/steps/upgrade.ts

@@ -1,3 +1,4 @@
+import { CONTROLLED_MULTICALL_AUTHORITY_ABI } from "../lib/controlledMulticallAbi";
 import { isAddress } from "ethers";
 import { ethers, network } from "../../projectHardhat";
 import path from "path";
@@ -327,7 +328,7 @@ export const runUpgradeStep = async (
     : undefined;
   const multicall = implementationMulticall
     ? await ethers.getContractAt(
-        "Multicall3",
+        CONTROLLED_MULTICALL_AUTHORITY_ABI,
         targetMulticall.controlledMulticall,
         context.signer,
       )