A practical, test-first lab for understanding common smart-contract security mistakes and checking how a mitigation changes the behavior. Examples are intentionally educational and paired with reproducible Foundry tests.
Useful to you? Give the repository a ⭐ Star so more Solidity builders can find it. Found a gap? Open an Issue. Want to help improve it? Beginner-friendly contributions are welcome.
| Topic | What you can learn | Code and tests |
|---|---|---|
| Reentrancy | How calling external code before updating accounting can expose a withdrawal path, and how checks-effects-interactions changes it | VulnerableVault.sol · FixedVault.sol · Reentrancy.t.sol |
| Access control | Why privileged state changes must enforce authorization | VulnerableFeeVault.sol · FixedFeeVault.sol · AccessControl.t.sol · Case notes |
tx.origin authorization |
Why authorizing with the original transaction initiator can trust the wrong caller | VulnerableTxOriginWallet.sol · FixedOwnerWallet.sol · TxOrigin.t.sol · Case notes |
| Failed ETH transfers | How reverted transfers should preserve vault balances and accounting | TransferFailure.t.sol |
| Vault accounting fuzzing | How fuzz tests can probe deposits, withdrawals, and per-user accounting invariants | VaultAccountingFuzz.t.sol |
| Empty withdrawal edge cases | How reverts and per-user accounting protect other depositors' funds | EmptyWithdrawal.t.sol |
Install Foundry, then run from the repository root:
forge install foundry-rs/forge-std --no-git
forge test -vvThe dependency install is local; it does not need to be committed. GitHub Actions runs the suite on pushes and pull requests using forge test -vv --fuzz-runs 1000. This runs 1,000 fuzz cases for each Foundry fuzz test. The current suite contains 18 passing tests, including five fuzz tests.
A separate GitHub Actions workflow runs Slither on the compiled Solidity examples under src/. It excludes Foundry tests and scripts from the analysis build and exports a SARIF report as a downloadable workflow artifact.
The workflow is intentionally non-blocking on findings because this lab includes contracts that are vulnerable by design. A successful Slither run means compilation and analysis completed; it does not mean that no findings were detected or that the contracts are secure. Review findings in context and compare them with the paired Foundry tests and the documented mitigations.
See the Slither workflow and its reports.
You do not need to be a security expert to help. Choose a task that fits your experience:
- Documentation: Issue #5 — Write a beginner-friendly reentrancy walkthrough
- Testing: Issue #14 — Add edge-case tests for FixedOwnerWallet
- Static analysis docs: Issue #15 — Explain how to read Slither SARIF results
- Solidity security lab: Issue #16 — Add a delegatecall storage-collision example
- Propose a security case: Issue #19 — Tell us what we should build next
- Use the structured proposal form: Suggest a security lab case
Suggested path: open an issue → comment that you would like to work on it → make a focused change → run forge test -vv → open a pull request. You can also report a bug or suggest a test without submitting code.
Read the Community Guide to understand the participation process and how merged contributions are recognised. Substantive external contributions are recorded in CONTRIBUTORS.md.
Before contributing, read CONTRIBUTING.md. For community expectations, read our Code of Conduct. For security-sensitive reports, follow our Security Policy instead of posting exploit details publicly.
Please do not submit customer code, confidential audit reports, private findings, secrets, API keys, or credentials.
This is an educational repository, not a production-ready contract library and not a complete security audit. The examples are intentionally simplified. A passing test suite does not prove a contract is secure, and a mitigation shown here does not replace a context-specific review of external-call paths, access controls, accounting, dependencies, and business logic.
Do not deploy vulnerable examples or use these snippets to assess a production contract without an independent, context-specific review.
Motech Audit researches smart-contract security and develops tools and learning resources to help Web3 teams understand and mitigate risk.