# Smart Contract Audits
**A portfolio of smart contract security reviews**
Security audit reports in PDF format — collected by platform and open for review.
[](LICENSE)
[](https://soliditylang.org/)
[](./reports/)
[Overview](#overview) ·
[Structure](#repository-structure) ·
[Platforms](#platforms) ·
[Methodology](#methodology) ·
[Severity](#finding-classification) ·
[Reading Reports](#how-to-read-a-report) ·
[Adding Audits](#adding-a-new-audit)
## Overview
This repository is a **public portfolio** of smart contract security audit work. It stores **PDF reports** produced on different **platforms** — bug bounty programs, audit contests, private engagements, and similar venues.
Each platform has its own folder under **`reports/`**. PDFs live **directly inside that folder** — no nested project directories.
smart-contract-audits
└── reports/
├── CodeHawks/
│ ├── 23-05-2026-passwordStore-audit.pdf
│ └── 27-05-2026-PuppyRaffle-audit.pdf
└──
/
└── -audit.pdf
│
└──► published on GitHub (portfolio)
### Why this repository exists
| Goal | Description |
|------|-------------|
| **Portfolio** | Showcase audit approach, depth of analysis, and report quality |
| **Transparency** | Simple layout: pick a platform, open the PDF |
| **History** | Archive completed work as a growing set of reports |
| **Sharing** | One place to link recruiters, clients, or the community |
## Repository structure
smart-contract-audits/
├── README.md
├── logo.png
├── LICENSE
└── reports/
├── CodeHawks/
│ └── --audit.pdf
└── /
└── --audit.pdf
**Rules:**
- One folder per **platform** under `reports/`.
- **PDF files only** inside platform folders — no project subfolders, no Markdown reports in the tree.
- File names should make the subject obvious at a glance.
### Naming conventions
| Element | Recommendation | Example |
|---------|----------------|---------|
| **Platform folder** | under `reports/`, lowercase or PascalCase as on platform | `reports/CodeHawks`, `reports/code4rena` |
| **PDF filename** | protocol or scope + optional date | `acme-vault-audit.pdf`, `bridge-2025-03.pdf` |
| **Format** | `.pdf` only | `report.pdf` |
**Good filenames:** `lending-pool-security-review.pdf`, `governance-module-2025-04.pdf`
**Avoid:** `report.pdf`, `final_v2.pdf`, `untitled.pdf`
## Platforms
Below is a **living index** of platform folders. Update this table when you add reports.
| Platform | Folder | PDFs | Notes |
|----------|--------|------|-------|
| CodeHawks | [reports/CodeHawks](./reports/CodeHawks/) | 2 | Audit contests |
To browse on GitHub: open the platform folder and click a PDF (GitHub renders PDFs in the browser).
## Methodology
1. Scope 2. Architecture 3. Manual review 4. Threat modeling
│ │ │ │
└────────────────────┴────────────────────┴────────────────────┘
│
▼
5. Tooling ─────┬──── Slither / Aderyn
│ ├──── Foundry / Hardhat
▼ └──── Fuzz / invariants
6. PoC and impact
│
▼
7. PDF report
### Stages
1. **Scope** — which contracts, chains, commits, and constraints are in scope.
2. **Architecture** — roles (admin, keeper, user) and external dependencies (oracles, bridges, governance).
3. **Manual review** — logic, access control, reentrancy, rounding, MEV, upgradeability.
4. **Threat modeling** — attack scenarios from economic and composability angles.
5. **Tooling** — static analysis, tests, and fuzzing where it adds value.
6. **Proof of Concept** — reproducible steps for high-severity findings.
7. **Report** — exported as PDF: findings, severity, remediation, references.
### Areas of focus
- Access control and privileged roles
- Reentrancy (including cross-function / cross-contract)
- Oracle manipulation and stale prices
- Share math, rounding, and first-depositor issues
- Upgradeability (proxy patterns, storage collisions)
- Token hooks (ERC-777, callbacks) and approvals
- Governance, timelocks, centralization risks
- Gas griefing and DoS in loops
- Composability with external protocols
## Finding classification
Reports use a severity scale common on audit contest platforms (Code4rena, Sherlock, and similar):
| Level | Label | Criteria (brief) |
|-------|-------|------------------|
| **High** | 🔴 | Direct loss of funds, protocol compromise, or severe DoS |
| **Medium** | 🟠 | Meaningful impact with non-trivial preconditions |
| **Low** | 🟡 | Limited impact, edge cases, minor deviations |
| **Informational** | ⚪ | Recommendations, documentation, best practices |
| **Gas** | ⛽ | Optimization with no security impact |
## How to read a report
1. Open the [Platforms](#platforms) table and choose a platform folder.
2. Pick a PDF by filename (protocol, module, or contest round).
3. In the document, start with the **executive summary**, then review findings from highest to lowest severity.
A typical PDF report includes:
| Section | Contents |
|---------|----------|
| **Cover / metadata** | Platform, date, scope, auditor |
| **Executive summary** | Finding counts, overall risk, key takeaways |
| **Scope** | Contracts, networks, commit or version |
| **Findings** | ID, severity, description, impact, recommendation, status |
| **Appendix** | Code references, diagrams, PoC notes (if allowed) |
## Adding a new audit
Checklist for publishing a report:
- [ ] Export or save the audit as **PDF**
- [ ] Create the platform folder if needed: `reports//`
- [ ] Place the PDF **directly** in that folder (no subfolders)
- [ ] Use a clear, descriptive filename
- [ ] Redact or omit anything under NDA (keys, private addresses, undisclosed details)
- [ ] Update the **Platforms** table in this README
# Example
mkdir -p reports/CodeHawks
cp ~/exports/27-05-2026-acme-vault-audit.pdf reports/CodeHawks/
git add reports/CodeHawks/27-05-2026-acme-vault-audit.pdf README.md
git commit -m "Add CodeHawks audit report: Acme Vault"
git push
## Tooling
Reports are delivered as PDFs; analysis behind them often uses:
| Category | Tools |
|----------|-------|
| Static analysis | [Slither](https://github.com/crytic/slither), [Aderyn](https://github.com/Cyfrin/aderyn) |
| Testing | [Foundry](https://book.getfoundry.sh/), [Hardhat](https://hardhat.org/) |
| Fuzz / invariants | Foundry `forge test`, [Echidna](https://github.com/crytic/echidna) |
| Report output | PDF export from your editor or report template |
## License
Repository contents are under the [MIT License](./LICENSE).
You do not buy or download a license — you add a plain-text `LICENSE` file to the repo root (this project already includes one). Official text: [choosealicense.com/licenses/mit](https://choosealicense.com/licenses/mit/). On GitHub you can also use **Add file → Create new file → “License”** when creating a repo, or **Settings → General → License** on an existing repo.
Replace the copyright name in `LICENSE` if you publish under a legal name or company, not your GitHub handle. Platform rules or NDAs may restrict what you can publish regardless of this license.
## Contact
| | |
|---|---|
| **GitHub** | [@Myth1call](https://github.com/Myth1call) |
| **Twitter / X** | [@Mythical0___0](https://x.com/Mythical0___0) |
| **Telegram** | [@himatachi](https://t.me/himatachi) |
*This repository is updated as new audit PDFs are published.*
**Security is a process, not a one-time check.**