@gzeoneth/gov-tracker 0.1.0

package/dist/stages/l2-to-l1-message.d.ts

@@ -0,0 +1,108 @@
+/**
+ * L2 to L1 Message Stage Tracking and Preparation
+ *
+ * Stage 5: L2_TO_L1_MESSAGE - Unified cross-chain message tracking
+ *
+ * Status semantics:
+ * - NOT_STARTED: No L2→L1 messages found or L2 timelock not executed
+ * - PENDING: Message sent, in challenge period
+ * - READY: Challenge period complete, ready to execute outbox
+ * - COMPLETED: Outbox executed (message confirmed on L1)
+ * - SKIPPED: L2-only path (Treasury Governor)
+ *
+ * Uses @arbitrum/sdk v4 for cross-chain message tracking.
+ * Includes preparation functions for outbox execution.
+ */
+import { BigNumber, ethers } from "ethers";
+import { ChildToParentMessageStatus, ChildToParentMessageReader } from "@arbitrum/sdk";
+import { ChildToParentMessageReaderNitro } from "@arbitrum/sdk/dist/lib/message/ChildToParentMessageNitro";
+import { TrackedStage, PrepareResult } from "../types";
+import { SimpleBulkResult } from "../utils/stage-helpers";
+/**
+ * Find the L1 transaction that executed the L2→L1 message (OutBox execution).
+ * Uses the message position to match OutBoxTransactionExecuted events.
+ *
+ * This transaction is important because:
+ * 1. It confirms the L2→L1 message was executed
+ * 2. It contains the CallScheduled event for the L1 timelock operation
+ */
+export declare function findOutboxExecutionTransaction(messagePosition: BigNumber, l2Provider: ethers.providers.Provider, l1Provider: ethers.providers.Provider, options: {
+    fromBlock: number;
+    toBlock?: number;
+    chunkSize?: number;
+}): Promise<{
+    hash: string;
+    blockNumber: number;
+} | undefined>;
+/**
+ * Extract all message positions from L2ToL1Tx events in a transaction receipt.
+ * The position uniquely identifies each message for matching on L1 OutBox execution.
+ */
+export declare function getAllMessagePositionsFromReceipt(receipt: ethers.providers.TransactionReceipt): BigNumber[];
+/**
+ * Result from L2→L1 message stage tracking.
+ */
+export interface L2ToL1MessageResult {
+    stage: TrackedStage;
+    messages: ChildToParentMessageReader[];
+    messagePosition?: BigNumber;
+    messagePositions: BigNumber[];
+    l2ExecutionBlock?: number;
+    isConfirmed: boolean;
+    isExecuted: boolean;
+    firstExecutableBlock?: number;
+    l1SearchFromBlock?: number;
+    /** OutBox execution transaction (contains L1 timelock CallScheduled event) */
+    outboxExecutionTx?: {
+        hash: string;
+        blockNumber: number;
+    };
+}
+/**
+ * Track L2→L1 message stage (Stage 5)
+ *
+ * Unified tracking of L2→L1 message lifecycle with status:
+ * - NOT_STARTED: L2 timelock not executed or no messages found
+ * - PENDING: Message sent, in challenge period
+ * - READY: Challenge period complete, ready to execute outbox
+ * - COMPLETED: Outbox executed (message confirmed on L1)
+ * - SKIPPED: L2-only path
+ *
+ * Returns:
+ * - `l1SearchFromBlock` - earliest L1 block where OutBox execution could occur
+ * - `outboxExecutionTx` - the OutBox execution transaction (when status is COMPLETED)
+ *
+ * The OutBox execution transaction is important because it contains both:
+ * 1. The confirmation that the L2→L1 message was executed
+ * 2. The CallScheduled event for the L1 timelock operation
+ */
+export declare function trackL2ToL1Message(executionTxHash: string, l2Provider: ethers.providers.Provider, l1Provider: ethers.providers.Provider): Promise<L2ToL1MessageResult>;
+/**
+ * Options for preparing L2→L1 messages
+ */
+export interface OutboxPrepareOptions {
+    /** Force preparation even if stage is completed (for historical validation) */
+    force?: boolean;
+    /** Outbox contract address (resolved automatically if not provided) */
+    outboxAddress?: string;
+}
+/**
+ * Prepare an L2→L1 message for execution on L1.
+ *
+ * This generates the Merkle proof required for Outbox execution.
+ * The proof is based on current L2 state and should be used promptly.
+ */
+export declare function prepareL2ToL1Message(reader: ChildToParentMessageReaderNitro, l2Provider: ethers.providers.Provider, options?: OutboxPrepareOptions): Promise<PrepareResult>;
+/**
+ * Get all L2→L1 messages from a transaction
+ */
+export declare function getL2ToL1Messages(l2TxHash: string, l2Provider: ethers.providers.Provider, l1Provider: ethers.providers.Provider): Promise<ChildToParentMessageReader[]>;
+/**
+ * Prepare all L2→L1 messages from a stage for execution.
+ *
+ * Note: This uses internal SDK types. For simpler usage, consumers can use
+ * the SDK's ChildToParentMessageWriter.execute() method directly.
+ */
+export declare function prepareL2ToL1MessageStage(stage: TrackedStage, l2Provider: ethers.providers.Provider, l1Provider: ethers.providers.Provider, options?: OutboxPrepareOptions): Promise<SimpleBulkResult>;
+export { ChildToParentMessageReader, ChildToParentMessageStatus };
+//# sourceMappingURL=l2-to-l1-message.d.ts.map

package/dist/stages/l2-to-l1-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"l2-to-l1-message.d.ts","sourceRoot":"","sources":["../../src/stages/l2-to-l1-message.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAG3B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,+BAA+B,EAAE,MAAM,0DAA0D,CAAC;AAC3G,OAAO,EAAE,YAAY,EAAa,aAAa,EAAgB,MAAM,UAAU,CAAC;AAShF,OAAO,EAGL,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAQhC;;;;;;;GAOG;AACH,wBAAsB,8BAA8B,CAClD,eAAe,EAAE,SAAS,EAC1B,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACrC,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACrC,OAAO,EAAE;IACP,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAmE5D;AAED;;;GAGG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,kBAAkB,GAC3C,SAAS,EAAE,CAYb;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B,gBAAgB,EAAE,SAAS,EAAE,CAAC;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,kBAAkB,CACtC,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACrC,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,GACpC,OAAO,CAAC,mBAAmB,CAAC,CAqP9B;AAID;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,+BAA+B,EACvC,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACrC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,CAuDxB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACrC,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,GACpC,OAAO,CAAC,0BAA0B,EAAE,CAAC,CAQvC;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACrC,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACrC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,gBAAgB,CAAC,CA+B3B;AAGD,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/stages/l2-to-l1-message.js

@@ -0,0 +1,422 @@
+"use strict";
+/**
+ * L2 to L1 Message Stage Tracking and Preparation
+ *
+ * Stage 5: L2_TO_L1_MESSAGE - Unified cross-chain message tracking
+ *
+ * Status semantics:
+ * - NOT_STARTED: No L2→L1 messages found or L2 timelock not executed
+ * - PENDING: Message sent, in challenge period
+ * - READY: Challenge period complete, ready to execute outbox
+ * - COMPLETED: Outbox executed (message confirmed on L1)
+ * - SKIPPED: L2-only path (Treasury Governor)
+ *
+ * Uses @arbitrum/sdk v4 for cross-chain message tracking.
+ * Includes preparation functions for outbox execution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChildToParentMessageStatus = exports.ChildToParentMessageReader = void 0;
+exports.findOutboxExecutionTransaction = findOutboxExecutionTransaction;
+exports.getAllMessagePositionsFromReceipt = getAllMessagePositionsFromReceipt;
+exports.trackL2ToL1Message = trackL2ToL1Message;
+exports.prepareL2ToL1Message = prepareL2ToL1Message;
+exports.getL2ToL1Messages = getL2ToL1Messages;
+exports.prepareL2ToL1MessageStage = prepareL2ToL1MessageStage;
+const ethers_1 = require("ethers");
+const sdk_1 = require("@arbitrum/sdk");
+Object.defineProperty(exports, "ChildToParentMessageStatus", { enumerable: true, get: function () { return sdk_1.ChildToParentMessageStatus; } });
+Object.defineProperty(exports, "ChildToParentMessageReader", { enumerable: true, get: function () { return sdk_1.ChildToParentMessageReader; } });
+const types_1 = require("../types");
+const constants_1 = require("../constants");
+const logger_1 = require("../utils/logger");
+const logStage = logger_1.loggers.stage.l2ToL1;
+const logExecution = logger_1.loggers.execution;
+const base_1 = require("./base");
+const stage_builder_1 = require("./stage-builder");
+const rpc_utils_1 = require("../utils/rpc-utils");
+const stage_helpers_1 = require("../utils/stage-helpers");
+const log_search_1 = require("../utils/log-search");
+const log_filters_1 = require("../utils/log-filters");
+const timing_1 = require("../utils/timing");
+const abis_1 = require("../abis");
+const ARB_SYS_ADDRESS = constants_1.ADDRESSES.ARB_SYS;
+/**
+ * Find the L1 transaction that executed the L2→L1 message (OutBox execution).
+ * Uses the message position to match OutBoxTransactionExecuted events.
+ *
+ * This transaction is important because:
+ * 1. It confirms the L2→L1 message was executed
+ * 2. It contains the CallScheduled event for the L1 timelock operation
+ */
+async function findOutboxExecutionTransaction(messagePosition, l2Provider, l1Provider, options) {
+    const { blockNumber: currentBlock } = await (0, timing_1.getCurrentBlockInfo)(l1Provider);
+    // Get the Outbox address from Arbitrum network config
+    let outboxAddress;
+    try {
+        const network = await (0, sdk_1.getArbitrumNetwork)(l2Provider);
+        outboxAddress = network.ethBridge.outbox;
+    }
+    catch {
+        outboxAddress = constants_1.ADDRESSES.ARB1_OUTBOX;
+    }
+    const executedTopic = abis_1.outboxInterface.getEventTopic("OutBoxTransactionExecuted");
+    // Filter by destination = L1 Timelock (indexed)
+    const toTopic = ethers_1.ethers.utils.hexZeroPad(constants_1.ADDRESSES.L1_TIMELOCK.toLowerCase(), 32);
+    const fromBlock = options.fromBlock;
+    const toBlock = options.toBlock ?? currentBlock;
+    logStage("searching for OutBox execution: position=%s fromBlock=%d toBlock=%d", messagePosition.toString(), fromBlock, toBlock);
+    const result = await (0, log_search_1.searchLogsInChunks)(l1Provider, {
+        address: outboxAddress,
+        topics: [executedTopic, toTopic],
+        fromBlock,
+        toBlock,
+    }, {
+        chunkSize: options.chunkSize ?? 1000,
+        delayBetweenChunks: 100,
+        earlyExitCheck: (chunkLogs) => {
+            for (const log of chunkLogs) {
+                try {
+                    const parsed = abis_1.outboxInterface.parseLog(log);
+                    if (parsed.args.transactionIndex.eq(messagePosition)) {
+                        return log;
+                    }
+                }
+                catch {
+                    // Continue to next log
+                }
+            }
+            return undefined;
+        },
+    });
+    if (result.matchedLog) {
+        logStage("found OutBox execution tx=%s block=%d", result.matchedLog.transactionHash, result.matchedLog.blockNumber);
+        return {
+            hash: result.matchedLog.transactionHash,
+            blockNumber: result.matchedLog.blockNumber,
+        };
+    }
+    return undefined;
+}
+/**
+ * Extract all message positions from L2ToL1Tx events in a transaction receipt.
+ * The position uniquely identifies each message for matching on L1 OutBox execution.
+ */
+function getAllMessagePositionsFromReceipt(receipt) {
+    const l2ToL1TxTopic = abis_1.arbSysInterface.getEventTopic("L2ToL1Tx");
+    const matchingLogs = (0, log_filters_1.filterLogs)(receipt.logs, {
+        topic: l2ToL1TxTopic,
+        address: ARB_SYS_ADDRESS,
+    });
+    return (0, log_filters_1.parseLogsSafe)(matchingLogs, (log) => {
+        const parsed = abis_1.arbSysInterface.parseLog(log);
+        return parsed.args.position;
+    });
+}
+/**
+ * Track L2→L1 message stage (Stage 5)
+ *
+ * Unified tracking of L2→L1 message lifecycle with status:
+ * - NOT_STARTED: L2 timelock not executed or no messages found
+ * - PENDING: Message sent, in challenge period
+ * - READY: Challenge period complete, ready to execute outbox
+ * - COMPLETED: Outbox executed (message confirmed on L1)
+ * - SKIPPED: L2-only path
+ *
+ * Returns:
+ * - `l1SearchFromBlock` - earliest L1 block where OutBox execution could occur
+ * - `outboxExecutionTx` - the OutBox execution transaction (when status is COMPLETED)
+ *
+ * The OutBox execution transaction is important because it contains both:
+ * 1. The confirmation that the L2→L1 message was executed
+ * 2. The CallScheduled event for the L1 timelock operation
+ */
+async function trackL2ToL1Message(executionTxHash, l2Provider, l1Provider) {
+    const builder = new stage_builder_1.StageBuilder("L2_TO_L1_MESSAGE", "L2");
+    if (!executionTxHash) {
+        return {
+            stage: builder.status("NOT_STARTED").build(),
+            messages: [],
+            messagePositions: [],
+            isConfirmed: false,
+            isExecuted: false,
+        };
+    }
+    // Get transaction receipt
+    const receipt = await (0, rpc_utils_1.queryWithRetry)(() => l2Provider.getTransactionReceipt(executionTxHash));
+    if (!receipt) {
+        return {
+            stage: builder
+                .status("NOT_STARTED")
+                .data({ reason: "Transaction receipt not found" })
+                .build(),
+            messages: [],
+            messagePositions: [],
+            isConfirmed: false,
+            isExecuted: false,
+        };
+    }
+    // Extract all message positions for L1 matching
+    const messagePositions = getAllMessagePositionsFromReceipt(receipt);
+    const messagePosition = messagePositions[0];
+    const l2ExecutionBlock = receipt.blockNumber;
+    // Wrap receipt for Arbitrum SDK v4
+    const childReceipt = new sdk_1.ChildTransactionReceipt(receipt);
+    // Get L2→L1 messages from the receipt
+    const messages = await childReceipt.getChildToParentMessages(l1Provider);
+    if (messages.length === 0) {
+        // No L2→L1 messages - this path doesn't go through L1
+        return {
+            stage: builder.skip("No L2→L1 messages in transaction").build(),
+            messages: [],
+            messagePositions: [],
+            isConfirmed: false,
+            isExecuted: false,
+        };
+    }
+    // Store the L2ToL1Tx event for downstream salt computation
+    const l2ToL1TxEvent = messages[0].nitroReader.event;
+    const l2Timestamp = await (0, base_1.getBlockTimestamp)(receipt.blockNumber, l2Provider);
+    // Add data about the messages
+    builder.data({
+        messageCount: messages.length,
+        l2Block: receipt.blockNumber,
+        l2TxHash: executionTxHash,
+        messagePositions: messagePositions.map((p) => p.toString()),
+        hasMultipleMessages: messages.length > 1,
+        l2ToL1TxEvent,
+    });
+    // Warn about multi-message limitation
+    if (messages.length > 1) {
+        logStage("WARNING: Multiple L2→L1 messages detected (%d messages). " +
+            "Only the first message's OutBox execution will be tracked for L1 timelock discovery. " +
+            "Downstream stages (L1 timelock, retryables) for messages 2-%d may not be fully tracked. ", messages.length, messages.length);
+    }
+    // Check status of ALL messages - they may have different states
+    const messageStatuses = [];
+    for (const message of messages) {
+        const status = await (0, rpc_utils_1.queryWithRetry)(() => message.status(l2Provider));
+        messageStatuses.push(status);
+    }
+    const { blockNumber: currentL1Block, timestamp: currentTimestamp } = await (0, timing_1.getCurrentBlockInfo)(l1Provider);
+    // Determine aggregate status based on all messages
+    const allExecuted = messageStatuses.every((s) => s === sdk_1.ChildToParentMessageStatus.EXECUTED);
+    const anyUnconfirmed = messageStatuses.some((s) => s === sdk_1.ChildToParentMessageStatus.UNCONFIRMED);
+    const allConfirmedOrExecuted = messageStatuses.every((s) => s === sdk_1.ChildToParentMessageStatus.CONFIRMED || s === sdk_1.ChildToParentMessageStatus.EXECUTED);
+    let aggregateStatus;
+    if (allExecuted) {
+        aggregateStatus = sdk_1.ChildToParentMessageStatus.EXECUTED;
+    }
+    else if (anyUnconfirmed) {
+        aggregateStatus = sdk_1.ChildToParentMessageStatus.UNCONFIRMED;
+    }
+    else if (allConfirmedOrExecuted) {
+        aggregateStatus = sdk_1.ChildToParentMessageStatus.CONFIRMED;
+    }
+    else {
+        aggregateStatus = messageStatuses[0];
+    }
+    // Get first executable block from unconfirmed messages
+    let firstExecutableBlock;
+    if (anyUnconfirmed) {
+        for (let i = 0; i < messages.length; i++) {
+            if (messageStatuses[i] === sdk_1.ChildToParentMessageStatus.UNCONFIRMED) {
+                try {
+                    const blockBN = await (0, rpc_utils_1.queryWithRetry)(() => messages[i].getFirstExecutableBlock(l2Provider));
+                    if (blockBN) {
+                        const blockNum = blockBN.toNumber();
+                        if (!firstExecutableBlock || blockNum < firstExecutableBlock) {
+                            firstExecutableBlock = blockNum;
+                        }
+                    }
+                }
+                catch (err) {
+                    // Log the error to help distinguish RPC failures from "not available yet"
+                    logStage("Warning: failed to get first executable block for message %d: %s", i, err instanceof Error ? err.message : String(err));
+                }
+            }
+        }
+    }
+    // Build per-message status details
+    const messageDetails = messageStatuses.map((status, i) => ({
+        index: i,
+        status: sdk_1.ChildToParentMessageStatus[status],
+    }));
+    builder.data({
+        status: sdk_1.ChildToParentMessageStatus[aggregateStatus],
+        messageDetails,
+        firstExecutableBlock,
+        currentL1Block,
+    });
+    // Calculate L1 search block for OutBox execution
+    const l1BlockAtL2Execution = await (0, timing_1.getL1BlockForL2Block)(l2Provider, l2ExecutionBlock);
+    let l1SearchFromBlock = l1BlockAtL2Execution + constants_1.TIMING.CHALLENGE_PERIOD_BLOCKS_L1;
+    // Use firstExecutableBlock if more accurate
+    if (firstExecutableBlock && firstExecutableBlock <= currentL1Block) {
+        l1SearchFromBlock = firstExecutableBlock;
+        logStage("L1 search hint from firstExecutableBlock=%d", firstExecutableBlock);
+    }
+    let outboxExecutionTx;
+    switch (aggregateStatus) {
+        case sdk_1.ChildToParentMessageStatus.CONFIRMED:
+            // Challenge period complete, ready to execute
+            builder
+                .status("READY")
+                .tx(executionTxHash, receipt.blockNumber, "L2", {
+                timestamp: l2Timestamp,
+                description: "L2 sent",
+            })
+                .timing({ startedAt: l2Timestamp });
+            break;
+        case sdk_1.ChildToParentMessageStatus.EXECUTED:
+            // Already executed - find the OutBox execution transaction
+            builder.status("COMPLETED").tx(executionTxHash, receipt.blockNumber, "L2", {
+                timestamp: l2Timestamp,
+                description: "L2 sent",
+            });
+            if (messagePosition) {
+                if (messages.length > 1) {
+                    logStage("WARNING: Finding OutBox execution for first message only (position=%s). " +
+                        "%d additional messages have separate OutBox executions that will not be tracked.", messagePosition.toString(), messages.length - 1);
+                }
+                outboxExecutionTx = await findOutboxExecutionTransaction(messagePosition, l2Provider, l1Provider, { fromBlock: l1SearchFromBlock });
+                if (outboxExecutionTx) {
+                    const timestamp = await (0, base_1.getBlockTimestamp)(outboxExecutionTx.blockNumber, l1Provider);
+                    builder
+                        .tx(outboxExecutionTx.hash, outboxExecutionTx.blockNumber, "L1", {
+                        timestamp,
+                        description: "L1 confirmed",
+                    })
+                        .timing({ startedAt: l2Timestamp });
+                }
+            }
+            break;
+        case sdk_1.ChildToParentMessageStatus.UNCONFIRMED:
+            // Still in challenge period
+            builder.status("PENDING").tx(executionTxHash, receipt.blockNumber, "L2", {
+                timestamp: l2Timestamp,
+                description: "L2 sent",
+            });
+            if (firstExecutableBlock) {
+                // Ensure remaining time is non-negative (message may already be executable)
+                const remainingBlocks = Math.max(0, firstExecutableBlock - currentL1Block);
+                const remainingSeconds = remainingBlocks * constants_1.BLOCK_TIMES.L1;
+                builder.timing({
+                    startedAt: l2Timestamp,
+                    eta: remainingSeconds > 0 ? currentTimestamp + remainingSeconds : undefined,
+                    delaySeconds: remainingSeconds,
+                });
+            }
+            else {
+                builder.timing({
+                    startedAt: l2Timestamp,
+                    delaySeconds: constants_1.TIMING.CHALLENGE_PERIOD_BLOCKS_L1 * constants_1.BLOCK_TIMES.L1,
+                });
+            }
+            break;
+        default:
+            builder.status("NOT_STARTED");
+    }
+    return {
+        stage: builder.build(),
+        messages,
+        messagePosition,
+        messagePositions,
+        l2ExecutionBlock,
+        isConfirmed: aggregateStatus === sdk_1.ChildToParentMessageStatus.CONFIRMED,
+        isExecuted: allExecuted,
+        firstExecutableBlock,
+        l1SearchFromBlock,
+        outboxExecutionTx,
+    };
+}
+/**
+ * Prepare an L2→L1 message for execution on L1.
+ *
+ * This generates the Merkle proof required for Outbox execution.
+ * The proof is based on current L2 state and should be used promptly.
+ */
+async function prepareL2ToL1Message(reader, l2Provider, options = {}) {
+    logExecution("Preparing L2→L1 message execution");
+    const status = await (0, rpc_utils_1.queryWithRetry)(() => reader.status(l2Provider));
+    logExecution("Message status: %s", sdk_1.ChildToParentMessageStatus[status]);
+    // Skip state check if force=true for historical validation
+    if (!options.force) {
+        if (status === sdk_1.ChildToParentMessageStatus.EXECUTED) {
+            return (0, base_1.failPrepare)("Message already executed");
+        }
+        if (status !== sdk_1.ChildToParentMessageStatus.CONFIRMED) {
+            return (0, base_1.failPrepare)(`Message not ready. Status: ${sdk_1.ChildToParentMessageStatus[status]}, expected: CONFIRMED`);
+        }
+    }
+    // Get the outbox proof - this is the expensive part
+    logExecution("Generating outbox proof...");
+    const proof = await reader.getOutboxProof(l2Provider);
+    // Access event data from the Nitro reader
+    const event = reader.event;
+    // Get outbox address from options or fall back to default
+    const outboxAddress = options.outboxAddress ?? constants_1.ADDRESSES.ARB1_OUTBOX;
+    if (!outboxAddress) {
+        return (0, base_1.failPrepare)("Could not determine outbox address");
+    }
+    // Encode the executeTransaction call
+    const calldata = abis_1.outboxExecuteInterface.encodeFunctionData("executeTransaction", [
+        proof,
+        event.position,
+        event.caller,
+        event.destination,
+        event.arbBlockNum,
+        event.ethBlockNum,
+        event.timestamp,
+        event.callvalue,
+        event.data,
+    ]);
+    return {
+        success: true,
+        prepared: {
+            to: outboxAddress,
+            data: calldata,
+            value: "0",
+            chain: "L1",
+            description: `Execute L2→L1 message #${event.position.toString()} via Outbox`,
+        },
+    };
+}
+/**
+ * Get all L2→L1 messages from a transaction
+ */
+async function getL2ToL1Messages(l2TxHash, l2Provider, l1Provider) {
+    const receipt = await (0, rpc_utils_1.queryWithRetry)(() => l2Provider.getTransactionReceipt(l2TxHash));
+    if (!receipt) {
+        return [];
+    }
+    const childReceipt = new sdk_1.ChildTransactionReceipt(receipt);
+    return childReceipt.getChildToParentMessages(l1Provider);
+}
+/**
+ * Prepare all L2→L1 messages from a stage for execution.
+ *
+ * Note: This uses internal SDK types. For simpler usage, consumers can use
+ * the SDK's ChildToParentMessageWriter.execute() method directly.
+ */
+async function prepareL2ToL1MessageStage(stage, l2Provider, l1Provider, options = {}) {
+    const validationError = (0, stage_helpers_1.validateStageForSimpleBulk)(stage, { force: options.force });
+    if (validationError)
+        return validationError;
+    const stageData = (0, types_1.getStageData)(stage, "L2_TO_L1_MESSAGE");
+    if (!stageData?.l2TxHash)
+        return (0, stage_helpers_1.simpleBulkError)("L2 transaction hash not found");
+    const readers = await getL2ToL1Messages(stageData.l2TxHash, l2Provider, l1Provider);
+    if (readers.length === 0)
+        return (0, stage_helpers_1.simpleBulkError)("No L2→L1 messages found");
+    // Resolve outbox address
+    let outboxAddress = options.outboxAddress;
+    if (!outboxAddress) {
+        const network = await (0, sdk_1.getArbitrumNetwork)(l2Provider);
+        outboxAddress = network.ethBridge.outbox;
+    }
+    logExecution("Preparing %d L2→L1 messages", readers.length);
+    const prepareOptions = { ...options, outboxAddress };
+    const results = await Promise.all(readers.map((reader) => prepareL2ToL1Message(reader.nitroReader, l2Provider, prepareOptions)));
+    return { total: readers.length, results };
+}
+//# sourceMappingURL=l2-to-l1-message.js.map

package/dist/stages/l2-to-l1-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"l2-to-l1-message.js","sourceRoot":"","sources":["../../src/stages/l2-to-l1-message.ts"],"names":[],"mappings":"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"}

package/dist/stages/proposal-created.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Proposal Created Stage Tracking
+ *
+ * Stage 1: Track ProposalCreated event from Governor contract
+ */
+import { ethers } from "ethers";
+import { ProposalData, TrackedStage } from "../types";
+/**
+ * Track proposal creation stage
+ *
+ * Entry point: Governor address + proposalId or creationTxHash
+ */
+export declare function trackProposalCreated(governorAddress: string, proposalId: string, provider: ethers.providers.Provider, options?: {
+    creationTxHash?: string;
+    fromBlock?: number;
+}): Promise<{
+    stage: TrackedStage;
+    proposalData: ProposalData | null;
+}>;
+//# sourceMappingURL=proposal-created.d.ts.map

package/dist/stages/proposal-created.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-created.d.ts","sourceRoot":"","sources":["../../src/stages/proposal-created.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAUtD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACnC,OAAO,GAAE;IACP,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC;IACT,KAAK,EAAE,YAAY,CAAC;IACpB,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;CACnC,CAAC,CAiDD"}

package/dist/stages/proposal-created.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Proposal Created Stage Tracking
+ *
+ * Stage 1: Track ProposalCreated event from Governor contract
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackProposalCreated = trackProposalCreated;
+const constants_1 = require("../constants");
+const governor_discovery_1 = require("../discovery/governor-discovery");
+const base_1 = require("./base");
+const stage_builder_1 = require("./stage-builder");
+/**
+ * Track proposal creation stage
+ *
+ * Entry point: Governor address + proposalId or creationTxHash
+ */
+async function trackProposalCreated(governorAddress, proposalId, provider, options = {}) {
+    const builder = new stage_builder_1.StageBuilder("PROPOSAL_CREATED", "L2");
+    // Detect governor type
+    const proposalType = (0, governor_discovery_1.detectProposalType)(governorAddress);
+    builder.data({ proposalType });
+    // Try to find proposal data
+    let proposalData = null;
+    // Fast path: use creation tx hash if provided
+    if (options.creationTxHash) {
+        proposalData = await (0, governor_discovery_1.findProposalByTxHash)(options.creationTxHash, provider);
+    }
+    // Fallback: search for ProposalCreated event
+    if (!proposalData) {
+        proposalData = await (0, governor_discovery_1.findProposalCreatedEvent)(governorAddress, proposalId, provider, {
+            startBlock: options.fromBlock ?? constants_1.GOVERNANCE_START_BLOCKS.L2,
+        });
+    }
+    if (proposalData) {
+        // Stage completed - proposal was created
+        const valuesArray = Array.from(proposalData.values);
+        const timestamp = await (0, base_1.getBlockTimestamp)(proposalData.creationBlock, provider);
+        builder
+            .status("COMPLETED")
+            .tx(proposalData.creationTxHash, proposalData.creationBlock, "L2", { timestamp })
+            .timing({ startedAt: timestamp })
+            .data({
+            proposalId: proposalData.proposalId,
+            proposer: proposalData.proposer,
+            description: proposalData.description,
+            startBlock: proposalData.startBlock.toString(),
+            endBlock: proposalData.endBlock.toString(),
+            targetCount: proposalData.targets.length,
+            targets: proposalData.targets,
+            values: valuesArray.map((v) => v.toString()),
+            signatures: proposalData.signatures,
+            calldatas: proposalData.calldatas,
+        });
+    }
+    else {
+        // Proposal not found - either not created yet or invalid
+        builder.status("NOT_STARTED");
+    }
+    return { stage: builder.build(), proposalData };
+}
+//# sourceMappingURL=proposal-created.js.map

package/dist/stages/proposal-created.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-created.js","sourceRoot":"","sources":["../../src/stages/proposal-created.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAkBH,oDA4DC;AA1ED,4CAAuD;AACvD,wEAIyC;AACzC,iCAA2C;AAC3C,mDAA+C;AAE/C;;;;GAIG;AACI,KAAK,UAAU,oBAAoB,CACxC,eAAuB,EACvB,UAAkB,EAClB,QAAmC,EACnC,UAGI,EAAE;IAKN,MAAM,OAAO,GAAG,IAAI,4BAAY,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;IAE3D,uBAAuB;IACvB,MAAM,YAAY,GAAG,IAAA,uCAAkB,EAAC,eAAe,CAAC,CAAC;IACzD,OAAO,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC;IAE/B,4BAA4B;IAC5B,IAAI,YAAY,GAAwB,IAAI,CAAC;IAE7C,8CAA8C;IAC9C,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;QAC3B,YAAY,GAAG,MAAM,IAAA,yCAAoB,EAAC,OAAO,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IAC9E,CAAC;IAED,6CAA6C;IAC7C,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,YAAY,GAAG,MAAM,IAAA,6CAAwB,EAAC,eAAe,EAAE,UAAU,EAAE,QAAQ,EAAE;YACnF,UAAU,EAAE,OAAO,CAAC,SAAS,IAAI,mCAAuB,CAAC,EAAE;SAC5D,CAAC,CAAC;IACL,CAAC;IAED,IAAI,YAAY,EAAE,CAAC;QACjB,yCAAyC;QACzC,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QACpD,MAAM,SAAS,GAAG,MAAM,IAAA,wBAAiB,EAAC,YAAY,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;QAEhF,OAAO;aACJ,MAAM,CAAC,WAAW,CAAC;aACnB,EAAE,CAAC,YAAY,CAAC,cAAc,EAAE,YAAY,CAAC,aAAa,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,CAAC;aAChF,MAAM,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;aAChC,IAAI,CAAC;YACJ,UAAU,EAAE,YAAY,CAAC,UAAU;YACnC,QAAQ,EAAE,YAAY,CAAC,QAAQ;YAC/B,WAAW,EAAE,YAAY,CAAC,WAAW;YACrC,UAAU,EAAE,YAAY,CAAC,UAAU,CAAC,QAAQ,EAAE;YAC9C,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,QAAQ,EAAE;YAC1C,WAAW,EAAE,YAAY,CAAC,OAAO,CAAC,MAAM;YACxC,OAAO,EAAE,YAAY,CAAC,OAAO;YAC7B,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;YAC5C,UAAU,EAAE,YAAY,CAAC,UAAU;YACnC,SAAS,EAAE,YAAY,CAAC,SAAS;SAClC,CAAC,CAAC;IACP,CAAC;SAAM,CAAC;QACN,yDAAyD;QACzD,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAChC,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,YAAY,EAAE,CAAC;AAClD,CAAC"}