0
# Configuration
1

2
Configuration system for API keys, custom networks, and verification settings across multiple blockchain networks.
3

4
## Capabilities
5

6
### Etherscan Configuration
7

8
Main configuration interface for the plugin, extending Hardhat's configuration system.
9

10
```typescript { .api }
11
/**
12
 * User configuration for Etherscan plugin
13
 * Used in hardhat.config.js/ts
14
 */
15
interface EtherscanUserConfig {
16
  /** API key(s) for Etherscan services - single string or network-specific object */
17
  apiKey?: string | Record<string, string>;
18
  /** Custom blockchain networks not included in built-in support */
19
  customChains?: CustomChain[];
20
}
21

22
/**
23
 * Resolved Etherscan configuration with defaults applied
24
 * Available in Hardhat runtime environment
25
 */
26
interface EtherscanConfig {
27
  /** API key(s) for Etherscan services */
28
  apiKey?: string | Record<string, string>;
29
  /** Custom chains with defaults merged */
30
  customChains: CustomChain[];
31
}
32
```
33

34
**Usage Examples:**
35

36
```typescript
37
// hardhat.config.ts - Single API key for all networks
38
export default {
39
  etherscan: {
40
    apiKey: "YOUR_ETHERSCAN_API_KEY"
41
  }
42
};
43

44
// Network-specific API keys
45
export default {
46
  etherscan: {
47
    apiKey: {
48
      mainnet: "MAINNET_ETHERSCAN_KEY",
49
      polygon: "POLYGONSCAN_API_KEY",
50
      bsc: "BSCSCAN_API_KEY"
51
    }
52
  }
53
};
54

55
// With custom chains
56
export default {
57
  etherscan: {
58
    apiKey: {
59
      customNetwork: "CUSTOM_API_KEY"
60
    },
61
    customChains: [
62
      {
63
        network: "customNetwork",
64
        chainId: 1234,
65
        urls: {
66
          apiURL: "https://api.custom-explorer.com/api",
67
          browserURL: "https://custom-explorer.com"
68
        }
69
      }
70
    ]
71
  }
72
};
73
```
74

75
### Custom Chain Configuration
76

77
Configuration for blockchain networks not included in the built-in chain support.
78

79
```typescript { .api }
80
/**
81
 * Custom blockchain network configuration
82
 * Allows adding support for networks not built into the plugin
83
 */
84
interface CustomChain {
85
  /** Network name used in Hardhat network configuration */
86
  network: string;
87
  /** Blockchain chain ID */
88
  chainId: number;
89
  /** Block explorer URLs for this network */
90
  urls: EtherscanURLs;
91
}
92

93
/**
94
 * Block explorer URL configuration
95
 * Defines API and browser endpoints for a block explorer
96
 */
97
interface EtherscanURLs {
98
  /** API endpoint for verification requests */
99
  apiURL: string;
100
  /** Browser URL for viewing contracts */
101
  browserURL: string;
102
}
103
```
104

105
### Configuration Extension Function
106

107
```typescript { .api }
108
/**
109
 * Hardhat configuration extender function
110
 * Applies default values and validates Etherscan configuration
111
 * @param resolvedConfig - Hardhat's resolved configuration object
112
 * @param config - User-provided configuration
113
 */
114
declare const etherscanConfigExtender: ConfigExtender;
115

116
type ConfigExtender = (
117
  resolvedConfig: HardhatConfig,
118
  config: HardhatUserConfig
119
) => void;
120
```
121

122
### Configuration Validation
123

124
```typescript { .api }
125
/**
126
 * Validate that API keys are only configured for supported networks
127
 * Throws error if API key is set for unsupported network
128
 * @param etherscanConfig - Resolved Etherscan configuration
129
 * @throws NomicLabsHardhatPluginError for unsupported networks
130
 */
131
function verifyAllowedChains(etherscanConfig: EtherscanConfig): void;
132
```
133

134
**Usage Examples:**
135

136
```typescript
137
// This will throw an error if 'unsupportedNetwork' is not in built-in chains or customChains
138
const config = {
139
  etherscan: {
140
    apiKey: {
141
      mainnet: "key1",
142
      unsupportedNetwork: "key2" // Error: unsupported network
143
    }
144
  }
145
};
146
```
147

148
### API Key Resolution
149

150
```typescript { .api }
151
/**
152
 * Resolve API key for specific network from configuration
153
 * Handles both single string and network-specific object formats
154
 * @param apiKey - API key configuration (string or object)
155
 * @param network - Network name to resolve key for
156
 * @returns Resolved API key string
157
 * @throws NomicLabsHardhatPluginError if no key found for network
158
 */
159
function resolveEtherscanApiKey(
160
  apiKey: EtherscanConfig["apiKey"],
161
  network: string
162
): string;
163
```
164

165
**Usage Examples:**
166

167
```typescript
168
// Single API key - same key used for all networks
169
const key1 = resolveEtherscanApiKey("abc123", "mainnet"); // returns "abc123"
170

171
// Network-specific keys
172
const keys = {
173
  mainnet: "mainnet_key",
174
  polygon: "polygon_key"
175
};
176
const key2 = resolveEtherscanApiKey(keys, "mainnet"); // returns "mainnet_key"
177
const key3 = resolveEtherscanApiKey(keys, "bsc"); // throws error - no key for bsc
178
```
179

180
### Network Entry Resolution
181

182
```typescript { .api }
183
/**
184
 * Network entry with resolved URLs
185
 * Used internally to determine correct endpoints for verification
186
 */
187
interface EtherscanNetworkEntry {
188
  /** Network name */
189
  network: string;
190
  /** Block explorer URLs for this network */
191
  urls: EtherscanURLs;
192
}
193
```
194

195
### Hardhat Config Type Extensions
196

197
The plugin extends Hardhat's configuration types to include Etherscan settings:
198

199
```typescript { .api }
200
// Type extensions for Hardhat configuration
201
declare module "hardhat/types/config" {
202
  interface HardhatUserConfig {
203
    etherscan?: EtherscanUserConfig;
204
  }
205

206
  interface HardhatConfig {
207
    etherscan: EtherscanConfig;
208
  }
209
}
210
```
211

212
This allows TypeScript users to have full type safety when configuring the plugin in their Hardhat configuration files.