gate-evm-tools 1.0.27 → 1.0.31

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

@@ -0,0 +1,227 @@
+# Custody Hardhat Signers 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:** Extend `gate-evm-tools` with one custody credential format that automatically creates an ethers v5 or v6 remote signer and transparently supplies it through Hardhat signer helpers.
+
+**Architecture:** A dependency-light credential module parses real private keys and `custody:<ProjectSecret>:<WalletAddress>` values. A runtime signer factory receives the active `hre.ethers` object, detects its real major version, and constructs the matching v5/v6 Signer without bundling ethers. A Hardhat environment wrapper replaces `getSigners`, matching `getSigner`, and matching `provider.getSigner`, while real private keys continue through native `networks.accounts`. The package publishes ESM and CJS subpath exports so both modern imports and Hardhat 2 configuration loading work.
+
+**Tech Stack:** TypeScript, Node.js ESM/CJS, Node test runner, ethers 5.7/6.15, Hardhat 2, OpenZeppelin Hardhat Upgrades 3.9.
+
+---
+
+### Task 1: Credential parsing and Hardhat accounts
+
+**Files:**
+- Create: `test/custody-credential.test.mjs`
+- Create: `src/custody/credential.ts`
+- Create: `src/custody/version.ts`
+- Create: `src/custody/index.ts`
+
+- [ ] **Step 1: Write failing credential tests**
+
+Test these public calls before they exist:
+
+```js
+parseWalletCredential(`0x${"11".repeat(32)}`)
+parseWalletCredential(`custody:${projectSecret}:${walletAddress}`)
+resolveHardhatAccounts(custodyCredential)
+resolveWalletCredential({ PRIVATE_KEY: custodyCredential })
+detectEthersMajor({ version: "ethers/5.7.2" })
+detectEthersMajor({ version: "6.15.0" })
+```
+
+Require private keys to normalize to `0x` form, custody credentials to expose only the parsed secret/address internally, custody accounts to return `[]`, private-key accounts to return `[privateKey]`, conflicting environment variables to fail, zero/invalid addresses to fail, and unsupported ethers versions to fail.
+
+- [ ] **Step 2: Verify RED**
+
+Run:
+
+```bash
+npm run build
+node --test test/custody-credential.test.mjs
+```
+
+Expected: FAIL because `gate-evm-tools/custody` is not exported.
+
+- [ ] **Step 3: Implement minimal parsing and version detection**
+
+Expose:
+
+```ts
+parseWalletCredential(value: string): ParsedWalletCredential
+resolveWalletCredential(env?: NodeJS.ProcessEnv): ParsedWalletCredential | undefined
+resolveHardhatAccounts(value?: string): string[]
+detectEthersMajor(ethersRuntime: { version?: unknown }): 5 | 6
+```
+
+Accept only `0x`-optional 64-hex private keys or the versioned custody format. Never treat a valid-looking 64-hex value as a custody credential.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run the focused test and require all assertions to pass.
+
+### Task 2: Real ethers v5/v6 remote signers
+
+**Files:**
+- Create: `test/custody-signer.test.mjs`
+- Create: `src/custody/service.ts`
+- Create: `src/custody/signer.ts`
+- Modify: `src/custody/index.ts`
+- Modify: `package.json`
+- Modify: `package-lock.json`
+
+- [ ] **Step 1: Install a test-only ethers v5 alias**
+
+Add:
+
+```json
+"ethers5": "npm:ethers@5.7.2"
+```
+
+Keep host `ethers` as a peer dependency rather than a production dependency.
+
+- [ ] **Step 2: Write failing cross-version signer tests**
+
+For real ethers 5.7 and 6.15 runtime objects, require `createSigner` to:
+
+```js
+createSigner({
+  ethers: ethersRuntime,
+  credential,
+  provider,
+  baseUrl: "http://custody.local",
+  fetchImpl,
+})
+```
+
+Test a real private key returns the matching native Wallet. For custody mode, make the fake HTTP service sign transactions, UTF-8 messages, byte messages, and EIP-712 values with a known wallet. Require v6 `signTypedData`, v5 `_signTypedData`, locally recovered addresses, signed raw transaction sender, unchanged unsigned transaction, Authorization header, endpoint paths, and unique idempotency keys.
+
+- [ ] **Step 3: Verify RED**
+
+Run the focused test. Expected: FAIL because `createSigner` does not exist.
+
+- [ ] **Step 4: Implement service client and dynamic signer classes**
+
+The v6 class must extend the active runtime's `AbstractSigner`; the v5 class must extend its `Signer`. Both implement `getAddress`, `connect`, `signTransaction`, and `signMessage`; v6 implements `signTypedData`, while v5 implements `_signTypedData`. Validate every returned signature locally before returning it, and compare signed/unsigned transaction payloads before broadcast.
+
+- [ ] **Step 5: Verify GREEN**
+
+Run focused credential and signer tests for both majors.
+
+### Task 3: Hardhat signer injection
+
+**Files:**
+- Create: `test/custody-hardhat.test.mjs`
+- Create: `src/custody/hardhat-runtime.ts`
+- Create: `src/custody/hardhat.ts`
+
+- [ ] **Step 1: Write failing Hardhat wrapper tests**
+
+Use v5 and v6-shaped HRE fixtures. Require custody mode to return the remote signer from:
+
+```js
+await hre.ethers.getSigners()
+await hre.ethers.getSigner(custodyAddress)
+await hre.ethers.provider.getSigner(0)
+await hre.ethers.provider.getSigner(custodyAddress)
+```
+
+Require an unrelated address and non-custody configuration to delegate to the original methods. Require version/address logging without logging the Project Secret.
+
+- [ ] **Step 2: Verify RED**
+
+Run the focused test. Expected: FAIL because `installCustodyHardhatRuntime` does not exist.
+
+- [ ] **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.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run all custody unit tests.
+
+### Task 4: Dual ESM/CJS packaging and documentation
+
+**Files:**
+- Create: `tsconfig.custody-cjs.json`
+- Create: `scripts/write-cjs-package.mjs`
+- Modify: `package.json`
+- Modify: `package-lock.json`
+- Modify: `README.md`
+- Verify: `dist/custody/**`
+- Verify: `dist-cjs/custody/**`
+
+- [ ] **Step 1: Write failing package export tests**
+
+Extend tests to load both:
+
+```js
+await import("gate-evm-tools/custody")
+require("gate-evm-tools/custody")
+await import("gate-evm-tools/hardhat")
+require("gate-evm-tools/hardhat")
+```
+
+Expected before packaging work: CJS or subpath resolution fails.
+
+- [ ] **Step 2: Build both module formats**
+
+Compile all source to `dist` as ESM and custody source to `dist-cjs` as CommonJS. Write `dist-cjs/package.json` containing `{ "type": "commonjs" }`. Add `exports` entries with `types`, `import`, and `require`, include `dist-cjs/` in package files, expand the ethers peer range to `>=5.7.0 <7.0.0`, and build before tests.
+
+- [ ] **Step 3: Document migration**
+
+Document:
+
+```ts
+import { resolveHardhatAccounts } from "gate-evm-tools/hardhat";
+
+const PRIVATE_KEY = process.env.PRIVATE_KEY || "";
+accounts: resolveHardhatAccounts(PRIVATE_KEY)
+```
+
+Explain that business scripts stay unchanged, custody mode leaves native accounts empty, v5/v6 are selected from `hre.ethers.version`, and OpenZeppelin CREATE2 patching remains independent.
+
+- [ ] **Step 4: Verify package contents**
+
+Run build, all tests, and `npm pack --dry-run`; require both module formats and docs to be included with no fixture secrets.
+
+### Task 5: Native Hardhat and OpenZeppelin local integration
+
+**Files:**
+- Create: `test/fixtures/custody-hardhat-v6/**`
+- Create: `scripts/test-custody-hardhat-v6.mjs`
+- Modify: `package.json`
+
+- [ ] **Step 1: Create a local native fixture**
+
+Start a Hardhat node with its public first development key, start a mock custody HTTP service for that key, and run a second Hardhat config whose remote `localhost` network uses:
+
+```ts
+accounts: resolveHardhatAccounts(process.env.PRIVATE_KEY)
+```
+
+The deployment script must call `ethers.getContractFactory` and `upgrades.deployProxy` without explicitly passing a signer.
+
+- [ ] **Step 2: Verify the native flow**
+
+Set only the composite `PRIVATE_KEY`, custody URL, and RPC URL. Require implementation/proxy deployment transactions to hit `/sign-transaction`, the proxy state to be initialized, and the signer address to equal the custody address.
+
+- [ ] **Step 3: Final verification**
+
+Run:
+
+```bash
+npm test
+npm run test:custody:hardhat-v6
+npm pack --dry-run
+git diff --check
+```
+
+Expected: all commands exit 0. Record the limitation that a separate native ethers-v5 Hardhat fixture remains necessary before publishing v5 support if the real plugin integration differs from the unit-tested runtime contract.
+
+## Self-review
+
+- Spec coverage: unified credential, native private key fallback, automatic ethers v5/v6 detection, Hardhat signer replacement, OpenZeppelin proxy deployment, ESM/CJS loading, and local tests are covered.
+- Safety: Project Secrets are never logged or written to fixtures; the mock uses only Hardhat's public development key.
+- Type consistency: the public factory, Hardhat wrapper, and tests all use the same credential and signer option names.

package/docs/superpowers/plans/2026-09-09-remove-template-infrastructure-contracts.md

@@ -0,0 +1,11 @@
+# Remove template infrastructure contracts
+
+Goal: business projects consume deployed Multicall and placeholder addresses without compiling their implementations.
+
+- [x] Add packaged authority ABI; use it in deploy/upgrade without named Multicall artifacts.
+- [x] Accept business implementation name in proxy step.contract, require agreement with firstUpgrade.contract, retain legacy placeholder name as compatibility metadata.
+- [x] Remove two template contracts, compile ERC1967Proxy directly from OpenZeppelin through the package adapter and business compiler configuration.
+- [x] Update examples, initialization detection and tests; do not delete historical project contracts automatically.
+- [x] Bump minimum runtime/template patch versions and validate using a local tarball, tests and no-broadcast compilation.
+
+Compatibility: deployed infrastructure and proxy init code must remain unchanged. No redeployment, salt changes, transaction broadcast, npm publication or Git push. Historical artifact fixtures stay available for unrelated infrastructure deployment tests.

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.