npm package: @pinto-org/hardhat-etherscan
Description: Hardhat plugin for verifying contracts on etherscan (Pinto fork with Etherscan v2 API fixes)
Author: Nomic Labs LLC
Latest version: 3.1.8-pinto.1

# @nomiclabs/hardhat-etherscan - Etherscan v2 API Compatible Fork

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A fork of [`@nomiclabs/hardhat-etherscan`](https://www.npmjs.com/package/@nomiclabs/hardhat-etherscan) with fixes for **Etherscan v2 API compatibility** on any chain.

> **Note:** The original `@nomiclabs/hardhat-etherscan` package is [officially deprecated](https://www.npmjs.com/package/@nomiclabs/hardhat-etherscan). For Hardhat 3.0+, use [`@nomicfoundation/hardhat-verify`](https://www.npmjs.com/package/@nomicfoundation/hardhat-verify) instead. This fork exists for projects still using Hardhat 2.x that need v2 API support with query parameters.

---

## 🐛 The Problem

When verifying contracts on **any chain** that uses Etherscan v2 API with query parameters (e.g., Basescan, or any custom explorer), the original plugin fails with:

```
Error in plugin @nomiclabs/hardhat-etherscan: The Etherscan API responded with a failure status.
The verification may still succeed but should be checked manually.
Reason: Missing chainid parameter (required for v2 api)
```

**Root cause:** Many Etherscan v2 API implementations require query parameters like `chainid` in all requests. The original plugin was **stripping these parameters** when building query strings for verification status checks.

**Affected chains:** Any chain where you configure `apiURL` with query parameters:
- Base (Basescan)
- Any L2 or sidechain using Etherscan API v2
- Custom block explorers requiring query parameters

---

## ✅ The Fix

This fork preserves existing URL query parameters (like `chainid`) when making API requests.

### Changed Files

- **`src/etherscan/EtherscanService.ts`**
  - Modified `getVerificationStatus()` function
  - Modified `isAlreadyVerified()` function

- **`dist/src/etherscan/EtherscanService.js`**
  - Compiled JavaScript with same fixes

### Technical Details

**Before (broken):**
```javascript
// ❌ Old behavior - overwrites chainid parameter
const parameters = new URLSearchParams({ ...req });
const urlWithQuery = new URL(url);
urlWithQuery.search = parameters.toString(); // chainid LOST!
```

**After (fixed):**
```javascript
// ✅ New behavior - preserves chainid parameter
const urlWithQuery = new URL(url);
const mergedParams = new URLSearchParams(urlWithQuery.search); // Get existing params
for (const [key, value] of Object.entries(req)) {
  mergedParams.set(key, value); // Merge new params
}
urlWithQuery.search = mergedParams.toString(); // chainid PRESERVED!
```

---

## 📦 Installation

### Using npm/yarn with GitHub dependency

```bash
npm install github:pinto-org/hardhat-etherscan
# or
yarn add github:pinto-org/hardhat-etherscan
```

### In your package.json

```json
{
  "dependencies": {
    "@nomiclabs/hardhat-etherscan": "github:pinto-org/hardhat-etherscan#master"
  }
}
```

---

## ⚙️ Configuration

Configure your `hardhat.config.js` with any **Etherscan v2 API URL** that includes query parameters:

### Example: Base Network (Basescan)

```javascript
require("@nomiclabs/hardhat-etherscan");

module.exports = {
  networks: {
    base: {
      url: process.env.BASE_RPC_URL || "https://mainnet.base.org",
      accounts: [process.env.PRIVATE_KEY]
    }
  },
  etherscan: {
    apiKey: {
      base: process.env.BASESCAN_API_KEY
    },
    customChains: [
      {
        network: "base",
        chainId: 8453,
        urls: {
          // ↓ Important: Query parameters (like chainid) are now preserved
          apiURL: "https://api.basescan.org/api?chainid=8453",
          browserURL: "https://basescan.org"
        }
      }
    ]
  },
  solidity: "0.8.20"
};
```

### Generic Pattern for Any Chain

```javascript
customChains: [
  {
    network: "your-chain",
    chainId: <YOUR_CHAIN_ID>,
    urls: {
      // Add any required query parameters to the API URL
      apiURL: "https://api.your-explorer.com/api?chainid=<YOUR_CHAIN_ID>",
      browserURL: "https://your-explorer.com"
    }
  }
]
```

---

## 🚀 Usage

Same as the original package:

```bash
npx hardhat verify --network base <contract-address> <constructor-args>
```

### Example

```bash
npx hardhat verify --network base 0x1234...5678 "Constructor arg 1" 42
```

### Complex Arguments

For contracts with complex constructor arguments, create an `arguments.js` file:

```javascript
module.exports = [
  "0x1234567890123456789012345678901234567890",
  50,
  {
    x: 10,
    y: 5
  }
];
```

Then verify with:

```bash
npx hardhat verify --network base --constructor-args arguments.js 0x1234...5678
```

---

## 🌐 Compatibility

| Package | Version |
|---------|---------|
| **Hardhat** | 2.x |
| **Node.js** | 14+ |
| **Networks** | All Etherscan-compatible explorers (especially v2 API) |

### Tested With

- ✅ **Base** (Basescan mainnet & testnet)
- ✅ **Ethereum** mainnet (Etherscan)
- ✅ Any chain using **Etherscan API v2** with query parameters

### Compatible With

This fork works with **any block explorer** that:
- Uses Etherscan-compatible API
- Requires query parameters in the API URL
- Implements v2 API standards

Examples include L2s, sidechains, and custom explorers requiring `chainid` or other query parameters.

---

## ⚠️ For Hardhat 3.0+ Users

If you're using **Hardhat 3.0 or later**, use the official replacement package instead:

```bash
npm install --save-dev @nomicfoundation/hardhat-verify
```

This fork is specifically for Hardhat 2.x projects that cannot easily upgrade.

---

## 🔧 Maintenance

- **Base version:** `@nomiclabs/hardhat-etherscan@3.1.8` (final release)
- **Status:** Frozen at this version (original package is deprecated)
- **Updates:** Only critical security fixes will be applied

---

## 🤝 Contributing

Found another issue or have improvements?

1. Open an issue describing the problem
2. Fork this repo
3. Submit a PR with your fix
4. Include tests if possible

---

## 📚 Related Links

- [Original package on npm](https://www.npmjs.com/package/@nomiclabs/hardhat-etherscan)
- [Hardhat GitHub](https://github.com/NomicFoundation/hardhat)
- [Basescan API Documentation](https://docs.basescan.org/)
- [Pinto Protocol](https://github.com/pinto-org/protocol)

---

## 📄 License

MIT (same as original package)

---

## 💬 Credits

- **Original package:** [Nomic Labs LLC](https://github.com/NomicFoundation/hardhat)
- **Fork maintained by:** [Pinto](https://github.com/pinto-org)
- **Contributors:** See [GitHub contributors](https://github.com/pinto-org/hardhat-etherscan/graphs/contributors)

---

## 🐛 When You Need This Fork

If you see **any** of these errors, you need this fork:

```
Missing chainid parameter (required for v2 api)
```

```
Missing <parameter> parameter
```

Or any error indicating that query parameters are being stripped from your API URL.

**Solution:** Use this fork with query parameters in your `apiURL` configuration as shown above. This fork preserves all query parameters throughout the verification process.