@gzeoneth/gov-tracker 0.1.0

package/dist/utils/salt-computation.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Salt Computation for Timelock Operations
+ *
+ * Centralized salt computation logic for different proposal types.
+ * Salt is computed during tracking and cached in stage data.
+ */
+import { ethers, BigNumber } from "ethers";
+import { TrackedStage } from "../types";
+/**
+ * Derive salt from a proposal description (Governor pattern)
+ *
+ * The Governor contract uses `keccak256(bytes(description))` as the salt
+ * In Solidity, bytes(string) converts to UTF-8 bytes, which is equivalent to id()
+ */
+export declare function saltFromDescription(description: string): string;
+/**
+ * Generate salt for a Security Council member update using on-chain contract
+ *
+ * Calls SecurityCouncilManager.generateSalt() for 100% accuracy.
+ *
+ * Security Council uses `keccak256(abi.encode(newMembers, nonce))`
+ */
+export declare function generateSecurityCouncilSalt(members: string[], nonce: BigNumber, provider: ethers.providers.Provider): Promise<string>;
+/**
+ * Decoded L1 timelock schedule call parameters
+ */
+export type DecodedTimelockSchedule = {
+    type: "single";
+    target: string;
+    value: BigNumber;
+    data: string;
+    predecessor: string;
+    salt: string;
+    delay: BigNumber;
+} | {
+    type: "batch";
+    targets: string[];
+    values: BigNumber[];
+    payloads: string[];
+    predecessor: string;
+    salt: string;
+    delay: BigNumber;
+};
+/**
+ * Decode L1 timelock schedule call from L2ToL1Tx event data
+ *
+ * Extracts the actual schedule/scheduleBatch parameters that were sent to L1.
+ * This is the ground truth for what was scheduled on L1 timelock.
+ *
+ * @param l2ToL1TxData - The `data` field from L2ToL1Tx event
+ * @returns Decoded schedule parameters or null if not a timelock schedule call
+ */
+export declare function decodeL1TimelockSchedule(l2ToL1TxData: string): DecodedTimelockSchedule | null;
+/**
+ * Compute salt for L2 timelock stage
+ *
+ * Priority:
+ * 1. Security Council: use on-chain generateSalt(members, nonce)
+ * 2. Governor: use keccak256(description)
+ * 3. Fallback: HashZero
+ */
+export declare function computeL2TimelockSalt(stageData: {
+    isSecurityCouncilOperation?: boolean;
+    securityCouncilMembers?: string[];
+    securityCouncilNonce?: string | number | BigNumber;
+}, allStages?: TrackedStage[], provider?: ethers.providers.Provider): Promise<string>;
+/**
+ * Compute salt for L1 timelock stage
+ *
+ * Priority:
+ * 1. Decoded from L2→L1 message event (100% accurate - this is the actual salt sent)
+ * 2. Fallback: HashZero
+ */
+export declare function computeL1TimelockSalt(allStages?: TrackedStage[]): {
+    salt: string;
+    predecessor?: string;
+};
+//# sourceMappingURL=salt-computation.d.ts.map

package/dist/utils/salt-computation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"salt-computation.d.ts","sourceRoot":"","sources":["../../src/utils/salt-computation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAKxC;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,GAClC,OAAO,CAAC,MAAM,CAAC,CASjB;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAC/B;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;CAClB,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;CAClB,CAAC;AAEN;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,GAAG,uBAAuB,GAAG,IAAI,CA4B7F;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE;IACT,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,oBAAoB,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACpD,EACD,SAAS,CAAC,EAAE,YAAY,EAAE,EAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,GACnC,OAAO,CAAC,MAAM,CAAC,CA2BjB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,YAAY,EAAE,GAAG;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAiBA"}

package/dist/utils/salt-computation.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * Salt Computation for Timelock Operations
+ *
+ * Centralized salt computation logic for different proposal types.
+ * Salt is computed during tracking and cached in stage data.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saltFromDescription = saltFromDescription;
+exports.generateSecurityCouncilSalt = generateSecurityCouncilSalt;
+exports.decodeL1TimelockSchedule = decodeL1TimelockSchedule;
+exports.computeL2TimelockSalt = computeL2TimelockSalt;
+exports.computeL1TimelockSalt = computeL1TimelockSalt;
+const ethers_1 = require("ethers");
+const abis_1 = require("../abis");
+const constants_1 = require("../constants");
+const rpc_utils_1 = require("./rpc-utils");
+/**
+ * Derive salt from a proposal description (Governor pattern)
+ *
+ * The Governor contract uses `keccak256(bytes(description))` as the salt
+ * In Solidity, bytes(string) converts to UTF-8 bytes, which is equivalent to id()
+ */
+function saltFromDescription(description) {
+    return ethers_1.ethers.utils.id(description);
+}
+/**
+ * Generate salt for a Security Council member update using on-chain contract
+ *
+ * Calls SecurityCouncilManager.generateSalt() for 100% accuracy.
+ *
+ * Security Council uses `keccak256(abi.encode(newMembers, nonce))`
+ */
+async function generateSecurityCouncilSalt(members, nonce, provider) {
+    const manager = new ethers_1.ethers.Contract(constants_1.ADDRESSES.SECURITY_COUNCIL_MANAGER, abis_1.SECURITY_COUNCIL_MANAGER_ABI, provider);
+    // Use contract's generateSalt function for consistency
+    return await (0, rpc_utils_1.queryWithRetry)(() => manager.generateSalt(members, nonce));
+}
+/**
+ * Decode L1 timelock schedule call from L2ToL1Tx event data
+ *
+ * Extracts the actual schedule/scheduleBatch parameters that were sent to L1.
+ * This is the ground truth for what was scheduled on L1 timelock.
+ *
+ * @param l2ToL1TxData - The `data` field from L2ToL1Tx event
+ * @returns Decoded schedule parameters or null if not a timelock schedule call
+ */
+function decodeL1TimelockSchedule(l2ToL1TxData) {
+    const timelockInterface = new ethers_1.ethers.utils.Interface(abis_1.TIMELOCK_ABI);
+    // Try to decode as scheduleBatch first
+    try {
+        const batch = timelockInterface.decodeFunctionData("scheduleBatch", l2ToL1TxData);
+        return {
+            type: "batch",
+            targets: batch[0],
+            values: batch[1],
+            payloads: batch[2],
+            predecessor: batch[3],
+            salt: batch[4],
+            delay: batch[5],
+        };
+    }
+    catch {
+        // Not a batch, try single schedule
+        const single = timelockInterface.decodeFunctionData("schedule", l2ToL1TxData);
+        return {
+            type: "single",
+            target: single[0],
+            value: single[1],
+            data: single[2],
+            predecessor: single[3],
+            salt: single[4],
+            delay: single[5],
+        };
+    }
+}
+/**
+ * Compute salt for L2 timelock stage
+ *
+ * Priority:
+ * 1. Security Council: use on-chain generateSalt(members, nonce)
+ * 2. Governor: use keccak256(description)
+ * 3. Fallback: HashZero
+ */
+async function computeL2TimelockSalt(stageData, allStages, provider) {
+    // Priority 1: Security Council operation
+    if (stageData.isSecurityCouncilOperation &&
+        stageData.securityCouncilMembers &&
+        stageData.securityCouncilNonce !== undefined &&
+        provider) {
+        const members = stageData.securityCouncilMembers;
+        const nonce = ethers_1.BigNumber.isBigNumber(stageData.securityCouncilNonce)
+            ? stageData.securityCouncilNonce
+            : ethers_1.BigNumber.from(stageData.securityCouncilNonce);
+        // Use on-chain generation for maximum accuracy
+        return await generateSecurityCouncilSalt(members, nonce, provider);
+    }
+    // Priority 2: Governor proposal with description
+    if (allStages) {
+        const proposalStage = allStages.find((s) => s.type === "PROPOSAL_CREATED");
+        if (proposalStage?.data.description) {
+            return saltFromDescription(proposalStage.data.description);
+        }
+    }
+    // Priority 3: HashZero fallback
+    return ethers_1.ethers.constants.HashZero;
+}
+/**
+ * Compute salt for L1 timelock stage
+ *
+ * Priority:
+ * 1. Decoded from L2→L1 message event (100% accurate - this is the actual salt sent)
+ * 2. Fallback: HashZero
+ */
+function computeL1TimelockSalt(allStages) {
+    if (allStages) {
+        const l2ToL1Stage = allStages.find((s) => s.type === "L2_TO_L1_MESSAGE");
+        if (l2ToL1Stage?.data.l2ToL1TxEvent) {
+            // Decode salt and predecessor from the L2ToL1Tx event data
+            const decoded = decodeL1TimelockSchedule(l2ToL1Stage.data.l2ToL1TxEvent.data);
+            if (decoded) {
+                return {
+                    salt: decoded.salt,
+                    predecessor: decoded.predecessor,
+                };
+            }
+        }
+    }
+    // Fallback
+    return { salt: ethers_1.ethers.constants.HashZero };
+}
+//# sourceMappingURL=salt-computation.js.map

package/dist/utils/salt-computation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"salt-computation.js","sourceRoot":"","sources":["../../src/utils/salt-computation.ts"],"names":[],"mappings":"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"}

package/dist/utils/salt-resolver.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Salt Resolution for Timelock Execution
+ *
+ * Salt resolution hierarchy:
+ * 1. options.salt (explicit override)
+ * 2. stage.data.salt (cached from tracking)
+ * 3. Security Council: generateSalt(members, nonce)
+ * 4. Governor: keccak256(description)
+ * 5. HashZero (0x00...00) - last resort for operations that use default salt
+ * 6. FAIL - throw error if no salt matches the operation ID
+ *
+ * Each resolved salt is validated against the expected operation ID before use.
+ * If validation fails, the next option in the hierarchy is tried.
+ */
+import { ethers } from "ethers";
+import { PrepareOptions, TrackedStage } from "../types";
+import { saltFromDescription, saltForSecurityCouncil } from "../utils/operation-id";
+export { saltFromDescription, saltForSecurityCouncil };
+/**
+ * Resolved prepare options with required salt and predecessor
+ */
+export type ResolvedExecuteOptions = Required<Pick<PrepareOptions, "salt" | "predecessor">> & Omit<PrepareOptions, "salt" | "predecessor">;
+/**
+ * Candidate salts in priority order for validation
+ */
+export interface SaltCandidate {
+    salt: string;
+    source: "explicit" | "cached" | "security-council" | "description" | "hash-zero";
+}
+/**
+ * Get all candidate salts from a TrackedStage in priority order.
+ *
+ * Returns an array of salt candidates to try, in order of priority.
+ * The caller is responsible for validating each salt against the operation ID.
+ *
+ * @param stage - The stage being prepared (L2_TIMELOCK or L1_TIMELOCK)
+ * @param options - Preparation options (can include explicit salt override)
+ * @param provider - Provider for on-chain salt generation
+ * @param allStages - All tracked stages (used to extract context from other stages)
+ */
+export declare function getSaltCandidates(stage: TrackedStage, options?: PrepareOptions, provider?: ethers.providers.Provider, allStages?: TrackedStage[]): Promise<SaltCandidate[]>;
+/**
+ * Error thrown when salt cannot be resolved from available sources.
+ * This prevents silent failures that would cause mysterious on-chain errors.
+ */
+export declare class SaltResolutionError extends Error {
+    readonly attemptedSources: SaltCandidate["source"][];
+    readonly stageType: string;
+    constructor(message: string, attemptedSources: SaltCandidate["source"][], stageType: string);
+}
+/**
+ * Get prepare options with resolved salt for a stage.
+ *
+ * IMPORTANT: Throws SaltResolutionError if salt cannot be resolved from any source.
+ *
+ * @param stage - The stage being prepared
+ * @param options - Preparation options
+ * @param provider - Provider for on-chain operations
+ * @param allStages - All tracked stages (used to extract context)
+ * @throws {SaltResolutionError} if no salt can be resolved
+ */
+export declare function resolveExecuteOptionsForStage(stage: TrackedStage, options?: PrepareOptions, provider?: ethers.providers.Provider, allStages?: TrackedStage[]): Promise<ResolvedExecuteOptions>;
+//# sourceMappingURL=salt-resolver.d.ts.map

package/dist/utils/salt-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"salt-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/salt-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,EAAa,MAAM,QAAQ,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAgB,MAAM,UAAU,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAIpF,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,CAAC;AAEvD;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,GACzF,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,GAAG,QAAQ,GAAG,kBAAkB,GAAG,aAAa,GAAG,WAAW,CAAC;CAClF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,cAAmB,EAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACpC,SAAS,CAAC,EAAE,YAAY,EAAE,GACzB,OAAO,CAAC,aAAa,EAAE,CAAC,CAsE1B;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAG1B,gBAAgB,EAAE,aAAa,CAAC,QAAQ,CAAC,EAAE;aAC3C,SAAS,EAAE,MAAM;gBAFjC,OAAO,EAAE,MAAM,EACC,gBAAgB,EAAE,aAAa,CAAC,QAAQ,CAAC,EAAE,EAC3C,SAAS,EAAE,MAAM;CAKpC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,cAAmB,EAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACpC,SAAS,CAAC,EAAE,YAAY,EAAE,GACzB,OAAO,CAAC,sBAAsB,CAAC,CA4BjC"}

package/dist/utils/salt-resolver.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Salt Resolution for Timelock Execution
+ *
+ * Salt resolution hierarchy:
+ * 1. options.salt (explicit override)
+ * 2. stage.data.salt (cached from tracking)
+ * 3. Security Council: generateSalt(members, nonce)
+ * 4. Governor: keccak256(description)
+ * 5. HashZero (0x00...00) - last resort for operations that use default salt
+ * 6. FAIL - throw error if no salt matches the operation ID
+ *
+ * Each resolved salt is validated against the expected operation ID before use.
+ * If validation fails, the next option in the hierarchy is tried.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SaltResolutionError = exports.saltForSecurityCouncil = exports.saltFromDescription = void 0;
+exports.getSaltCandidates = getSaltCandidates;
+exports.resolveExecuteOptionsForStage = resolveExecuteOptionsForStage;
+const ethers_1 = require("ethers");
+const types_1 = require("../types");
+const operation_id_1 = require("../utils/operation-id");
+Object.defineProperty(exports, "saltFromDescription", { enumerable: true, get: function () { return operation_id_1.saltFromDescription; } });
+Object.defineProperty(exports, "saltForSecurityCouncil", { enumerable: true, get: function () { return operation_id_1.saltForSecurityCouncil; } });
+const security_council_1 = require("../discovery/security-council");
+/**
+ * Get all candidate salts from a TrackedStage in priority order.
+ *
+ * Returns an array of salt candidates to try, in order of priority.
+ * The caller is responsible for validating each salt against the operation ID.
+ *
+ * @param stage - The stage being prepared (L2_TIMELOCK or L1_TIMELOCK)
+ * @param options - Preparation options (can include explicit salt override)
+ * @param provider - Provider for on-chain salt generation
+ * @param allStages - All tracked stages (used to extract context from other stages)
+ */
+async function getSaltCandidates(stage, options = {}, provider, allStages) {
+    const candidates = [];
+    // 1. Explicit user override (highest priority)
+    if (options.salt) {
+        candidates.push({ salt: options.salt, source: "explicit" });
+    }
+    // Try to get typed stage data from any timelock stage type
+    const stageData = (0, types_1.getStageData)(stage, "L2_TIMELOCK") ?? (0, types_1.getStageData)(stage, "L1_TIMELOCK");
+    // 2. Cached salt from tracking
+    if (stageData?.salt) {
+        candidates.push({ salt: stageData.salt, source: "cached" });
+    }
+    // 3. Decoded salt from L2→L1 message (L1 timelock scheduling call)
+    // This is the actual salt that was sent to L1 - 100% accurate!
+    // This was decoded during L2_TO_L1_MESSAGE tracking and stored in stage data
+    if (allStages && stage.type === "L1_TIMELOCK") {
+        const l2ToL1Stage = allStages.find((s) => s.type === "L2_TO_L1_MESSAGE");
+        if (l2ToL1Stage) {
+            const l2ToL1Data = (0, types_1.getStageData)(l2ToL1Stage, "L2_TO_L1_MESSAGE");
+            if (l2ToL1Data?.l1TimelockSalt) {
+                candidates.push({ salt: l2ToL1Data.l1TimelockSalt, source: "cached" });
+                // Also use the decoded predecessor if available and not overridden
+                if (!options.predecessor && l2ToL1Data.l1TimelockPredecessor) {
+                    options.predecessor = l2ToL1Data.l1TimelockPredecessor;
+                }
+            }
+        }
+    }
+    // 4. Security Council: use on-chain generation
+    // Security Council data is enriched in L2_TIMELOCK stage during tracking
+    const members = stageData?.securityCouncilMembers;
+    const nonce = stageData?.securityCouncilNonce;
+    if (members?.length && nonce !== undefined) {
+        const nonceValue = ethers_1.BigNumber.isBigNumber(nonce) ? nonce : ethers_1.BigNumber.from(nonce);
+        try {
+            const scSalt = provider
+                ? await (0, security_council_1.generateSecurityCouncilSalt)(members, nonceValue, provider)
+                : (0, operation_id_1.saltForSecurityCouncil)(members, nonceValue);
+            candidates.push({ salt: scSalt, source: "security-council" });
+        }
+        catch {
+            // Skip if security council salt generation fails
+        }
+    }
+    // 5. Derive from proposal description
+    // Description is stored in PROPOSAL_CREATED stage, extract it if allStages provided
+    let description;
+    if (allStages) {
+        const proposalStage = allStages.find((s) => s.type === "PROPOSAL_CREATED");
+        if (proposalStage) {
+            const proposalData = (0, types_1.getStageData)(proposalStage, "PROPOSAL_CREATED");
+            description = proposalData?.description;
+        }
+    }
+    // Fallback to options or stage data (for backward compatibility)
+    description = description ?? options.description ?? stageData?.description;
+    if (description) {
+        candidates.push({ salt: (0, operation_id_1.saltFromDescription)(description), source: "description" });
+    }
+    // 6. HashZero as last resort
+    candidates.push({ salt: ethers_1.ethers.constants.HashZero, source: "hash-zero" });
+    return candidates;
+}
+/**
+ * Error thrown when salt cannot be resolved from available sources.
+ * This prevents silent failures that would cause mysterious on-chain errors.
+ */
+class SaltResolutionError extends Error {
+    constructor(message, attemptedSources, stageType) {
+        super(message);
+        this.attemptedSources = attemptedSources;
+        this.stageType = stageType;
+        this.name = "SaltResolutionError";
+    }
+}
+exports.SaltResolutionError = SaltResolutionError;
+/**
+ * Get prepare options with resolved salt for a stage.
+ *
+ * IMPORTANT: Throws SaltResolutionError if salt cannot be resolved from any source.
+ *
+ * @param stage - The stage being prepared
+ * @param options - Preparation options
+ * @param provider - Provider for on-chain operations
+ * @param allStages - All tracked stages (used to extract context)
+ * @throws {SaltResolutionError} if no salt can be resolved
+ */
+async function resolveExecuteOptionsForStage(stage, options = {}, provider, allStages) {
+    const candidates = await getSaltCandidates(stage, options, provider, allStages);
+    // If only HashZero is available, it means no actual salt source was found
+    // This should be an error because we don't know the correct salt
+    const hasActualSaltSource = candidates.some((c) => c.source !== "hash-zero");
+    if (!hasActualSaltSource) {
+        const attemptedSources = candidates.map((c) => c.source);
+        throw new SaltResolutionError(`Cannot resolve salt for stage ${stage.type}. ` +
+            `Attempted sources: ${attemptedSources.length > 0 ? attemptedSources.join(", ") : "none available"}. ` +
+            `Provide an explicit salt via options.salt or ensure stage.data contains the required salt source ` +
+            `(description for governor proposals, securityCouncilMembers+nonce for SC updates).`, attemptedSources, stage.type);
+    }
+    const resolvedSalt = candidates[0]?.salt ?? ethers_1.ethers.constants.HashZero;
+    return {
+        ...options,
+        salt: resolvedSalt,
+        predecessor: options.predecessor ?? ethers_1.ethers.constants.HashZero,
+        skipSaltValidation: options.skipSaltValidation ?? false,
+    };
+}
+//# sourceMappingURL=salt-resolver.js.map

package/dist/utils/salt-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"salt-resolver.js","sourceRoot":"","sources":["../../src/utils/salt-resolver.ts"],"names":[],"mappings":"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"}

package/dist/utils/scoped-logger.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Scoped Logger using AsyncLocalStorage
+ *
+ * Provides automatic context prefixing for concurrent operations.
+ * All log calls within a scope automatically include the scope prefix.
+ *
+ * Usage:
+ *   import { withScope, scopedLog } from "./scoped-logger";
+ *
+ *   // Create scoped logger
+ *   const log = scopedLog("gov-tracker:discovery");
+ *
+ *   // Run with scope - all nested logs get the prefix
+ *   await withScope("core-gov", async () => {
+ *     log("discovering..."); // outputs: [core-gov] discovering...
+ *     await nestedFunction(); // nested calls also get prefix
+ *   });
+ */
+/**
+ * Get current scope prefix, or empty string if not in a scope.
+ */
+export declare function getCurrentScope(): string;
+/**
+ * Run a function within a logging scope.
+ * All scopedLog calls within this function (and nested calls) will
+ * automatically include the scope prefix.
+ *
+ * Scopes can be nested - inner scopes override outer scopes.
+ */
+export declare function withScope<T>(prefix: string, fn: () => T): T;
+/**
+ * Create a scoped debug logger.
+ * Returns a function that automatically prepends the current scope.
+ *
+ * Unlike regular debug loggers, the scope is dynamically determined
+ * at call time using AsyncLocalStorage.
+ */
+export declare function scopedLog(namespace: string): (fmt: string, ...args: unknown[]) => void;
+/**
+ * Create multiple scoped loggers for common namespaces.
+ */
+export declare function createScopedLoggers<K extends string>(namespaces: Record<K, string>): Record<K, (fmt: string, ...args: unknown[]) => void>;
+//# sourceMappingURL=scoped-logger.d.ts.map

package/dist/utils/scoped-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-logger.d.ts","sourceRoot":"","sources":["../../src/utils/scoped-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAWH;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAQtF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAClD,UAAU,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,GAC5B,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC,CAMtD"}

package/dist/utils/scoped-logger.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Scoped Logger using AsyncLocalStorage
+ *
+ * Provides automatic context prefixing for concurrent operations.
+ * All log calls within a scope automatically include the scope prefix.
+ *
+ * Usage:
+ *   import { withScope, scopedLog } from "./scoped-logger";
+ *
+ *   // Create scoped logger
+ *   const log = scopedLog("gov-tracker:discovery");
+ *
+ *   // Run with scope - all nested logs get the prefix
+ *   await withScope("core-gov", async () => {
+ *     log("discovering..."); // outputs: [core-gov] discovering...
+ *     await nestedFunction(); // nested calls also get prefix
+ *   });
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrentScope = getCurrentScope;
+exports.withScope = withScope;
+exports.scopedLog = scopedLog;
+exports.createScopedLoggers = createScopedLoggers;
+const async_hooks_1 = require("async_hooks");
+const debug_1 = __importDefault(require("debug"));
+const scopeStorage = new async_hooks_1.AsyncLocalStorage();
+/**
+ * Get current scope prefix, or empty string if not in a scope.
+ */
+function getCurrentScope() {
+    return scopeStorage.getStore()?.prefix ?? "";
+}
+/**
+ * Run a function within a logging scope.
+ * All scopedLog calls within this function (and nested calls) will
+ * automatically include the scope prefix.
+ *
+ * Scopes can be nested - inner scopes override outer scopes.
+ */
+function withScope(prefix, fn) {
+    return scopeStorage.run({ prefix }, fn);
+}
+/**
+ * Create a scoped debug logger.
+ * Returns a function that automatically prepends the current scope.
+ *
+ * Unlike regular debug loggers, the scope is dynamically determined
+ * at call time using AsyncLocalStorage.
+ */
+function scopedLog(namespace) {
+    const baseLog = (0, debug_1.default)(namespace);
+    return (fmt, ...args) => {
+        const scope = getCurrentScope();
+        const prefix = scope ? `[${scope}] ` : "";
+        baseLog(prefix + fmt, ...args);
+    };
+}
+/**
+ * Create multiple scoped loggers for common namespaces.
+ */
+function createScopedLoggers(namespaces) {
+    const loggers = {};
+    for (const [key, ns] of Object.entries(namespaces)) {
+        loggers[key] = scopedLog(ns);
+    }
+    return loggers;
+}
+//# sourceMappingURL=scoped-logger.js.map

package/dist/utils/scoped-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoped-logger.js","sourceRoot":"","sources":["../../src/utils/scoped-logger.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;;;AAcH,0CAEC;AASD,8BAEC;AASD,8BAQC;AAKD,kDAQC;AAvDD,6CAAgD;AAChD,kDAAgC;AAMhC,MAAM,YAAY,GAAG,IAAI,+BAAiB,EAAY,CAAC;AAEvD;;GAEG;AACH,SAAgB,eAAe;IAC7B,OAAO,YAAY,CAAC,QAAQ,EAAE,EAAE,MAAM,IAAI,EAAE,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,SAAS,CAAI,MAAc,EAAE,EAAW;IACtD,OAAO,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,SAAiB;IACzC,MAAM,OAAO,GAAG,IAAA,eAAW,EAAC,SAAS,CAAC,CAAC;IAEvC,OAAO,CAAC,GAAW,EAAE,GAAG,IAAe,EAAE,EAAE;QACzC,MAAM,KAAK,GAAG,eAAe,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1C,OAAO,CAAC,MAAM,GAAG,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IACjC,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,mBAAmB,CACjC,UAA6B;IAE7B,MAAM,OAAO,GAAG,EAA0D,CAAC;IAC3E,KAAK,MAAM,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAkB,EAAE,CAAC;QACpE,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/utils/stage-helpers.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Stage Helpers
+ *
+ * Utility functions for timelock stage operations and validation.
+ */
+import { ethers } from "ethers";
+import { TrackedStage, PrepareResult, StageType, ChainType, CallScheduledData, TimelockState, OperationState } from "../types";
+export { serialize, deserialize, serializeCallScheduledData, deserializeCallScheduledData, serializeCallScheduledDataArray, deserializeCallScheduledDataArray, } from "../stages/base";
+/** Execution payload data for timelock operations. */
+export interface TimelockExecutionPayload {
+    timelockAddress: string;
+    operationId: string;
+    callScheduledData: CallScheduledData[];
+    isSecurityCouncilOperation?: boolean;
+    securityCouncilMembers?: string[];
+    securityCouncilNonce?: string;
+}
+/** Extract timelock execution payload from a stage. */
+export declare function createTimelockStageData(stage: TrackedStage): TimelockExecutionPayload | null;
+/** Collect all CallScheduledData from a timelock state. */
+export declare function collectAllScheduledData(timelockState: TimelockState): CallScheduledData[];
+/** Calculate ETA for a timelock operation. */
+export declare function calculateTimelockEta(timelockState: TimelockState, operationState: OperationState, provider: ethers.providers.Provider): Promise<number | undefined>;
+/** Build serialized execution payload data for stage storage. */
+export declare function buildExecutionPayloadData(timelockAddress: string, operationId: string, allScheduledData: CallScheduledData[]): Record<string, unknown>;
+export interface PrepareValidationOptions {
+    force?: boolean;
+    expectedTypes?: StageType[];
+}
+/** Validate stage for preparation. Returns error or null if valid. */
+export declare function validateStageForPrepare(stage: TrackedStage, options?: PrepareValidationOptions): PrepareResult | null;
+export interface BulkPrepareResult<T extends ChainType = ChainType> {
+    total: number;
+    results: PrepareResult[];
+    targetChain: T;
+}
+export interface SimpleBulkResult {
+    total: number;
+    results: PrepareResult[];
+}
+export declare function bulkPrepareError<T extends ChainType>(error: string, targetChain: T): BulkPrepareResult<T>;
+export declare function simpleBulkError(error: string): SimpleBulkResult;
+export declare function validateStageForBulkPrepare<T extends ChainType>(stage: TrackedStage, targetChain: T, options?: PrepareValidationOptions): BulkPrepareResult<T> | null;
+export declare function validateStageForSimpleBulk(stage: TrackedStage, options?: PrepareValidationOptions): SimpleBulkResult | null;
+/** Search for timelock execution event and complete stage. */
+export declare function searchAndCompleteTimelockExecution(stage: TrackedStage, timelockAddress: string, operationId: string, provider: ethers.providers.Provider, chain: ChainType, fromBlock: number, toBlock?: number, queueTimestamp?: number): Promise<{
+    stage: TrackedStage;
+    executionTxHash: string | null;
+    executionBlock: number | null;
+}>;
+//# sourceMappingURL=stage-helpers.d.ts.map

package/dist/utils/stage-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-helpers.d.ts","sourceRoot":"","sources":["../../src/utils/stage-helpers.ts"],"names":[],"mappings":"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"}