openscan-hardhat-links 0.0.2 → 0.0.4

package/README.md

@@ -1,6 +1,6 @@
 # `openscan-hardhat-links`
 
-This is an example plugin that adds a task that prints a greeting.
+A Hardhat plugin that automatically launches the OpenScan Explorer webapp and adds OpenScan links to all transaction logs.
 
 ## Installation
 
@@ -21,23 +21,40 @@ export default defineConfig({
 });
 ```
 
+## Features
+
+This plugin provides two main features:
+
+1. **Automatic OpenScan Explorer Launch**: When you start the Hardhat node, the plugin automatically:
+   - Launches a local OpenScan Explorer webapp on port 3030
+   - Opens your default browser to <http://localhost:3030>
+   - Serves the explorer from the plugin's built-in webapp
+
+2. **OpenScan Links in Logs**: All transaction-related logs include clickable OpenScan links:
+   - Transaction hashes → OpenScan transaction view
+   - Addresses → OpenScan address view
+   - Blocks → OpenScan block view
+   - Contract deployments → OpenScan contract view
+
 ## Usage
 
-The plugin adds a new task called `my-task`. To run it, use the this command:
+Simply start your Hardhat node:
 
 ```bash
-npx hardhat my-task
+npx hardhat node
 ```
 
-You should see the following output:
-
-```
-Hello, Hardhat!
-```
+The OpenScan Explorer will automatically launch and your browser will open to the explorer interface. All subsequent transactions will include OpenScan links in the console output
 
 ### Configuration
 
-You can configure the greeting that's printed by using the `myConfig` field in your Hardhat config. For example, you can have this config:
+The plugin works out of the box with zero configuration required. The following settings are hardcoded:
+
+- **Port**: 3030 (fixed, not configurable)
+- **Auto-open browser**: Always enabled
+- **Webapp path**: Automatically detected from plugin installation
+
+You can optionally configure the OpenScan URL and chain ID if you want to customize the link format:
 
 ```ts
 import { defineConfig } from "hardhat/config";
@@ -45,39 +62,51 @@ import myPlugin from "openscan-hardhat-links";
 
 export default defineConfig({
   plugins: [myPlugin],
-  OpenScan: {
-    url: "http://localhost:3030",
-    chainId: "31337",
+  openScan: {
+    url: "http://localhost:3030", // Optional: default is http://localhost:3030
+    chainId: 31337, // Optional: default is 31337
   },
-  //...
 });
 ```
 
-### RPC Methods calls logs
-
-This plugin adds some example code to log different network events. To see it in action, all you need to do is run your Hardhat tests, deployment, or a script.
-
-```md
-eth_sendTransaction
-Contract deployment: Counter
-Contract address: 0x5fbdb2315678afecb367f032d93f642f64180aa3
-Transaction: 0xa938ef09640a71a454b58e457e4046253d10e2e88674b5e45d724519eb070566
-From: 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266
-Value: 0 ETH
-Gas used: 263088 of 263088
-Block #1: 0x53bc103d906615c9b1790960a24ddf9a15e8decb3ed672ad2ec654fb1491397d
-
-Transaction: http://localhost:3030/31337/tx/0xa938ef09640a71a454b58e457e4046253d10e2e88674b5e45d724519eb070566
-From: http://localhost:3030/31337/address/0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266
-Contract deployment detected
-
-eth_getTransactionReceipt
-
-Transaction Receipt:
-Transaction: http://localhost:3030/31337/tx/0xa938ef09640a71a454b58e457e4046253d10e2e88674b5e45d724519eb070566
-Block #1: http://localhost:3030/31337/block/0x53bc103d906615c9b1790960a24ddf9a15e8decb3ed672ad2ec654fb1491397d
-From: http://localhost:3030/31337/address/0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266
-Gas used: 263088
-Status: Success
-Contract: http://localhost:3030/31337/address/0x5fbdb2315678afecb367f032d93f642f64180aa3
+## How It Works
+
+### Webapp Launch
+
+The plugin hooks into Hardhat's network lifecycle using the `newConnection` hook. When the Hardhat node starts:
+
+1. The hook detects the first network connection
+2. Checks if port 3030 is available (fails fast if not)
+3. Starts a custom HTTP server serving static files from the built-in explorer webapp
+4. Opens your default browser to the explorer URL
+5. Logs a success message with a clickable link
+
+The webapp continues running as long as the Hardhat node is active and automatically cleans up when the node stops.
+
+### Transaction Logging
+
+The plugin uses the `onRequest` network hook to intercept all JSON-RPC requests. For relevant methods (like `eth_sendTransaction`, `eth_getTransactionReceipt`, etc.), it extracts transaction hashes, addresses, and block numbers, then outputs clickable OpenScan links to the console.
+
+## Requirements
+
+- Hardhat 3.x
+- Node.js 18+
+- Port 3030 must be available
+
+## Troubleshooting
+
+### Port 3030 Already in Use
+
+If you see an error about port 3030 being in use, you need to free up that port:
+
+```bash
+# Find process using port 3030
+lsof -i:3030
+
+# Kill the process
+kill -9 <PID>
 ```
+
+### Browser Doesn't Open Automatically
+
+The plugin attempts to open your default browser automatically. If this fails, you can manually navigate to <http://localhost:3030>.

package/dist/src/hooks/network.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../src/hooks/network.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,YAAY,EAAE,MAAM,qBAAqB,CAAC;8BAU5C,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;AAAvD,wBA0HE"}
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../src/hooks/network.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,YAAY,EAAE,MAAM,qBAAqB,CAAC;8BAkD5C,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;AAAvD,wBA8HE"}

package/dist/src/hooks/network.js

@@ -1,16 +1,53 @@
+import { createOpenscanServer } from "../server.js";
+import { isPortAvailable, openBrowser } from "../utils.js";
 // Helper function to create clickable terminal links
 function createClickableLink(url, text) {
     const displayText = text || url;
     // OSC 8 escape sequence for hyperlinks: \e]8;;URL\e\\TEXT\e]8;;\e\\
     return `\x1b]8;;${url}\x1b\\${displayText}\x1b]8;;\x1b\\`;
 }
+// Module-level state for webapp server
+let webappServer = null;
+let webappStarted = false;
+/**
+ * Start the webapp server
+ * - Checks port 3030 availability (fail fast if occupied)
+ * - Starts server
+ * - Auto-opens browser
+ */
+async function startWebapp(chainId) {
+    try {
+        // Check if port 3030 is available (fail fast)
+        const portAvailable = await isPortAvailable();
+        if (!portAvailable) {
+            throw new Error("Port 3030 is already in use. Please free the port and try again.");
+        }
+        // Create and start server
+        webappServer = createOpenscanServer();
+        await webappServer.listen();
+        const webappUrl = webappServer.getWebappUrl();
+        console.log(`\n🔍 OpenScan Explorer: ${createClickableLink(webappUrl)}`);
+        console.log(`   Network: Chain ID ${chainId}\n`);
+        // Auto-open browser (always enabled)
+        await openBrowser(webappUrl);
+    }
+    catch (error) {
+        // Fail fast - throw error to stop execution
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to start OpenScan Explorer: ${message}`);
+    }
+}
 export default async () => {
     const handlers = {
         async newConnection(context, next) {
             const connection = await next(context);
-            const { url, chainId } = context.config.openScan;
-            const openScanUrl = `${url}/${chainId}`;
-            console.log(`OpenScan: ${createClickableLink(openScanUrl)}`);
+            const { chainId } = context.config.openScan;
+            // Start webapp on first connection (when Hardhat node starts)
+            // The network name is "default" for the built-in Hardhat network
+            if (!webappStarted && connection.networkName === "default") {
+                webappStarted = true;
+                await startWebapp(chainId);
+            }
             return connection;
         },
         async onRequest(context, networkConnection, jsonRpcRequest, next) {
@@ -38,10 +75,9 @@ export default async () => {
                 const receipt = result?.result;
                 if (receipt && receipt.blockNumber) {
                     const txHash = receipt.transactionHash;
-                    const blockHash = receipt.blockHash;
                     const blockNumber = parseInt(receipt.blockNumber, 16);
                     const txUrl = `${url}/${chainId}/tx/${txHash}`;
-                    const blockUrl = `${url}/${chainId}/block/${blockHash}`;
+                    const blockUrl = `${url}/${chainId}/block/${blockNumber}`;
                     const fromUrl = `${url}/${chainId}/address/${receipt.from}`;
                     console.log(`${"  Transaction:".padEnd(18)}${createClickableLink(txUrl)}`);
                     console.log(`${`  Block #${blockNumber}:`.padEnd(18)}${createClickableLink(blockUrl)}`);
@@ -75,4 +111,22 @@ export default async () => {
     };
     return handlers;
 };
+/**
+ * Cleanup on process exit
+ */
+const cleanup = async () => {
+    if (webappServer) {
+        await webappServer.stop();
+        webappServer = null;
+    }
+};
+process.on("SIGINT", () => {
+    void cleanup();
+});
+process.on("SIGTERM", () => {
+    void cleanup();
+});
+process.on("exit", () => {
+    void cleanup();
+});
 //# sourceMappingURL=network.js.map

package/dist/src/hooks/network.js.map

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

package/dist/src/server.d.ts

@@ -0,0 +1,37 @@
+import { WebappService } from "./services/index.js";
+/**
+ * OpenscanServer interface - manages webapp lifecycle
+ * Fixed configuration: port 3030, always auto-opens browser
+ */
+export interface OpenscanServer {
+    /**
+     * Get references to running services
+     */
+    services(): {
+        webappService: WebappService | null;
+    };
+    /**
+     * Start the webapp server
+     */
+    listen(): Promise<void>;
+    /**
+     * Stop the webapp server
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the webapp URL (always http://localhost:3030)
+     */
+    getWebappUrl(): string | null;
+    /**
+     * Get the webapp port (always 3030)
+     */
+    getWebappPort(): number;
+}
+/**
+ * Create an OpenscanServer instance
+ * Fixed dist path: packages/explorer/dist
+ * Fixed port: 3030
+ * Always auto-opens browser
+ */
+export declare function createOpenscanServer(): OpenscanServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/src/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAKpD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,IAAI;QACV,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;KACrC,CAAC;IAEF;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB;;OAEG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;OAEG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI,CAAC;IAE9B;;OAEG;IACH,aAAa,IAAI,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAoCrD"}

package/dist/src/server.js

@@ -0,0 +1,42 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { WebappService } from "./services/index.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Create an OpenscanServer instance
+ * Fixed dist path: packages/explorer/dist
+ * Fixed port: 3030
+ * Always auto-opens browser
+ */
+export function createOpenscanServer() {
+    let webappService = null;
+    // Fixed dist path relative to plugin location
+    // When compiled: packages/plugin/dist/src/server.js -> packages/plugin/dist/explorer
+    const distPath = path.resolve(__dirname, "../explorer");
+    return {
+        services() {
+            return { webappService };
+        },
+        async listen() {
+            // Create webapp service
+            webappService = new WebappService(distPath);
+            // Start service (will throw if fails - fail fast strategy)
+            await webappService.start();
+            await webappService.waitForReady();
+        },
+        async stop() {
+            if (webappService) {
+                await webappService.stop();
+                webappService = null;
+            }
+        },
+        getWebappUrl() {
+            return webappService ? `http://localhost:3030` : null;
+        },
+        getWebappPort() {
+            return 3030;
+        },
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/src/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAmC3C;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB;IAClC,IAAI,aAAa,GAAyB,IAAI,CAAC;IAE/C,8CAA8C;IAC9C,qFAAqF;IACrF,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IAExD,OAAO;QACL,QAAQ;YACN,OAAO,EAAE,aAAa,EAAE,CAAC;QAC3B,CAAC;QAED,KAAK,CAAC,MAAM;YACV,wBAAwB;YACxB,aAAa,GAAG,IAAI,aAAa,CAAC,QAAQ,CAAC,CAAC;YAE5C,2DAA2D;YAC3D,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC;YAC5B,MAAM,aAAa,CAAC,YAAY,EAAE,CAAC;QACrC,CAAC;QAED,KAAK,CAAC,IAAI;YACR,IAAI,aAAa,EAAE,CAAC;gBAClB,MAAM,aAAa,CAAC,IAAI,EAAE,CAAC;gBAC3B,aAAa,GAAG,IAAI,CAAC;YACvB,CAAC;QACH,CAAC;QAED,YAAY;YACV,OAAO,aAAa,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,IAAI,CAAC;QACxD,CAAC;QAED,aAAa;YACX,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/services/base.d.ts

@@ -0,0 +1,32 @@
+import type { ChildProcess } from "child_process";
+/**
+ * Abstract base class for services (webapp server, external processes, etc.)
+ * Uses fixed port 3030 for webapp
+ */
+export declare abstract class Service {
+    process: ChildProcess | null;
+    readonly port: number;
+    constructor();
+    /**
+     * Start the service
+     */
+    abstract start(): Promise<void>;
+    /**
+     * Stop the service and cleanup resources
+     */
+    abstract stop(): Promise<void>;
+    /**
+     * Wait for service to be ready (health check)
+     * @param maxAttempts - Maximum number of health check attempts
+     */
+    abstract waitForReady(maxAttempts?: number): Promise<void>;
+    /**
+     * Handle process exit events with proper logging
+     */
+    protected handleOnExit(name: string): (code: number | null, signal: NodeJS.Signals | null) => void;
+    /**
+     * Handle process errors with proper logging
+     */
+    protected handleOnError(name: string, reject: (reason?: Error) => void): (error: Error) => void;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/src/services/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/services/base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;;GAGG;AACH,8BAAsB,OAAO;IACpB,OAAO,EAAE,YAAY,GAAG,IAAI,CAAQ;IAC3C,SAAgB,IAAI,EAAE,MAAM,CAAQ;;IAMpC;;OAEG;IACH,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1D;;OAEG;IACH,SAAS,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,IACzB,MAAM,MAAM,GAAG,IAAI,EAAE,QAAQ,MAAM,CAAC,OAAO,GAAG,IAAI;IAS5D;;OAEG;IACH,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,KAAK,IAAI,IAC5D,OAAO,KAAK;CAKvB"}

package/dist/src/services/base.js

@@ -0,0 +1,34 @@
+/**
+ * Abstract base class for services (webapp server, external processes, etc.)
+ * Uses fixed port 3030 for webapp
+ */
+export class Service {
+    process = null;
+    port = 3030;
+    constructor() {
+        // Fixed port 3030
+    }
+    /**
+     * Handle process exit events with proper logging
+     */
+    handleOnExit(name) {
+        return (code, signal) => {
+            if (signal) {
+                console.log(`[openscan] ${name} received ${signal}, exiting...`);
+            }
+            else if (code !== null && code !== 0) {
+                console.error(`[openscan] ${name} exited with code ${code}`);
+            }
+        };
+    }
+    /**
+     * Handle process errors with proper logging
+     */
+    handleOnError(name, reject) {
+        return (error) => {
+            console.error(`[openscan] Error starting ${name}: ${error.message}`);
+            reject(error);
+        };
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/src/services/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/services/base.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAgB,OAAO;IACpB,OAAO,GAAwB,IAAI,CAAC;IAC3B,IAAI,GAAW,IAAI,CAAC;IAEpC;QACE,kBAAkB;IACpB,CAAC;IAkBD;;OAEG;IACO,YAAY,CAAC,IAAY;QACjC,OAAO,CAAC,IAAmB,EAAE,MAA6B,EAAE,EAAE;YAC5D,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,aAAa,MAAM,cAAc,CAAC,CAAC;YACnE,CAAC;iBAAM,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;gBACvC,OAAO,CAAC,KAAK,CAAC,cAAc,IAAI,qBAAqB,IAAI,EAAE,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED;;OAEG;IACO,aAAa,CAAC,IAAY,EAAE,MAAgC;QACpE,OAAO,CAAC,KAAY,EAAE,EAAE;YACtB,OAAO,CAAC,KAAK,CAAC,6BAA6B,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACrE,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CAAC;IACJ,CAAC;CACF"}

package/dist/src/services/index.d.ts

@@ -0,0 +1,3 @@
+export { Service } from "./base.js";
+export { WebappService } from "./webapp.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/services/index.js

@@ -0,0 +1,3 @@
+export { Service } from "./base.js";
+export { WebappService } from "./webapp.js";
+//# sourceMappingURL=index.js.map

package/dist/src/services/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/services/webapp.d.ts

@@ -0,0 +1,40 @@
+import { Service } from "./base.js";
+/**
+ * WebappService - Custom HTTP server for serving static files
+ * No external dependencies - uses only Node.js built-in modules
+ * Fixed port: 3030
+ */
+export declare class WebappService extends Service {
+    private distPath;
+    private server;
+    constructor(distPath: string);
+    /**
+     * Start the HTTP server
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the HTTP server
+     */
+    stop(): Promise<void>;
+    /**
+     * Wait for server to be ready by polling the health endpoint
+     */
+    waitForReady(maxAttempts?: number): Promise<void>;
+    /**
+     * Handle incoming HTTP requests
+     */
+    private handleRequest;
+    /**
+     * Serve a file with proper MIME type and caching headers
+     */
+    private serveFile;
+    /**
+     * Send 404 Not Found response
+     */
+    private send404;
+    /**
+     * Send 500 Internal Server Error response
+     */
+    private send500;
+}
+//# sourceMappingURL=webapp.d.ts.map

package/dist/src/services/webapp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webapp.d.ts","sourceRoot":"","sources":["../../../src/services/webapp.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuBpC;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,OAAO;IACxC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAA4B;gBAE9B,QAAQ,EAAE,MAAM;IAK5B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA4C5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B;;OAEG;IACG,YAAY,CAAC,WAAW,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBnD;;OAEG;IACH,OAAO,CAAC,aAAa;IAgDrB;;OAEG;IACH,OAAO,CAAC,SAAS;IAgCjB;;OAEG;IACH,OAAO,CAAC,OAAO;IAKf;;OAEG;IACH,OAAO,CAAC,OAAO;CAIhB"}