Merge pull request #9 from MatiasOS/dev

Release v1.3.0

Author: MatiasOS

README.md

@@ -1,78 +1,70 @@
-# Hardhat 3 plugin template
+# @openscan/hardhat-plugin
 
-This repository is a template for creating a Hardhat 3 plugin.
+A Hardhat 3 plugin that automatically launches a local [OpenScan Explorer](https://openscan.eth.link) and adds clickable transaction links to your terminal.
 
-## Getting started
-
-> This repository is structured as a pnpm monorepo, so make sure you have [`pnpm`](https://pnpm.io/) installed first
-
-To get started, clone the repository and run:
-
-```sh
-pnpm install
-pnpm build
-```
+![OpenScan hardhat logs](image.png)
 
-This will install all the dependencies and build the plugin.
+![OpenScan Call Tree](image-1.png)
 
-You can now run the tests of the plugin with:
+## Features
 
-```sh
-pnpm test
-```
+- **Local block explorer** — auto-launches on `hardhat node` and opens your browser
+- **Clickable terminal links** — transaction hashes, addresses, and blocks are OSC 8 hyperlinks to the explorer
+- **Contract deployment tracking** — matches bytecode to artifacts so the explorer shows contract names, ABIs, and source code
+- **Works with Hardhat Ignition and raw deploy scripts**
 
-And try the plugin out in `packages/example-project` with:
+## Quick Start
 
-```sh
-cd packages/example-project
-pnpm hardhat node
+```bash
+npm install --save-dev @openscan/hardhat-plugin
 ```
 
-This will automatically:
+Add the plugin to your `hardhat.config.ts`:
 
-- Launch the OpenScan Explorer webapp on <http://localhost:3030>
-- Open your browser to the explorer
-- Log transaction links with OpenScan URLs
+```ts
+import { defineConfig } from "hardhat/config";
+import openScanPlugin from "@openscan/hardhat-plugin";
 
-![OpenScan hardhat logs](image.png)
-
-## Understanding the repository structure
-
-### Monorepo structure
-
-This repository is structured as a pnpm monorepo with the following packages:
 
-- `packages/plugin`: The plugin itself.
-- `packages/example-project`: An example Hardhat 3 project that uses the plugin.
+export default defineConfig({
+  plugins: [openScanPlugin],
+  solidity: "0.8.29",
+});
+```
 
-All the development will happen in the `packages/plugin` directory, while `packages/example-project` is a playground to experiment with your plugin, and manually test it.
+Start a node:
 
-### Plugin template structure
+```bash
+npx hardhat node
+```
 
-The `packages/plugin` directory has a complete plugin example. It includes:
+The OpenScan Explorer will launch at <http://localhost:3030> and your browser will open automatically.
 
-- A `README.md` file that documents the plugin.
-- A `src/index.ts` file that defines and exports the plugin.
-- A network Hook Handler, which is in `src/hooks/network.ts`, which shows how to define them, and prints OpenScan links.
+## Documentation
 
-### Github Actions setup
+See the [plugin README](packages/plugin/README.md) for full configuration options, usage examples, and troubleshooting.
 
-This repository is setup with a Github Actions workflow. You don't need to do anything to set it up, it runs on every push to `main`, on pull requests, and when manually triggered.
+## Contributing
 
-The workflow is equivalent to running this steps in the root of the repository:
+This repository is a pnpm monorepo. Make sure you have [`pnpm`](https://pnpm.io/) installed.
 
 ```sh
 pnpm install
 pnpm build
 pnpm test
-pnpm lint
 ```
 
-It runs using Node.js 24, on an `ubuntu-latest` runner.
+### Monorepo structure
+
+- `packages/plugin` — the plugin source code
+- `packages/example-project` — a Hardhat 3 project for manual testing
+
+Running `pnpm watch` in the root is useful during development — it rebuilds the plugin as you edit, so changes are picked up when you test in `packages/example-project`.
+
+### CI
+
+GitHub Actions runs on every push to `main` and on pull requests: install, build, test, and lint using Node.js 24.
 
-## Development setup
+## License
 
-- This repository includes a setup of typescript and eslint, based on the official recommendation of each project, and a a few custom rules that help building Hardhat plugins.
-- It also includes `prettier` to format the code, with its default configuration.
-- There are npm scripts in the root that should be enough to build, lint, test, etc.
-  - Running `pnpm watch` can be helpful when using the example project. If you keep a terminal running it, things will normally be rebuilt by the time you try them out in `packages/example-project`.
+MIT

image-1.png

@@ -1,6 +1,6 @@
-# A Hardhat 3 project that uses your plugin
+# A Hardhat 3 project that uses @openscan/hardhat-plugin
 
-This is an example project that uses your plugin.
+This is an example project that uses the OpenScan plugin.
 
 ## Getting started
 
@@ -45,10 +45,10 @@ pnpm run deploy
 pnpm run send-tx
 ```
 
-All transactions will be logged with clickable OpenScan links in the console. Check the code is verified
+All transactions will be logged with clickable OpenScan links in the console.
 
 ## What's inside the project?
 
-This is a minimal Hardhat 3 project that only has the built-in functionality of Hardhat and your plugin.
+This is a minimal Hardhat 3 project that only has the built-in functionality of Hardhat and the OpenScan plugin.
 
-This means that you don't have `ethers,` `viem`, `mocha`, nor the Node.js test runner plugins.
+This means that you don't have `ethers`, `viem`, `mocha`, nor the Node.js test runner plugins.

packages/example-project/README.md

@@ -1,112 +1,124 @@
-# `openscan-hardhat-links`
+# @openscan/hardhat-plugin
 
-A Hardhat plugin that automatically launches the OpenScan Explorer webapp and adds OpenScan links to all transaction logs.
+A Hardhat 3 plugin that automatically launches the OpenScan Explorer webapp and adds clickable OpenScan links to transaction logs in your terminal.
 
-## Installation
+Learn more at <https://openscan.eth.link>
 
-To install this plugin, run the following command:
+## Installation
 
 ```bash
-npm install --save-dev openscan-hardhat-links
+npm install --save-dev @openscan/hardhat-plugin
 ```
 
-In your `hardhat.config.ts` file, import the plugin and add it to the `plugins` array:
+## Configuration
+
+In your `hardhat.config.ts`, import the plugin and add it to the `plugins` array:
 
 ```ts
+import openScanPlugin from "@openscan/hardhat-plugin";
 import { defineConfig } from "hardhat/config";
-import openScanPlugin from "openscan-hardhat-links";
 
 export default defineConfig({
   plugins: [openScanPlugin],
+  solidity: "0.8.29",
   networks: {
-    ...
+    localhost: {
+      type: "http",
+      url: "http://127.0.0.1:8545",
+    },
   },
   openScan: {
-    url: "http://localhost:3030",
-    chainId: 31337,
+    url: "http://localhost:3030", // default
+    chainId: 31337, // default
   },
 });
-
 ```
 
+### Options
+
+| Option    | Type     | Default                   | Description                      |
+| --------- | -------- | ------------------------- | -------------------------------- |
+| `url`     | `string` | `"http://localhost:3030"` | URL where the explorer is served |
+| `chainId` | `number` | `31337`                   | Chain ID for the explorer links  |
+
 ## Features
 
-This plugin provides two main features:
+### Automatic Explorer Launch
+
+When the first network connection is established (e.g. via `npx hardhat node`), the plugin:
 
-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
+1. Checks if port 3030 is available
+2. Starts a local HTTP server serving the OpenScan Explorer webapp
+3. Opens your default browser to the explorer
 
-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
+The explorer serves contract artifacts (ABIs, source code, deployment addresses) so you can inspect deployed contracts directly in the browser. It supports both Hardhat Ignition deployments and raw deployment scripts.
+
+### Clickable Transaction Links
+
+The plugin intercepts JSON-RPC requests and logs clickable terminal links (via OSC 8 hyperlinks) for:
+
+- **`eth_sendTransaction`** — logs links to the transaction, sender, and recipient addresses
+- **`eth_getTransactionReceipt`** — logs links to the transaction, block, sender, recipient, and deployed contract address (if applicable)
+- **`eth_accounts`** — logs links to each account address
+
+### Contract Deployment Tracking
+
+When contracts are deployed (transactions with no `to` address), the plugin matches the creation bytecode against compiled artifacts in your project. This allows the explorer to display the contract name, ABI, and source code for deployed contracts — even without Hardhat Ignition.
 
 ## Usage
 
-### 1. Start the node
+### 1. Start the Hardhat node
 
 ```bash
 npx hardhat node
 ```
 
-The OpenScan Explorer will automatically launch and your browser will open to the explorer interface.
+The OpenScan Explorer will automatically launch and your browser will open.
 
-### 2. Deploy contracts with Ignition
+### 2. Deploy contracts
 
-In a separate terminal:
+With Hardhat Ignition:
 
 ```bash
 npx hardhat ignition deploy ignition/modules/Counter.ts --network localhost
 ```
 
-### 3. Deploy contracts with script
+Or with a script:
 
 ```bash
 npx hardhat run scripts/deploy.ts --network localhost
 ```
 
-### 4. Send transactions with script
+### 3. Send transactions
 
 ```bash
 npx hardhat run scripts/send-tx.ts --network localhost
 ```
 
-All transactions will be logged with clickable OpenScan links in the console. Check that the code is verified
-
-## 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.
+All transactions will be logged with clickable OpenScan links in the terminal.
 
 ## Requirements
 
 - Hardhat 3.x
-- Node.js 24+
-- Port 3030 must be available
+- Node.js 24
+- Port 3030 must be available (the explorer is hardcoded to this port — the `url` option only affects terminal link URLs, not the server port)
 
 ## Troubleshooting
 
-### Port 8545 or 3030 Already in Use
+### Port 3030 Already in Use
 
-If you see an error about port 8545 or 3030 being in use, you need to free up that port:
+If the explorer fails to start, check what is using the port:
 
 ```bash
-kill -9 $(lsof -t -i:8545)
-kill -9 $(lsof -t -i:3030)
+lsof -i :3030
 ```
+
+Then stop the conflicting process, or if it's a leftover Hardhat/OpenScan process:
+
+```bash
+kill $(lsof -t -i:3030)
+```
+
+## License
+
+MIT

packages/plugin/README.md

@@ -1,6 +1,6 @@
 {
   "name": "@openscan/hardhat-plugin",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Hardhat 3 plugin to use openscan explorer",
   "license": "MIT",
   "type": "module",
@@ -35,7 +35,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@openscan/explorer": "1.2.3-alpha"
+    "@openscan/explorer": "1.2.5-alpha"
   },
   "devDependencies": {
     "@eslint/js": "^9.35.0",