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.
Every audited .sol file consumes one Blockhertz credit. As of v0.3.0, the plugin discloses the file list and cost upfront and asks you to confirm before making any API calls, so a mistyped path or a forgotten interface directory can't silently drain your balance.
🔍 Blockhertz AI Auditor Found 3 contract files to audit (2 excluded). − contracts/mocks/MockOracle.sol (test/mock path) − contracts/IERC20Extended.sol (interface-only) This will use up to 3 credits. Continue? (y/N)
In a non-interactive shell (CI, Docker, scripts) the prompt would block the process indefinitely. Skip it with the --yes / -y CLI flag, or the BLOCKHERTZ_YES=1 environment variable. Interactive terminals still see the prompt unless one of these is set.
# Skip the interactive "Continue? (y/N)" prompt npx hardhat blockhertz-audit --yes # Or set BLOCKHERTZ_YES=1 in the environment (for CI) BLOCKHERTZ_YES=1 npx hardhat blockhertz-audit
CI pipelines that omit --yes in a non-TTY environment fail fast with a clear message rather than hanging. Add the flag (or the env var) to every automated run.
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",
// Optional — override the audit endpoint. Also readable from
// the BLOCKHERTZ_API_URL environment variable. Useful for
// pointing at a preview / staging deployment during rollout.
// apiUrl: "https://blockhertz.com/api/v1/audit",
// Optional — additional glob patterns to exclude (micromatch,
// matched against project-root-relative paths). Additive on
// top of the built-in filters (node_modules, test/mock paths,
// interface-only files).
// exclude: ["contracts/experimental/**", "**/*Deprecated.sol"],
// Optional — bypass the built-in test/mock and interface-only
// filters. node_modules stays excluded regardless. Set to true
// only if the built-in heuristics misidentify one of your files.
// skipBuiltInFilters: false,
},
};| Option | Type | Default | Description |
|---|---|---|---|
apiKey | string | "" | Your Blockhertz API key (or BLOCKHERTZ_API_KEY env). Required. |
apiUrl | string | production endpoint | Override the audit endpoint (or BLOCKHERTZ_API_URL env). Useful for staging/preview. |
failOn | string | "high" | Minimum severity to fail build. See failOn Options below. |
contractsPath | string | "./contracts" | Path to contracts directory. |
exclude | string[] | [] | Extra glob patterns (micromatch, project-root-relative). Additive to the built-in filters. |
skipBuiltInFilters | boolean | false | Bypass test/mock-path and interface-only exclusions. node_modules is still always excluded. |
The plugin walks contractsPath recursively and, since v0.3.0, applies a filtering pipeline before charging any credits. Built-in exclusions catch the files that almost never belong in an audit, and you can layer your own globs on top.
| Filter | Matches | Overridable? |
|---|---|---|
| node_modules | Any file under a node_modules/ path segment. | no — always excluded |
| test / mock paths | Any file under a test, tests, mock, or mocks path segment (case-insensitive). | skipBuiltInFilters: true |
| interface-only files | Files whose source (with comments stripped) contains interface X declarations and no contract / library. Regex heuristic — handles the common cases. | skipBuiltInFilters: true |
excludeAdd project-specific globs on top of the built-in filters. Patterns are evaluated by micromatch against project-root-relative paths. This is additive — it does not disable the built-in filters.
blockhertz: {
apiKey: process.env.BLOCKHERTZ_API_KEY ?? "",
exclude: [
"contracts/experimental/**", // whole directory
"**/*Deprecated.sol", // by suffix
"contracts/vendor/OldLib.sol", // one file
],
}skipBuiltInFiltersBypass the test-path and interface-only heuristics. Use this only when the built-in filters misidentify one of your files (for example an interface named after a real contract). node_modules remains excluded regardless.
blockhertz: {
apiKey: process.env.BLOCKHERTZ_API_KEY ?? "",
skipBuiltInFilters: true, // audit every .sol under contractsPath
}The pre-flight prompt always lists what was excluded and why (node_modules, test/mock path, interface-only, or user exclude), so you can spot a mistaken filter before spending credits.
The plugin itself is free and open-source. Audits consume Blockhertz API credits.
| Plan | Credits | Rate Limit | Price |
|---|---|---|---|
| Free | Limited | 20 / hour | $0 |
| Starter | 5 | 50 / hour | $19 one-time |
| Unlimited | Unlimited | 200 / hour | $99 / month |
Each contract audit = 1 credit. Get free API key: blockhertz.com/tools/dashboard/api-keys.
| 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. As of plugin 0.2.0 this is a distinct, populated tier; older versions collapsed high findings into critical or medium, so upgrading may surface new CI failures under the default failOn: "high".
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
# --yes bypasses the interactive "Continue? (y/N)" prompt so the
# job does not hang in a non-interactive shell. BLOCKHERTZ_YES=1
# in env achieves the same thing.
- name: Run security audit
run: npx hardhat blockhertz-audit --yes
env:
BLOCKHERTZ_API_KEY: ${{ secrets.BLOCKHERTZ_API_KEY }}audit:
image: node:22
script:
- npm install
# --yes skips the pre-flight confirmation prompt (CI has no TTY)
- npx hardhat blockhertz-audit --yes
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 --yes as a step in your CI pipeline and set BLOCKHERTZ_API_KEY as a secret. The --yes flag skips the interactive pre-flight prompt (CI has no TTY). 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.