gate-evm-tools 1.0.28 → 1.2.0

package/runtime/workflow/lib/transactionPlanner.ts

@@ -0,0 +1,314 @@
+import crypto from "crypto";
+
+export type ExecutionRoute = "operator" | "external";
+
+export interface ReleaseExecutionTransaction {
+  transactionId: string;
+  stepId: string;
+  transactionIndex: number;
+  route: ExecutionRoute;
+  executor: string;
+  to: string;
+  value: string;
+  data: string;
+  operation: 0 | 1;
+  scheme?: "zksync-eravm";
+  factoryDeps?: string[];
+}
+
+export interface ReleaseExecutionTransactionInput {
+  stepId: string;
+  executor: string;
+  to: string;
+  value: string;
+  data: string;
+  operation: 0 | 1;
+  scheme?: "zksync-eravm";
+  factoryDeps?: string[];
+}
+
+export interface CompletedExecutionTransaction {
+  transactionId: string;
+  transactionHash: string;
+}
+
+export interface PlannedExecutionTransaction extends ReleaseExecutionTransaction {
+  executionAction: "execute" | "package" | "replay";
+  transactionHash?: string;
+}
+
+export class ExecutionSegmentDeferred extends Error {
+  constructor(readonly transactionId: string) {
+    super(`Execution is waiting for the preceding external segment before ${transactionId}`);
+    this.name = "ExecutionSegmentDeferred";
+  }
+}
+
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/;
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+const DATA = /^0x(?:[0-9a-fA-F]{2})*$/;
+const HASH = /^[0-9a-f]{64}$/;
+
+const safeId = (value: unknown, label: string): string => {
+  if (typeof value !== "string" || !SAFE_ID.test(value)) {
+    throw new Error(`${label} must match ${SAFE_ID}`);
+  }
+  return value;
+};
+
+const address = (value: unknown, label: string): string => {
+  if (typeof value !== "string" || !ADDRESS.test(value)) {
+    throw new Error(`${label} must be an EVM address`);
+  }
+  if (value.toLowerCase() === "0x0000000000000000000000000000000000000000") {
+    throw new Error(`${label} must be non-zero`);
+  }
+  return value.toLowerCase();
+};
+
+const value = (raw: unknown, label: string): string => {
+  if (typeof raw !== "string" || !/^(?:0[xX][0-9a-fA-F]+|[0-9]+)$/.test(raw)) {
+    throw new Error(`${label} must be a nonnegative integer string`);
+  }
+  return BigInt(raw).toString(10);
+};
+
+const data = (raw: unknown, label: string): string => {
+  if (typeof raw !== "string" || !DATA.test(raw)) {
+    throw new Error(`${label} must be canonical byte calldata`);
+  }
+  return raw.toLowerCase();
+};
+
+const factoryDeps = (raw: unknown, label: string): string[] => {
+  if (!Array.isArray(raw)) throw new Error(`${label} must be an array`);
+  const seen = new Set<string>();
+  const normalized: string[] = [];
+  for (const [index, dependency] of raw.entries()) {
+    if (typeof dependency !== "string" || !/^0x(?:[0-9a-fA-F]{2})+$/.test(dependency)) {
+      throw new Error(`${label}[${index}] must be non-empty byte-aligned bytecode`);
+    }
+    const value = dependency.toLowerCase();
+    const hash = crypto
+      .createHash("sha256")
+      .update(Buffer.from(value.slice(2), "hex"))
+      .digest("hex");
+    if (seen.has(hash)) continue;
+    seen.add(hash);
+    normalized.push(value);
+  }
+  return normalized;
+};
+
+const exactKeys = (value: Record<string, unknown>, expected: string[], label: string): void => {
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+    throw new Error(`${label} contains unsupported or missing fields`);
+  }
+};
+
+const record = (raw: unknown, label: string): Record<string, unknown> => {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return raw as Record<string, unknown>;
+};
+
+export const normalizeTransaction = (
+  raw: unknown,
+  index: number,
+  strict: boolean,
+): ReleaseExecutionTransaction => {
+  const input = record(raw, `transactions[${index}]`);
+  const isZkSync = input.scheme === "zksync-eravm";
+  if (input.scheme !== undefined && !isZkSync) {
+    throw new Error(`transactions[${index}].scheme must be zksync-eravm when present`);
+  }
+  if (isZkSync && input.factoryDeps === undefined) {
+    throw new Error(`transactions[${index}].factoryDeps is required for zkSync`);
+  }
+  if (!isZkSync && input.factoryDeps !== undefined) {
+    throw new Error(`transactions[${index}].factoryDeps is only supported for zkSync`);
+  }
+  if (strict) {
+    exactKeys(input, [
+      "transactionId",
+      "stepId",
+      "transactionIndex",
+      "route",
+      "executor",
+      "to",
+      "value",
+      "data",
+      "operation",
+      ...(isZkSync ? ["scheme", "factoryDeps"] : []),
+    ], `transactions[${index}]`);
+  }
+  if (input.transactionIndex !== index) {
+    throw new Error(`transactions[${index}].transactionIndex must equal ${index}`);
+  }
+  if (input.route !== "operator" && input.route !== "external") {
+    throw new Error(`transactions[${index}].route is invalid`);
+  }
+  if (input.operation !== 0 && input.operation !== 1) {
+    throw new Error(`transactions[${index}].operation must be 0 or 1`);
+  }
+  return {
+    transactionId: safeId(input.transactionId, `transactions[${index}].transactionId`),
+    stepId: safeId(input.stepId, `transactions[${index}].stepId`),
+    transactionIndex: index,
+    route: input.route,
+    executor: address(input.executor, `transactions[${index}].executor`),
+    to: address(input.to, `transactions[${index}].to`),
+    value: value(input.value, `transactions[${index}].value`),
+    data: data(input.data, `transactions[${index}].data`),
+    operation: input.operation,
+    ...(isZkSync ? {
+      scheme: "zksync-eravm" as const,
+      factoryDeps: factoryDeps(input.factoryDeps, `transactions[${index}].factoryDeps`),
+    } : {}),
+  };
+};
+
+export const normalizeTransactions = (
+  raw: unknown, operator: string,
+): ReleaseExecutionTransaction[] => {
+  if (!Array.isArray(raw)) throw new Error("transactions must be an array");
+  const transactions = raw.map((tx, index) => normalizeTransaction(tx, index, true));
+  const ids = new Set<string>();
+  for (const tx of transactions) {
+    if (ids.has(tx.transactionId)) throw new Error("duplicate transactionId");
+    ids.add(tx.transactionId);
+    if (tx.transactionId !== `tx-${String(tx.transactionIndex + 1).padStart(4, "0")}-${tx.stepId}`) throw new Error("transactionId must match its ordered index and step");
+    if ((tx.executor === operator.toLowerCase()) !== (tx.route === "operator")) throw new Error("transaction route does not match operator");
+  }
+  return transactions;
+};
+
+export interface TransactionPlannerPort {
+  add(input: ReleaseExecutionTransactionInput): PlannedExecutionTransaction;
+}
+
+export class TransactionPlanner {
+  private readonly operator: string;
+  private readonly allowExternal: boolean;
+  private readonly expected?: { transactions: ReleaseExecutionTransaction[] };
+  private readonly transactions: ReleaseExecutionTransaction[] = [];
+  private readonly segmentedExecution: boolean;
+  private readonly completedTransactions: CompletedExecutionTransaction[];
+  private readonly segmentEnd: number;
+
+  constructor(input: {
+    operator: string;
+    allowExternal?: boolean;
+    expectedTransactions?: readonly ReleaseExecutionTransaction[];
+    segmentedExecution?: boolean;
+    replayCompletedPrefix?: boolean;
+    completedTransactions?: CompletedExecutionTransaction[];
+  }) {
+    this.operator = address(input.operator, "planner operator");
+    this.allowExternal = input.allowExternal !== false;
+    if (input.expectedTransactions) {
+      this.expected = { transactions: normalizeTransactions(input.expectedTransactions, this.operator) };
+    }
+    this.segmentedExecution = input.segmentedExecution === true;
+    this.completedTransactions = input.completedTransactions ?? [];
+    if (this.segmentedExecution && !this.expected) {
+      throw new Error("segmented execution requires a locked execution plan");
+    }
+    if (input.replayCompletedPrefix && this.completedTransactions.length > 0 && !this.expected) throw new Error("completed replay requires expected transactions");
+    if (!this.segmentedExecution && !input.replayCompletedPrefix && this.completedTransactions.length > 0) {
+      throw new Error("completed transactions require segmented execution");
+    }
+    if (this.expected) {
+      if (this.completedTransactions.length > this.expected.transactions.length) {
+        throw new Error("completed transactions exceed the execution plan");
+      }
+      for (const [index, completed] of this.completedTransactions.entries()) {
+        if (
+          completed.transactionId !== this.expected.transactions[index]?.transactionId
+          || typeof completed.transactionHash !== "string"
+          || !/^0x[0-9a-fA-F]{64}$/.test(completed.transactionHash)
+        ) {
+          throw new Error("completed transactions must form a contiguous plan prefix");
+        }
+      }
+    }
+    const expectedTransactions = this.expected?.transactions ?? [];
+    let segmentEnd = this.completedTransactions.length;
+    if (this.segmentedExecution && segmentEnd < expectedTransactions.length) {
+      if (expectedTransactions[segmentEnd].route === "operator") {
+        while (
+          segmentEnd < expectedTransactions.length
+          && expectedTransactions[segmentEnd].route === "operator"
+        ) segmentEnd += 1;
+      }
+      while (
+        segmentEnd < expectedTransactions.length
+        && expectedTransactions[segmentEnd].route === "external"
+      ) segmentEnd += 1;
+    } else if (!this.segmentedExecution) {
+      segmentEnd = Number.MAX_SAFE_INTEGER;
+    }
+    this.segmentEnd = segmentEnd;
+  }
+
+  add(input: ReleaseExecutionTransactionInput): PlannedExecutionTransaction {
+    const index = this.transactions.length;
+    const stepId = safeId(input.stepId, "planned transaction stepId");
+    const executor = address(input.executor, "planned transaction executor");
+    const transaction = normalizeTransaction({
+      transactionId: `tx-${String(index + 1).padStart(4, "0")}-${stepId}`,
+      stepId,
+      transactionIndex: index,
+      route: executor === this.operator ? "operator" : "external",
+      executor,
+      to: input.to,
+      value: input.value,
+      data: input.data,
+      operation: input.operation,
+      ...(input.scheme === undefined ? {} : { scheme: input.scheme }),
+      ...(input.factoryDeps === undefined ? {} : { factoryDeps: input.factoryDeps }),
+    }, index, false);
+    if (!this.allowExternal && transaction.route === "external") {
+      throw new Error("development execution plans cannot contain external transactions");
+    }
+    const expected = this.expected?.transactions[index];
+    if (this.expected && (!expected || JSON.stringify(expected) !== JSON.stringify(transaction))) {
+      throw new Error(
+        `transaction ${transaction.transactionId} does not match locked execution plan`,
+      );
+    }
+    if (this.segmentedExecution && index >= this.segmentEnd) {
+      throw new ExecutionSegmentDeferred(transaction.transactionId);
+    }
+    this.transactions.push(transaction);
+    const completed = this.completedTransactions[index];
+    if (completed) {
+      return {
+        ...transaction,
+        executionAction: "replay",
+        transactionHash: completed.transactionHash.toLowerCase(),
+      };
+    }
+    return {
+      ...transaction,
+      executionAction: transaction.route === "external" ? "package" : "execute",
+    };
+  }
+
+  complete(options: { allowPartial?: boolean } = {}): ReleaseExecutionTransaction[] {
+    if (
+      this.expected
+      && this.transactions.length !== this.expected.transactions.length
+      && options.allowPartial !== true
+    ) {
+      throw new Error("execution did not consume every locked transaction");
+    }
+    if (options.allowPartial === true && !this.segmentedExecution) {
+      throw new Error("partial execution plan completion requires segmented execution");
+    }
+    return normalizeTransactions(this.transactions, this.operator);
+  }
+}

package/runtime/workflow/lib/typedValue.ts

@@ -0,0 +1,46 @@
+import type { TypedValue } from './evidencePorts';
+import { canonicalData, deepFreeze, exactObject } from './canonicalData';
+export function typedValue(value: unknown): TypedValue {
+  if (value === null) return { type: 'null', value: null };
+  if (typeof value === 'bigint') return { type: 'bigint', value: value.toString() };
+  if (typeof value === 'string' || typeof value === 'boolean') return { type: typeof value, value } as TypedValue;
+  if (typeof value === 'number' && Number.isSafeInteger(value)) return { type: 'number', value: value.toString() };
+  if (Array.isArray(value)) {
+    if (Object.keys(value).length !== value.length || Object.getOwnPropertySymbols(value).length) throw new Error('typed arrays require own indexed data');
+    return { type: 'array', value: Array.from({ length: value.length }, (_, index) => {
+      const d = Object.getOwnPropertyDescriptor(value, String(index));
+      if (!d || !d.enumerable || !('value' in d)) throw new Error('typed arrays require own indexed data');
+      return typedValue(d.value);
+    }) };
+  }
+  if (value && typeof value === 'object' && [Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    const result: Record<string, TypedValue> = Object.create(null);
+    if (Object.getOwnPropertySymbols(value).length) throw new Error("typed objects require own string data");
+    for (const key of Object.getOwnPropertyNames(value)) {
+      const d = Object.getOwnPropertyDescriptor(value, key)!;
+      if (!d.enumerable || !('value' in d)) throw new Error('typed values require own data');
+      result[key] = typedValue(d.value);
+    }
+    return { type: 'object', value: result };
+  }
+  throw new Error('Unsupported typed verification value');
+}
+export function parseTypedValue(raw: unknown): TypedValue {
+  const v = exactObject(raw, ['type', 'value'], 'typed value');
+  switch (v.type) {
+    case 'null': if (v.value !== null) throw new Error('Invalid typed null'); break;
+    case 'string': if (typeof v.value !== 'string') throw new Error('Invalid typed string'); break;
+    case 'boolean': if (typeof v.value !== 'boolean') throw new Error('Invalid typed boolean'); break;
+    case 'number': case 'bigint':
+      if (typeof v.value !== 'string' || !/^(0|-?[1-9][0-9]*)$/.test(v.value)) throw new Error('Invalid typed integer');
+      if (v.type === 'number' && (BigInt(v.value) > BigInt(Number.MAX_SAFE_INTEGER) || BigInt(v.value) < BigInt(Number.MIN_SAFE_INTEGER))) throw new Error('Unsafe typed number');
+      break;
+    case 'array': if (!Array.isArray(v.value)) throw new Error('Invalid typed array'); v.value.forEach(parseTypedValue); break;
+    case 'object': {
+      if (!v.value || typeof v.value !== 'object' || Array.isArray(v.value)) throw new Error('Invalid typed object');
+      Object.values(v.value).forEach(parseTypedValue); break;
+    }
+    default: throw new Error('Unknown typed value');
+  }
+  return deepFreeze(canonicalData(v) as TypedValue);
+}

package/runtime/workflow/lib/validation.ts

@@ -0,0 +1,50 @@
+import type { InterfaceAbi } from "ethers";
+import type { WorkflowContext } from "./context";
+import { resolveValue } from "./parameters";
+import type {
+  GateToolPreparationValidation,
+  GateToolPreparationRequestV1,
+  GateToolPreparationPlanV1,
+} from "gate-evm-tools/workflow";
+export type Create2FieldKind = "step" | "target" | "uups" | "multicall";
+/** Neutral optional port: legacy launchers do not import delivery policy. */
+export interface WorkflowValidationPort {
+  /** Owned compiler contribution plus actual local deployment and pinned source absence. */
+  sameForkUpgrade?(proxy: string): Promise<void>;
+  resolve(value: unknown): unknown;
+  create2Fields(value: unknown, kind: Create2FieldKind): Record<string, unknown>;
+  address(value: unknown): void;
+  call(
+    abiName: string,
+    method: string,
+    args: unknown,
+    value?: unknown,
+  ): Promise<void>;
+  callInterface(abi: InterfaceAbi, method: string, args: unknown): void;
+  check(abi: InterfaceAbi, method: string, expected: unknown): void;
+  compare(
+    abi: InterfaceAbi,
+    method: string,
+    actual: unknown,
+    expected: unknown,
+  ): { actual: string; expected: string };
+  stringify(value: unknown): string;
+  preparation: GateToolPreparationValidation;
+  preparationPlan(
+    request: GateToolPreparationRequestV1,
+    plan: GateToolPreparationPlanV1,
+  ): Promise<void>;
+}
+export function resolveWorkflowValue(
+  context: WorkflowContext,
+  value: unknown,
+): unknown {
+  return context.validation
+    ? context.validation.resolve(value)
+    : resolveValue(value, {
+        targetId: context.targetId,
+        target: context.target,
+        params: context.targetParams,
+        state: context.state,
+      });
+}

package/runtime/workflow/planAdd.ts

@@ -0,0 +1,8 @@
+import { runPlanAddCli } from "./lib/planCli";
+
+try {
+  console.log(JSON.stringify(runPlanAddCli(process.argv.slice(2))));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/runtime/workflow/planRead.ts

@@ -0,0 +1,8 @@
+import { runPlanReadCli } from "./lib/planCli";
+
+try {
+  console.log(JSON.stringify(runPlanReadCli(process.argv.slice(2))));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/runtime/workflow/planStatus.ts

@@ -0,0 +1,8 @@
+import { runPlanStatusCli } from "./lib/planCli";
+
+try {
+  console.log(JSON.stringify(runPlanStatusCli(process.argv.slice(2))));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/runtime/workflow/planWrite.ts

@@ -0,0 +1,8 @@
+import { runPlanWriteCli } from "./lib/planCli";
+
+try {
+  console.log(JSON.stringify(runPlanWriteCli(process.argv.slice(2))));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}