0
# Network Support
1

2
Built-in support for major blockchain networks and block explorers, with the ability to add custom networks through configuration.
3

4
## Capabilities
5

6
### Built-in Network Configuration
7

8
The plugin includes built-in support for 20+ blockchain networks and their corresponding block explorers.
9

10
```typescript { .api }
11
/**
12
 * Chain configuration mapping network names to their settings
13
 * Contains built-in support for major blockchain networks
14
 */
15
type ChainConfig = Record<string, EtherscanChainConfig>;
16

17
/**
18
 * Configuration for a specific blockchain network
19
 * Defines chain ID and block explorer URLs
20
 */
21
interface EtherscanChainConfig {
22
  /** Blockchain chain ID */
23
  chainId: number;
24
  /** Block explorer URLs for this network */
25
  urls: EtherscanURLs;
26
}
27

28
/**
29
 * Built-in chain configuration object
30
 * Contains pre-configured settings for supported networks
31
 */
32
declare const chainConfig: ChainConfig;
33
```
34

35
### Supported Networks
36

37
The plugin includes built-in support for the following networks:
38

39
**Ethereum Networks:**
40
- `mainnet` (Chain ID: 1) - Ethereum Mainnet via etherscan.io
41
- `ropsten` (Chain ID: 3) - Ropsten Testnet via ropsten.etherscan.io
42
- `rinkeby` (Chain ID: 4) - Rinkeby Testnet via rinkeby.etherscan.io
43
- `goerli` (Chain ID: 5) - Goerli Testnet via goerli.etherscan.io
44
- `kovan` (Chain ID: 42) - Kovan Testnet via kovan.etherscan.io
45
- `sepolia` (Chain ID: 11155111) - Sepolia Testnet via sepolia.etherscan.io
46

47
**Layer 2 Networks:**
48
- `optimisticEthereum` (Chain ID: 10) - Optimism Mainnet via optimistic.etherscan.io
49
- `optimisticGoerli` (Chain ID: 420) - Optimism Goerli via goerli-optimism.etherscan.io
50
- `arbitrumOne` (Chain ID: 42161) - Arbitrum One via arbiscan.io
51
- `arbitrumGoerli` (Chain ID: 421613) - Arbitrum Goerli via goerli.arbiscan.io
52
- `arbitrumTestnet` (Chain ID: 421611) - Arbitrum Testnet via testnet.arbiscan.io
53

54
**Polygon Networks:**
55
- `polygon` (Chain ID: 137) - Polygon Mainnet via polygonscan.com
56
- `polygonMumbai` (Chain ID: 80001) - Polygon Mumbai via mumbai.polygonscan.com
57

58
**BSC Networks:**
59
- `bsc` (Chain ID: 56) - BSC Mainnet via bscscan.com
60
- `bscTestnet` (Chain ID: 97) - BSC Testnet via testnet.bscscan.com
61

62
**Other Networks:**
63
- `avalanche` (Chain ID: 43114) - Avalanche C-Chain via snowtrace.io
64
- `avalancheFujiTestnet` (Chain ID: 43113) - Avalanche Fuji via testnet.snowtrace.io
65
- `opera` (Chain ID: 250) - Fantom Opera via ftmscan.com
66
- `ftmTestnet` (Chain ID: 4002) - Fantom Testnet via testnet.ftmscan.com
67
- `moonbeam` (Chain ID: 1284) - Moonbeam via moonbeam.moonscan.io
68
- `moonriver` (Chain ID: 1285) - Moonriver via moonriver.moonscan.io
69
- `moonbaseAlpha` (Chain ID: 1287) - Moonbase Alpha via moonbase.moonscan.io
70
- `gnosis` (Chain ID: 100) - Gnosis Chain via gnosisscan.io
71
- `xdai` (Chain ID: 100) - xDai (alias for Gnosis) via gnosisscan.io
72
- `aurora` (Chain ID: 1313161554) - Aurora Mainnet via aurorascan.dev
73
- `auroraTestnet` (Chain ID: 1313161555) - Aurora Testnet via testnet.aurorascan.dev
74

75
### Network Endpoint Resolution
76

77
```typescript { .api }
78
/**
79
 * Determine correct Etherscan endpoints for a network
80
 * Automatically detects network from provider and resolves appropriate URLs
81
 * @param provider - Ethereum provider for the current network
82
 * @param networkName - Hardhat network name
83
 * @param chainConfig - Built-in chain configuration
84
 * @param customChains - User-defined custom chains
85
 * @returns Network entry with resolved URLs
86
 * @throws Error for unsupported networks
87
 */
88
function getEtherscanEndpoints(
89
  provider: EthereumProvider,
90
  networkName: string,
91
  chainConfig: ChainConfig,
92
  customChains: CustomChain[]
93
): Promise<EtherscanNetworkEntry>;
94
```
95

96
**Usage Examples:**
97

98
```typescript
99
import { getEtherscanEndpoints } from "@nomiclabs/hardhat-etherscan";
100

101
// Automatically resolve endpoints based on connected network
102
const networkInfo = await getEtherscanEndpoints(
103
  hre.network.provider,
104
  hre.network.name,
105
  chainConfig,
106
  hre.config.etherscan.customChains
107
);
108

109
console.log(networkInfo.network); // "mainnet"
110
console.log(networkInfo.urls.apiURL); // "https://api.etherscan.io/api"
111
console.log(networkInfo.urls.browserURL); // "https://etherscan.io"
112
```
113

114
### Network Discovery and Validation
115

116
```typescript { .api }
117
/**
118
 * Retrieve contract bytecode from network
119
 * Used to fetch deployed contract bytecode for verification matching
120
 * @param address - Contract address
121
 * @param provider - Ethereum provider
122
 * @param networkName - Network name for error reporting
123
 * @returns Hex-encoded bytecode string
124
 * @throws Error if contract not found or network issues
125
 */
126
function retrieveContractBytecode(
127
  address: string,
128
  provider: EthereumProvider,
129
  networkName: string
130
): Promise<string>;
131
```
132

133
### Supported Networks Display
134

135
```typescript { .api }
136
/**
137
 * Print table of all supported networks
138
 * Displays both built-in networks and user-defined custom chains
139
 * @param customChains - User-defined custom chains to include in output
140
 */
141
function printSupportedNetworks(customChains: CustomChain[]): Promise<void>;
142
```
143

144
**Usage Examples:**
145

146
```bash
147
# List all supported networks
148
npx hardhat verify --list-networks
149
```
150

151
Output format:
152
```
153
Networks supported by hardhat-etherscan:
154

155
┌─────────────────────┬──────────┐
156
│ network             │ chain id │
157
├─────────────────────┼──────────┤
158
│ mainnet             │ 1        │
159
│ goerli              │ 5        │
160
│ sepolia             │ 11155111 │
161
│ optimisticEthereum  │ 10       │
162
│ arbitrumOne         │ 42161    │
163
│ polygon             │ 137      │
164
│ bsc                 │ 56       │
165
└─────────────────────┴──────────┘
166

167
Custom networks added by you or by plugins:
168

169
┌─────────────────┬──────────┐
170
│ network         │ chain id │
171
├─────────────────┼──────────┤
172
│ customNetwork   │ 1234     │
173
└─────────────────┴──────────┘
174
```
175

176
### Custom Network Integration
177

178
Custom networks defined in configuration are automatically integrated with built-in networks:
179

180
```typescript { .api }
181
// Custom networks take precedence over built-in networks with same chain ID
182
// and are included in network validation and endpoint resolution
183
```
184

185
**Usage Examples:**
186

187
```typescript
188
// hardhat.config.ts - Adding custom network support
189
export default {
190
  etherscan: {
191
    apiKey: {
192
      myCustomNetwork: "CUSTOM_API_KEY"
193
    },
194
    customChains: [
195
      {
196
        network: "myCustomNetwork",
197
        chainId: 1337,
198
        urls: {
199
          apiURL: "https://api.my-custom-explorer.com/api",
200
          browserURL: "https://my-custom-explorer.com"
201
        }
202
      }
203
    ]
204
  },
205
  networks: {
206
    myCustomNetwork: {
207
      url: "https://rpc.my-custom-network.com",
208
      chainId: 1337,
209
      // ... other network config
210
    }
211
  }
212
};
213
```
214

215
### Error Handling
216

217
```typescript { .api }
218
/**
219
 * Throw error for unsupported networks
220
 * @param networkName - Network name that was requested
221
 * @param chainId - Chain ID that was detected
222
 * @throws NomicLabsHardhatPluginError with helpful error message
223
 */
224
function throwUnsupportedNetwork(networkName: string, chainId: number): never;
225
```