gate-evm-tools 1.0.27 → 1.0.31

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.31",
   "description": "Gate 智能合约工具集 - 字节码检查、合约升级验证、合约状态同步",
   "type": "module",
   "exports": {
@@ -32,7 +32,76 @@
       "types": "./dist-runtime/config/*.d.ts",
       "default": "./dist-runtime/config/*.js"
     },
-    "./runtime-source/*": "./runtime/*.ts"
+    "./runtime-source/*": "./runtime/*.ts",
+    "./delivery-setup": {
+      "types": "./dist-runtime/delivery/setup.d.ts",
+      "default": "./dist-runtime/delivery/setup.js"
+    },
+    "./delivery-protocol": {
+      "types": "./dist-runtime/delivery/protocol.d.ts",
+      "default": "./dist-runtime/delivery/protocol.js"
+    },
+    "./delivery-hardhat": {
+      "types": "./dist-runtime/delivery/hardhat.d.ts",
+      "default": "./dist-runtime/delivery/hardhat.js"
+    },
+    "./delivery-policy": {
+      "types": "./dist/delivery/policy.d.ts",
+      "import": "./dist/delivery/policy.js",
+      "require": "./dist-cjs/delivery/policy.js"
+    },
+    "./delivery-source": {
+      "types": "./dist-runtime/delivery/source.d.ts",
+      "default": "./dist-runtime/delivery/source.js"
+    },
+    "./delivery-parameters": {
+      "types": "./dist-runtime/delivery/parameters.d.ts",
+      "default": "./dist-runtime/delivery/parameters.js"
+    },
+    "./delivery-inputs": {
+      "types": "./dist-runtime/delivery/inputs.d.ts",
+      "default": "./dist-runtime/delivery/inputs.js"
+    },
+    "./delivery-configuration": {
+      "types": "./dist-runtime/delivery/configuration.d.ts",
+      "default": "./dist-runtime/delivery/configuration.js"
+    },
+    "./delivery-aggregate": {
+      "types": "./dist-runtime/delivery/aggregate.d.ts",
+      "default": "./dist-runtime/delivery/aggregate.js"
+    },
+    "./delivery-export": {
+      "types": "./dist-runtime/delivery/export.d.ts",
+      "default": "./dist-runtime/delivery/export.js"
+    },
+    "./delivery-execution-store": {
+      "types": "./dist-runtime/delivery/execution-store.d.ts",
+      "default": "./dist-runtime/delivery/execution-store.js"
+    },
+    "./delivery-eoa": {
+      "types": "./dist-runtime/delivery/eoa.d.ts",
+      "default": "./dist-runtime/delivery/eoa.js"
+    },
+    "./delivery-development": {
+      "types": "./dist-runtime/delivery/development.d.ts",
+      "default": "./dist-runtime/delivery/development.js"
+    },
+    "./delivery-release": {
+      "types": "./dist-runtime/delivery/release.d.ts",
+      "default": "./dist-runtime/delivery/release.js"
+    },
+    "./delivery-production": {
+      "types": "./dist-runtime/delivery/production.d.ts",
+      "default": "./dist-runtime/delivery/production.js"
+    },
+    "./delivery-safe": {
+      "types": "./dist-runtime/delivery/safe.d.ts",
+      "default": "./dist-runtime/delivery/safe.js"
+    },
+    "./create2-miner": {
+      "types": "./dist-runtime/miner/index.d.ts",
+      "default": "./dist-runtime/miner/index.js"
+    }
   },
   "typesVersions": {
     "*": {
@@ -53,12 +122,64 @@
       ],
       "runtime-config/*": [
         "dist-runtime/config/*.d.ts"
+      ],
+      "delivery-setup": [
+        "dist-runtime/delivery/setup.d.ts"
+      ],
+      "delivery-protocol": [
+        "dist-runtime/delivery/protocol.d.ts"
+      ],
+      "delivery-hardhat": [
+        "dist-runtime/delivery/hardhat.d.ts"
+      ],
+      "delivery-policy": [
+        "dist/delivery/policy.d.ts"
+      ],
+      "delivery-source": [
+        "dist-runtime/delivery/source.d.ts"
+      ],
+      "delivery-parameters": [
+        "dist-runtime/delivery/parameters.d.ts"
+      ],
+      "delivery-inputs": [
+        "dist-runtime/delivery/inputs.d.ts"
+      ],
+      "delivery-configuration": [
+        "dist-runtime/delivery/configuration.d.ts"
+      ],
+      "delivery-aggregate": [
+        "dist-runtime/delivery/aggregate.d.ts"
+      ],
+      "delivery-export": [
+        "dist-runtime/delivery/export.d.ts"
+      ],
+      "delivery-execution-store": [
+        "dist-runtime/delivery/execution-store.d.ts"
+      ],
+      "delivery-eoa": [
+        "dist-runtime/delivery/eoa.d.ts"
+      ],
+      "delivery-development": [
+        "dist-runtime/delivery/development.d.ts"
+      ],
+      "delivery-release": [
+        "dist-runtime/delivery/release.d.ts"
+      ],
+      "delivery-production": [
+        "dist-runtime/delivery/production.d.ts"
+      ],
+      "delivery-safe": [
+        "dist-runtime/delivery/safe.d.ts"
+      ],
+      "create2-miner": [
+        "dist-runtime/miner/index.d.ts"
       ]
     }
   },
   "bin": {
     "gate-tool": "./bin/cli.js",
-    "gate-workflow": "./bin/workflow.cjs"
+    "gate-workflow": "./bin/workflow.cjs",
+    "gate-delivery": "./bin/delivery.cjs"
   },
   "files": [
     "bin/",
@@ -67,15 +188,18 @@
     "README.md",
     "contractInfo.example.json",
     "dist-runtime/",
-    "runtime/"
+    "runtime/",
+    "docs/",
+    "resources/create2/"
   ],
   "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",
+    "build": "tsc && tsc -p tsconfig.custody-cjs.json && node scripts/write-cjs-package.mjs && tsc -p tsconfig.runtime.json && node scripts/stage-plan-codec.mjs && node scripts/write-runtime-package.mjs",
     "dev": "tsc --watch",
     "start": "node bin/cli.js",
     "pretest": "npm run build",
     "test": "node --test test/*.test.mjs",
-    "test:custody:hardhat-v6": "npm run build && node scripts/test-custody-hardhat-v6.mjs"
+    "test:custody:hardhat-v6": "npm run build && node scripts/test-custody-hardhat-v6.mjs",
+    "test:delivery:core": "npm run build && node --test test/integration/delivery-core.test.mjs"
   },
   "keywords": [
     "bytecode",
@@ -92,12 +216,14 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
+    "ajv": "8.17.1",
     "chalk": "^5.3.0",
     "commander": "^11.1.0",
     "fs-extra": "^11.2.0",
     "ora": "^7.0.1",
     "prompts": "^2.4.2",
     "semver": "^7.8.5",
+    "typescript": "5.9.3",
     "yaml": "2.8.1",
     "zksync-ethers": "6.15.0"
   },
@@ -116,8 +242,7 @@
     "ethers": "^6.15.0",
     "ethers5": "npm:ethers@5.7.2",
     "hardhat": "2.27.1",
-    "ts-node": "10.9.2",
-    "typescript": "^5.9.3"
+    "ts-node": "10.9.2"
   },
   "peerDependencies": {
     "@matterlabs/hardhat-zksync-deploy": "1.8.0",
@@ -144,6 +269,6 @@
     }
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.13.0"
   }
 }

package/resources/create2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 0age
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/resources/create2/README.md

@@ -0,0 +1,9 @@
+# Bundled CREATE2 miner
+
+`smartflow_miner` accepts a single JSON request on stdin and emits a single final JSON response. These macOS arm64 and x64 executables are copied byte-for-byte from SmartFlowAI `resources/create2`, whose last resource commit was `a31308bdbe81c02181ff4bcd2b992681c184d40f`. The original application resources are unchanged.
+
+`manifest.json` records sizes, SHA-256 digests and provenance. The runtime also embeds the trusted digests and checks executable permissions before invoking a bundled binary. Editing the manifest cannot authorize a replacement binary.
+
+The local create2Crunch source reference is `38b2dcd55c45cc79947fb9bf5f363222adf24ab0`. It describes the JSON protocol, but is **not a proven build revision** for these existing executable artifacts. The exact build revision is unknown. The upstream MIT license is retained in `LICENSE`.
+
+No downloads, postinstall hooks, or application resource lookups are used. Other hosts require a compatible user-supplied build via `GATE_TOOL_CREATE2_MINER_BIN` or `binaryPath`. See [the API and CLI documentation](../../docs/create2-miner.md).

package/resources/create2/manifest.json

@@ -0,0 +1,27 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "repository": "SmartFlowAI",
+    "resourceCommit": "a31308bdbe81c02181ff4bcd2b992681c184d40f",
+    "resourceDirectory": "resources/create2"
+  },
+  "rustReference": {
+    "repository": "create2Crunch",
+    "revision": "38b2dcd55c45cc79947fb9bf5f363222adf24ab0",
+    "provenBuildRevision": false
+  },
+  "binaryBuildRevision": null,
+  "provenanceNote": "Copied byte-for-byte from the existing SmartFlowAI resources. The Rust checkout is a protocol/source reference, not a proven revision used to build these binaries.",
+  "binaries": {
+    "darwin-arm64": {
+      "path": "darwin-arm64/smartflow_miner",
+      "sha256": "9611c1ca900c24f9b14924a144b7a3ab431111b855e676f2e145e7ab8c05f954",
+      "bytes": 1297616
+    },
+    "darwin-x64": {
+      "path": "darwin-x64/smartflow_miner",
+      "sha256": "a38279143658a8849db484e248c62af6ae2db78de4251021f195efd9bf987d82",
+      "bytes": 1306112
+    }
+  }
+}

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/config/openzeppelin.ts

@@ -3,20 +3,14 @@ import path from "path";
 import YAML from "yaml";
 import { parseForkSnapshotJson } from "../workflow/lib/forkSnapshot";
 
-export type DeploymentEnvironment = "local" | "development" | "production";
+import { validateManifestPolicy, type ManifestEnvironment } from "../delivery/policy";
+export type DeploymentEnvironment = ManifestEnvironment;
 
 export interface OpenZeppelinTargetConfig {
   environment: DeploymentEnvironment;
   openzeppelin?: { manifestDir?: unknown };
 }
 
-const TARGET_ENVIRONMENTS = new Set<DeploymentEnvironment>([
-  "local",
-  "development",
-  "production",
-]);
-const SAFE_MANIFEST_DIR = /^\.openzeppelin(?:\.[a-z0-9][a-z0-9-]*)?$/;
-
 const assertConfinedManifestDirectory = (root: string, manifestDir: string): void => {
   const rootPath = fs.realpathSync(root);
   const candidatePath = path.resolve(root, manifestDir);
@@ -37,19 +31,7 @@ export function resolveOpenZeppelinManifestDir(
   network: string,
   target: OpenZeppelinTargetConfig,
 ): string {
-  if (!TARGET_ENVIRONMENTS.has(target?.environment)) {
-    throw new Error(`Network ${network} must declare a valid deployment environment`);
-  }
-  const manifestDir = target.openzeppelin?.manifestDir;
-  if (typeof manifestDir !== "string" || !SAFE_MANIFEST_DIR.test(manifestDir)) {
-    throw new Error(`Network ${network} must declare one safe OpenZeppelin manifest directory segment`);
-  }
-  if (target.environment === "production" && manifestDir !== ".openzeppelin") {
-    throw new Error(`Production network ${network} must use exactly .openzeppelin`);
-  }
-  if (target.environment !== "production" && manifestDir === ".openzeppelin") {
-    throw new Error(`Non-production network ${network} must not use .openzeppelin`);
-  }
+  const manifestDir = validateManifestPolicy(target?.environment, target.openzeppelin?.manifestDir);
   assertConfinedManifestDirectory(root, manifestDir);
   return manifestDir;
 }