diff --git a/README.md b/README.md index db6081d..27a9fea 100644 --- a/README.md +++ b/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 -- 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 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 diff --git a/image-1.png b/image-1.png new file mode 100644 index 0000000..51a957b Binary files /dev/null and b/image-1.png differ diff --git a/packages/example-project/README.md b/packages/example-project/README.md index 39bd098..5c58495 100644 --- a/packages/example-project/README.md +++ b/packages/example-project/README.md @@ -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. diff --git a/packages/plugin/README.md b/packages/plugin/README.md index 9656071..da61db7 100644 --- a/packages/plugin/README.md +++ b/packages/plugin/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 -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 - - 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 diff --git a/packages/plugin/package.json b/packages/plugin/package.json index ecf71eb..e2a19fc 100644 --- a/packages/plugin/package.json +++ b/packages/plugin/package.json @@ -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", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 58c7241..3e362ed 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -45,8 +45,8 @@ importers: packages/plugin: dependencies: '@openscan/explorer': - specifier: 1.2.3-alpha - version: 1.2.3-alpha + specifier: 1.2.5-alpha + version: 1.2.5-alpha devDependencies: '@eslint/js': specifier: ^9.35.0 @@ -585,8 +585,8 @@ packages: resolution: {integrity: sha512-q4n32/FNKIhQ3zQGGw5CvPF6GTvDCpYwIf7bEY/dZTZbgfDsHyjJwURxUJf3VQuuJj+fDIFl4+KkBVbw4Ef6jA==} engines: {node: '>= 12'} - '@openscan/explorer@1.2.3-alpha': - resolution: {integrity: sha512-yF6mzIJ1KLPURbGaqFBJNBIRN+nCxYkLUQMnzIX7gY18bcKRe7e3y8bLO7Vugyk9+mokiRerKf2bnP8xYY1lMQ==} + '@openscan/explorer@1.2.5-alpha': + resolution: {integrity: sha512-sNPRS/zMjZnYvmAgRa7C1YG5O41yjvrxX7Bkf3jFv8TNFZBqtrgavBCI5MSD0hGMg1YtW2o836lUj3rGacw39g==} '@pkgjs/parseargs@0.11.0': resolution: {integrity: sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==} @@ -2692,7 +2692,7 @@ snapshots: '@nomicfoundation/solidity-analyzer-linux-x64-musl': 0.1.2 '@nomicfoundation/solidity-analyzer-win32-x64-msvc': 0.1.2 - '@openscan/explorer@1.2.3-alpha': {} + '@openscan/explorer@1.2.5-alpha': {} '@pkgjs/parseargs@0.11.0': optional: true