dannydoodlesstory/evm-audit-helpersCollection of Solidity snippets and Foundry scripts for smart contract security audits
evm-audit-helpers is a curated collection of Solidity snippets, Foundry scripts, and test templates designed to accelerate EVM smart‑contract security audits. The repository bundles reusable building blocks for common audit concerns such as reentrancy, storage layout mismatches, and gas‑optimisation pitfalls, allowing auditors and developers to focus on logic rather than boiler‑plate.
Key goals:
| Category | Description | Primary Files |
|---|---|---|
| Reentrancy Checkers | Helper modifiers, nonReentrant patterns, and runtime detection scripts. | src/helpers/Reentrancy.sol, scripts/reentrancy_check.sol |
| Storage Layout Analyzer | Utilities to compare storage slots, generate layout diagrams, and detect unsafe upgrades. | src/helpers/StorageLayout.sol, scripts/storage_analyzer.sol |
| Foundry Test Templates | Boilerplate test suites covering common vulnerabilities (access control, arithmetic, delegatecall, etc.). | test/templates/* |
| Gas & Opcode Audits | Scripts to profile gas usage and flag expensive opcodes. | scripts/gas_profiler.sol |
| Reporting Helpers | JSON/Markdown reporters that can be piped into CI dashboards. | scripts/report_generator.sol |
| CI Integration | Example GitHub Actions workflow for automated audit runs. | .github/workflows/ci.yml |
All helpers are written for Solidity ^0.8.20 and are compatible with Foundry (forge, cast).
# 1️⃣ Clone the repository
git clone https://github.com/your-org/evm-audit-helpers.git
cd evm-audit-helpers
# 2️⃣ Install Foundry (if not already installed)
curl -L https://foundry.paradigm.xyz | bash
foundryup
# 3️⃣ Install dependencies
forge install
# 4️⃣ Run the default test suite (includes reentrancy, storage, and gas checks)
forge test
Tip: Add
export FOUNDRY_PROFILE=cito your shell to use the CI‑optimised compiler settings.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import "evm-audit-helpers/src/helpers/Reentrancy.sol";
contract MyVault is ReentrancyGuard {
mapping(address => uint256) private balances;
function deposit() external payable nonReentrant {
balances[msg.sender] += msg.value;
}
function withdraw(uint256 amount) external nonReentrant {
require(balances[msg.sender] >= amount, "Insufficient");
balances[msg.sender] -= amount;
(bool ok,) = msg.sender.call{value: amount}("");
require(ok, "Transfer failed");
}
}
Run the runtime detector on a compiled contract:
forge script scripts/reentrancy_check.sol:ReentrancyChecker --rpc-url $RPC_URL --broadcast
# Generate a JSON description of a compiled contract's storage layout
cast abi-storage --contract MyUpgradeable.sol:MyUpgradeable > storage.json
# Compare against a reference layout (e.g., from a previous version)
forge script scripts/storage_analyzer.sol:StorageComparator \
--sig "compare(string memory, string memory)" storage.json reference.json
The script will output mismatched slots, potential shadowing, and suggestions for @custom:oz-upgrades-unsafe-allow annotations.
Copy a template into your audit repo:
cp -r test/templates/reentrancy/ my-audit/tests/
Edit MyContract.t.sol to import the contract under audit and run:
forge test --match-contract MyContract
Add the provided workflow to your repository:
# .github/workflows/audit.yml
name: EVM Audit
on:
push:
branches: [main]
pull_request:
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Foundry
run: curl -L https://foundry.paradigm.xyz | bash && foundryup
- name: Run Audit Suite
run: |
forge install
forge test -vv
forge script scripts/reentrancy_check.sol:ReentrancyChecker --rpc-url ${{ secrets.RPC_URL }}
forge script scripts/storage_analyzer.sol:StorageComparator --sig "compare(string,string)" storage.json reference.json
The workflow will automatically flag failures and publish a markdown report as a PR comment.
We welcome contributions! Please follow these steps:
git checkout -b feat/<name>).forge coverage).npm run lint – uses solhint and prettier).pragma solidity ^0.8.20;snake_case for internal functions, camelCase for public/external.///).# Install linting tools
npm install
# Run solhint
npx solhint 'src/**/*.sol' 'test/**/*.sol'
# Auto‑format
npx prettier --write '**/*.sol'
evm-audit-helpers is licensed under the MIT License. See the LICENSE file for details.
Happy auditing!