Expose etherscan instance

[schaable]

Closes: #7644

Documentation: (readme) was updated with the new API.

Usage examples

Contract deployment and verification

/**
 * NOTE: This script demonstrates manual contract verification using the
 * low-level verifier API. This is NOT the recommended way to verify contracts.
 *
 * For standard contract verification, use the `verifyContract` function instead:
 * https://github.com/NomicFoundation/hardhat/tree/main/v-next/hardhat-verify#programmatic-verification
 *
 * Only use this manual approach if you have a specific scenario that cannot be
 * covered by the standard `verifyContract` function.
 */

import type { BuildInfo } from "hardhat/types/artifacts";

import fsPromises from "node:fs/promises";
import path from "node:path";
import { setTimeout } from "node:timers/promises";

import { network, artifacts } from "hardhat";

const { viem, verifier } = await network.connect("sepolia");

const contract = await viem.deployContract("Counter", [], { confirmations: 5 });
const contractAddress = contract.address;

console.log("Contract deployed at:", contractAddress);

const artifact = await artifacts.readArtifact("Counter");

const buildInfoPath = path.join(
  process.cwd(),
  "artifacts",
  "build-info",
  `${artifact.buildInfoId}.json`,
);
const content = await fsPromises.readFile(buildInfoPath, { encoding: "utf8" });
const buildInfo: BuildInfo = JSON.parse(content);

const guid = await verifier.etherscan.verify({
  contractAddress: contractAddress,
  compilerInput: buildInfo.input,
  contractName: `${artifact.inputSourceName}:Counter`,
  compilerVersion: `v${buildInfo.solcLongVersion}`,
  constructorArguments: "",
});

// wait for 1 second before polling so that Etherscan has time to process
// the verification request
await setTimeout(1000);

const response = await verifier.etherscan.pollVerificationStatus(
  guid,
  contractAddress,
  `${artifact.inputSourceName}:Counter`,
);

console.log("Verification response:", response);

Using customApiCall to fetch event logs

import { network } from "hardhat";
import { keccak256, toBytes } from "viem";

const { verifier } = await network.connect("sepolia");

const logs = await verifier.etherscan.customApiCall({
  module: "logs",
  action: "getLogs",
  fromBlock: "0",
  toBlock: "latest",
  address: "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
  topic0: keccak256(toBytes("Transfer(address,address,uint256)")),
});

console.log("Logs:", logs);

[changeset-bot]

🦋 Changeset detected

Latest commit: 7ad8412

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@nomicfoundation/hardhat-verify	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Pull request overview

This PR exposes the Etherscan verification instance to users through the network connection object, allowing direct access to Etherscan API methods and verification functionality.

Changes:

• Added a verifier property to NetworkConnection containing an etherscan instance with getter methods and verification operations
• Implemented customApiCall method for making arbitrary Etherscan API requests
• Created lazy initialization wrapper to defer Etherscan instance creation until needed

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
v-next/hardhat-verify/src/types.ts	Defines public types for the verifier helpers interface and exports Etherscan-related types
v-next/hardhat-verify/src/type-extensions.ts	Extends NetworkConnection type to include the verifier property
v-next/hardhat-verify/src/internal/verifier.ts	Implements the Verifier class that creates and holds the lazy Etherscan instance
v-next/hardhat-verify/src/internal/hook-handlers/network.ts	Adds network hook handler to attach verifier to new connections
v-next/hardhat-verify/src/internal/etherscan.types.ts	Defines types for Etherscan API interactions including LazyEtherscan interface
v-next/hardhat-verify/src/internal/etherscan.ts	Implements customApiCall method and LazyEtherscanImpl wrapper class
v-next/hardhat-verify/src/internal/verification.ts	Exports createVerificationProviderInstance for use by LazyEtherscanImpl
v-next/hardhat-verify/src/index.ts	Registers the network hook handler
v-next/hardhat-verify/package.json	Adds export for types module
v-next/hardhat-verify/test/etherscan.ts	Tests for the customApiCall method
v-next/hardhat-verify/test/hook-handlers/network.ts	Tests verifying the verifier property is correctly attached to connections

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ChristopherDedominici]

I left a very minor comment, other than that, LGTM