gate-evm-tools 1.0.28 → 1.2.0

package/docs/plans/2026-11-02-transparent-proxy-delivery.md

@@ -0,0 +1,78 @@
+# Transparent / ProxyAdmin delivery support
+
+## Scope
+
+New ordinary EVM projects using the locked OpenZeppelin Contracts 5 toolchain.
+Keep full free of patches and private OpenZeppelin options. Preserve the UUPS
+and zkSync paths. Business ownership and ProxyAdmin ownership are explicit,
+separate business inputs completed by the developer before prod release freeze.
+Production operators consume frozen inputs and supply only execution identity.
+
+## Ordered work
+
+- [x] T1. Add explicit transparent deployment/upgrade preparation requests and
+  canonical plans. Bind implementation/proxy constructor calldata, derived
+  ProxyAdmin address, admin owner, official safety/storage checks and reuse.
+- [x] T2. Connect native workflow steps and delivery semantic/journal/compiler
+  checks. Include same-fork deployment followed by upgrade and external routing.
+- [x] T3. Register and reconcile transparent implementations, proxies and admin
+  identities in manifests/metadata. Extend CheckCode, dev acceptance and prod
+  finalization/history checks without weakening UUPS evidence.
+- [x] T4. Document the capability in deployment skill and tool instructions;
+  keep template defaults and official OpenZeppelin packages unchanged.
+- [x] T5. Build and run targeted regressions plus isolated local-chain
+  deployment, initialization, upgrade, calldata and rejection verification.
+
+## Acceptance
+
+CREATE2 prediction includes the official OZ 5 transparent proxy constructor.
+Its internally created ProxyAdmin is verified at the deterministic CREATE
+address and its owner is verified independently of the business owner. Upgrades
+target ProxyAdmin, retain original proxy address, validate the current registered
+implementation/layout and bind the expected admin identity. Wrong admin/owner,
+unsafe implementation/layout, mismatched runtime and unsupported chain scheme
+fail before execution. No package lifecycle patches or public-chain broadcasts.
+
+## Evidence
+
+Task baseline and isolated verification artifacts:
+`/Users/vector/gate/.artifacts/transparent-proxy-support/`.
+Existing dirty worktree changes are preserved. Local package publication/App
+staging are separate from source implementation and validation.
+
+## Verified results
+
+- TypeScript ESM/CJS/runtime builds pass.
+- Installed official packages on a disposable chain: CREATE2 constructor binding,
+  separate business/admin ownership, compatible upgrade and state retention,
+  incompatible layout refusal, wrong admin/owner/runtime refusal, reuse, workflow
+  manifest sync and external upgrade routing all pass. Official OZ file hashes
+  remain unchanged; original UUPS acceptance also passes.
+- Full template two-target qualification passes.
+- Full Transparent development delivery passes with deploy → same-fork upgrade →
+  configure, 4 transactions, 3 business assertions, implementation/proxy/admin
+  CheckCode and file-only recovery without duplicate signatures.
+- Static production finalizer rejects admin slot/immutable/owner/runtime drift
+  at the finalized block. Deployment skill validation passes.
+- Final production preparation now consumes the released qualification's
+  derivationSeed while retaining the new executionId. This fixes same-fork
+  compiler-closure drift without removing any baseline or hash check.
+- Full production release/export/execution/recovery passes: 4 transactions,
+  exactly 4 signatures and 4 broadcasts, 3 business assertions; release marker
+  interruption, lost broadcast response and finalization file interruption all
+  recover, repeated verification does not resend. Calldata export runs without a
+  signer or a new block, includes all 4 transactions and matches the locked plan.
+- Targeted regression: 236 tests pass; sibling-fixture zkSync regression: 8 pass.
+  Skill validation and whitespace checks pass. No project template or official
+  OZ payload change was needed for this capability.
+
+Evidence summary: `acceptance-summary.json`; production evidence:
+`local-production-acceptance.json`, `local-production-export.json`,
+`local-production-raw.json` under the evidence directory above. The local node
+was stopped after acceptance. Source changes remain uncommitted; npm publication
+and replacement of the App-owned packages were not performed.
+
+The two older zkSync tests reference a sibling `contract-tools` checkout. For
+this worktree verification only, a temporary sibling symlink was created and
+removed after the tests. No production fixture or repository source was changed
+for that accommodation.

package/docs/superpowers/plans/2026-08-17-custody-hardhat-signers.md

@@ -135,7 +135,7 @@ Run the focused test. Expected: FAIL because `installCustodyHardhatRuntime` does
 
 - [ ] **Step 3: Implement runtime installation and plugin registration**
 
-Expose a pure testable installer and register it through `extendEnvironment`. Read `WALLET_CREDENTIAL` or legacy `PRIVATE_KEY` only when signer helpers execute, cache by credential, require `CUSTODY_API_BASE_URL`, and never change impersonated signers.
+Expose a pure testable installer and register it through `extendEnvironment`. Read `PRIVATE_KEY` only when signer helpers execute, cache by credential, require `CUSTODY_API_BASE_URL`, and never change impersonated signers.
 
 - [ ] **Step 4: Verify GREEN**
 

package/docs/superpowers/plans/2026-09-24-scheme-aware-static-validation.md

@@ -0,0 +1,193 @@
+# Scheme-Aware Dual Static Validation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the canonical static-validation command run and record the required EVM and zkSync compile checks while preserving the existing zkSync project configuration and fail-closed evidence contract.
+
+**Architecture:** Keep `hardhat.config.ts` and its zkSync compiler/network settings untouched. Extend GateTool's static-validation API with explicit compile targets for `evm` and `zksync-eravm`; the CLI resolves those targets from task/workflow inputs and records scheme-aware checks in `static-validation.json`. Existing TypeScript, test, and task-document checks remain shared checks. No deploy/upgrade adapter rewrite is included in this phase.
+
+**Tech Stack:** TypeScript, Node.js `spawnSync`, YAML/JSON evidence, Node test runner, GateTool runtime package.
+
+---
+
+### Task 1: Define scheme-aware static-validation evidence and target inputs
+
+**Files:**
+- Modify: `runtime/workflow/lib/staticValidation.ts`
+- Test: `test/static-validation.test.mjs`
+
+- [ ] **Step 1: Write failing tests**
+
+Add tests proving that `runStaticValidation` accepts explicit compile targets and emits:
+
+```json
+{
+  "scheme": "evm",
+  "network": "gtDev"
+}
+```
+
+and
+
+```json
+{
+  "scheme": "zksync-eravm",
+  "network": "zk"
+}
+```
+
+for the two compile checks, while `compiledSchemes` contains both schemes. Add a failure test proving a failed zkSync compile creates a blocking reason naming the scheme and network.
+
+- [ ] **Step 2: Run the focused test and verify it fails**
+
+Run:
+
+```bash
+cd /Users/vector/gate/EvmGateTools
+npm run build && node --test test/static-validation.test.mjs
+```
+
+Expected: the new assertions fail because compile evidence currently has no scheme/network fields and only one compile command is run.
+
+- [ ] **Step 3: Implement the minimal evidence model**
+
+Add explicit compile-target types and extend compile check evidence with optional `scheme` and `network`. Add `compiledSchemes` and `compileTargets` to the structured evidence. Preserve the existing report paths and fail-closed status calculation.
+
+- [ ] **Step 4: Run the focused test and verify it passes**
+
+Run the same build and test command. Expected: all static-validation tests pass.
+
+- [ ] **Step 5: Commit the focused GateTool change**
+
+```bash
+git add runtime/workflow/lib/staticValidation.ts test/static-validation.test.mjs
+git commit -m "feat: record scheme-aware static validation"
+```
+
+### Task 2: Make the static-validation CLI run explicit EVM and zkSync compiles
+
+**Files:**
+- Modify: `runtime/workflow/staticValidate.ts`
+- Modify: `runtime/workflow/lib/staticValidation.ts`
+- Test: `test/static-validation.test.mjs`
+
+- [ ] **Step 1: Write failing CLI/runner tests**
+
+Add a test that supplies two compile targets and asserts the runner invokes exactly:
+
+```text
+npm run compile -- --network <evm-network>
+npm run compile -- --network <zksync-network>
+```
+
+before `tsc`, tests, and document parsing. Add a test that omits either required target and verifies the runner fails before claiming `passed`.
+
+- [ ] **Step 2: Run tests to verify the new behavior fails**
+
+```bash
+cd /Users/vector/gate/EvmGateTools
+npm run build && node --test test/static-validation.test.mjs
+```
+
+Expected: the invocation and missing-target assertions fail against the current single-network implementation.
+
+- [ ] **Step 3: Implement target-driven compile execution**
+
+Add `compileTargets` to `StaticValidationOptions`. For this phase require one `evm` and one `zksync-eravm` target from the canonical CLI path. Execute each target with its own `--network` value, preserve command errors, and record target-specific evidence. Keep the existing optional test command and shared checks unchanged.
+
+- [ ] **Step 4: Run the focused tests**
+
+```bash
+npm run build && node --test test/static-validation.test.mjs
+```
+
+Expected: all tests pass and evidence contains both compile checks and both compiled schemes.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add runtime/workflow/staticValidate.ts runtime/workflow/lib/staticValidation.ts test/static-validation.test.mjs
+ git commit -m "feat: require EVM and zkSync static compiles"
+```
+
+### Task 3: Wire workflow inputs and preserve the project zkSync configuration
+
+**Files:**
+- Modify: `runtime/workflow/staticValidate.ts`
+- Modify: `ai-workflows/workflows/v2/deployment/contract-deployment-developer-role-v2.yaml`
+- Modify: `ai-workflows/tests/deployment-runtime-context-policy.test.mjs`
+
+- [ ] **Step 1: Add policy regression assertions**
+
+Require the canonical command to pass explicit EVM and zkSync network arguments/targets and require both scheme results in structured evidence. Assert that the policy retains the project's `zksolc` configuration rather than asking the developer to delete it.
+
+- [ ] **Step 2: Run the policy test to verify it fails**
+
+```bash
+cd /Users/vector/gate/ai-workflows
+node --test tests/deployment-runtime-context-policy.test.mjs
+```
+
+Expected: the new dual-target assertions fail before the workflow text is updated.
+
+- [ ] **Step 3: Update the canonical workflow instructions**
+
+Document that `hardhat.config.ts` keeps its zkSync plugin, network, and `zksolc` settings; the developer must run isolated EVM and zkSync compiles using the selected configured network names; and `static-validation.json` must contain passed evidence for both schemes. Do not add a new user-facing scheme selector or infer scheme from a network name.
+
+- [ ] **Step 4: Run policy tests**
+
+```bash
+node --test tests/deployment-runtime-context-policy.test.mjs tests/zksync-create2-policy.test.mjs
+```
+
+Expected: all relevant policy tests pass.
+
+- [ ] **Step 5: Commit and push workflow policy**
+
+```bash
+git add workflows/v2/deployment/contract-deployment-developer-role-v2.yaml tests/deployment-runtime-context-policy.test.mjs
+git commit -m "docs: require dual-scheme static validation"
+git push origin main
+```
+
+### Task 4: Validate compiler compatibility and package the result
+
+**Files:**
+- Modify only if the compatibility test proves the current project combination is invalid: the SuperTask worktree's project-owned `hardhat.config.ts` and dependency manifest; do not alter GateTool's shared runtime config.
+- Test: current SuperTask worktree compile commands and generated evidence.
+
+- [ ] **Step 1: Run the exact EVM and zkSync compile commands in the current SuperTask worktree**
+
+```bash
+cd /Users/vector/gate/repo_migrate/GateFun/.worktrees/supertask-muf4zhlc-l4a7e-gatefun4
+npm run compile -- --network gtDev
+npm run compile -- --network zk
+```
+
+Expected: EVM compile passes; zkSync compile either passes or produces the exact plugin/compiler incompatibility needed for a project-owned version update.
+
+- [ ] **Step 2: If zkSync compile fails, verify the installed plugin's supported compiler range before changing config**
+
+Inspect the installed `@matterlabs/hardhat-zksync-solc` constants and compile error. Only update `zksolc` to an officially supported version if the current `1.3.22` is actually rejected by the installed plugin; preserve the plugin and network declarations.
+
+- [ ] **Step 3: Run GateTool's complete test suite and build**
+
+```bash
+cd /Users/vector/gate/EvmGateTools
+npm test
+```
+
+Expected: all tests pass.
+
+- [ ] **Step 4: Pack and install the resulting local package into the current SuperTask worktree**
+
+```bash
+mkdir -p /tmp/gateflow-local-packages
+npm pack --pack-destination /tmp/gateflow-local-packages
+cd /Users/vector/gate/repo_migrate/GateFun/.worktrees/supertask-muf4zhlc-l4a7e-gatefun4
+npm install --no-save --ignore-scripts /tmp/gateflow-local-packages/gate-evm-tools-1.0.28.tgz
+```
+
+- [ ] **Step 5: Verify structured evidence and repository status**
+
+Run the canonical static validation with explicit targets, inspect `docs/static-validation.json`, and confirm the evidence is current-run and contains both schemes. Do not modify or delete failed SuperTask state automatically. Confirm all intended repositories are clean or contain only explicitly documented changes.

package/docs/superpowers/plans/2026-10-28-create2-miner.md

@@ -0,0 +1,82 @@
+# GateTool CREATE2 Miner Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox syntax for tracking.
+
+**Goal:** Add an independently callable, packaged CREATE2 miner to GateTool while retaining the existing GateFlow miner unchanged.
+
+**Architecture:** Reuse the existing create2Crunch macOS executables, with a GateTool-owned typed request/result API, binary resolver, bounded child-process lifecycle and independent cryptographic verification. Mining is explicit preparation work: no automatic deployment hooks, transaction signing, DB/state migration or parameter mutation. Publish a `gate-evm-tools/create2-miner` subpath and `gate-tool miner` CLI; distribute both binaries offline in the npm archive.
+
+**Tech Stack:** TypeScript, Node child_process, existing ethers v6 runtime/hash helpers, Rust Mach-O binaries, node:test, npm pack.
+
+**Workspace:** `/Users/vector/gate/.worktrees/evm-delivery/EvmGateTools`, existing clean branch `feat/evm-delivery`, base `31c709a6bf7eb69ecad99a3f49ec08f332819cd5`. No changes in SmartFlowAI, EvmHardhatCli or create2Crunch; no npm publication/version bump/App rebuild.
+
+## Task 1: Miner API, CLI and offline distribution
+
+**Files:**
+- Create `runtime/miner/{types,request,verify,binary,runner,index,cli}.ts` with one responsibility per module.
+- Create `resources/create2/{darwin-arm64,darwin-x64}/smartflow_miner`, `resources/create2/{LICENSE,manifest.json,README.md}`.
+- Modify `package.json` exports/typesVersions/files; `bin/cli.js` may route the `miner` command before heavyweight legacy CLI loading. Add help integration in `src/index.ts` if needed.
+- Create `test/create2-miner.test.mjs`, `test/create2-miner-process.test.mjs`, `test/create2-miner-package.test.mjs` and small executable test fixtures as needed.
+- Modify `README.md`, add `docs/create2-miner.md`; regenerate tracked build artifacts with the existing build.
+
+### Public contract
+
+```ts
+// Export typed requests, normalized requests/results and options from the subpath.
+normalizeCreate2MinerRequest(input: unknown): NormalizedCreate2MinerRequest;
+create2MinerRequestFromArtifact(input: {
+  scheme?: 'evm' | 'zksync-eravm'; artifact: Create2HashArtifact;
+  args: unknown[]; factory: string; caller: string;
+  leadingZeroBytes?: number; leadingPattern?: number; targetCount?: number;
+  backend?: 'auto' | 'cpu' | 'gpu' | 'metal' | 'opencl';
+}): NormalizedCreate2MinerRequest;
+resolveCreate2MinerBinary(options?: { binaryPath?: string }): string;
+verifyCreate2MinerResponse(request: Create2MinerRequest, response: unknown): Create2MinerRunResult;
+mineCreate2(request: Create2MinerRequest, options?: {
+  binaryPath?: string; signal?: AbortSignal; timeoutMs?: number;
+  onProgress?: (progress: { status: 'running'; elapsedMs: number }) => void;
+}): Promise<Create2MinerRunResult>;
+```
+
+Contract details:
+- Normalize EVM default scheme and explicit EraVM, strict address/hash lengths, separate scheme-specific hashes, required caller salt prefix, positive bounded targetCount (1–100), leadingZeroBytes 0–20, leadingPattern 0–255. Default backend auto, targetCount 1, difficulty/pattern 0. Unknown/irrelevant fields must not silently change intent. Do not expose Rust debugging nonce/prefix controls yet.
+- GPU supports only repeated-nibble patterns (00,11,...,ff); reject other patterns before spawn unless CPU selected. Validate platform-incompatible backend selection clearly.
+- Artifact helper reuses existing canonicalCreate2Hashes (actual ABI constructor encoding, artifact format and linked bytecode validation); no HRE/RPC/compiler/secret needed.
+- Return normalized request identity plus verified results, actual backend, attempts/duration/rate from binary, explicit status found. Strictly require status, scheme, count, unique salts/addresses and all identity fields. Reject forged/missing/foreign hashes, caller mismatch, leading policy mismatch, nonmatching computed addresses/patterns and partial results. EVM address uses ff/factory/salt/initCodeHash; EraVM uses zksyncCreate2 domain/factory padding/salt/bytecodeHash/constructorInputHash. Metrics must be finite nonnegative; they are reported telemetry, not proof.
+- Resolver uses explicit binaryPath, then GATE_TOOL_CREATE2_MINER_BIN, then package-relative resources for host platform/architecture. Unsupported hosts get an actionable override/build error. Validate bundled file SHA-256 against a trusted manifest pin and executable permissions. Explicit overrides are trusted executable paths; do not fall back silently when invalid. No cwd-based discovery/download/postinstall.
+- Manifest records actual file lengths/SHA-256 and honest provenance (copied from SmartFlow repository resources at its inspected commit; Rust reference checkout is not proof of the binary build revision). Include upstream MIT license, preserve executable bits.
+- Spawn without shell; send JSON over stdin. Bounded stdout/stderr, handle spawn/nonzero exit/malformed JSON/stalled processes. Abort/timeout kills and reaps child (TERM with bounded KILL fallback), clears timers/listeners, settles once, no orphan process. Progress reports elapsed time only. Catch callback errors and terminate cleanly. Pre-aborted calls must not spawn.
+- CLI: `gate-tool miner --request request.json [--output result.json] [--binary /absolute/path] [--timeout-ms N]`; request `-` accepts stdin. JSON result on stdout, diagnostics on stderr, optional output written only after successful verification (avoid truncating existing files on failure; reject overwriting request). SIGINT/SIGTERM must cancel child and exit nonzero. Help must be discoverable through both `gate-tool --help` and `gate-tool miner --help`.
+- This API uses the existing ethers v6 runtime requirement; document it. No changes to old SuperTask adapters, handoff tasks, release sealing, frozen salts, setup version pin or deployment executors.
+
+### Execution steps
+
+- [x] Write failing functional tests for request normalization, artifact hash construction, EVM known address and EraVM reference vectors, and forged response rejection. Assert exports exist before importing lazily so the initial failure identifies missing capability. Run `node --test test/create2-miner.test.mjs` and record expected RED.
+- [x] Implement request/types/verification and API exports; run `npm run build` and the functional test to GREEN.
+- [x] Write lifecycle and CLI tests before implementation: real fixture subprocess stdout/failure/hang/oversized output, AbortSignal, timeout, callback failure, executable resolution and invalid paths. Run new tests to expected RED; then implement process runner/resolver/CLI.
+- [x] Copy the two authorized existing executables (do not remove originals), license and manifest with source/hash evidence. Write package acceptance test before packaging changes: pack into a temp directory, extract away from checkout, verify both binary bytes/modes and API types/exports/help, invoke bundled native CPU mining for EVM and EraVM on supported hosts. Tests may use isolated installed dependencies or explicit symlinks to dependencies, but must not resolve the miner from a checkout path. Test failure diagnostics and clean temporary resources.
+- [x] Wire package and help; add usage docs and verified-result JSON example. Run `npm run build`, `node --test test/create2-miner*.test.mjs test/delivery-source-package.test.mjs test/runtime-version.test.mjs` once all source changes are ready. Record actual tar size. Smoke real native GPU if the current Mac supports it, separately from required deterministic CPU acceptance.
+- [x] Review source and spec independently, resolve concrete findings, and rerun affected checks only. Record evidence here. Commit only these changes locally after verification; do not push/publish/update App runtime archives.
+
+## Acceptance record
+
+Implementation and independent reviews complete. The GateFlow application continues using its original miner until a separately authorized integration.
+
+Parent baseline checks (before new wrapper implementation):
+- Existing runtime identity binding regression: 1 passed.
+- Existing macOS arm64 executable: CPU EVM and EraVM requests returned complete `found` responses.
+- Existing macOS arm64 executable: GPU EVM request with one leading zero byte returned a qualifying address through Metal (~5.8 seconds); reported attempts/hashRate were zero, confirming these counters are unavailable on GPU.
+- Existing x64 executable cannot run on this arm64 host (`Bad CPU type in executable`); x64 runtime acceptance remains outside this host's coverage.
+- Both executables link to macOS system libraries/frameworks, not developer checkout paths.
+- Source resource SHA-256: arm64 `9611c1ca900c24f9b14924a144b7a3ab431111b855e676f2e145e7ab8c05f954` (1,297,616 bytes); x64 `a38279143658a8849db484e248c62af6ae2db78de4251021f195efd9bf987d82` (1,306,112 bytes).
+
+Feature commit `8f7a8a2d1d9cb7106ac53b0dcb2b2beefa2ddc32`:
+- Functional RED (5 missing-export failures), lifecycle/CLI RED (15 missing-runner failures), package/type RED (missing resources and raw-input type) were observed before corresponding implementation. Result type alias also received a consumer RED/GREEN check.
+- Full build succeeded. Focused command passed 25 tests, 0 failures/skips. Raw logs are preserved outside the published package at `../setup-logs/create2-miner-20261028/{build.log,focused-tests.log}`.
+- Extracted npm package CPU runs: EVM and EraVM each returned two unique, verified addresses with a leading zero byte; CJS/ESM imports and `.cts`/`.mts` consumers passed. Both architectures' binary hashes, modes and tamper rejection passed.
+- Implementer's separate extracted-package Metal smoke passed EVM (5,117 ms, address `0x001f764470407c723db31f0f490c2edaed0fed70`) and EraVM (11,733 ms, address `0x0012736ec2bc4d20068df1bc6bd9676663a02e2b`). Native GPU attempts/rate remained zero/unavailable.
+- Acceptance tar at this stage was 2,448,819 bytes compressed; final delivery tar may differ due to review fixes and this record.
+- Independent specification review identified a CLI cancellation window during asynchronous output writing. Fix `86daf843d44486561dc60ea3f1541e4f47a99fb9` checks cancellation around output commit and before success reporting. All 16 process tests passed, including SIGINT/SIGTERM at three real filesystem-operation boundaries. The reviewer independently rechecked and issued specification PASS. Raw logs: `output-cancellation-{build,red-original,green}.log` in the same evidence directory.
+- Quality review found that the exported verifier's array `map` could skip sparse result slots from JavaScript callers (native JSON cannot encode holes). Fix `c21667ffd7151db2b6316d2fcb3d414c22285306` validates every expected index, independent of array holes/custom iterators. Full build and affected functional tests passed (5/5); the reviewer independently reproduced rejection and issued quality PASS. Raw logs: `sparse-response-{red,iterator-red,build,green}.log`.
+- No remaining critical/important review findings. Final source has 26 focused tests; the full 25-test run preceded review corrections, which were verified with affected suites (16 process/CLI and 5 functional tests). No production-chain execution, npm publication, App build/toolchain replacement, or changes to other repositories were performed.
+- A local installation archive and machine-readable receipt are produced at `../artifacts/create2-miner-20261028/`. `ACCEPTANCE.json` records final package SHA-256, bytes, source commit and extracted-package CLI acceptance for both schemes. Reproduction script: `../setup-logs/create2-miner-20261028/verify-local-package.mjs`. Package-only checks reuse the worktree's dependencies by symlink; miner code and native resources come exclusively from the extracted archive.

package/docs/workflow-reference.md

@@ -1,3 +1,5 @@
+> 历史文档：其中的 gate-workflow 命令已移除。新项目使用 gate-tool delivery 与 delivery API，见 [部署接入](delivery-setup.md)。
+
 # Full EVM workflow reference
 
 Reference for the full EVM template and GateTool task-based deployment workflow.
@@ -90,8 +92,7 @@ CUSTODY_API_BASE_URL=https://custody.example.com
 `CUSTODY_API_BASE_URL` must be an HTTP(S) base URL without embedded
 credentials, query parameters, or fragments.
 
-`WALLET_CREDENTIAL` is an optional alias for `PRIVATE_KEY`. If both variables
-are configured, they must contain the same value. `hardhat.config.ts` loads the
+`PRIVATE_KEY` is the only wallet credential environment variable. `hardhat.config.ts` loads the
 custody plugin after the ethers and OpenZeppelin plugins. A real private key is
 passed through native `networks.accounts`; a custody credential leaves native
 accounts empty and supplies the remote signer through Hardhat and the workflow
@@ -285,7 +286,7 @@ npm run workflow -- \
 `--network` to Hardhat and passes workflow arguments such as `--task`, `--mode`,
 `--target`, `--step`, `--from`, `--simulationSigner`, and `--operator` to the runtime.
 For `--mode execute` on real configured networks, the runtime fails early when
-neither `WALLET_CREDENTIAL` nor `PRIVATE_KEY` is present in the project `.env`
+`PRIVATE_KEY` is absent or empty in the project `.env`
 or process environment.
 Every target whose `environment` is `production` additionally requires
 `--useLock`; a production execute without the immutable final-simulation plan
@@ -710,7 +711,7 @@ acceptance requirement.
 signer setup. The tracked `rpc.env` file provides the shared `BASE_RPC_URI` for
 the project; SmartFlow may populate its initially empty value once when it
 creates a new internal project. `.env` remains untracked and only provides
-`WALLET_CREDENTIAL`/`PRIVATE_KEY`, `CUSTODY_API_BASE_URL`, and the optional full
+`PRIVATE_KEY`, `CUSTODY_API_BASE_URL`, and the optional full
 `ZKSYNC_RPC_URL`.
 
 Each remote network declares `route`, `publicFallback`, and `useBaseRpc`
@@ -1179,3 +1180,10 @@ Workflow implementations are provided by `gate-evm-tools`; npm scripts invoke th
 `npx --no-install gate-workflow --help` exposes compiled workflow commands without a manual ts-node preload. Existing npm commands remain supported. Before upgrading an existing task, finish it with the original runtime or reconcile it and prepare a new execution ID; execution bindings reject a different package build. `gate-workflow migrate` previews removal of recognized baseline files and shims; `--apply` backs up originals, updates known commands/imports and removes known runtime scripts; customized files or unresolved references require manual review. It does not change business data or install dependencies.
 
 Network declarations live directly in `hardhat.config.ts` under its single `networks` block. Edit names, chain IDs, RPC routes/fallbacks and zkSync flags there; do not create a second network list. `createNetworkHelpers` from `gate-evm-tools/runtime-config/networks` supplies only account/RPC/fork mechanics. Add `rpcUrl: process.env.BSC_DEV_RPC_URL` to one `remoteNetwork({ ... })` entry to override its RPC, or spread that entry into `{ ...remoteNetwork({ ... }), timeout: 60000 }` for other Hardhat fields. Load rpc.env/.env before creating the helpers. Dev/Prod represent business environments, not testnet/mainnet. Compiler versions/settings remain project-owned; overlay migration merges the network block and keeps the original toolchain. The deprecated `createTemplateNetworks` export remains for older generated projects only and is not called by the current template.
+
+### Official unpatched OpenZeppelin
+
+CREATE2 / UUPS use GateTool preparation and explicit planned calls, not private
+OpenZeppelin deployProxy options. Transparent/ProxyAdmin is unsupported here.
+See [OpenZeppelin integration](openzeppelin-integration.md) for script API,
+atomic initialization, explicit ownership and prod calldata boundaries.

package/docs/workflow-runtime.md

@@ -1,3 +1,5 @@
+> 历史文档：其中的 gate-workflow 命令已移除。新项目使用 gate-tool delivery 与 delivery API，见 [部署接入](delivery-setup.md)。
+
 # 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.
@@ -54,3 +56,7 @@ Register `registerZkSyncSolcAdapter(subtask, TASK_COMPILE_SOLIDITY_RUN_SOLC)` wi
 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.
+
+`gate-evm-tools/deployment-evm` exposes signer-free preparation/composition over
+the same workflow engine. Official OZ packages remain unchanged; the proxy
+workflow supports UUPS. See [OpenZeppelin integration](openzeppelin-integration.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gate-evm-tools",
-  "version": "1.0.28",
+  "version": "1.2.0",
   "description": "Gate 智能合约工具集 - 字节码检查、合约升级验证、合约状态同步",
   "type": "module",
   "exports": {
@@ -32,7 +32,89 @@
       "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-task": {
+      "types": "./dist-runtime/delivery/task-identity.d.ts",
+      "default": "./dist-runtime/delivery/task-identity.js"
+    },
+    "./delivery-calldata": {
+      "types": "./dist-runtime/delivery/public-calldata.d.ts",
+      "default": "./dist-runtime/delivery/public-calldata.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"
+    },
+    "./deployment-evm": {
+      "types": "./dist/deployment-evm/index.d.ts",
+      "import": "./dist/deployment-evm/index.js",
+      "require": "./dist-cjs/deployment-evm/index.js"
+    }
   },
   "typesVersions": {
     "*": {
@@ -53,12 +135,65 @@
       ],
       "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"
+      ],
+      "deployment-evm": [
+        "dist/deployment-evm/index.d.ts"
       ]
     }
   },
   "bin": {
-    "gate-tool": "./bin/cli.js",
-    "gate-workflow": "./bin/workflow.cjs"
+    "gate-tool": "./bin/cli.js"
   },
   "files": [
     "bin/",
@@ -68,15 +203,17 @@
     "contractInfo.example.json",
     "dist-runtime/",
     "runtime/",
-    "docs/"
+    "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:evm": "npm run build && node --test test/integration/delivery-evm.test.mjs"
   },
   "keywords": [
     "bytecode",
@@ -93,12 +230,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"
   },
@@ -117,8 +256,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",
@@ -145,6 +283,6 @@
     }
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.13.0"
   }
 }