@gzeoneth/gov-tracker 0.1.0

package/dist/utils/stage-helpers.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Stage Helpers
+ *
+ * Utility functions for timelock stage operations and validation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deserializeCallScheduledDataArray = exports.serializeCallScheduledDataArray = exports.deserializeCallScheduledData = exports.serializeCallScheduledData = exports.deserialize = exports.serialize = void 0;
+exports.createTimelockStageData = createTimelockStageData;
+exports.collectAllScheduledData = collectAllScheduledData;
+exports.calculateTimelockEta = calculateTimelockEta;
+exports.buildExecutionPayloadData = buildExecutionPayloadData;
+exports.validateStageForPrepare = validateStageForPrepare;
+exports.bulkPrepareError = bulkPrepareError;
+exports.simpleBulkError = simpleBulkError;
+exports.validateStageForBulkPrepare = validateStageForBulkPrepare;
+exports.validateStageForSimpleBulk = validateStageForSimpleBulk;
+exports.searchAndCompleteTimelockExecution = searchAndCompleteTimelockExecution;
+const types_1 = require("../types");
+const base_1 = require("../stages/base");
+const stage_builder_1 = require("../stages/stage-builder");
+const timelock_discovery_1 = require("../discovery/timelock-discovery");
+// Re-export serialization from base for backwards compatibility
+var base_2 = require("../stages/base");
+Object.defineProperty(exports, "serialize", { enumerable: true, get: function () { return base_2.serialize; } });
+Object.defineProperty(exports, "deserialize", { enumerable: true, get: function () { return base_2.deserialize; } });
+Object.defineProperty(exports, "serializeCallScheduledData", { enumerable: true, get: function () { return base_2.serializeCallScheduledData; } });
+Object.defineProperty(exports, "deserializeCallScheduledData", { enumerable: true, get: function () { return base_2.deserializeCallScheduledData; } });
+Object.defineProperty(exports, "serializeCallScheduledDataArray", { enumerable: true, get: function () { return base_2.serializeCallScheduledDataArray; } });
+Object.defineProperty(exports, "deserializeCallScheduledDataArray", { enumerable: true, get: function () { return base_2.deserializeCallScheduledDataArray; } });
+/** Extract timelock execution payload from a stage. */
+function createTimelockStageData(stage) {
+    let stageData = null;
+    for (const stageType of base_1.TIMELOCK_STAGE_TYPES) {
+        stageData = (0, types_1.getStageData)(stage, stageType);
+        if (stageData)
+            break;
+    }
+    if (!stageData?.timelockAddress ||
+        !stageData?.operationId ||
+        !stageData?.callScheduledData?.length) {
+        return null;
+    }
+    const payload = {
+        timelockAddress: stageData.timelockAddress,
+        operationId: stageData.operationId,
+        callScheduledData: (0, base_1.deserializeCallScheduledDataArray)(stageData.callScheduledData),
+    };
+    if (stageData.isSecurityCouncilOperation) {
+        payload.isSecurityCouncilOperation = true;
+        payload.securityCouncilMembers = stageData.securityCouncilMembers;
+        payload.securityCouncilNonce = stageData.securityCouncilNonce;
+    }
+    return payload;
+}
+// ============================================================================
+// Timelock State Helpers
+// ============================================================================
+/** Collect all CallScheduledData from a timelock state. */
+function collectAllScheduledData(timelockState) {
+    return (timelockState.allScheduledData ??
+        (timelockState.scheduledData ? [timelockState.scheduledData] : []));
+}
+/** Calculate ETA for a timelock operation. */
+async function calculateTimelockEta(timelockState, operationState, provider) {
+    if (timelockState.scheduledData) {
+        return (0, base_1.calculateEtaFromScheduledData)(timelockState.scheduledData.blockNumber, timelockState.scheduledData.delay.toNumber(), provider);
+    }
+    const contractTimestamp = operationState.timestamp.toNumber();
+    return !operationState.isDone && contractTimestamp > 1 ? contractTimestamp : undefined;
+}
+/** Build serialized execution payload data for stage storage. */
+function buildExecutionPayloadData(timelockAddress, operationId, allScheduledData) {
+    const payload = { timelockAddress, operationId };
+    if (allScheduledData.length > 0) {
+        payload.callScheduledData = (0, base_1.serializeCallScheduledDataArray)(allScheduledData);
+    }
+    return payload;
+}
+/** Validate stage for preparation. Returns error or null if valid. */
+function validateStageForPrepare(stage, options = {}) {
+    if (!options.force && stage.status !== "READY") {
+        return (0, base_1.failPrepare)(`Stage is not ready. Current status: ${stage.status}`);
+    }
+    if (options.expectedTypes?.length && !options.expectedTypes.includes(stage.type)) {
+        return (0, base_1.failPrepare)(`Unexpected stage type: ${stage.type}. Expected: ${options.expectedTypes.join(", ")}`);
+    }
+    return null;
+}
+function bulkPrepareError(error, targetChain) {
+    return { total: 0, results: [{ success: false, error }], targetChain };
+}
+function simpleBulkError(error) {
+    return { total: 0, results: [{ success: false, error }] };
+}
+function validateStageForBulkPrepare(stage, targetChain, options = {}) {
+    const error = validateStageForPrepare(stage, options);
+    return error ? { total: 0, results: [error], targetChain } : null;
+}
+function validateStageForSimpleBulk(stage, options = {}) {
+    const error = validateStageForPrepare(stage, options);
+    return error ? { total: 0, results: [error] } : null;
+}
+// ============================================================================
+// Execution Search Helper
+// ============================================================================
+/** Search for timelock execution event and complete stage. */
+async function searchAndCompleteTimelockExecution(stage, timelockAddress, operationId, provider, chain, fromBlock, toBlock, queueTimestamp) {
+    const event = await (0, timelock_discovery_1.findCallExecutedEvent)(timelockAddress, operationId, provider, {
+        startBlock: fromBlock,
+        endBlock: toBlock,
+    });
+    const builder = new stage_builder_1.StageBuilder(stage.type, stage.chain)
+        .data(stage.data)
+        .transactions(stage.transactions);
+    if (stage.timing)
+        builder.timing(stage.timing);
+    if (event) {
+        const execTimestamp = await (0, base_1.getBlockTimestamp)(event.blockNumber, provider);
+        builder
+            .status("COMPLETED")
+            .tx(event.txHash, event.blockNumber, chain, {
+            timestamp: execTimestamp,
+            description: "executed",
+        })
+            .timing({ startedAt: queueTimestamp ?? execTimestamp })
+            .data({ operationId });
+        return {
+            stage: builder.build(),
+            executionTxHash: event.txHash,
+            executionBlock: event.blockNumber,
+        };
+    }
+    return {
+        stage: builder
+            .status("COMPLETED")
+            .data({ operationId, note: "Execution confirmed by state, event not found" })
+            .build(),
+        executionTxHash: null,
+        executionBlock: null,
+    };
+}
+//# sourceMappingURL=stage-helpers.js.map

package/dist/utils/stage-helpers.js.map

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

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

@@ -0,0 +1,62 @@
+/**
+ * Stage Metadata - Human-readable stage information for UI display
+ *
+ * Provides titles, descriptions, and timing info for governance stages.
+ */
+import type { StageType, ProposalType } from "../types";
+/**
+ * Metadata for a governance stage
+ */
+export interface StageMetadata {
+    /** Short human-readable title */
+    title: string;
+    /** Longer description of what happens in this stage */
+    description: string;
+    /** Which chain this stage occurs on */
+    chain: "L1" | "L2" | "NOVA" | "CROSS_CHAIN";
+    /** Estimated duration in days (may vary by governor type) */
+    estimatedDays: number;
+    /** Whether this stage requires user action to proceed */
+    requiresAction: boolean;
+}
+/**
+ * Get metadata for a specific stage
+ *
+ * @example
+ * ```typescript
+ * const meta = getStageMetadata("VOTING_ACTIVE");
+ * console.log(`${meta.title}: ${meta.description}`);
+ * // => "Voting Active: Token holders are voting on the proposal"
+ * ```
+ */
+export declare function getStageMetadata(stageType: StageType, _proposalType?: ProposalType): StageMetadata;
+/**
+ * Get metadata for all stages in order
+ *
+ * @example
+ * ```typescript
+ * const allMeta = getAllStageMetadata();
+ * for (const [type, meta] of Object.entries(allMeta)) {
+ *   console.log(`${meta.title} (${meta.estimatedDays}d)`);
+ * }
+ * ```
+ */
+export declare function getAllStageMetadata(proposalType?: ProposalType): Record<StageType, StageMetadata>;
+/**
+ * Get stages that require user action (executable stages)
+ */
+export declare function getActionableStages(): StageType[];
+/**
+ * Format stage type as human-readable title
+ *
+ * @example
+ * ```typescript
+ * formatStageTitle("L2_TIMELOCK") // => "L2 Timelock"
+ * ```
+ */
+export declare function formatStageTitle(stageType: StageType): string;
+/**
+ * Get total expected duration for the full governance lifecycle in days
+ */
+export declare function getTotalExpectedDuration(): number;
+//# sourceMappingURL=stage-metadata.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stage-metadata.d.ts","sourceRoot":"","sources":["../../src/utils/stage-metadata.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,KAAK,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAAG,aAAa,CAAC;IAC5C,6DAA6D;IAC7D,aAAa,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,cAAc,EAAE,OAAO,CAAC;CACzB;AA+DD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,EACpB,aAAa,CAAC,EAAE,YAAY,GAC3B,aAAa,CAQf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC,SAAS,EAAE,aAAa,CAAC,CAiBjG;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,EAAE,CAIjD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,CAE7D;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD"}

package/dist/utils/stage-metadata.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Stage Metadata - Human-readable stage information for UI display
+ *
+ * Provides titles, descriptions, and timing info for governance stages.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getStageMetadata = getStageMetadata;
+exports.getAllStageMetadata = getAllStageMetadata;
+exports.getActionableStages = getActionableStages;
+exports.formatStageTitle = formatStageTitle;
+exports.getTotalExpectedDuration = getTotalExpectedDuration;
+const constants_1 = require("../constants");
+const BASE_METADATA = {
+    PROPOSAL_CREATED: {
+        title: "Proposal Created",
+        description: "Proposal submitted on-chain and awaiting voting period to begin",
+        chain: "L2",
+        requiresAction: false,
+    },
+    VOTING_ACTIVE: {
+        title: "Voting Active",
+        description: "Token holders are voting on the proposal",
+        chain: "L2",
+        requiresAction: false,
+    },
+    PROPOSAL_QUEUED: {
+        title: "Proposal Queued",
+        description: "Voting succeeded, proposal queued in L2 timelock",
+        chain: "L2",
+        requiresAction: false,
+    },
+    L2_TIMELOCK: {
+        title: "L2 Timelock",
+        description: "L2 timelock delay and execution. Status: PENDING (waiting for delay), READY (can execute), COMPLETED (executed)",
+        chain: "L2",
+        requiresAction: true,
+    },
+    L2_TO_L1_MESSAGE: {
+        title: "L2→L1 Message",
+        description: "Cross-chain message with challenge period. Status: PENDING (in challenge period), READY (can execute outbox), COMPLETED (confirmed on L1)",
+        chain: "CROSS_CHAIN",
+        requiresAction: true,
+    },
+    L1_TIMELOCK: {
+        title: "L1 Timelock",
+        description: "L1 timelock delay and execution. Status: PENDING (waiting for delay), READY (can execute), COMPLETED (executed)",
+        chain: "L1",
+        requiresAction: true,
+    },
+    RETRYABLE_EXECUTED: {
+        title: "Retryable Executed",
+        description: "Retryable ticket(s) executed on target chain",
+        chain: "CROSS_CHAIN",
+        requiresAction: true,
+    },
+};
+const DEFAULT_DURATIONS = {
+    PROPOSAL_CREATED: 0,
+    VOTING_ACTIVE: constants_1.GOVERNANCE_STAGE_DURATION_DAYS.VOTING,
+    PROPOSAL_QUEUED: 0,
+    // L2_TIMELOCK combines delay (8 days for Core, 3 for Treasury) + execution (0 days)
+    L2_TIMELOCK: constants_1.GOVERNANCE_STAGE_DURATION_DAYS.L2_CONSTITUTIONAL_TIMELOCK,
+    // L2_TO_L1_MESSAGE combines sent (0 days) + challenge period (6.4 days)
+    L2_TO_L1_MESSAGE: constants_1.GOVERNANCE_STAGE_DURATION_DAYS.CHALLENGE_PERIOD,
+    // L1_TIMELOCK combines delay (3 days) + execution (0 days)
+    L1_TIMELOCK: constants_1.GOVERNANCE_STAGE_DURATION_DAYS.L1_TIMELOCK,
+    RETRYABLE_EXECUTED: 0,
+};
+/**
+ * Get metadata for a specific stage
+ *
+ * @example
+ * ```typescript
+ * const meta = getStageMetadata("VOTING_ACTIVE");
+ * console.log(`${meta.title}: ${meta.description}`);
+ * // => "Voting Active: Token holders are voting on the proposal"
+ * ```
+ */
+function getStageMetadata(stageType, _proposalType) {
+    const base = BASE_METADATA[stageType];
+    const estimatedDays = DEFAULT_DURATIONS[stageType];
+    return {
+        ...base,
+        estimatedDays,
+    };
+}
+/**
+ * Get metadata for all stages in order
+ *
+ * @example
+ * ```typescript
+ * const allMeta = getAllStageMetadata();
+ * for (const [type, meta] of Object.entries(allMeta)) {
+ *   console.log(`${meta.title} (${meta.estimatedDays}d)`);
+ * }
+ * ```
+ */
+function getAllStageMetadata(proposalType) {
+    const stages = [
+        "PROPOSAL_CREATED",
+        "VOTING_ACTIVE",
+        "PROPOSAL_QUEUED",
+        "L2_TIMELOCK",
+        "L2_TO_L1_MESSAGE",
+        "L1_TIMELOCK",
+        "RETRYABLE_EXECUTED",
+    ];
+    const result = {};
+    for (const stage of stages) {
+        result[stage] = getStageMetadata(stage, proposalType);
+    }
+    return result;
+}
+/**
+ * Get stages that require user action (executable stages)
+ */
+function getActionableStages() {
+    return Object.entries(BASE_METADATA)
+        .filter(([, meta]) => meta.requiresAction)
+        .map(([type]) => type);
+}
+/**
+ * Format stage type as human-readable title
+ *
+ * @example
+ * ```typescript
+ * formatStageTitle("L2_TIMELOCK") // => "L2 Timelock"
+ * ```
+ */
+function formatStageTitle(stageType) {
+    return BASE_METADATA[stageType].title;
+}
+/**
+ * Get total expected duration for the full governance lifecycle in days
+ */
+function getTotalExpectedDuration() {
+    return Object.values(DEFAULT_DURATIONS).reduce((sum, d) => sum + d, 0);
+}
+//# sourceMappingURL=stage-metadata.js.map

package/dist/utils/stage-metadata.js.map

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

package/dist/utils/timing.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Timing utilities for ETA calculations
+ *
+ * Handles block-based timing across L1 and L2
+ */
+import { BigNumber, ethers } from "ethers";
+import type { TrackedStage } from "../types";
+/**
+ * Convert block number to estimated timestamp
+ */
+export declare function estimateTimestampFromBlock(blockNumber: number, currentBlock: number, currentTimestamp: number, blockTime?: number): number;
+/**
+ * Calculate ETA for a future block
+ */
+export declare function calculateEta(targetBlock: number, currentBlock: number, currentTimestamp: number, blockTime?: number): number | null;
+/**
+ * Calculate remaining time in seconds
+ */
+export declare function calculateRemainingSeconds(targetBlock: number, currentBlock: number, blockTime?: number): number;
+/**
+ * Get current block info from a provider
+ *
+ * Results are cached for 2 seconds to reduce redundant RPC calls during a single
+ * tracking operation. The cache is per-provider.
+ */
+export declare function getCurrentBlockInfo(provider: ethers.providers.Provider): Promise<{
+    blockNumber: number;
+    timestamp: number;
+}>;
+/**
+ * Get current L1 block number as seen from L2
+ *
+ * Arbitrum L2 blocks include the L1 block number in their metadata.
+ * This returns the L1 block number from the latest L2 block.
+ *
+ * IMPORTANT: This returns the actual L1 block number, not the L2 block number.
+ * Use this for comparing against vetting deadlines which are in L1 blocks.
+ */
+export declare function getL1BlockNumberFromL2(l2Provider: ethers.providers.Provider): Promise<BigNumber>;
+/**
+ * Get the corresponding L1 block number for an L2 block.
+ *
+ * Arbitrum L2 blocks include the L1 block number at the time they were created.
+ * This is exposed via the `l1BlockNumber` field in the raw block data.
+ *
+ * This is useful for determining search ranges when looking for L1 events
+ * that correspond to L2 actions.
+ *
+ * Note: This relies on Arbitrum-specific block metadata and requires a
+ * JsonRpcProvider that supports the `send` method for raw RPC calls.
+ */
+export declare function getL1BlockForL2Block(l2Provider: ethers.providers.Provider, l2BlockNumber: number): Promise<number>;
+/**
+ * Get the first L2 block for a given L1 block number using Arbitrum SDK.
+ *
+ * Arbitrum governors use L1 block numbers for voting deadlines. This function
+ * finds the corresponding L2 block for searching L2 logs.
+ *
+ * Uses binary search via the SDK's getFirstBlockForL1Block which queries
+ * NodeInterface.l2BlockRangeForL1() internally.
+ *
+ * @param l2Provider - L2 provider (must be JsonRpcProvider)
+ * @param targetL1Block - Target L1 block number
+ * @param options.minL2Block - Minimum L2 block to search from (speeds up binary search)
+ * @param options.maxL2Block - Maximum L2 block to search to (speeds up binary search)
+ * @returns First L2 block for the given L1 block, or undefined if not found
+ */
+export declare function getFirstL2BlockForL1Block(l2Provider: ethers.providers.Provider, targetL1Block: number, options?: {
+    minL2Block?: number;
+    maxL2Block?: number;
+}): Promise<number | undefined>;
+/**
+ * Find a block number shortly after a delay expires.
+ *
+ * Instead of using a hardcoded block time which can overshoot or undershoot,
+ * this function checks actual block timestamps and adjusts iteratively.
+ *
+ * IMPORTANT: This function errs on the side of being EARLY rather than late.
+ * When searching for events, it's better to start searching a bit before the
+ * target time than to miss the event by starting too late.
+ *
+ * @param provider - Provider to fetch block data
+ * @param startBlock - The block number where the delay started
+ * @param delaySeconds - The delay duration in seconds
+ * @param estimatedBlockTime - Estimated seconds per block (default: 12 for L1)
+ * @returns A block number at or shortly before timestamp >= startTimestamp + delaySeconds
+ */
+export declare function blockAfterDelay(provider: ethers.providers.Provider, startBlock: number, delaySeconds: number, estimatedBlockTime?: number): Promise<number>;
+/**
+ * Calculate expected ETA for a stage that hasn't started yet
+ *
+ * Estimates when a future stage will complete based on:
+ * 1. Finding a reference point (completed stage timestamp or existing ETA)
+ * 2. Calculating cumulative delays from that reference to the target stage
+ *
+ * @param stages - Array of tracked stages from a TrackingResult
+ * @param stageIndex - Index of the stage to calculate ETA for
+ * @returns Estimated completion timestamp in seconds, or undefined if cannot calculate
+ *
+ * @example
+ * ```typescript
+ * const result = await tracker.trackFromGovernor(governor, proposalId);
+ * for (let i = 0; i < result.stages.length; i++) {
+ *   const stage = result.stages[i];
+ *   if (stage.status === "NOT_STARTED") {
+ *     const eta = calculateExpectedEta(result.stages, i);
+ *     if (eta) {
+ *       console.log(`${stage.type}: Expected ~${new Date(eta * 1000).toISOString()}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare function calculateExpectedEta(stages: TrackedStage[], stageIndex: number): number | undefined;
+//# sourceMappingURL=timing.d.ts.map

package/dist/utils/timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../../src/utils/timing.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE3C,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,UAAU,CAAC;AAyBxD;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,EACxB,SAAS,GAAE,MAA6B,GACvC,MAAM,CAIR;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,EACxB,SAAS,GAAE,MAA6B,GACvC,MAAM,GAAG,IAAI,CAMf;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,MAA6B,GACvC,MAAM,CAMR;AAUD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,GAClC,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAqBrD;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,GACpC,OAAO,CAAC,SAAS,CAAC,CAkBpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACrC,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACrC,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACzD,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAsB7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EACnC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,kBAAkB,GAAE,MAA6B,GAChD,OAAO,CAAC,MAAM,CAAC,CAoFjB;AAcD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,EAAE,EACtB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,SAAS,CAmCpB"}