gate-evm-tools 1.0.26 → 1.0.27

package/runtime/workflow/lib/create2.ts

@@ -0,0 +1,278 @@
+import type { Signer } from "ethers";
+import { getAddress, Interface, isAddress } from "ethers";
+import { resolveValue, WorkflowStep } from "./parameters";
+import type { WorkflowContext } from "../run";
+
+const CONTROLLED_MULTICALL_INTERFACE = new Interface([
+  "function aggregate3(tuple(address target,bool allowFailure,bytes callData)[] calls) payable returns (tuple(bool success, bytes returnData)[] returnData)",
+  "function aggregate3Value(tuple(address target,bool allowFailure,uint256 value,bytes callData)[] calls) payable returns (tuple(bool success, bytes returnData)[] returnData)",
+]);
+
+export type Create2Scheme = "evm" | "zksync-eravm";
+
+export interface Create2Options {
+  scheme: Create2Scheme;
+  factory: string;
+  salt: string;
+  controlledMulticall?: string;
+  create2ForwardValue?: string;
+  callForwardValue?: string;
+  expectedAddress?: string;
+  leadingZeroBytes?: number;
+  uupsPlaceholderImplementation?: string;
+}
+
+export interface PreparedWorkflowTransaction {
+  target: string;
+  value: string;
+  data: string;
+  operation: 0;
+  scheme?: "zksync-eravm";
+  factoryDeps?: string[];
+}
+
+export interface ControlledMulticallInnerCall {
+  target: string;
+  value: string;
+  data: string;
+  factoryDeps?: string[];
+}
+
+export interface PreparedControlledMulticallTransaction
+  extends PreparedWorkflowTransaction {
+  method: "aggregate3" | "aggregate3Value";
+  calls: Array<{
+    target: string;
+    allowFailure: false;
+    value: string;
+    callData: string;
+  }>;
+}
+
+interface SentTransaction {
+  hash: string;
+  wait: () => Promise<unknown>;
+}
+
+const bigintValue = (value: string | undefined): bigint => {
+  if (!value || value === "0") return 0n;
+  const parsed = BigInt(value);
+  if (parsed < 0n) throw new Error("transaction value must be nonnegative");
+  return parsed;
+};
+
+const normalizeFactoryDeps = (
+  input: string[],
+  label: string,
+): string[] => {
+  const seen = new Set<string>();
+  const output: string[] = [];
+  for (const [index, dependency] of input.entries()) {
+    if (!/^0x(?:[0-9a-fA-F]{2})+$/.test(dependency)) {
+      throw new Error(`${label}[${index}] must be non-empty byte-aligned bytecode`);
+    }
+    const normalized = dependency.toLowerCase();
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    output.push(normalized);
+  }
+  return output;
+};
+
+export const prepareControlledMulticallTransaction = (
+  controlledMulticall: string,
+  inputCalls: ControlledMulticallInnerCall[],
+  scheme: Create2Scheme = "evm",
+): PreparedControlledMulticallTransaction => {
+  if (!isAddress(controlledMulticall)) {
+    throw new Error("controlledMulticall must be an EVM address");
+  }
+  if (inputCalls.length === 0) {
+    throw new Error("controlled multicall requires at least one inner call");
+  }
+  if (scheme === "evm" && inputCalls.some((call) => call.factoryDeps !== undefined)) {
+    throw new Error("factoryDeps are only supported for zkSync transactions");
+  }
+  if (scheme === "zksync-eravm" && inputCalls.some((call) => call.factoryDeps === undefined)) {
+    throw new Error("every zkSync GateTool call must include factoryDeps");
+  }
+  const calls = inputCalls.map((call) => ({
+    target: getAddress(call.target),
+    allowFailure: false as const,
+    value: bigintValue(call.value).toString(10),
+    callData: call.data,
+  }));
+  const totalValue = calls.reduce((sum, call) => sum + BigInt(call.value), 0n);
+  const method = totalValue === 0n ? "aggregate3" as const : "aggregate3Value" as const;
+  const encodedCalls = method === "aggregate3"
+    ? calls.map(({ value: _value, ...call }) => call)
+    : calls;
+  const factoryDeps = scheme === "zksync-eravm"
+    ? normalizeFactoryDeps(inputCalls.flatMap((call) => call.factoryDeps!), "factoryDeps")
+    : undefined;
+  return {
+    target: getAddress(controlledMulticall),
+    value: totalValue.toString(10),
+    data: CONTROLLED_MULTICALL_INTERFACE.encodeFunctionData(method, [encodedCalls]),
+    operation: 0,
+    method,
+    calls,
+    ...(scheme === "zksync-eravm"
+      ? { scheme: "zksync-eravm" as const, factoryDeps: factoryDeps! }
+      : {}),
+  };
+};
+
+export const sendPreparedWorkflowTransaction = async (
+  prepared: PreparedWorkflowTransaction,
+  signer: Signer,
+): Promise<SentTransaction> => {
+  if (prepared.scheme === "zksync-eravm" && prepared.factoryDeps === undefined) {
+    throw new Error("zkSync transaction requires an explicit factoryDeps list");
+  }
+  if (prepared.scheme === undefined && prepared.factoryDeps !== undefined) {
+    throw new Error("EVM transaction cannot include factoryDeps");
+  }
+  const transaction = await signer.sendTransaction({
+    to: prepared.target,
+    value: prepared.value,
+    data: prepared.data,
+    ...(prepared.scheme === "zksync-eravm"
+      ? { customData: { factoryDeps: prepared.factoryDeps } }
+      : {}),
+  } as Parameters<Signer["sendTransaction"]>[0]);
+  const receipt = await transaction.wait();
+  const receiptHash = receipt && typeof receipt === "object"
+    ? "hash" in receipt && typeof receipt.hash === "string"
+      ? receipt.hash
+      : "transactionHash" in receipt && typeof receipt.transactionHash === "string"
+        ? receipt.transactionHash
+        : undefined
+    : undefined;
+  if (receiptHash && receiptHash.toLowerCase() !== transaction.hash.toLowerCase()) {
+    throw new Error("transaction receipt hash does not match the submitted locked envelope");
+  }
+  return transaction;
+};
+
+export const sendPreparedControlledMulticallTransaction = async (
+  prepared: PreparedControlledMulticallTransaction,
+  signer: Signer,
+): Promise<SentTransaction> => sendPreparedWorkflowTransaction(prepared, signer);
+
+const resolveObject = (
+  context: WorkflowContext,
+  value: unknown,
+): Record<string, unknown> => {
+  const resolved = resolveValue(value || {}, {
+    targetId: context.targetId,
+    target: context.target,
+    params: context.targetParams,
+    state: context.state,
+  });
+  if (!resolved || typeof resolved !== "object" || Array.isArray(resolved)) return {};
+  return resolved as Record<string, unknown>;
+};
+
+const stringField = (
+  value: Record<string, unknown>,
+  key: string,
+): string | undefined => {
+  const field = value[key];
+  return typeof field === "string" && field.trim() ? field.trim() : undefined;
+};
+
+const numberField = (
+  value: Record<string, unknown>,
+  key: string,
+): number | undefined => {
+  const field = value[key];
+  return typeof field === "number" ? field : undefined;
+};
+
+const assertLeadingZeroBytes = (
+  stepId: string,
+  leadingZeroBytes: number | undefined,
+): void => {
+  if (leadingZeroBytes === undefined) return;
+  if (!Number.isInteger(leadingZeroBytes) || leadingZeroBytes < 0 || leadingZeroBytes > 20) {
+    throw new Error(`Step ${stepId} create2.leadingZeroBytes must be an integer from 0 to 20`);
+  }
+};
+
+export const resolveCreate2Options = (
+  context: WorkflowContext,
+  step: WorkflowStep,
+): Create2Options | undefined => {
+  const strategy = typeof step.strategy === "string" ? step.strategy : undefined;
+  const stepCreate2 = resolveObject(context, step.create2);
+  const targetCreate2 = resolveObject(context, context.target.create2);
+  const targetUups = resolveObject(context, context.target.uups);
+  const targetMulticall = resolveObject(context, context.target.multicall);
+  if (strategy !== "create2" && Object.keys(stepCreate2).length === 0) return undefined;
+
+  const rawScheme = stringField(targetCreate2, "scheme") || "evm";
+  if (rawScheme !== "evm" && rawScheme !== "zksync-eravm") {
+    throw new Error(`Step ${step.id} create2.scheme must be evm or zksync-eravm`);
+  }
+  const factory = stringField(stepCreate2, "factory") || stringField(targetCreate2, "factory");
+  const salt = stringField(stepCreate2, "salt");
+  const leadingZeroBytes = numberField(stepCreate2, "leadingZeroBytes")
+    ?? numberField(targetCreate2, "leadingZeroBytes");
+  const uupsPlaceholderImplementation = stringField(targetUups, "placeholderImplementation");
+  const controlledMulticall = stringField(targetMulticall, "controlledMulticall");
+  if (!factory) throw new Error(`Step ${step.id} uses create2 but no factory address was provided`);
+  if (!salt) throw new Error(`Step ${step.id} uses create2 but no salt was provided`);
+  assertLeadingZeroBytes(step.id, leadingZeroBytes);
+  if (step.upgradeableStrategy === "uups-placeholder-proxy" && !uupsPlaceholderImplementation) {
+    throw new Error(`Step ${step.id} requires target.uups.placeholderImplementation`);
+  }
+  return {
+    scheme: rawScheme,
+    factory,
+    salt,
+    controlledMulticall,
+    create2ForwardValue: stringField(stepCreate2, "create2ForwardValue"),
+    callForwardValue: stringField(stepCreate2, "callForwardValue"),
+    expectedAddress: stringField(stepCreate2, "expectedAddress"),
+    leadingZeroBytes,
+    uupsPlaceholderImplementation,
+  };
+};
+
+export const hasLeadingZeroBytes = (
+  address: string,
+  leadingZeroBytes: number,
+): boolean => {
+  if (!isAddress(address)) throw new Error(`Invalid CREATE2 address: ${address}`);
+  return address.slice(2, 2 + leadingZeroBytes * 2).toLowerCase() === "00".repeat(leadingZeroBytes);
+};
+
+export const assertCreate2AddressPolicy = (
+  label: string,
+  predictedAddress: string,
+  options: Pick<Create2Options, "expectedAddress" | "leadingZeroBytes">,
+): void => {
+  if (!isAddress(predictedAddress)) {
+    throw new Error(`${label} predicted invalid CREATE2 address: ${predictedAddress}`);
+  }
+  if (options.expectedAddress) {
+    if (!isAddress(options.expectedAddress)) {
+      throw new Error(`${label} expectedAddress is invalid: ${options.expectedAddress}`);
+    }
+    if (getAddress(predictedAddress) !== getAddress(options.expectedAddress)) {
+      throw new Error(
+        `${label} predicted ${predictedAddress} but parameters expected ${options.expectedAddress}`,
+      );
+    }
+  }
+  if (
+    options.leadingZeroBytes !== undefined
+    && !hasLeadingZeroBytes(predictedAddress, options.leadingZeroBytes)
+  ) {
+    throw new Error(
+      `${label} predicted ${predictedAddress} but create2.leadingZeroBytes requires prefix `
+      + `0x${"00".repeat(options.leadingZeroBytes)}`,
+    );
+  }
+};

package/runtime/workflow/lib/create2Hashes.ts

@@ -0,0 +1,83 @@
+import { createHash } from "node:crypto";
+import {
+  Interface,
+  concat,
+  getBytes,
+  hexlify,
+  keccak256,
+  type InterfaceAbi,
+} from "ethers";
+
+export type Create2AddressScheme = "evm" | "zksync-eravm";
+
+export interface Create2HashArtifact {
+  _format?: string;
+  abi: InterfaceAbi;
+  bytecode: string;
+}
+
+export type CanonicalCreate2Hashes =
+  | {
+      scheme: "evm";
+      initCodeHash: string;
+    }
+  | {
+      scheme: "zksync-eravm";
+      bytecodeHash: string;
+      constructorInputHash: string;
+    };
+
+export const normalizeCreate2Scheme = (value: unknown): Create2AddressScheme => {
+  if (value === undefined || value === null || value === "" || value === "evm") {
+    return "evm";
+  }
+  if (value === "zksync-eravm") return value;
+  throw new Error("CREATE2 scheme must be evm or zksync-eravm");
+};
+
+export const hashZkSyncBytecode = (bytecode: string): string => {
+  const bytes = getBytes(bytecode);
+  if (bytes.length === 0 || bytes.length % 32 !== 0) {
+    throw new Error("zkSync EraVM bytecode length must be a non-zero multiple of 32 bytes");
+  }
+  const lengthInWords = bytes.length / 32;
+  if (lengthInWords % 2 === 0) {
+    throw new Error("zkSync EraVM bytecode must contain an odd number of 32-byte words");
+  }
+  if (lengthInWords > 0xffff) {
+    throw new Error("zkSync EraVM bytecode must contain fewer than 65536 words");
+  }
+
+  const digest = Uint8Array.from(createHash("sha256").update(bytes).digest());
+  digest[0] = 1;
+  digest[1] = 0;
+  digest[2] = lengthInWords >> 8;
+  digest[3] = lengthInWords & 0xff;
+  return hexlify(digest).toLowerCase();
+};
+
+export const canonicalCreate2Hashes = (input: {
+  scheme?: Create2AddressScheme;
+  artifact: Create2HashArtifact;
+  args: unknown[];
+}): CanonicalCreate2Hashes => {
+  const scheme = normalizeCreate2Scheme(input.scheme);
+  if (scheme === "zksync-eravm" && input.artifact._format !== "hh-zksolc-artifact-1") {
+    throw new Error("zkSync CREATE2 requires a zksolc artifact (hh-zksolc-artifact-1)");
+  }
+  if (scheme === "evm" && input.artifact._format !== "hh-sol-artifact-1") {
+    throw new Error("EVM CREATE2 requires a solc artifact (hh-sol-artifact-1)");
+  }
+  const constructorInput = new Interface(input.artifact.abi).encodeDeploy(input.args);
+  if (scheme === "zksync-eravm") {
+    return {
+      scheme,
+      bytecodeHash: hashZkSyncBytecode(input.artifact.bytecode),
+      constructorInputHash: keccak256(constructorInput).toLowerCase(),
+    };
+  }
+  return {
+    scheme,
+    initCodeHash: keccak256(concat([input.artifact.bytecode, constructorInput])).toLowerCase(),
+  };
+};

package/runtime/workflow/lib/deploymentInfo.ts

@@ -0,0 +1,286 @@
+import fs from "fs";
+import path from "path";
+import { getAddress, isAddress } from "ethers";
+import { readJsonFile, writeJsonFile } from "./config";
+import type { ContractInfo } from "./deployments";
+import { resolveDeployment, validateContractInfo } from "./deployments";
+
+export interface DeploymentInfoEntry {
+  contractInfoKey: string;
+  address: string;
+  actualContract: string;
+  proxyKind?: "uups" | "transparent";
+  implementationAddress?: string;
+  source: DeploymentInfoSource;
+  updatedAt: string;
+}
+
+export type DeploymentInfoSource = {
+  kind: "deployment";
+  deploymentId: string;
+  executionId: string;
+  recordPath: string;
+} | {
+  kind: "migration";
+  migrationId: string;
+  evidencePath: string;
+};
+
+export interface DeploymentInfo {
+  version: 1;
+  networks: Record<string, Record<string, DeploymentInfoEntry>>;
+}
+
+export interface DeploymentRecordPromotionInput {
+  recordPath: string;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => (
+  Boolean(value) && typeof value === "object" && !Array.isArray(value)
+);
+
+const safeId = (value: unknown, label: string): string => {
+  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value)) {
+    throw new Error(`${label} must be a safe identifier`);
+  }
+  return value;
+};
+
+const address = (value: unknown, label: string): string => {
+  if (typeof value !== "string" || !isAddress(value)) {
+    throw new Error(`${label} must be a valid EVM address`);
+  }
+  return getAddress(value);
+};
+
+const optionalAddress = (value: unknown, label: string): string | undefined => (
+  value === undefined ? undefined : address(value, label)
+);
+
+const deploymentInfoPath = (root: string): string => path.join(root, "deploymentInfo.json");
+
+const validateSource = (value: unknown, label: string): DeploymentInfoSource => {
+  if (!isRecord(value)) throw new Error(`${label} is required`);
+  const sourceKeys = Object.keys(value).sort();
+  if (value.kind === "migration") {
+    if (sourceKeys.join(",") !== "evidencePath,kind,migrationId") {
+      throw new Error(`${label} migration source must use the canonical fields`);
+    }
+    const migrationId = safeId(value.migrationId, `${label}.migrationId`);
+    const evidencePath = String(value.evidencePath).split(path.sep).join("/");
+    const expectedPath = `scripts/migrations/${migrationId}/state-import.json`;
+    if (evidencePath !== expectedPath) {
+      throw new Error(`${label}.evidencePath must be ${expectedPath}`);
+    }
+    return { kind: "migration", migrationId, evidencePath };
+  }
+
+  const legacyDeployment = value.kind === undefined
+    && sourceKeys.join(",") === "deploymentId,executionId,recordPath";
+  const canonicalDeployment = value.kind === "deployment"
+    && sourceKeys.join(",") === "deploymentId,executionId,kind,recordPath";
+  if (!legacyDeployment && !canonicalDeployment) {
+    throw new Error(`${label} deployment source must use the canonical fields`);
+  }
+  return {
+    kind: "deployment",
+    deploymentId: safeId(value.deploymentId, `${label}.deploymentId`),
+    executionId: safeId(value.executionId, `${label}.executionId`),
+    recordPath: String(value.recordPath),
+  };
+};
+
+const confinedRecordPath = (root: string, recordPath: string): string => {
+  if (!recordPath || path.isAbsolute(recordPath)) {
+    throw new Error(`Deployment record path must be project-relative: ${recordPath}`);
+  }
+  const absolute = path.resolve(root, recordPath);
+  const relative = path.relative(path.resolve(root), absolute);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`Deployment record path escapes the project: ${recordPath}`);
+  }
+  const stat = fs.lstatSync(absolute);
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new Error(`Deployment record must be a regular file: ${recordPath}`);
+  }
+  return absolute;
+};
+
+const validateEntry = (value: unknown, label: string): DeploymentInfoEntry => {
+  if (!isRecord(value)) throw new Error(`${label} must be an object`);
+  const allowed = new Set([
+    "contractInfoKey",
+    "address",
+    "actualContract",
+    "proxyKind",
+    "implementationAddress",
+    "source",
+    "updatedAt",
+  ]);
+  if (Object.keys(value).some((key) => !allowed.has(key))) {
+    throw new Error(`${label} contains unsupported fields`);
+  }
+  if (typeof value.contractInfoKey !== "string" || !value.contractInfoKey.trim()) {
+    throw new Error(`${label}.contractInfoKey is required`);
+  }
+  if (typeof value.actualContract !== "string" || !value.actualContract.trim()) {
+    throw new Error(`${label}.actualContract is required`);
+  }
+  if (value.proxyKind !== undefined && value.proxyKind !== "uups" && value.proxyKind !== "transparent") {
+    throw new Error(`${label}.proxyKind is invalid`);
+  }
+  if (typeof value.updatedAt !== "string" || !Number.isFinite(Date.parse(value.updatedAt))) {
+    throw new Error(`${label}.updatedAt must be an ISO timestamp`);
+  }
+  return {
+    contractInfoKey: value.contractInfoKey,
+    address: address(value.address, `${label}.address`),
+    actualContract: value.actualContract,
+    ...(value.proxyKind ? { proxyKind: value.proxyKind } : {}),
+    ...(value.implementationAddress
+      ? { implementationAddress: address(value.implementationAddress, `${label}.implementationAddress`) }
+      : {}),
+    source: validateSource(value.source, `${label}.source`),
+    updatedAt: value.updatedAt,
+  };
+};
+
+export const validateDeploymentInfo = (value: unknown): DeploymentInfo => {
+  if (!isRecord(value) || value.version !== 1 || !isRecord(value.networks)) {
+    throw new Error("deploymentInfo.json must contain version 1 network metadata");
+  }
+  if (Object.keys(value).some((key) => key !== "version" && key !== "networks")) {
+    throw new Error("deploymentInfo.json contains unsupported fields");
+  }
+  const networks: DeploymentInfo["networks"] = {};
+  for (const [network, entries] of Object.entries(value.networks)) {
+    safeId(network, "deploymentInfo network");
+    if (!isRecord(entries)) throw new Error(`deploymentInfo network ${network} must be an object`);
+    networks[network] = Object.fromEntries(Object.entries(entries).map(([instanceId, entry]) => [
+      safeId(instanceId, `deploymentInfo ${network} instanceId`),
+      validateEntry(entry, `deploymentInfo ${network}.${instanceId}`),
+    ]));
+  }
+  return { version: 1, networks };
+};
+
+export function loadDeploymentInfo(root: string): DeploymentInfo {
+  const filePath = deploymentInfoPath(root);
+  if (!fs.existsSync(filePath)) return { version: 1, networks: {} };
+  return validateDeploymentInfo(readJsonFile<unknown>(filePath));
+}
+
+export function saveDeploymentInfo(root: string, value: DeploymentInfo): void {
+  writeJsonFile(deploymentInfoPath(root), validateDeploymentInfo(value));
+}
+
+export function prepareDeploymentInfoFromRecords(input: {
+  root: string;
+  records: DeploymentRecordPromotionInput[];
+  expectedContractInfo: ContractInfo;
+}): DeploymentInfo {
+  const expectedContractInfo = validateContractInfo(input.expectedContractInfo);
+  const current = loadDeploymentInfo(input.root);
+  const networks = Object.fromEntries(Object.entries(current.networks).map(([network, entries]) => [
+    network,
+    { ...entries },
+  ]));
+  const seenPaths = new Set<string>();
+
+  for (const inputRecord of input.records) {
+    if (seenPaths.has(inputRecord.recordPath)) throw new Error(`Duplicate deployment record path: ${inputRecord.recordPath}`);
+    seenPaths.add(inputRecord.recordPath);
+    const absolutePath = confinedRecordPath(input.root, inputRecord.recordPath);
+    const record = readJsonFile<unknown>(absolutePath);
+    if (!isRecord(record) || !Array.isArray(record.changes)) {
+      throw new Error(`Deployment record is malformed: ${inputRecord.recordPath}`);
+    }
+    const network = safeId(record.network, "deployment record network");
+    const deploymentId = safeId(record.taskId, "deployment record taskId");
+    const executionId = safeId(record.executionId, "deployment record executionId");
+    const targetEntries = { ...(networks[network] ?? {}) };
+
+    for (const [index, rawChange] of record.changes.entries()) {
+      if (!isRecord(rawChange)) throw new Error(`Deployment record change ${index} must be an object`);
+      const instanceId = safeId(rawChange.instanceId, `deployment record change ${index} instanceId`);
+      const actualContract = safeId(rawChange.actualContract, `deployment record change ${index} actualContract`);
+      if (typeof rawChange.contractInfoKey !== "string" || !rawChange.contractInfoKey.trim()) {
+        throw new Error(`Deployment record change ${index} contractInfoKey is required`);
+      }
+      const resolved = resolveDeployment(expectedContractInfo, network, instanceId);
+      if (!resolved || resolved.key !== rawChange.contractInfoKey) {
+        throw new Error(`Deployment metadata conflicts with contractInfo for ${network}.${instanceId}`);
+      }
+      const deployedAddress = address(
+        rawChange.proxyAddress ?? rawChange.candidateAddress ?? rawChange.address,
+        `deployment record change ${index} address`,
+      );
+      if (resolved.address.toLowerCase() !== deployedAddress.toLowerCase()) {
+        throw new Error(`Deployment metadata address conflicts with contractInfo for ${network}.${instanceId}`);
+      }
+      const existing = targetEntries[instanceId];
+      if (
+        existing
+        && existing.address.toLowerCase() !== deployedAddress.toLowerCase()
+        && optionalAddress(rawChange.previousAddress, `deployment record change ${index} previousAddress`)?.toLowerCase()
+          !== existing.address.toLowerCase()
+      ) {
+        throw new Error(`Deployment metadata address conflict for ${network}.${instanceId}`);
+      }
+      const rawProxyKind = rawChange.proxyKind === undefined
+        ? existing?.proxyKind
+        : rawChange.proxyKind;
+      if (rawProxyKind !== undefined && rawProxyKind !== "uups" && rawProxyKind !== "transparent") {
+        throw new Error(`Deployment record change ${index} proxyKind is invalid`);
+      }
+      const proxyKind: DeploymentInfoEntry["proxyKind"] = rawProxyKind;
+      const implementationAddress = rawChange.implementationAddress === undefined
+        ? existing?.implementationAddress
+        : optionalAddress(rawChange.implementationAddress, `deployment record change ${index} implementationAddress`);
+      const nextEntry = {
+        contractInfoKey: rawChange.contractInfoKey,
+        address: deployedAddress,
+        actualContract,
+        ...(proxyKind ? { proxyKind } : {}),
+        ...(implementationAddress ? { implementationAddress } : {}),
+        source: {
+          kind: "deployment" as const,
+          deploymentId,
+          executionId,
+          recordPath: inputRecord.recordPath,
+        },
+      };
+      const existingComparable = existing
+        ? {
+            contractInfoKey: existing.contractInfoKey,
+            address: existing.address,
+            actualContract: existing.actualContract,
+            ...(existing.proxyKind ? { proxyKind: existing.proxyKind } : {}),
+            ...(existing.implementationAddress
+              ? { implementationAddress: existing.implementationAddress }
+              : {}),
+            source: existing.source,
+          }
+        : undefined;
+      targetEntries[instanceId] = {
+        ...nextEntry,
+        updatedAt: existingComparable
+          && JSON.stringify(existingComparable) === JSON.stringify(nextEntry)
+          ? existing!.updatedAt
+          : new Date().toISOString(),
+      };
+    }
+    networks[network] = targetEntries;
+  }
+  return validateDeploymentInfo({ version: 1, networks });
+}
+
+export function updateDeploymentInfoFromRecords(input: {
+  root: string;
+  records: DeploymentRecordPromotionInput[];
+  expectedContractInfo: ContractInfo;
+}): DeploymentInfo {
+  const next = prepareDeploymentInfoFromRecords(input);
+  saveDeploymentInfo(input.root, next);
+  return next;
+}