When

Mandatory Checklist

Before sending the audit package, verify all items:

[ ] Exact commit hash pinned and tagged (git tag v1.0.0-audit <hash>)
[ ] scope.md: all in-scope files listed with LOC count
[ ] scope.md: all out-of-scope files listed with reason
[ ] scope.md: all dependencies listed with versions and audit status
[ ] protocol.md: plain-English protocol description written
[ ] protocol.md: all actors and permissions listed
[ ] protocol.md: state machine documented
[ ] protocol.md: all invariants listed (minimum 3, ideally 5+)
[ ] protocol.md: trust assumptions explicitly written out
[ ] threat-model.md: attacker goals listed and ranked by priority
[ ] threat-model.md: attacker capabilities explicitly bounded
[ ] threat-model.md: specific vectors of concern listed with current mitigation status
[ ] findings-log.md: all internal findings logged with resolution and regression test
[ ] Coverage report generated and all uncovered lines annotated with justification
[ ] forge test passes with zero failures at the audit commit
[ ] slither runs clean — all findings triaged or documented
[ ] No console.log in src/ (grep -rn "console" src/ must return nothing)
[ ] All NatSpec complete on public/external functions, errors, events
[ ] README updated with deployment addresses and setup instructions

Document 1: Scope (docs/audit/scope.md)

The scope document is the contract between the dev team and auditors. Auditors quote time and cost based on scope. Scope changes mid-audit add cost and delay.

Required sections:

1.1 Commit Hash (Exact)

# Audit Scope

## Commit
Repository: https://github.com/<org>/<repo>
Commit hash: `abc123def456789...` (exact 40-char SHA — not a branch name)
Branch: main
Tag (if any): v1.0.0-audit

Pin the exact commit. Not "the main branch at the time of audit." Tag it.

1.2 In-Scope Files

## In-Scope Files
| File | Lines of Code | Description |
|------|---------------|-------------|
| src/Vault.sol | 287 | Core ERC-4626 vault implementation |
| src/VaultFactory.sol | 95 | Factory for deploying new vaults |
| src/interfaces/IVault.sol | 64 | Vault interface and events |
| src/libraries/ShareMath.sol | 42 | Share calculation library |

Total in-scope LOC: 488

Count lines with: cloc src/ --include-lang=Solidity

1.3 Out-of-Scope Files

## Out-of-Scope Files
| File/Directory | Reason |
|----------------|--------|
| src/mocks/ | Test-only, not deployed |
| lib/ | Third-party dependencies, separately audited |
| test/ | Test code, not deployed |
| script/ | Deployment scripts, not deployed |

1.4 Dependencies

## Dependencies
| Dependency | Version | Audit Status | Where Used |
|------------|---------|--------------|------------|
| OpenZeppelin Contracts | 5.0.2 | Audited by multiple firms | All contracts |
| Chainlink Data Feeds | v0.8 | Audited | src/Vault.sol (oracle) |
| Uniswap V3 Core | 1.0.0 | Audited | src/Vault.sol (TWAP) |

Unaudited dependencies are high-priority audit targets. Highlight them explicitly.

Document 2: Protocol Overview (docs/audit/protocol.md)

This document gives auditors the context they need before reading a line of code.

Required sections:

2.1 What It Does — plain English, no jargon

## What It Does

The Vault is an ERC-4626 yield-bearing vault that:
1. Accepts deposits of USDC from users
2. Deploys the deposited USDC to a lending strategy (Aave v3)
3. Accrues yield continuously from Aave interest
4. Allows users to withdraw their proportional share of assets plus yield at any time
5. Charges a 1% fee on withdrawals, sent to the protocol treasury

2.2 Actors and Their Permissions

## Actors
| Role | Who | Permissions | Address Type |
|------|-----|-------------|--------------|
| Owner | Protocol multisig | Set fees, pause, unpause, upgrade, set oracle | 3-of-5 Gnosis Safe |
| User | Any EOA or contract | Deposit, withdraw, transfer shares | Any address |
| Keeper | Protocol bot | Harvest yield (no fund access) | EOA controlled by team |

2.3 State Machine

## Contract Lifecycle

Deployment → Initialized → Active ←→ Paused → [Deprecated]

### Active State: users can deposit and withdraw; keeper can harvest yield
### Paused State: deposits blocked; withdrawals allowed (pause cannot trap funds)
### Deprecated State: irreversible; no deposits; withdrawals until all claimed

2.4 Invariants

List all invariants from the planner phase. These are the auditor's truth table:

## Invariants

These must hold after every transaction under any sequence of operations:

1. **Solvency**: token.balanceOf(vault) >= vault.totalAssets()
2. **Share accounting**: vault.totalSupply() == sum of vault.balanceOf(user) for all users
3. **Monotonicity**: totalAssetsDeposited is non-decreasing (absent strategy loss)
4. **Access control**: only OWNER_ROLE can call setFee(), pause(), upgradeTo()
5. **Pause**: whenPaused → deposit() reverts AND withdraw() succeeds

2.5 Trust Assumptions

## Trust Assumptions

### Trusted
- Owner multisig (3-of-5) is not malicious
- Chainlink oracle provides accurate prices within staleness threshold
- OpenZeppelin contracts behave as documented

### Adversarial
- Any user-supplied address (may be a malicious contract)
- Transaction ordering (MEV bots may front-run or sandwich)
- Flash loan capital (any amount can be borrowed atomically)

### Known Limitations (by design, not bugs)
- Fee-on-transfer tokens are not supported
- Rebasing tokens are not supported
- Tokens with blocklists may cause individual user issues

Document 3: Threat Model (docs/audit/threat-model.md)

Write it as if you're trying to break your own protocol. This is the auditor's attack playbook.

Required sections:

3.1 Attacker Goals — ranked by potential profit

## Attacker Goals

1. Drain vault funds — steal all deposited assets from all users
2. Inflate own position — manipulate share price to receive more assets than deposited
3. Deflate other positions — reduce redeemable value of other users' shares
4. Brick the contract (DoS) — prevent all users from withdrawing permanently
5. Extract MEV — front-run large deposits/withdrawals for risk-free profit
6. Bypass access control — gain owner-level permissions without multisig

3.2 Attacker Capabilities

## Attacker Capabilities

An attacker CAN:
- Submit transactions at any time and in any order
- Control transaction ordering (as a validator or via Flashbots)
- Take flash loans of any token in unlimited amounts within one block
- Deploy contracts with arbitrary logic (including malicious receive()/fallback())
- Read all on-chain state and pending mempool transactions
- Manipulate oracle prices within economic bounds

An attacker CANNOT:
- Forge signatures without the private key
- Break EVM cryptographic primitives
- Exceed the block gas limit in a single transaction
- Modify the state of a previous block (assuming >2 confirmations)

3.3 Specific Attack Vectors of Concern

List every known attack vector, even if mitigated. Include mitigation status:

## Specific Attack Vectors of Concern

### HIGH PRIORITY

**V-1: First-Depositor Share Inflation Attack**
- Scenario: First depositor deposits 1 wei, donates 1M tokens directly to vault,
  inflating share price. Next depositor receives 0 shares.
- Mitigation: Virtual shares offset (totalSupply + 1e18, totalAssets + 1e18)
- Status: Mitigated. Ask auditors to verify the virtual share math is correct.

**V-2: Flash Loan Price Manipulation**
- Scenario: Attacker uses flash loan to manipulate spot price used in share math.
- Mitigation: No spot price used; share conversion uses vault's own totalAssets.
- Status: Mitigated. Ask auditors to verify no path for same-block manipulation.

### MEDIUM PRIORITY

**V-3: Oracle Staleness**
- Scenario: Chainlink offline; stale price enables incorrect operations.
- Mitigation: Staleness check: if (block.timestamp - updatedAt > 1 hours) revert.
- Status: Mitigated.

Document 4: Internal Findings Log (docs/audit/findings-log.md)

Proves to external auditors that internal review was thorough. Also defines known issues.

# Internal Findings Log

## Finding Table
| ID | Severity | Title | Status | Regression Test |
|----|----------|-------|--------|-----------------|
| INT-001 | High | Missing CEI in withdraw() — reentrancy possible | Fixed (commit abc123) | test_withdraw_nonReentrant |
| INT-002 | Medium | No staleness check on Chainlink oracle | Fixed (commit def456) | test_getPrice_revertsWhenStale |
| INT-003 | Low | uint256 overflow in calculateFee for extreme values | Fixed with SafeCast | testFuzz_calculateFee_noOverflow |

## Wontfix / Known Limitations
| ID | Severity | Title | Reason |
|----|----------|-------|--------|
| INT-004 | Low | Fee-on-transfer tokens silently lose value | By design: only allowlisted standard tokens accepted |

Coverage Report

# Generate LCOV coverage data
forge coverage --report lcov

# Generate HTML report for browsing
genhtml lcov.info --branch-coverage --output-dir coverage/

Coverage requirements:

• Security-critical paths: 100% line and branch coverage
• Happy paths: 100% line coverage
• Error paths: 100% (every revert path has at least one test)
• Uncovered lines: annotate each in coverage/coverage-notes.md

# Coverage Notes

## Uncovered Lines and Justification
| File | Line | Code | Reason |
|------|------|------|--------|
| src/Vault.sol | 247 | revert UnreachableCode(); | Defensive revert; state is impossible given function preconditions. Covered by invariant tests. |
| src/Vault.sol | 312 | catch {} | Chainlink failure path. Covered by mock oracle fork test. |

Auditors see every uncovered line. An unexplained uncovered line looks like an untested bug. Explain all of them.

Forge Commands

# Tag the audit commit
git tag v1.0.0-audit <commit-hash>
git push origin v1.0.0-audit

# Run full test suite (must pass at zero failures)
forge test

# Generate coverage report
forge coverage --report lcov
genhtml lcov.info --branch-coverage --output-dir coverage/

# Run Slither (must be triaged before audit)
slither . --filter-paths "test,script,lib"

# Count in-scope LOC
cloc src/ --include-lang=Solidity

# Check for console.log (must return nothing)
grep -rn "console" src/

# Generate NatSpec docs
forge doc --out docs/natspec/

# Verify no compile warnings
forge build

Output Artifacts

• docs/audit/scope.md
• docs/audit/protocol.md
• docs/audit/threat-model.md
• docs/audit/findings-log.md
• coverage/ — HTML coverage report
• coverage/lcov.info — raw LCOV data
• coverage/coverage-notes.md — uncovered line justifications

Terminal State

This is the final skill in the V1 lifecycle. After audit prep is complete:

• Send the package to auditors
• Engage with auditor questions using the documentation as reference
• After audit completion: apply findings, write regression tests, update findings log

Blocked Rationalizations