code-analysis

# Code Reconnaissance Methodology

## Purpose

Rapidly understand **what the code does** through structural analysis and flow tracing.
This is reconnaissance, not vulnerability hunting.

---

## 1. File Discovery

### By Language

| Language | Find Files | Framework Markers |
|----------|------------|-------------------|
| Solidity | `Glob("**/*.sol")` | `foundry.toml`, `hardhat.config.*` |
| Rust | `Glob("**/programs/**/*.rs")` | `Anchor.toml`, `Cargo.toml` |
| Cairo | `Glob("**/*.cairo")` | `Scarb.toml` |
| Move | `Glob("**/*.move")` | `Move.toml` |

### Skip These
- `test/`, `tests/`, `*.t.sol`, `*.test.sol`
- `mock/`, `mocks/`, `*Mock.sol`
- `node_modules/`, `lib/` (dependencies)
- Generated/compiled files

---

## 2. Contract Structure Analysis

### For Each Contract, Extract:

```
Contract: {Name}
File: {path}
Purpose: {one line description}
Inherits: {parent contracts}
Key State: {important state variables}
Entry Points: {external/public functions}
```

### Inheritance Mapping

```
BaseContract
├── ChildA
│   └── GrandchildA1
└── ChildB
```

### External Dependencies

| Import | Type | Notes |
|--------|------|-------|
| @openzeppelin/... | Standard lib | Usually safe |
| @chainlink/... | Oracle | Price dependency |
| @uniswap/... | DEX integration | External call |

---

## 3. Flow Tracing

### The Core Question
**"How does value enter, move through, and exit this protocol?"**

### Entry Flows (How users put value in)

| Pattern | Function Names | What Happens |
|---------|---------------|--------------|
| Deposit | `deposit`, `supply`, `provide` | Assets in, receipts out |
| Stake | `stake`, `lock`, `bond` | Assets locked, tracking updated |
| Swap In | `swap`, `exchange` | Asset A in, Asset B out |
| Mint | `mint`, `create` | Payment in, tokens created |

### Internal Flows (How value transforms)

| Pattern | What to Look For |
|---------|------------------|
| Calculations | Fee deductions, interest accrual, share pricing |
| State Changes | Balance updates, position tracking |
| Internal Calls | Function-to-function flow within contract |
| External Calls | Interactions with other contracts |

### Exit Flows (How users get value out)

| Pattern | Function Names | What Happens |
|---------|---------------|--------------|
| Withdraw | `withdraw`, `remove`, `redeem` | Receipts burned, assets out |
| Unstake | `unstake`, `unlock`, `unbond` | Assets released |
| Claim | `claim`, `harvest`, `collect` | Rewards distributed |

### Privileged Flows (Admin operations)

| Pattern | Risk Level | What to Note |
|---------|------------|--------------|
| `emergencyWithdraw` | High | Can bypass normal checks |
| `sweep`, `rescue` | High | Can move arbitrary tokens |
| `pause`, `unpause` | Medium | Can halt operations |
| `setFee`, `setRate` | Medium | Can change economics |

---

## 4. Protocol Type Classification

### Identify by Code Patterns

| Protocol Type | Key Indicators | Main Flows |
|---------------|----------------|------------|
| **AMM/DEX** | `reserve0`, `reserve1`, `k`, `swap()`, `addLiquidity()` | swap, add/remove liquidity |
| **Lending** | `borrow()`, `collateral`, `liquidate()`, `interestRate` | supply, borrow, repay, liquidate |
| **Vault** | `totalAssets()`, `totalSupply()`, `shares`, ERC4626 | deposit, withdraw, yield |
| **Governance** | `propose()`, `vote()`, `execute()`, `quorum` | propose, vote, execute |
| **Staking** | `stake()`, `rewards`, `epoch`, `rewardPerToken` | stake, claim rewards |
| **Bridge** | `lock()`, `mint()`, `relayMessage()`, `nonce` | lock on L1, mint on L2 |

---

## 5. Asset Storage Patterns

### ETH Storage

```solidity
// Direct balance
address(this).balance

// Wrapped
WETH.balanceOf(address(this))
```

### Token Storage

```solidity
// External balance check
IERC20(token).balanceOf(address(this))

// Internal accounting
mapping(address => uint256) balances;
uint256 totalDeposited;
```

### Share/Receipt Tokens

```solidity
// Protocol issues these
mapping(address => uint256) shares;
uint256 totalSupply;
function balanceOf(address) external view returns (uint256);
```

---

## 6. Notable Patterns to Mark

Mark location only. No analysis needed - Phase 2 handles that.

| Pattern | Why Notable |
|---------|-------------|
| `.call{value:}` | External call with ETH |
| `delegatecall` | Code execution delegation |
| External contract calls | Trust boundary crossing |
| `onlyOwner`, `onlyAdmin` | Privileged operations |
| Oracle integration | External data dependency |
| Complex math | Potential calculation issues |
| Assembly blocks | Low-level operations |

---

## 7. Search Queries

### Find Entry Points

```
Grep("function.*external|function.*public", glob="**/*.sol")
```

### Find Asset Movements

```
Grep("transfer\\(|transferFrom\\(|safeTransfer", glob="**/*.sol")
```

### Find Privileged Functions

```
Grep("onlyOwner|onlyAdmin|onlyRole|require.*msg\\.sender", glob="**/*.sol")
```

### Find External Calls

```
Grep("\\.call\\{|\\.delegatecall\\(|address\\(.*\\)\\..*\\(", glob="**/*.sol")
```

---

## Output

Write findings to `.vigilo/recon/code-findings.md` following the format in
[template.md](template.md).

---

## Additional Resources

- [template.md](template.md) - Output template for code reconnaissance findings
- [examples/minimal-output.md](examples/minimal-output.md) - Minimal output example for small projects