0
# Plugin Configuration
1

2
The Hardhat Toolbox plugin bundle automatically imports and configures essential Hardhat plugins for Ethereum smart contract development. When imported, it registers all plugins and applies sensible default configurations.
3

4
## Capabilities
5

6
### Plugin Bundle Import
7

8
Automatically imports and registers all bundled plugins with Hardhat.
9

10
```typescript { .api }
11
/**
12
 * Import the complete plugin bundle to register all tools
13
 * Must be imported in hardhat.config.ts or hardhat.config.js
14
 */
15
import "@nomicfoundation/hardhat-toolbox";
16
```
17

18
**Bundled Plugins:**
19

20
- `@nomicfoundation/hardhat-chai-matchers` - Blockchain-specific Chai matchers for testing
21
- `@nomicfoundation/hardhat-ethers` - Ethers.js integration with Hardhat
22
- `@nomicfoundation/hardhat-verify` - Contract source code verification tools
23
- `@nomicfoundation/hardhat-ignition-ethers` - Deployment framework integration
24
- `@typechain/hardhat` - TypeScript type generation for smart contracts
25
- `hardhat-gas-reporter` - Gas usage reporting and analysis
26
- `solidity-coverage` - Test coverage measurement for Solidity contracts
27

28
### Configuration Extension
29

30
Internal configuration function that applies default settings for gas reporting and TypeScript compilation.
31

32
```typescript { .api }
33
/**
34
 * Extends Hardhat configuration with toolbox defaults
35
 * Called automatically when plugin is imported
36
 * @param config - Hardhat configuration object
37
 * @param userConfig - User-provided configuration
38
 */
39
function extendConfig(config: HardhatConfig, userConfig: HardhatUserConfig): void;
40
```
41

42
**Automatic Configuration Changes:**
43

44
1. **Gas Reporter Configuration**:
45
   - Enables gas reporting based on `REPORT_GAS` environment variable
46
   - Sets default currency to "USD"
47
   - Preserves user-provided gas reporter settings
48

49
2. **TypeScript Configuration**:
50
   - Disables TypeScript compilation overrides for JavaScript projects
51
   - Automatically detected based on config file extension (.js, .cjs)
52

53
### Available Tasks and Scopes
54

55
Once imported, the toolbox makes the following tasks available in Hardhat:
56

57
```typescript { .api }
58
// Available via Hardhat CLI or programmatically
59
interface AvailableTasks {
60
  verify: "Verify contract source code on block explorers";
61
  coverage: "Generate test coverage reports for Solidity contracts";
62
  typechain: "Generate TypeScript types for smart contracts";
63
}
64

65
interface AvailableScopes {
66
  vars: "Manage configuration variables";
67
  ignition: "Deploy contracts using Hardhat Ignition";
68
}
69
```
70

71
**Usage Examples:**
72

73
```bash
74
# Verify a contract
75
npx hardhat verify --network mainnet DEPLOYED_CONTRACT_ADDRESS "Constructor argument 1"
76

77
# Generate coverage report
78
npx hardhat coverage
79

80
# Generate TypeScript types
81
npx hardhat typechain
82

83
# Use Ignition for deployment
84
npx hardhat ignition deploy ./ignition/modules/Lock.ts --network localhost
85

86
# Manage configuration variables
87
npx hardhat vars set PRIVATE_KEY
88
```
89

90
### Environment Integration
91

92
The toolbox automatically extends the Hardhat Runtime Environment (HRE) with:
93

94
```typescript { .api }
95
// Available in tasks, scripts, and tests
96
declare global {
97
  var ethers: typeof import("ethers") & {
98
    // Hardhat-specific ethers extensions
99
    getSigners(): Promise<Signer[]>;
100
    getContractFactory(name: string): Promise<ContractFactory>;
101
    deployContract(name: string, ...args: any[]): Promise<Contract>;
102
  };
103
  
104
  var tasks: {
105
    [taskName: string]: TaskDefinition;
106
  };
107
  
108
  var scopes: {
109
    [scopeName: string]: ScopeDefinition;
110
  };
111
}
112
```
113

114
**Configuration File Example:**
115

116
```typescript
117
// hardhat.config.ts
118
import { HardhatUserConfig } from "hardhat/config";
119
import "@nomicfoundation/hardhat-toolbox";
120

121
const config: HardhatUserConfig = {
122
  solidity: {
123
    version: "0.8.20",
124
    settings: {
125
      optimizer: {
126
        enabled: true,
127
        runs: 200,
128
      },
129
    },
130
  },
131
  networks: {
132
    localhost: {
133
      url: "http://127.0.0.1:8545"
134
    },
135
    sepolia: {
136
      url: process.env.SEPOLIA_URL || "",
137
      accounts: process.env.PRIVATE_KEY !== undefined ? [process.env.PRIVATE_KEY] : [],
138
    }
139
  },
140
  gasReporter: {
141
    enabled: process.env.REPORT_GAS !== undefined,
142
    currency: "USD",
143
  },
144
  etherscan: {
145
    apiKey: process.env.ETHERSCAN_API_KEY,
146
  },
147
};
148

149
export default config;
150
```
151

152
### Environment Variables
153

154
The toolbox recognizes and uses these environment variables:
155

156
```typescript { .api }
157
interface RecognizedEnvironmentVariables {
158
  /** Enable gas reporting in tests (any truthy value) */
159
  REPORT_GAS?: string;
160
  /** Etherscan API key for contract verification */
161
  ETHERSCAN_API_KEY?: string;
162
  /** Private key for network deployments */
163
  PRIVATE_KEY?: string;
164
  /** RPC URLs for various networks */
165
  MAINNET_URL?: string;
166
  SEPOLIA_URL?: string;
167
  POLYGON_URL?: string;
168
  // ... other network URLs
169
}
170
```
171

172
**Usage:**
173

174
```bash
175
# Enable gas reporting
176
REPORT_GAS=true npx hardhat test
177

178
# Run tests with specific network
179
SEPOLIA_URL="https://sepolia.infura.io/v3/YOUR_PROJECT_ID" npx hardhat test --network sepolia
180
```
181

182
## Types
183

184
```typescript { .api }
185
interface HardhatConfig {
186
  gasReporter?: {
187
    enabled?: boolean;
188
    currency?: string;
189
    gasPrice?: number;
190
    coinmarketcap?: string;
191
  };
192
  
193
  typechain?: {
194
    dontOverrideCompile?: boolean;
195
    outDir?: string;
196
    target?: string;
197
  };
198
  
199
  etherscan?: {
200
    apiKey?: string | { [network: string]: string };
201
  };
202
}
203

204
interface HardhatUserConfig extends Partial<HardhatConfig> {
205
  solidity?: string | SolidityConfig;
206
  networks?: NetworksConfig;
207
  paths?: PathsConfig;
208
}
209

210
interface TaskDefinition {
211
  name: string;
212
  description: string;
213
  action: (...args: any[]) => Promise<any>;
214
}
215

216
interface ScopeDefinition {
217
  name: string;
218
  description: string;
219
  tasks: { [taskName: string]: TaskDefinition };
220
}
221
```