npm package: @rubanrubi/hardhat-dashboard
Description: A Hardhat plugin that routes transaction signing through a local browser dashboard.
Latest version: 0.2.2

# @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.