Home/Tools/hardhat-blockhertz/Docs
Complete guide to installing, configuring and using the hardhat-blockhertz Hardhat 3 plugin.
Quick answer
hardhat-blockhertz is a free open-source Hardhat 3 plugin that automatically audits Solidity smart contracts for security vulnerabilities using the Blockhertz AI API. Install with npm install hardhat-blockhertz and run npx hardhat blockhertz-audit.
| Requirement | Minimum Version |
|---|---|
| Node.js | 22.0.0+ |
| Hardhat | 3.0.0+ |
| npm / pnpm / yarn | Any recent version |
| Blockhertz API Key | Free (get one below) |
npm install hardhat-blockhertz
import hardhatBlockhertz from "hardhat-blockhertz";
import type { HardhatUserConfig } from "hardhat/config";
const config: HardhatUserConfig = {
plugins: [hardhatBlockhertz],
blockhertz: {
apiKey: process.env.BLOCKHERTZ_API_KEY ?? "",
failOn: "high",
},
};
export default config;Generate your free API key at blockhertz.com/tools/dashboard/api-keys.
Get Free API Key# .env BLOCKHERTZ_API_KEY=bh_your_key_here
Never commit your API key to version control. Add .env to your .gitignore.
npx hardhat blockhertz-audit
Automatically discovers and audits all .sol files in your contracts/ directory. Results are displayed with colored severity indicators.
npx hardhat blockhertz-audit \ --contract contracts/Token.sol
🔍 Blockhertz AI Auditor Auditing 1 contract(s)... 📄 Token.sol Risk Score: 85/100 (critical) Findings: 3 [CRITICAL] Reentrancy in withdraw() The ETH transfer occurs before the balance is zeroed... Fix: Apply CEI pattern — zero balance before external call. [MEDIUM] Missing zero-address check transfer() does not validate the to address... Fix: Add require(to != address(0)) [GAS] Cache storage variable balances[msg.sender] read twice... Fix: Cache in local variable. Summary: Contract contains critical reentrancy vulnerability... ────────────────────────────────────── Audit complete: 1 contract(s), 3 finding(s) ✗ Build failed: Found high+ severity issues.
import hardhatBlockhertz from "hardhat-blockhertz";
const config = {
plugins: [hardhatBlockhertz],
blockhertz: {
// Required
apiKey: process.env.BLOCKHERTZ_API_KEY ?? "",
// Optional — default: "high"
failOn: "high",
// Optional — default: "./contracts"
contractsPath: "./contracts",
},
};| Option | Type | Default | Description |
|---|---|---|---|
apiKey | string | "" | Your Blockhertz API key |
failOn | string | "high" | Minimum severity to fail build |
contractsPath | string | "./contracts" | Path to contracts directory |
| Value | Fails On | Best For |
|---|---|---|
"critical" | Critical only | Quick production check |
"high" | High + critical | Recommended default ✅ |
"medium" | Medium and above | Strict security |
"none" | Never | Audit-only mode |
BLOCKHERTZ_API_KEY=bh_xxx \ npx hardhat blockhertz-audit
Exploitable vulnerabilities that must be fixed before deployment. Reentrancy, access control failures, fund draining risks.
Serious issues that significantly increase exploit risk. Oracle manipulation, signature replay, unprotected initializers.
Vulnerabilities that may be exploited under specific conditions. Missing validations, logic errors, weak access controls.
Minor issues and best practice violations. Unused variables, missing events, code quality.
Gas optimization opportunities. Storage access patterns, loop optimizations, type choices.
name: Smart Contract Security Audit
on: [push, pull_request]
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install dependencies
run: npm install
- name: Run security audit
run: npx hardhat blockhertz-audit
env:
BLOCKHERTZ_API_KEY: ${{ secrets.BLOCKHERTZ_API_KEY }}audit:
image: node:22
script:
- npm install
- npx hardhat blockhertz-audit
variables:
BLOCKHERTZ_API_KEY: $BLOCKHERTZ_API_KEYBLOCKHERTZ_API_KEY.${{ secrets.BLOCKHERTZ_API_KEY }}.hardhat-blockhertz is a free open-source Hardhat 3 plugin that automatically audits Solidity smart contracts for security vulnerabilities using the Blockhertz AI Security API. Run npx hardhat blockhertz-audit to scan all contracts in your project in seconds.
Yes. hardhat-blockhertz is completely free and open-source under the MIT license. It requires a free Blockhertz API key available at blockhertz.com/tools/dashboard/api-keys.
Visit blockhertz.com/tools/dashboard/api-keys, sign in to your Blockhertz account, and click Generate API Key. The key is shown once — copy it immediately and store it as BLOCKHERTZ_API_KEY in your environment variables.
hardhat-blockhertz detects reentrancy attacks, access control failures, oracle manipulation, integer overflow, missing input validation, unchecked return values, front-running vectors, gas inefficiencies, and 10+ additional vulnerability classes using the Blockhertz AI Security Engine.
Add npx hardhat blockhertz-audit as a step in your CI pipeline and set BLOCKHERTZ_API_KEY as a secret. The plugin exits with code 1 when vulnerabilities at or above your failOn threshold are found, blocking the pipeline automatically.
failOn controls which severity level causes the build to fail. Set to critical to fail only on critical issues, high (default) to fail on high and critical, medium to fail on medium and above, or none to never fail the build and use the plugin in audit-only mode.
No. hardhat-blockhertz is built for Hardhat 3 only and requires Node.js 22 or higher. Hardhat 2 uses a different plugin architecture that is not compatible.
Slither is a static analysis tool that runs locally and requires Python. hardhat-blockhertz uses AI-powered analysis via the Blockhertz API, requires no additional dependencies, runs inside your existing Hardhat workflow, and provides natural language descriptions and fix recommendations for every finding.
hardhat-blockhertz supports all Solidity versions. The plugin sends your contract source code to the Blockhertz AI Security Engine which analyzes any valid Solidity syntax regardless of compiler version.
Yes. Run npx hardhat blockhertz-audit --contract contracts/MyContract.sol to audit a specific file instead of all contracts in the contracts directory.