gate-evm-tools 1.0.26 → 1.0.28

package/dist-runtime/workflow/lib/externalExecutionScanner.js

@@ -0,0 +1,638 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconcileExternalExecution = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const ethers_1 = require("ethers");
+const executionPlan_1 = require("./executionPlan");
+const external_1 = require("./external");
+const operatorExecution_1 = require("./operatorExecution");
+const deploymentRecords_1 = require("./deploymentRecords");
+const config_1 = require("./config");
+const gateToolSync_1 = require("./gateToolSync");
+const SAFE_INTERFACE = new ethers_1.Interface([
+    "function execTransaction(address to,uint256 value,bytes data,uint8 operation,uint256 safeTxGas,uint256 baseGas,uint256 gasPrice,address gasToken,address payable refundReceiver,bytes signatures) returns (bool success)",
+    "function VERSION() view returns (string)",
+    "event ExecutionSuccess(bytes32 txHash,uint256 payment)",
+    "event ExecutionFailure(bytes32 txHash,uint256 payment)",
+]);
+const MULTISEND_INTERFACE = new ethers_1.Interface([
+    "function multiSend(bytes transactions)",
+]);
+const sha256 = (value) => (crypto_1.default.createHash("sha256").update(value).digest("hex"));
+const numberValue = (value, label) => {
+    let parsed;
+    try {
+        parsed = typeof value === "bigint" ? value : BigInt(value);
+    }
+    catch {
+        throw new Error(`${label} is not an integer`);
+    }
+    if (parsed < 0n || parsed > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new Error(`${label} is outside the safe integer range`);
+    }
+    return Number(parsed);
+};
+const address = (value, label) => {
+    if (typeof value !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(value)) {
+        throw new Error(`${label} is not an EVM address`);
+    }
+    return value.toLowerCase();
+};
+const calldata = (transaction) => {
+    const value = transaction.data ?? transaction.input;
+    if (typeof value !== "string" || !/^0x(?:[0-9a-fA-F]{2})*$/.test(value)) {
+        throw new Error(`Transaction ${transaction.hash} has invalid calldata`);
+    }
+    return value.toLowerCase();
+};
+const receiptStatus = (receipt) => {
+    const status = numberValue(receipt.status, "receipt status");
+    if (status !== 0 && status !== 1)
+        throw new Error("receipt status must be 0 or 1");
+    return status;
+};
+const relative = (root, filePath) => {
+    const value = path_1.default.relative(path_1.default.resolve(root), path_1.default.resolve(filePath));
+    if (value.startsWith("..") || path_1.default.isAbsolute(value)) {
+        throw new Error("Reconciliation evidence path escapes the project root");
+    }
+    return value.split(path_1.default.sep).join("/");
+};
+const readJson = (filePath, label) => {
+    try {
+        return JSON.parse(fs_1.default.readFileSync(filePath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`${label} is invalid: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+const writeJsonAtomic = (filePath, value) => {
+    fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+    const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        fs_1.default.writeFileSync(temporary, JSON.stringify(value, null, 2) + "\n");
+        fs_1.default.renameSync(temporary, filePath);
+    }
+    catch (error) {
+        if (fs_1.default.existsSync(temporary))
+            fs_1.default.unlinkSync(temporary);
+        throw error;
+    }
+};
+const loadExternalPackage = (input) => {
+    const externalTransactions = input.plan.transactions.filter((transaction) => (transaction.route === "external"));
+    const filePath = path_1.default.join(input.taskDir, "calldata", input.plan.target, input.plan.executionId, "external-execution.json");
+    if (externalTransactions.length === 0) {
+        if (fs_1.default.existsSync(filePath)) {
+            throw new Error("All-operator execution must not contain an external package");
+        }
+        return undefined;
+    }
+    const loaded = (0, external_1.loadExternalExecutionPackage)({ taskDir: input.taskDir, plan: input.plan });
+    if (!loaded)
+        return undefined;
+    return {
+        package: loaded.package,
+        filePath: loaded.filePath,
+        hash: sha256(fs_1.default.readFileSync(loaded.filePath)),
+    };
+};
+const transactionMatches = (transaction, expected, from) => (address(transaction.from, "transaction sender") === address(from, "expected sender")
+    && transaction.to !== null
+    && address(transaction.to, "transaction target") === expected.to
+    && numberValue(transaction.value, "transaction value").toString() === expected.value
+    && calldata(transaction) === expected.data
+    && expected.operation === 0);
+const parseMultisend = (encoded) => {
+    const payload = encoded.startsWith("0x") ? encoded.slice(2) : encoded;
+    const calls = [];
+    let offset = 0;
+    while (offset < payload.length) {
+        if (payload.length - offset < 2 + 40 + 64 + 64) {
+            throw new Error("Safe MultiSend payload is truncated");
+        }
+        const operation = Number.parseInt(payload.slice(offset, offset + 2), 16);
+        offset += 2;
+        if (operation !== 0 && operation !== 1)
+            throw new Error("Safe MultiSend operation is invalid");
+        const to = `0x${payload.slice(offset, offset + 40)}`.toLowerCase();
+        offset += 40;
+        const value = BigInt(`0x${payload.slice(offset, offset + 64)}`).toString(10);
+        offset += 64;
+        const length = numberValue(`0x${payload.slice(offset, offset + 64)}`, "MultiSend data length");
+        offset += 64;
+        const end = offset + length * 2;
+        if (end > payload.length)
+            throw new Error("Safe MultiSend call data is truncated");
+        calls.push({ operation, to, value, data: `0x${payload.slice(offset, end)}`.toLowerCase() });
+        offset = end;
+    }
+    return calls;
+};
+const safeCalls = async (provider, transaction, safeAddress) => {
+    if (address(transaction.to, "Safe transaction target") !== safeAddress)
+        return [];
+    if (!provider.call)
+        throw new Error(`Unknown contract-wallet executor ${safeAddress}`);
+    try {
+        const versionResult = await provider.call({
+            to: safeAddress,
+            data: SAFE_INTERFACE.encodeFunctionData("VERSION", []),
+        });
+        SAFE_INTERFACE.decodeFunctionResult("VERSION", versionResult);
+    }
+    catch {
+        throw new Error(`Unknown contract-wallet executor ${safeAddress}`);
+    }
+    let decoded;
+    try {
+        decoded = SAFE_INTERFACE.decodeFunctionData("execTransaction", calldata(transaction));
+    }
+    catch {
+        return [];
+    }
+    const outer = {
+        to: address(decoded[0], "Safe inner target"),
+        value: BigInt(decoded[1]).toString(10),
+        data: String(decoded[2]).toLowerCase(),
+        operation: Number(decoded[3]),
+    };
+    try {
+        const multisend = MULTISEND_INTERFACE.decodeFunctionData("multiSend", outer.data);
+        return parseMultisend(String(multisend[0])).map((call, innerCallIndex) => ({
+            ...call,
+            kind: "safe_multisend",
+            innerCallIndex,
+        }));
+    }
+    catch {
+        return [{ ...outer, kind: "safe_call" }];
+    }
+};
+const assertSafeExecutionSucceeded = (receipt, safeAddress) => {
+    let success = false;
+    let failure = false;
+    for (const log of receipt.logs || []) {
+        if (typeof log.address !== "string"
+            || log.address.toLowerCase() !== safeAddress.toLowerCase()
+            || !Array.isArray(log.topics)
+            || typeof log.data !== "string") {
+            continue;
+        }
+        try {
+            const parsed = SAFE_INTERFACE.parseLog({ topics: log.topics, data: log.data });
+            if (parsed?.name === "ExecutionFailure")
+                failure = true;
+            if (parsed?.name === "ExecutionSuccess")
+                success = true;
+        }
+        catch {
+            // Ignore unrelated logs emitted by the Safe transaction.
+        }
+    }
+    if (failure)
+        throw new Error(`Safe ${safeAddress} emitted ExecutionFailure`);
+    if (!success)
+        throw new Error(`Safe ${safeAddress} receipt is missing ExecutionSuccess`);
+};
+const finalizedHeight = async (provider, confirmations) => {
+    try {
+        const block = await provider.send("eth_getBlockByNumber", ["finalized", false]);
+        if (block?.number !== undefined) {
+            return {
+                finalizedBlock: numberValue(block.number, "finalized block number"),
+                policy: { mode: "rpc_finalized" },
+            };
+        }
+    }
+    catch {
+        // Some EVM RPC providers do not implement the finalized block tag.
+    }
+    const latest = await provider.getBlockNumber();
+    if (!Number.isSafeInteger(latest) || latest < 0) {
+        throw new Error("RPC latest block number is invalid");
+    }
+    return {
+        finalizedBlock: Math.max(0, latest - confirmations),
+        policy: { mode: "confirmation_depth", confirmations },
+    };
+};
+const receiptMatch = (expected, transaction, receipt, finalizedBlock, details) => {
+    const blockNumber = numberValue(receipt.blockNumber, "receipt blockNumber");
+    const blockTransactionIndex = numberValue(receipt.index ?? receipt.transactionIndex ?? transaction.index ?? transaction.transactionIndex ?? 0, "receipt transaction index");
+    return {
+        transactionId: expected.transactionId,
+        transactionIndex: expected.transactionIndex,
+        route: expected.route,
+        executor: expected.executor,
+        submittedBy: address(details.submittedBy, "submittedBy"),
+        executionKind: details.executionKind,
+        transactionHash: transaction.hash.toLowerCase(),
+        blockNumber,
+        blockHash: receipt.blockHash.toLowerCase(),
+        blockTransactionIndex,
+        innerCallIndex: details.innerCallIndex,
+        receiptStatus: receiptStatus(receipt),
+        finalized: blockNumber <= finalizedBlock,
+    };
+};
+const validateCanonicalReceipt = async (provider, receipt) => {
+    const blockNumber = numberValue(receipt.blockNumber, "receipt blockNumber");
+    const block = await provider.send("eth_getBlockByNumber", [`0x${blockNumber.toString(16)}`, false]);
+    if (!block?.hash || block.hash.toLowerCase() !== receipt.blockHash.toLowerCase()) {
+        throw new Error("Transaction receipt is no longer in the canonical chain");
+    }
+};
+const reconcileExternalExecution = async (input) => {
+    const provider = input.provider;
+    const taskDir = path_1.default.join(input.root, "scripts", "tasks", input.taskId);
+    const plan = (0, executionPlan_1.loadReleaseExecutionPlan)({
+        root: input.root,
+        taskDir,
+        target: input.network,
+        executionId: input.executionId,
+    });
+    if (plan.taskId !== input.taskId)
+        throw new Error("Execution plan taskId mismatch");
+    const packageEvidence = loadExternalPackage({ root: input.root, taskDir, plan });
+    const operatorResultPath = path_1.default.join(taskDir, "results", plan.target, plan.executionId, "operator-execution.json");
+    const operatorResult = fs_1.default.existsSync(operatorResultPath)
+        ? (0, operatorExecution_1.loadOperatorExecutionResult)({ taskDir, plan })
+        : undefined;
+    const reportFile = path_1.default.join(taskDir, "results", input.network, input.executionId, "external-reconciliation.json");
+    const reportPath = relative(input.root, reportFile);
+    const previous = fs_1.default.existsSync(reportFile)
+        ? readJson(reportFile, "external reconciliation report")
+        : undefined;
+    if (previous
+        && (previous.version !== 1
+            || previous.taskId !== input.taskId
+            || previous.target !== input.network
+            || previous.executionId !== input.executionId
+            || previous.executionPlanHash !== plan.planHash)) {
+        throw new Error("Persisted reconciliation report does not match this execution");
+    }
+    const target = (0, config_1.resolveTarget)((0, config_1.loadConfig)(input.root), input.network);
+    const confirmations = (0, config_1.resolveFinalityConfirmations)(target, input.network);
+    const finality = await finalizedHeight(provider, confirmations);
+    const { finalizedBlock } = finality;
+    const matches = new Map();
+    let failure;
+    try {
+        for (const evidence of operatorResult?.receipts ?? []) {
+            const expected = plan.transactions.find((transaction) => (transaction.transactionId === evidence.transactionId));
+            if (!expected || expected.route !== "operator") {
+                throw new Error(`Operator receipt ${evidence.transactionId} does not match the plan`);
+            }
+            const transaction = await provider.getTransaction(evidence.transactionHash);
+            const receipt = await provider.getTransactionReceipt(evidence.transactionHash);
+            if (!transaction || !receipt)
+                continue;
+            await validateCanonicalReceipt(provider, receipt);
+            if (!transactionMatches(transaction, expected, expected.executor)) {
+                throw new Error(`Operator transaction ${expected.transactionId} does not match the plan`);
+            }
+            matches.set(expected.transactionId, receiptMatch(expected, transaction, receipt, finalizedBlock, { executionKind: "eoa", submittedBy: transaction.from }));
+        }
+        for (const previousMatch of previous?.matches || []) {
+            if (previousMatch.route !== "external")
+                continue;
+            const expected = plan.transactions[previousMatch.transactionIndex];
+            if (!expected || expected.transactionId !== previousMatch.transactionId) {
+                throw new Error("Persisted external match does not belong to the execution plan");
+            }
+            const transaction = await provider.getTransaction(previousMatch.transactionHash);
+            const receipt = await provider.getTransactionReceipt(previousMatch.transactionHash);
+            if (!transaction || !receipt) {
+                throw new Error(`Previously matched transaction disappeared: ${previousMatch.transactionHash}`);
+            }
+            await validateCanonicalReceipt(provider, receipt);
+            if (previousMatch.executionKind === "eoa") {
+                if (!transactionMatches(transaction, expected, expected.executor)) {
+                    throw new Error(`Previously matched transaction changed: ${expected.transactionId}`);
+                }
+            }
+            else {
+                const decoded = await safeCalls(provider, transaction, expected.executor);
+                const call = decoded[previousMatch.innerCallIndex || 0];
+                if (!call
+                    || call.to !== expected.to
+                    || call.value !== expected.value
+                    || call.data !== expected.data
+                    || call.operation !== expected.operation) {
+                    throw new Error(`Previously matched Safe transaction changed: ${expected.transactionId}`);
+                }
+                assertSafeExecutionSucceeded(receipt, expected.executor);
+            }
+            matches.set(expected.transactionId, receiptMatch(expected, transaction, receipt, finalizedBlock, {
+                executionKind: previousMatch.executionKind,
+                submittedBy: transaction.from,
+                innerCallIndex: previousMatch.innerCallIndex,
+            }));
+        }
+    }
+    catch (error) {
+        failure = {
+            code: "EVIDENCE_INVALID",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const external = plan.transactions.filter((transaction) => transaction.route === "external");
+    const previousSegments = new Map((previous?.segments ?? []).map((segment) => [
+        segment.segmentId,
+        segment,
+    ]));
+    const segmentProgress = packageEvidence?.package.segments.map((segment) => {
+        const persisted = previousSegments.get(segment.segmentId);
+        if (persisted && (persisted.handoffBlock !== segment.handoffBlock
+            || JSON.stringify(persisted.transactionIds) !== JSON.stringify(segment.transactionIds))) {
+            throw new Error(`Persisted reconciliation segment ${segment.segmentId} changed`);
+        }
+        return {
+            segmentId: segment.segmentId,
+            transactionIds: segment.transactionIds,
+            handoffBlock: segment.handoffBlock,
+            nextBlock: persisted?.nextBlock ?? segment.handoffBlock,
+        };
+    });
+    if (previousSegments.size > (segmentProgress?.length ?? 0)) {
+        throw new Error("External execution package removed a reconciled segment");
+    }
+    const firstIncompleteBeforeScan = plan.transactions.find((transaction) => {
+        const match = matches.get(transaction.transactionId);
+        return !match || match.receiptStatus !== 1 || !match.finalized;
+    });
+    const activeSegment = firstIncompleteBeforeScan?.route === "external"
+        ? packageEvidence?.package.segments.find((segment) => (segment.transactionIds.includes(firstIncompleteBeforeScan.transactionId)))
+        : undefined;
+    const activeProgress = activeSegment
+        ? segmentProgress?.find((segment) => segment.segmentId === activeSegment.segmentId)
+        : undefined;
+    const writeScanCheckpoint = () => {
+        const now = new Date().toISOString();
+        const checkpointMatches = [...matches.values()].sort((left, right) => (left.transactionIndex - right.transactionIndex));
+        const checkpoint = {
+            version: 1,
+            status: "waiting_external",
+            taskId: input.taskId,
+            target: input.network,
+            executionId: input.executionId,
+            executionPlanHash: plan.planHash,
+            packagePath: packageEvidence ? relative(input.root, packageEvidence.filePath) : undefined,
+            packageHash: packageEvidence?.hash,
+            segments: segmentProgress,
+            finalizedBlock,
+            finalityPolicy: finality.policy,
+            matchedTransactionIds: checkpointMatches.map((match) => match.transactionId),
+            matches: checkpointMatches,
+            reportPath,
+            createdAt: previous?.createdAt || now,
+            updatedAt: now,
+        };
+        writeJsonAtomic(reportFile, checkpoint);
+    };
+    if (!failure
+        && activeSegment
+        && activeProgress
+        && !matches.has(firstIncompleteBeforeScan.transactionId)) {
+        const latest = await provider.getBlockNumber();
+        const batchSize = input.batchSize ?? 1000;
+        if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > 1000) {
+            throw new Error("Reconciliation batchSize must be between 1 and 1000");
+        }
+        const start = activeProgress.nextBlock;
+        const end = Math.min(latest, start + batchSize - 1);
+        const segmentTransactions = activeSegment.transactionIds.map((transactionId) => {
+            const transaction = plan.transactions.find((candidate) => (candidate.transactionId === transactionId));
+            if (!transaction || transaction.route !== "external") {
+                throw new Error(`External segment transaction ${transactionId} is invalid`);
+            }
+            return transaction;
+        });
+        for (let blockNumber = start; blockNumber <= end; blockNumber += 1) {
+            let block;
+            try {
+                block = await provider.send("eth_getBlockByNumber", [`0x${blockNumber.toString(16)}`, true]);
+            }
+            catch (error) {
+                writeScanCheckpoint();
+                throw error;
+            }
+            try {
+                for (const transaction of block?.transactions || []) {
+                    const remaining = segmentTransactions.filter((candidate) => (!matches.has(candidate.transactionId)));
+                    const expected = remaining[0];
+                    if (!expected)
+                        break;
+                    const code = await provider.getCode(expected.executor);
+                    if (!code || code === "0x") {
+                        if (!transactionMatches(transaction, expected, expected.executor))
+                            continue;
+                        const receipt = await provider.getTransactionReceipt(transaction.hash);
+                        if (!receipt)
+                            continue;
+                        await validateCanonicalReceipt(provider, receipt);
+                        matches.set(expected.transactionId, receiptMatch(expected, transaction, receipt, finalizedBlock, { executionKind: "eoa", submittedBy: transaction.from }));
+                        continue;
+                    }
+                    const decoded = await safeCalls(provider, transaction, expected.executor);
+                    if (decoded.length === 0)
+                        continue;
+                    const receipt = await provider.getTransactionReceipt(transaction.hash);
+                    if (!receipt)
+                        continue;
+                    await validateCanonicalReceipt(provider, receipt);
+                    const matchedCalls = [];
+                    const remainingCalls = segmentTransactions.filter((item) => (!matches.has(item.transactionId)));
+                    for (const decodedCall of decoded) {
+                        const candidate = remainingCalls[matchedCalls.length];
+                        if (!candidate)
+                            break;
+                        if (decodedCall.to !== candidate.to
+                            || decodedCall.value !== candidate.value
+                            || decodedCall.data !== candidate.data
+                            || decodedCall.operation !== candidate.operation
+                            || candidate.executor !== expected.executor) {
+                            break;
+                        }
+                        matchedCalls.push({ transaction: candidate, decodedCall });
+                    }
+                    if (matchedCalls.length === 0)
+                        continue;
+                    assertSafeExecutionSucceeded(receipt, expected.executor);
+                    for (const { transaction: candidate, decodedCall } of matchedCalls) {
+                        matches.set(candidate.transactionId, receiptMatch(candidate, transaction, receipt, finalizedBlock, {
+                            executionKind: decodedCall.kind,
+                            submittedBy: transaction.from,
+                            innerCallIndex: decodedCall.innerCallIndex,
+                        }));
+                    }
+                }
+                activeProgress.nextBlock = blockNumber + 1;
+                writeScanCheckpoint();
+            }
+            catch (error) {
+                failure = {
+                    code: "SCAN_FAILED",
+                    message: error instanceof Error ? error.message : String(error),
+                };
+                break;
+            }
+        }
+    }
+    const orderedMatches = [...matches.values()].sort((left, right) => (left.transactionIndex - right.transactionIndex));
+    const reverted = orderedMatches.find((match) => match.receiptStatus === 0);
+    if (reverted) {
+        failure = {
+            code: "TRANSACTION_REVERTED",
+            message: `Transaction ${reverted.transactionHash} reverted`,
+            transactionId: reverted.transactionId,
+        };
+    }
+    const chainOrdered = [...orderedMatches].sort((left, right) => (left.blockNumber - right.blockNumber
+        || left.blockTransactionIndex - right.blockTransactionIndex
+        || (left.innerCallIndex ?? -1) - (right.innerCallIndex ?? -1)));
+    if (chainOrdered.some((match, index) => (index > 0 && chainOrdered[index - 1].transactionIndex >= match.transactionIndex))) {
+        failure = {
+            code: "PLAN_ORDER_VIOLATION",
+            message: "Canonical chain execution does not preserve immutable plan order",
+        };
+    }
+    const firstIncomplete = plan.transactions.find((transaction) => {
+        const match = matches.get(transaction.transactionId);
+        return !match || match.receiptStatus !== 1 || !match.finalized;
+    });
+    const incompleteMatch = firstIncomplete
+        ? matches.get(firstIncomplete.transactionId)
+        : undefined;
+    const submittedOperatorIds = new Set((operatorResult?.receipts ?? []).map((receipt) => receipt.transactionId));
+    const packageContainsIncomplete = Boolean(firstIncomplete?.route === "external"
+        && packageEvidence?.package.segments.some((segment) => (segment.transactionIds.includes(firstIncomplete.transactionId))));
+    const status = failure
+        ? "failed"
+        : !firstIncomplete
+            ? external.length > 0 ? "reconciled" : "not_required"
+            : incompleteMatch
+                ? "waiting_finality"
+                : firstIncomplete.route === "operator"
+                    ? submittedOperatorIds.has(firstIncomplete.transactionId)
+                        ? "waiting_finality"
+                        : "waiting_operator"
+                    : packageContainsIncomplete
+                        ? "waiting_external"
+                        : "waiting_operator";
+    const now = new Date().toISOString();
+    const report = {
+        version: 1,
+        status,
+        taskId: input.taskId,
+        target: input.network,
+        executionId: input.executionId,
+        executionPlanHash: plan.planHash,
+        packagePath: packageEvidence ? relative(input.root, packageEvidence.filePath) : undefined,
+        packageHash: packageEvidence?.hash,
+        segments: segmentProgress,
+        finalizedBlock,
+        finalityPolicy: finality.policy,
+        matchedTransactionIds: orderedMatches.map((match) => match.transactionId),
+        matches: orderedMatches,
+        failure,
+        reportPath,
+        createdAt: previous?.createdAt || now,
+        updatedAt: now,
+        completedAt: status === "reconciled" || status === "not_required" ? now : undefined,
+    };
+    const gateToolSyncByStep = {};
+    if (status === "reconciled") {
+        const deployment = (0, deploymentRecords_1.loadDeploymentExecutionRecord)({
+            taskDir,
+            taskId: input.taskId,
+            network: input.network,
+            executionId: input.executionId,
+        });
+        const matchByTransactionId = new Map(orderedMatches.map((match) => [match.transactionId, match]));
+        for (const change of deployment.changes) {
+            if (change.proxyKind !== "uups")
+                continue;
+            if (!change.proxyAddress
+                || !change.implementationAddress
+                || !Array.isArray(change.constructorArgs)
+                || !change.proxyTransactionId) {
+                throw new Error(`UUPS change ${change.stepId} is missing GateTool sync inputs`);
+            }
+            const candidates = plan.transactions.filter((transaction) => (transaction.transactionId === change.proxyTransactionId));
+            if (candidates.length !== 1) {
+                throw new Error(`UUPS change ${change.stepId} has no unique finalized proxy receipt`);
+            }
+            const transaction = candidates[0];
+            if (transaction.stepId !== change.stepId) {
+                throw new Error(`UUPS change ${change.stepId} proxy receipt does not match its plan step`);
+            }
+            if (change.kind === "upgrade"
+                && transaction.to.toLowerCase() !== change.proxyAddress.toLowerCase()) {
+                throw new Error(`UUPS change ${change.stepId} receipt does not target its proxy`);
+            }
+            if (change.kind === "deploy"
+                && (!change.multicall
+                    || transaction.to.toLowerCase() !== change.multicall.toLowerCase())) {
+                throw new Error(`UUPS change ${change.stepId} receipt does not target its controlled multicall`);
+            }
+            const match = matchByTransactionId.get(transaction.transactionId);
+            if (!match || match.receiptStatus !== 1 || !match.finalized) {
+                throw new Error(`UUPS change ${change.stepId} receipt is not finalized`);
+            }
+            const gateToolSync = await (input.dependencies?.syncGateToolUups ?? gateToolSync_1.syncGateToolUups)({
+                root: input.root,
+                evidenceDir: path_1.default.join(taskDir, "results", input.network, input.executionId, "gate-tool", "execute"),
+                evidenceName: change.stepId,
+                scheme: transaction.scheme || "evm",
+                network: input.network,
+                target: input.network,
+                manifestDir: target.openzeppelin.manifestDir,
+                proxy: change.proxyAddress,
+                implementation: change.implementationAddress,
+                contract: change.actualContract,
+                constructorArgs: change.constructorArgs,
+                transactionHash: match.transactionHash,
+                hre: input.gateToolSyncHre,
+            });
+            if (change.gateToolSync
+                && JSON.stringify(change.gateToolSync) !== JSON.stringify(gateToolSync)) {
+                throw new Error(`UUPS change ${change.stepId} stored GateTool sync evidence does not match the finalized receipt`);
+            }
+            gateToolSyncByStep[change.stepId] = gateToolSync;
+        }
+    }
+    const normalizedReport = JSON.parse(JSON.stringify(report));
+    const persistedReport = previous?.status === "reconciled"
+        && normalizedReport.status === "reconciled"
+        && previous.packagePath === normalizedReport.packagePath
+        && previous.packageHash === normalizedReport.packageHash
+        && JSON.stringify(previous.segments) === JSON.stringify(normalizedReport.segments)
+        && JSON.stringify(previous.matchedTransactionIds)
+            === JSON.stringify(normalizedReport.matchedTransactionIds)
+        && JSON.stringify(previous.matches) === JSON.stringify(normalizedReport.matches)
+        ? previous
+        : normalizedReport;
+    if (persistedReport !== previous)
+        writeJsonAtomic(reportFile, persistedReport);
+    if (status === "reconciled") {
+        (0, deploymentRecords_1.markDeploymentRecordReconciled)({
+            taskDir,
+            taskId: input.taskId,
+            network: input.network,
+            executionId: input.executionId,
+            reportPath,
+            reportHash: sha256(fs_1.default.readFileSync(reportFile)),
+            gateToolSyncByStep,
+        });
+    }
+    return persistedReport;
+};
+exports.reconcileExternalExecution = reconcileExternalExecution;
+//# sourceMappingURL=externalExecutionScanner.js.map