@rubanrubi/hardhat-dashboard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# @rubanrubi/hardhat-dashboard
+
+A Hardhat plugin that provides a **secure, browser-based dashboard** for reviewing and signing transactions during smart contract development. It eliminates the need to store private keys or mnemonics in `hardhat.config.ts` — all signing is delegated to MetaMask or a connected hardware wallet (Ledger/Trezor).
+
+> **Think of it as Truffle Dashboard, but for Hardhat.**
+
+---
+
+## ✨ Features
+
+- 🔐 **No private keys on disk** — signing happens entirely in your browser wallet
+- 🖥️ **Local dashboard UI** — review every transaction before it hits the chain
+- ⚡ **Auto-decode transactions** — contract ABIs are synced after `hardhat compile` for human-readable call details
+- 🔌 **Drop-in integration** — just add `--network dashboard` to any Hardhat command
+- 📋 **Session history** — track confirmed, rejected, and failed transactions
+- 🔒 **Localhost only** — the server binds to `127.0.0.1`; no network exposure
+
+---
+
+## 📦 Installation
+
+```bash
+npm install --save-dev @rubanrubi/hardhat-dashboard
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Register the plugin
+
+Add the import to your `hardhat.config.ts`:
+
+```typescript
+import "@rubanrubi/hardhat-dashboard";
+```
+
+Or in JavaScript (`hardhat.config.js`):
+
+```javascript
+require("@rubanrubi/hardhat-dashboard");
+```
+
+### 2. Start the dashboard
+
+```bash
+npx hardhat dashboard
+```
+
+This starts a local server at `http://localhost:24012` and opens it in your browser automatically. Connect your MetaMask wallet to the page.
+
+### 3. Run any Hardhat command with `--network dashboard`
+
+```bash
+# Compile first (ABIs are synced to the dashboard for tx decoding)
+npx hardhat compile
+
+# Deploy via the dashboard
+npx hardhat run scripts/deploy.ts --network dashboard
+
+# Or run any script/task
+npx hardhat run scripts/interact.ts --network dashboard
+```
+
+Each transaction appears in the browser UI. Review the decoded contract call details and click **Confirm** to sign via MetaMask, or **Reject** to cancel.
+
+---
+
+## ⚙️ Configuration
+
+You can customize the plugin in your `hardhat.config.ts`:
+
+```typescript
+import { defineConfig } from "hardhat/config";
+import "@rubanrubi/hardhat-dashboard";
+
+export default defineConfig({
+  solidity: "0.8.24",
+
+  dashboardPlugin: {
+    port: 24012,              // Port for the dashboard server (default: 24012)
+    networkName: "dashboard", // Name of the auto-registered network (default: "dashboard")
+    autoOpen: true,           // Open browser automatically on start (default: true)
+  },
+});
+```
+
+### CLI Options
+
+```bash
+# Override port from the command line
+npx hardhat dashboard --port 3000
+```
+
+---
+
+## 🏗️ How It Works
+
+```
+┌───────────────────┐       JSON-RPC        ┌─────────────────────┐
+│                   │  ──────────────────▶  │                     │
+│   Hardhat CLI     │                       │  Dashboard Server   │
+│  (your scripts)   │  ◀──────────────────  │  (localhost:24012)  │
+│                   │       Response         │                     │
+└───────────────────┘                       └─────────┬───────────┘
+                                                      │ WebSocket
+                                                      ▼
+                                            ┌─────────────────────┐
+                                            │                     │
+                                            │   Browser Dashboard │
+                                            │   (React UI)        │
+                                            │                     │
+                                            │   ┌───────────────┐ │
+                                            │   │   MetaMask /   │ │
+                                            │   │   Ledger /     │ │
+                                            │   │   Trezor       │ │
+                                            │   └───────────────┘ │
+                                            └─────────────────────┘
+```
+
+1. **Hardhat** sends JSON-RPC requests to the local dashboard server
+2. **Read-only calls** (`eth_call`, `eth_getBalance`, etc.) are forwarded automatically
+3. **Signing requests** (`eth_sendTransaction`, `personal_sign`, etc.) are queued and displayed in the browser UI
+4. **You** review the decoded transaction and click Confirm or Reject
+5. **MetaMask** signs the transaction — the private key never leaves the wallet
+6. The signed response is relayed back to Hardhat
+
+---
+
+## 🔑 Security
+
+- Private keys are **never** stored, logged, or transmitted by the plugin
+- The dashboard server binds to `127.0.0.1` only — it is **not** accessible over the network
+- The `/rpc` endpoint rejects requests not originating from localhost
+- All signing is handled natively by MetaMask or your hardware wallet
+
+---
+
+## 📋 Requirements
+
+| Requirement | Version |
+|---|---|
+| **Node.js** | ≥ 18.x |
+| **Hardhat** | ≥ 2.22.0 |
+| **Browser** | Chrome or Edge with MetaMask |
+
+---
+
+## 🛠️ Development
+
+```bash
+# Clone the repository
+git clone https://github.com/ruban/hardhat-dashboard.git
+cd hardhat-dashboard
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run the dashboard UI locally (no Hardhat needed)
+npm run dev
+
+# Run tests
+npm test
+```
+
+---
+
+## 📄 License
+
+MIT — see [LICENSE](./LICENSE) for details.

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import './plugin';
+export { default } from './plugin';
+export * from './plugin';
+export * from './server/artifacts';
+export * from './server/proxy';
+export * from './server/queue';
+export * from './types/config';
+export * from './types/rpc';

package/dist/index.js

@@ -0,0 +1,30 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = void 0;
+require("./plugin");
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(plugin_1).default; } });
+__exportStar(require("./plugin"), exports);
+__exportStar(require("./server/artifacts"), exports);
+__exportStar(require("./server/proxy"), exports);
+__exportStar(require("./server/queue"), exports);
+__exportStar(require("./types/config"), exports);
+__exportStar(require("./types/rpc"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA,oBAAkB;AAElB,mCAAmC;AAA1B,kHAAA,OAAO,OAAA;AAChB,2CAAyB;AACzB,qDAAmC;AACnC,iDAA+B;AAC/B,iDAA+B;AAC/B,iDAA+B;AAC/B,8CAA4B"}

package/dist/plugin.d.ts

@@ -0,0 +1,10 @@
+import type { HardhatRuntimeEnvironment } from 'hardhat/types';
+import { type DashboardServerHandle } from './server/proxy';
+import { type ResolvedDashboardPluginConfig } from './types/config';
+export declare function startDashboardServer(config: ResolvedDashboardPluginConfig): Promise<DashboardServerHandle>;
+export declare function relayCompiledArtifacts(hre: HardhatRuntimeEnvironment, config?: ResolvedDashboardPluginConfig): Promise<void>;
+declare const dashboardPlugin: {
+    startDashboardServer: typeof startDashboardServer;
+    relayCompiledArtifacts: typeof relayCompiledArtifacts;
+};
+export default dashboardPlugin;

package/dist/plugin.js

@@ -0,0 +1,123 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startDashboardServer = startDashboardServer;
+exports.relayCompiledArtifacts = relayCompiledArtifacts;
+const node_path_1 = __importDefault(require("node:path"));
+const chalk_1 = __importDefault(require("chalk"));
+const config_1 = require("hardhat/config");
+const task_names_1 = require("hardhat/builtin-tasks/task-names");
+const open_1 = __importDefault(require("open"));
+const artifacts_1 = require("./server/artifacts");
+const proxy_1 = require("./server/proxy");
+const config_2 = require("./types/config");
+let activeServer;
+function getDashboardOrigin(port) {
+    return `http://127.0.0.1:${port}`;
+}
+function getDashboardRpcUrl(port) {
+    return `${getDashboardOrigin(port)}/rpc`;
+}
+function applyDashboardNetwork(networks, config) {
+    const networkName = config.networkName || config_2.DEFAULT_DASHBOARD_NETWORK;
+    const existing = networks[networkName];
+    if (!existing) {
+        networks[networkName] = {
+            url: getDashboardRpcUrl(config.port),
+            timeout: 0,
+        };
+        return;
+    }
+    if (existing.url === undefined) {
+        existing.url = getDashboardRpcUrl(config.port);
+    }
+    if (existing.timeout === undefined) {
+        existing.timeout = 0;
+    }
+}
+function resolveTaskConfig(baseConfig, overrides) {
+    return (0, config_2.resolveDashboardPluginConfig)({
+        port: overrides?.port ?? baseConfig.port,
+        networkName: overrides?.networkName ?? baseConfig.networkName,
+        autoOpen: overrides?.autoOpen ?? baseConfig.autoOpen,
+    });
+}
+async function ensureServer(config) {
+    if (activeServer && activeServer.config.port === config.port) {
+        return activeServer.server;
+    }
+    if (activeServer) {
+        await activeServer.server.stop();
+    }
+    const server = (0, proxy_1.createDashboardServer)({
+        port: config.port,
+        host: '127.0.0.1',
+        uiDir: node_path_1.default.resolve(__dirname, 'ui'),
+    });
+    await server.start();
+    activeServer = { config, server };
+    return server;
+}
+async function waitForShutdown(server) {
+    await new Promise((resolve) => {
+        let closing = false;
+        const shutdown = () => {
+            if (closing) {
+                return;
+            }
+            closing = true;
+            process.off('SIGINT', shutdown);
+            process.off('SIGTERM', shutdown);
+            void server.stop().finally(resolve);
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+    });
+}
+async function relayArtifactsFromHre(hre, config) {
+    const artifacts = await (0, artifacts_1.collectArtifactsFromDirectory)(hre.config.paths.artifacts);
+    await (0, artifacts_1.postArtifactsToDashboard)(getDashboardOrigin(config.port), artifacts);
+}
+(0, config_1.extendConfig)((config, userConfig) => {
+    const resolved = (0, config_2.resolveDashboardPluginConfig)(userConfig.dashboardPlugin);
+    config.dashboardPlugin = resolved;
+    applyDashboardNetwork(config.networks, resolved);
+});
+(0, config_1.task)('dashboard', 'Start the local browser dashboard for transaction approval')
+    .addOptionalParam('port', 'Override the dashboard port', undefined, config_1.types.int)
+    .setAction(async ({ port }, hre) => {
+    const config = resolveTaskConfig(hre.config.dashboardPlugin, { port });
+    const server = await ensureServer(config);
+    // eslint-disable-next-line no-console
+    console.log(chalk_1.default.green(`Dashboard network: ${chalk_1.default.bold(config.networkName)}`));
+    // eslint-disable-next-line no-console
+    console.log(chalk_1.default.green(`RPC endpoint: ${chalk_1.default.bold(server.getRpcUrl())}`));
+    // eslint-disable-next-line no-console
+    console.log(chalk_1.default.green(`Open this page in MetaMask-enabled Chrome/Edge: ${chalk_1.default.bold(server.getOrigin())}`));
+    if (config.autoOpen) {
+        await (0, open_1.default)(server.getOrigin());
+    }
+    await waitForShutdown(server);
+    activeServer = undefined;
+});
+(0, config_1.subtask)(task_names_1.TASK_COMPILE).setAction(async (taskArgs, hre, runSuper) => {
+    const result = await runSuper(taskArgs);
+    void relayArtifactsFromHre(hre, hre.config.dashboardPlugin).catch(() => {
+        // The artifact relay is best-effort; compilation should still succeed when the dashboard isn't running.
+    });
+    return result;
+});
+async function startDashboardServer(config) {
+    return ensureServer(config);
+}
+async function relayCompiledArtifacts(hre, config = hre.config.dashboardPlugin) {
+    await relayArtifactsFromHre(hre, config);
+}
+const dashboardPlugin = {
+    startDashboardServer,
+    relayCompiledArtifacts,
+};
+exports.default = dashboardPlugin;
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":";;;;;AAwJA,oDAIC;AAED,wDAKC;AAnKD,0DAA6B;AAE7B,kDAA0B;AAC1B,2CAAoE;AACpE,iEAAgE;AAEhE,gDAAwB;AAExB,kDAA6F;AAC7F,0CAAmF;AACnF,2CAKwB;AAExB,IAAI,YAKS,CAAC;AAEd,SAAS,kBAAkB,CAAC,IAAY;IACtC,OAAO,oBAAoB,IAAI,EAAE,CAAC;AACpC,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAY;IACtC,OAAO,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC;AAC3C,CAAC;AAED,SAAS,qBAAqB,CAC5B,QAAiC,EACjC,MAAqC;IAErC,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,kCAAyB,CAAC;IACpE,MAAM,QAAQ,GAAG,QAAQ,CAAC,WAAW,CAAwC,CAAC;IAE9E,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,QAAQ,CAAC,WAAW,CAAC,GAAG;YACtB,GAAG,EAAE,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC;YACpC,OAAO,EAAE,CAAC;SACX,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAI,QAAQ,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC/B,QAAQ,CAAC,GAAG,GAAG,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC;IAED,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACnC,QAAQ,CAAC,OAAO,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CACxB,UAAyC,EACzC,SAAiC;IAEjC,OAAO,IAAA,qCAA4B,EAAC;QAClC,IAAI,EAAE,SAAS,EAAE,IAAI,IAAI,UAAU,CAAC,IAAI;QACxC,WAAW,EAAE,SAAS,EAAE,WAAW,IAAI,UAAU,CAAC,WAAW;QAC7D,QAAQ,EAAE,SAAS,EAAE,QAAQ,IAAI,UAAU,CAAC,QAAQ;KACrD,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,MAAqC;IAC/D,IAAI,YAAY,IAAI,YAAY,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC;QAC7D,OAAO,YAAY,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACnC,CAAC;IAED,MAAM,MAAM,GAAG,IAAA,6BAAqB,EAAC;QACnC,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC;KACrC,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACrB,YAAY,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAClC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,MAA6B;IAC1D,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAClC,IAAI,OAAO,GAAG,KAAK,CAAC;QAEpB,MAAM,QAAQ,GAAG,GAAG,EAAE;YACpB,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO;YACT,CAAC;YAED,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAChC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YACjC,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC,CAAC;QAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,qBAAqB,CAClC,GAA8B,EAC9B,MAAqC;IAErC,MAAM,SAAS,GAAG,MAAM,IAAA,yCAA6B,EAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAClF,MAAM,IAAA,oCAAwB,EAAC,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC;AAC7E,CAAC;AAED,IAAA,qBAAY,EAAC,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE;IAClC,MAAM,QAAQ,GAAG,IAAA,qCAA4B,EAAC,UAAU,CAAC,eAAe,CAAC,CAAC;IAC1E,MAAM,CAAC,eAAe,GAAG,QAAQ,CAAC;IAClC,qBAAqB,CAAC,MAAM,CAAC,QAAmC,EAAE,QAAQ,CAAC,CAAC;AAC9E,CAAC,CAAC,CAAC;AAEH,IAAA,aAAI,EAAC,WAAW,EAAE,4DAA4D,CAAC;KAC5E,gBAAgB,CAAC,MAAM,EAAE,6BAA6B,EAAE,SAAS,EAAE,cAAK,CAAC,GAAG,CAAC;KAC7E,SAAS,CAAC,KAAK,EAAE,EAAE,IAAI,EAAqB,EAAE,GAAG,EAAE,EAAE;IACpD,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IACvE,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;IAE1C,sCAAsC;IACtC,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,KAAK,CAAC,sBAAsB,eAAK,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;IACjF,sCAAsC;IACtC,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,KAAK,CAAC,iBAAiB,eAAK,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5E,sCAAsC;IACtC,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,KAAK,CAAC,mDAAmD,eAAK,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAE9G,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,MAAM,IAAA,cAAI,EAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,MAAM,eAAe,CAAC,MAAM,CAAC,CAAC;IAC9B,YAAY,GAAG,SAAS,CAAC;AAC3B,CAAC,CAAC,CAAC;AAEL,IAAA,gBAAO,EAAC,yBAAY,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE;IAChE,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAExC,KAAK,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;QACrE,wGAAwG;IAC1G,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC,CAAC;AAEI,KAAK,UAAU,oBAAoB,CACxC,MAAqC;IAErC,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC;AAEM,KAAK,UAAU,sBAAsB,CAC1C,GAA8B,EAC9B,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,eAAe;IAEnC,MAAM,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,eAAe,GAAG;IACtB,oBAAoB;IACpB,sBAAsB;CACvB,CAAC;AAEF,kBAAe,eAAe,CAAC"}

package/dist/server/artifacts.d.ts

@@ -0,0 +1,10 @@
+import type { ArtifactPayload, DecodedContractCall, JsonRpcRequest, PendingRpcRequest } from '../types/rpc';
+export declare class ArtifactRegistry {
+    private readonly selectors;
+    upsertArtifacts(artifacts: ArtifactPayload[]): void;
+    decodeRequest(request: JsonRpcRequest | PendingRpcRequest): DecodedContractCall | undefined;
+    decodeCalldata(calldata: string): DecodedContractCall;
+    private getSelector;
+}
+export declare function collectArtifactsFromDirectory(directory: string): Promise<ArtifactPayload[]>;
+export declare function postArtifactsToDashboard(serverOrigin: string, artifacts: ArtifactPayload[], timeoutMs?: number): Promise<boolean>;

package/dist/server/artifacts.js

@@ -0,0 +1,191 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArtifactRegistry = void 0;
+exports.collectArtifactsFromDirectory = collectArtifactsFromDirectory;
+exports.postArtifactsToDashboard = postArtifactsToDashboard;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const ethers_1 = require("ethers");
+function formatDecodedValue(value) {
+    if (typeof value === 'bigint') {
+        return value.toString();
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean' || value === null || value === undefined) {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => formatDecodedValue(entry)).join(', ')}]`;
+    }
+    if (typeof value === 'object') {
+        const objectValue = value;
+        return JSON.stringify(Object.fromEntries(Object.entries(objectValue).map(([key, nestedValue]) => [key, formatDecodedValue(nestedValue)])));
+    }
+    return String(value);
+}
+function getTransactionObject(params) {
+    if (Array.isArray(params) && params.length > 0) {
+        const [first] = params;
+        if (first && typeof first === 'object') {
+            return first;
+        }
+    }
+    if (params && typeof params === 'object' && !Array.isArray(params)) {
+        return params;
+    }
+    return undefined;
+}
+class ArtifactRegistry {
+    selectors = new Map();
+    upsertArtifacts(artifacts) {
+        for (const artifact of artifacts) {
+            if (!artifact.abi.length) {
+                continue;
+            }
+            const iface = new ethers_1.Interface(artifact.abi);
+            for (const fragment of iface.fragments) {
+                if (fragment.type !== 'function') {
+                    continue;
+                }
+                const functionFragment = fragment;
+                const selector = this.getSelector(iface, functionFragment);
+                const existing = this.selectors.get(selector) ?? [];
+                existing.push({ artifact, iface, fragment: functionFragment });
+                this.selectors.set(selector, existing);
+            }
+        }
+    }
+    decodeRequest(request) {
+        if (request.method !== 'eth_sendTransaction') {
+            return undefined;
+        }
+        const transaction = getTransactionObject(request.params);
+        const calldata = transaction?.data;
+        if (typeof calldata !== 'string') {
+            return undefined;
+        }
+        return this.decodeCalldata(calldata);
+    }
+    decodeCalldata(calldata) {
+        if (!calldata.startsWith('0x') || calldata.length < 10) {
+            return {
+                matched: false,
+                args: [],
+            };
+        }
+        const selector = calldata.slice(0, 10).toLowerCase();
+        const entries = this.selectors.get(selector);
+        if (!entries?.length) {
+            return {
+                matched: false,
+                selector,
+                args: [],
+            };
+        }
+        for (const entry of entries) {
+            try {
+                const decoded = entry.iface.decodeFunctionData(entry.fragment, calldata);
+                return {
+                    matched: true,
+                    selector,
+                    contractName: entry.artifact.contractName,
+                    functionName: entry.fragment.name,
+                    signature: entry.fragment.format(),
+                    args: Array.from(decoded).map((value) => formatDecodedValue(value)),
+                };
+            }
+            catch {
+                continue;
+            }
+        }
+        return {
+            matched: false,
+            selector,
+            args: [],
+        };
+    }
+    getSelector(iface, fragment) {
+        const fragmentWithSelector = fragment;
+        if (typeof fragmentWithSelector.selector === 'string') {
+            return fragmentWithSelector.selector.toLowerCase();
+        }
+        const ifaceWithSighash = iface;
+        if (typeof ifaceWithSighash.getSighash === 'function') {
+            return ifaceWithSighash.getSighash(fragment).toLowerCase();
+        }
+        const resolved = iface.getFunction(fragment.format());
+        if (!resolved) {
+            throw new Error(`Unable to resolve function fragment for ${fragment.format()}.`);
+        }
+        const resolvedWithSelector = resolved;
+        if (typeof resolvedWithSelector.selector !== 'string') {
+            throw new Error(`Unable to derive selector for ${fragment.format()}.`);
+        }
+        return resolvedWithSelector.selector.toLowerCase();
+    }
+}
+exports.ArtifactRegistry = ArtifactRegistry;
+async function collectJsonFiles(directory) {
+    const entries = await (0, promises_1.readdir)(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = node_path_1.default.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await collectJsonFiles(fullPath)));
+            continue;
+        }
+        if (entry.isFile() && entry.name.endsWith('.json') && !entry.name.endsWith('.dbg.json')) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+async function collectArtifactsFromDirectory(directory) {
+    const files = await collectJsonFiles(directory);
+    const artifacts = [];
+    for (const file of files) {
+        const contents = await (0, promises_1.readFile)(file, 'utf8');
+        const parsed = JSON.parse(contents);
+        if (!parsed.contractName || !Array.isArray(parsed.abi)) {
+            continue;
+        }
+        artifacts.push({
+            contractName: parsed.contractName,
+            sourceName: parsed.sourceName,
+            abi: parsed.abi,
+            bytecode: parsed.bytecode,
+            deployedBytecode: parsed.deployedBytecode,
+        });
+    }
+    return artifacts;
+}
+async function postArtifactsToDashboard(serverOrigin, artifacts, timeoutMs = 1_500) {
+    if (!artifacts.length) {
+        return true;
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(`${serverOrigin.replace(/\/$/, '')}/artifacts`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({ artifacts }),
+            signal: controller.signal,
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/server/artifacts.js.map

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

package/dist/server/proxy.d.ts

@@ -0,0 +1,15 @@
+import { type ArtifactPayload } from '../types/rpc';
+export interface DashboardServerOptions {
+    port: number;
+    host?: string;
+    uiDir?: string;
+    requestTimeoutMs?: number;
+}
+export interface DashboardServerHandle {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getOrigin(): string;
+    getRpcUrl(): string;
+    pushArtifacts(artifacts: ArtifactPayload[]): void;
+}
+export declare function createDashboardServer(options: DashboardServerOptions): DashboardServerHandle;