gate-evm-tools 1.0.28 → 1.2.0

package/runtime/delivery/configuration.ts

@@ -0,0 +1,67 @@
+/** Owned configuration/runtime contributor. It grants no planning, signing or execution authority. */
+import path from 'node:path';
+import {projectRoot,parseDeliveryProjectMarker} from './project-files';
+import {readInputBytes,inputDigest} from './input-files';
+import {parseConfigurationDefinition} from './configuration-definition';
+import {observeConfigurationHre} from './configuration-hre';
+import {RuntimeObservation,type RuntimeEvidence} from './configuration-runtime';
+import {openPlanCodecObservation,type PlanCodecObservation} from './codec';
+import {deepFreeze,semanticHash,exactObject} from '../workflow/lib/canonicalData';
+import type {DeepReadonly} from './source';
+import {projectRpcEnvironment} from './project-rpc';
+import {runtimeExecutionInput} from './execution-identity';
+
+export interface DeliveryConfigurationOptions {workspaceRoot:string;projectRoot:string;network:string}
+export interface DeliveryConfigurationEvidence {
+  version:1; files:Array<{path:string;digest:string}>;
+  configuration:Record<string,any>;runtime:RuntimeEvidence;codec:Readonly<PlanCodecObservation>;
+  compiler:{adapter:string;stableDigest:string;exactDigest:string}|null;
+  /** Contributor identity only. C must bind this with all other actual inputs. */
+  configurationRuntimeHash:string;
+}
+export interface DeliveryConfigurationHandle {
+  readonly snapshot:DeepReadonly<DeliveryConfigurationEvidence>;
+  /** Reread without compile, producer evaluation, RPC or preparation. Failure revokes the owner. */
+  assertUnchanged():void;
+  /** Terminal observation includes modules first loaded after open. */
+  seal():DeepReadonly<DeliveryConfigurationEvidence>;
+  close():void;
+}
+/** The initialized project singleton is looked up internally; a caller HRE/JSON is never accepted. */
+export function openDeliveryConfiguration(raw:DeliveryConfigurationOptions):DeliveryConfigurationHandle {
+  let runtime:RuntimeObservation|undefined,codec:ReturnType<typeof openPlanCodecObservation>|undefined;
+  try{
+    exactObject(raw,['workspaceRoot','projectRoot','network'],'configuration options');
+    const root=projectRoot(raw.workspaceRoot,raw.projectRoot);
+    if(path.resolve(process.cwd())!==root)throw new Error();
+    const config=readInputBytes(root,'hardhat.config.ts'),marker=readInputBytes(root,'.gate-template.json');
+    // Marker describes generation provenance; current source is independently observed.
+    parseDeliveryProjectMarker(marker);
+    const parse=(bytes:Buffer)=>parseConfigurationDefinition(bytes,raw.network,projectRpcEnvironment(root,bytes.toString('utf8'),process.env));
+    const parsed=parse(config);
+    runtime=new RuntimeObservation(root);codec=openPlanCodecObservation();
+    const hre=observeConfigurationHre(root,raw.network,parsed,runtime.files);
+    const files=[{path:'hardhat.config.ts',digest:inputDigest(config)},{path:'.gate-template.json',digest:inputDigest(marker)}];
+    const observe=():DeepReadonly<DeliveryConfigurationEvidence>=>{
+      // Reuse the actual owned compiler association when present, without recapturing any compiler jobs.
+      const {ownedDeliveryCompiler}=require('./compiler') as typeof import('./compiler');
+      const compiler=ownedDeliveryCompiler(hre.hre)?.evidence();
+      const body={version:1 as const,files,configuration:hre.configuration,runtime:runtime!.observe(),codec:codec!.snapshot,
+        compiler:compiler?{adapter:compiler.adapter,stableDigest:compiler.stableDigest,exactDigest:compiler.exactDigest}:null};
+      return deepFreeze({...body,configurationRuntimeHash:semanticHash({...body,runtime:runtimeExecutionInput(body.runtime),compiler:compiler?{adapter:compiler.adapter,stableDigest:compiler.stableDigest}:null})});
+    };
+    const snapshot=observe();let status:'open'|'sealed'|'failed'|'closed'='open';
+    const close=()=>{runtime!.close();codec!.close();};
+    const check=()=>{
+      const current=readInputBytes(root,'hardhat.config.ts');
+      if(inputDigest(current)!==files[0].digest||inputDigest(readInputBytes(root,'.gate-template.json'))!==files[1].digest)throw new Error();
+      hre.assertUnchanged(parse(current));codec!.assertUnchanged();runtime!.assertUnchanged();
+    };
+    const assertOpen=()=>{if(status!=='open')throw new Error('Delivery configuration session closed');};
+    return Object.freeze({snapshot,
+      assertUnchanged(){assertOpen();try{check();}catch{status='failed';close();throw new Error('Delivery configuration/runtime drift or mismatch');}},
+      seal(){assertOpen();status='failed';try{check();const result=observe();codec!.seal();status='sealed';return result;}catch{throw new Error('Delivery configuration/runtime drift or mismatch');}finally{close();}},
+      close(){status='closed';close();},
+    });
+  }catch{runtime?.close();codec?.close();throw new Error('Unsupported delivery configuration/runtime observation');}
+}

package/runtime/delivery/contract-source.ts

@@ -0,0 +1,112 @@
+/** Bind actual project Solidity inputs to their last source-changing Git commit. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { readInputBytes, inputDigest } from './input-files';
+import { confinedFile } from './project-files';
+import { portablePath } from './protocol';
+import { deepFreeze, semanticHash } from '../workflow/lib/canonicalData';
+import type { DeliveryAggregate } from './aggregate';
+
+export interface ContractSourceIdentity {
+  version: 1;
+  commit: string;
+  projectPath: string;
+  sourcesDirectory: string;
+  files: Array<{ path: string; digest: string }>;
+  sourceHash: string;
+}
+type TreeEntry = { mode: string; oid: string };
+const portable = (value: string) => value.split(path.sep).join('/');
+function git(root: string, args: string[]): string {
+  // These reads must inspect this worktree, including its own index.
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+  const result = spawnSync('git', ['--no-optional-locks', '-c', 'core.fsmonitor=false', ...args], {
+    cwd: root, env, encoding: 'utf8', timeout: 15000, maxBuffer: 32 * 1024 * 1024,
+  });
+  if (result.error || result.status !== 0) throw Error('Deployment release requires a Git repository with committed contract sources');
+  return result.stdout;
+}
+function sourceFiles(root: string, directory: string): string[] {
+  const files: string[] = [];
+  const visit = (relative: string) => {
+    const absolute = relative === '.' ? root : confinedFile(root, relative, 'directory');
+    if (!fs.existsSync(absolute)) return;
+    for (const entry of fs.readdirSync(absolute, { withFileTypes: true })) {
+      if (['.git', 'node_modules', '.gate-delivery'].includes(entry.name)) continue;
+      const file = relative === '.' ? entry.name : `${relative}/${entry.name}`;
+      if (entry.isSymbolicLink()) throw Error('Contract source directory cannot contain symlinks');
+      if (entry.isDirectory()) visit(file);
+      else if (entry.isFile() && file.endsWith('.sol')) files.push(file);
+    }
+  };
+  visit(directory);
+  return files;
+}
+function tree(root: string, commit: string, scopes: string[], wanted: (file: string) => boolean): Map<string, TreeEntry> {
+  const entries = new Map<string, TreeEntry>();
+  for (const row of git(root, ['ls-tree', '-r', '-z', '--full-tree', commit, '--', ...scopes]).split('\0').filter(Boolean)) {
+    const tab = row.indexOf('\t'), file = row.slice(tab + 1), [mode, kind, oid] = row.slice(0, tab).split(' ');
+    if (!wanted(file)) continue;
+    if (kind !== 'blob' || !['100644', '100755'].includes(mode)) throw Error('Contract sources must be regular committed files');
+    entries.set(file, { mode, oid });
+  }
+  return entries;
+}
+/** Called only with the collector's aggregate; no caller-selected Git reference is accepted. */
+export function captureCommittedContractSource(root: string, aggregate: DeliveryAggregate): Readonly<ContractSourceIdentity> {
+  root = fs.realpathSync(root);
+  const configurations = aggregate.inputs.targets.map(target => target.configuration.configuration.paths?.sources);
+  const directory = configurations[0];
+  if (typeof directory !== 'string' || configurations.some(value => value !== directory)) throw Error('Missing or inconsistent compiled contract source directory');
+  if (directory !== '.') portablePath(directory, 'contract sources directory');
+  const compiled = new Map<string, string>();
+  for (const target of aggregate.inputs.targets) for (const job of target.compiler.jobs) for (const source of job.sources) {
+    if (source.package !== null) continue;
+    portablePath(source.path, 'compiled contract source');
+    if (compiled.has(source.path) && compiled.get(source.path) !== source.digest) throw Error('Conflicting compiled contract sources');
+    compiled.set(source.path, source.digest);
+  }
+  if (!compiled.size) throw Error('Deployment release requires compiled project contract sources');
+  const repo = fs.realpathSync(git(root, ['rev-parse', '--show-toplevel']).trim());
+  const relative = path.relative(repo, root);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) throw Error('Project is outside its contract Git repository');
+  const projectPath = portable(relative) || '.', prefix = relative ? `${portable(relative)}/` : '';
+  const sourceScope = directory === '.' ? prefix.slice(0, -1) || '.' : `${prefix}${directory}`;
+  const paths = new Set([...sourceFiles(root, directory), ...compiled.keys()]);
+  const explicit = new Set([...compiled.keys()].map(file => prefix + file));
+  const wanted = (file: string) => explicit.has(file) || file.endsWith('.sol') && (sourceScope === '.' || file.startsWith(sourceScope + '/'));
+  const scopes = [...new Set([sourceScope, ...explicit])].map(file => `:(literal)${file}`);
+  const committed = tree(repo, 'HEAD', scopes, wanted);
+  const index = new Map<string, TreeEntry>();
+  for (const row of git(repo, ['ls-files', '--stage', '-z', '--', ...scopes]).split('\0').filter(Boolean)) {
+    const tab = row.indexOf('\t'), file = row.slice(tab + 1), [mode, oid, stage] = row.slice(0, tab).split(' ');
+    if (!wanted(file)) continue;
+    if (stage !== '0') throw Error('Contract sources have unresolved Git conflicts');
+    index.set(file, { mode, oid });
+  }
+  const uncommitted = () => { throw Error('Contract sources have uncommitted, staged, untracked or deleted files; commit contract changes before freezing a deployment release'); };
+  if (committed.size !== paths.size || index.size !== committed.size) uncommitted();
+  const format = git(repo, ['rev-parse', '--show-object-format']).trim();
+  if (!['sha1', 'sha256'].includes(format)) throw Error('Unsupported contract Git object format');
+  const files = [...paths].sort().map(file => {
+    const entry = committed.get(prefix + file), staged = index.get(prefix + file);
+    if (!entry || !staged || entry.mode !== staged.mode || entry.oid !== staged.oid) uncommitted();
+    let bytes: Buffer;
+    try { bytes = readInputBytes(root, file); } catch { return uncommitted(); }
+    const oid = createHash(format).update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+    if (oid !== entry!.oid) uncommitted();
+    const digest = inputDigest(bytes);
+    if (compiled.has(file) && compiled.get(file) !== digest) throw Error('Contract source changed after deployment qualification');
+    return { path: file, digest };
+  });
+  // Ignore script/documentation commits, while retaining source additions and deletions.
+  const glob = sourceScope === '.' ? '**/*.sol' : `${sourceScope}/**/*.sol`;
+  const commit = git(repo, ['log', '-1', '--format=%H', '--first-parent', '--full-history', 'HEAD', '--', `:(glob)${glob}`, ...[...explicit].map(file => `:(literal)${file}`)]).trim();
+  if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(commit)) throw Error('No committed contract source version found');
+  const version = tree(repo, commit, scopes, wanted);
+  if (version.size !== committed.size || [...committed].some(([file, entry]) => version.get(file)?.oid !== entry.oid)) throw Error('Contract commit does not reproduce current contract sources');
+  return deepFreeze({ version: 1 as const, commit, projectPath, sourcesDirectory: directory, files,
+    sourceHash: semanticHash({ sourcesDirectory: directory, files }) });
+}

package/runtime/delivery/create2.ts

@@ -0,0 +1,57 @@
+import { ParamType } from "ethers";
+import type { Create2FieldKind } from "../workflow/lib/validation";
+import { copyOwnData } from "./data";
+import { DEFERRED } from "./references";
+import { validateAbiValue, validateTransactionValue } from "./abi";
+
+/** Check supplied fields before shared extraction can discard or fall back from them. */
+export function validateCreate2Fields(
+  raw: unknown,
+  kind: Create2FieldKind,
+  allowDeferred = false,
+): Record<string, unknown> {
+  const value = copyOwnData(
+    raw, `CREATE2 ${kind}`, allowDeferred ? DEFERRED : undefined,
+  );
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`CREATE2 ${kind} requires an object`);
+  const fields = value as Record<string, unknown>;
+  const addresses = kind === "step"
+    ? ["factory", "expectedAddress"]
+    : kind === "target"
+      ? ["factory", "caller"]
+      : kind === "uups" ? ["placeholderImplementation"] : ["controlledMulticall"];
+  for (const key of addresses) {
+    if (!Object.hasOwn(fields, key)) continue;
+    validateAbiValue(
+      ParamType.from("address"), fields[key], `CREATE2 ${kind}.${key}`, allowDeferred,
+    );
+    if (typeof fields[key] === "string" && /^0x0{40}$/i.test(fields[key]))
+      throw new Error(`CREATE2 ${kind}.${key} requires a nonzero address`);
+  }
+  if (
+    kind === "target" && Object.hasOwn(fields, "scheme") &&
+    !(allowDeferred && fields.scheme === DEFERRED) && fields.scheme !== "evm"
+  )
+    throw new Error("Delivery CREATE2 scheme must be evm");
+  if (kind === "step" && Object.hasOwn(fields, "salt"))
+    validateAbiValue(ParamType.from("bytes32"), fields.salt, "CREATE2 salt", allowDeferred);
+  if (
+    (kind === "step" || kind === "target") && Object.hasOwn(fields, "leadingZeroBytes")
+  ) {
+    const zeroes = fields.leadingZeroBytes;
+    if (
+      !(allowDeferred && zeroes === DEFERRED) &&
+      (typeof zeroes !== "number" || !Number.isSafeInteger(zeroes) || zeroes < 0 || zeroes > 20)
+    )
+      throw new Error("CREATE2 leadingZeroBytes must be an integer from 0 to 20");
+  }
+  if (kind === "step") {
+    for (const key of ["create2ForwardValue", "callForwardValue"]) {
+      if (!Object.hasOwn(fields, key)) continue;
+      validateTransactionValue(fields[key], allowDeferred);
+      if (typeof fields[key] === "number") fields[key] = String(fields[key]);
+    }
+  }
+  return fields;
+}