solidity-argus 0.1.0

package/skills/protocol-patterns/lending-borrowing/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: lending-borrowing
+description: Security review framework for lending and borrowing systems including liquidations and accounting.
+---
+<!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->
+
+# Lending Protocol Security Guide
+
+## Overview
+
+Lending protocols (Aave, Compound, Morpho) enable collateralized borrowing. Core security concerns: liquidation logic, interest accrual, oracle reliance, and collateral management.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      LENDING PROTOCOL                       │
+├─────────────────────────────────────────────────────────────┤
+│  SUPPLY          │  BORROW           │  LIQUIDATE          │
+│  ─────────       │  ─────────        │  ─────────          │
+│  Deposit asset   │  Lock collateral  │  Seize collateral   │
+│  Receive shares  │  Receive asset    │  Repay debt         │
+│  Earn interest   │  Pay interest     │  Get bonus          │
+├─────────────────────────────────────────────────────────────┤
+│                      RISK ENGINE                            │
+│  Health Factor = Collateral Value / Borrowed Value          │
+│  If HF < 1: Position is liquidatable                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Critical Security Areas
+
+### 1. Liquidation Logic
+
+**Attack Vectors:**
+- Self-liquidation for profit
+- Liquidation front-running
+- Incorrect health factor calculation
+- Liquidation bonus manipulation
+
+**Checklist:**
+- [ ] Can users self-liquidate profitably?
+- [ ] Is health factor calculation correct with all decimal handling?
+- [ ] Is liquidation bonus reasonable (not exploitable)?
+- [ ] Are partial liquidations handled correctly?
+- [ ] Can dust amounts block liquidation?
+
+```solidity
+// VULNERABLE: No self-liquidation check
+function liquidate(address borrower, uint256 amount) external {
+    require(getHealthFactor(borrower) < 1e18, "Healthy");
+    // Missing: require(msg.sender != borrower, "No self-liquidation");
+}
+```
+
+### 2. Interest Rate Model
+
+**Attack Vectors:**
+- Interest rate manipulation via large deposits/borrows
+- Accrual timing exploits
+- Compound interest calculation errors
+
+**Checklist:**
+- [ ] Is interest accrued before all operations?
+- [ ] Are utilization rate calculations correct?
+- [ ] Can interest rate be manipulated within a transaction?
+- [ ] Are there bounds on interest rates?
+
+```solidity
+// VULNERABLE: Interest not accrued before operation
+function withdraw(uint256 amount) external {
+    // Missing: accrueInterest();
+    uint256 shares = amount * totalShares / totalAssets;
+    _burn(msg.sender, shares);
+}
+
+// SECURE
+function withdraw(uint256 amount) external {
+    accrueInterest();  // Always accrue first
+    uint256 shares = amount * totalShares / totalAssets;
+    _burn(msg.sender, shares);
+}
+```
+
+### 3. Oracle Dependency
+
+**Attack Vectors:**
+- Price oracle manipulation
+- Stale price exploitation
+- Flash loan + oracle attack
+
+**Checklist:**
+- [ ] Are oracle prices validated for freshness?
+- [ ] Are price bounds checked?
+- [ ] Can prices be manipulated via flash loans?
+- [ ] Is there circuit breaker for price anomalies?
+
+See: [oracle.md](./exploits/oracle.md)
+
+### 4. Collateral Management
+
+**Attack Vectors:**
+- Depositing worthless collateral
+- Collateral factor manipulation
+- Bad debt accumulation
+
+**Checklist:**
+- [ ] Are collateral factors appropriate for asset volatility?
+- [ ] Is there a whitelist for supported collateral?
+- [ ] How is bad debt handled?
+- [ ] Can users withdraw collateral below safe threshold?
+
+### 5. Share/Asset Accounting (ERC4626)
+
+**Attack Vectors:**
+- Inflation attacks on first deposit
+- Rounding direction exploitation
+- Donation attacks
+
+**Checklist:**
+- [ ] Is first depositor protected from inflation attack?
+- [ ] Does rounding favor the protocol (round down on mint, up on burn)?
+- [ ] Are direct asset transfers (donations) handled?
+- [ ] Is totalAssets always ≥ sum of deposits?
+
+```solidity
+// Inflation attack protection
+function deposit(uint256 assets) external returns (uint256 shares) {
+    require(assets >= MINIMUM_DEPOSIT, "Below minimum");
+    shares = totalSupply == 0 
+        ? assets  // First deposit
+        : assets * totalSupply / totalAssets;
+    require(shares > 0, "Zero shares");
+    // ...
+}
+```
+
+---
+
+## Common Vulnerabilities
+
+### Reentrancy in Lending
+
+```solidity
+// VULNERABLE: CEI violation
+function borrow(uint256 amount) external {
+    require(checkCollateral(msg.sender, amount), "Undercollateralized");
+    token.transfer(msg.sender, amount);  // External call before state update
+    borrowBalances[msg.sender] += amount;  // State update after
+}
+```
+
+### Incorrect Decimal Handling
+
+```solidity
+// VULNERABLE: Assumes all tokens have 18 decimals
+function calculateValue(address token, uint256 amount) public view returns (uint256) {
+    uint256 price = oracle.getPrice(token);  // Price in USD with 8 decimals
+    return amount * price / 1e8;  // Wrong if token isn't 18 decimals!
+}
+
+// SECURE
+function calculateValue(address token, uint256 amount) public view returns (uint256) {
+    uint256 price = oracle.getPrice(token);
+    uint8 decimals = IERC20Metadata(token).decimals();
+    return amount * price / (10 ** decimals);
+}
+```
+
+### Liquidation Threshold Edge Cases
+
+```solidity
+// VULNERABLE: Dust prevents liquidation
+function liquidate(address borrower, uint256 amount) external {
+    uint256 debt = borrowBalances[borrower];
+    require(amount <= debt, "Too much");
+    // If debt = 100 wei and minimum repay = 100 wei, can't liquidate
+}
+```
+
+---
+
+## Testing Checklist
+
+### Unit Tests
+- [ ] Deposit/withdraw accounting correct
+- [ ] Borrow/repay accounting correct
+- [ ] Interest accrual over time
+- [ ] Liquidation triggers at correct threshold
+- [ ] Health factor calculation
+
+### Integration Tests
+- [ ] Oracle integration
+- [ ] Multi-asset interactions
+- [ ] Liquidation bot behavior
+
+### Invariant Tests
+- [ ] totalBorrowed ≤ totalSupplied * maxUtilization
+- [ ] Each user's healthFactor > 1 OR liquidatable
+- [ ] Sum of deposits = totalAssets (accounting)
+- [ ] No negative balances
+
+### Edge Case Tests
+- [ ] First deposit (empty pool)
+- [ ] Last withdrawal (drain pool)
+- [ ] Zero amount operations
+- [ ] Max uint256 operations
+- [ ] 1 wei operations
+
+---
+
+## References
+
+- [Aave V3 Security](https://github.com/aave/aave-v3-core/tree/master/audits)
+- [Compound Security Considerations](https://docs.compound.finance/security/)
+- [ERC4626 Security Considerations](https://eips.ethereum.org/EIPS/eip-4626#security-considerations)
+- [Morpho Security](https://docs.morpho.org/morpho-blue/security-and-risk-management)

package/skills/protocol-patterns/staking-vesting/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: staking-vesting
+description: Staking security guidance for reward accounting, lock periods, timing attacks, and withdrawals.
+---
+<!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->
+
+# Staking Protocol Security Guide
+
+## Overview
+
+Staking protocols lock tokens to earn rewards. Core security concerns: reward calculation, timing attacks, withdrawal delays, and token accounting.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     STAKING PROTOCOL                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│   STAKE            EARN              UNSTAKE                │
+│   ──────           ────              ───────                │
+│   Lock tokens  →   Accrue rewards  →  Withdraw + rewards    │
+│                                                             │
+│   rewardPerToken = totalRewards / totalStaked / time        │
+│                                                             │
+│   userReward = (rewardPerToken - userRewardPaid) * balance  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Critical Security Areas
+
+### 1. Reward Calculation
+
+**Attack Vectors:**
+- Claim rewards multiple times
+- Manipulation of rewardPerToken
+- Precision loss in reward math
+
+**Checklist:**
+- [ ] Is rewardPerTokenStored updated before any balance changes?
+- [ ] Is userRewardPerTokenPaid updated when claiming?
+- [ ] Can rewards be claimed multiple times for same period?
+- [ ] Is precision sufficient (multiply before divide)?
+
+```solidity
+// Standard Synthetix staking pattern
+uint256 public rewardPerTokenStored;
+mapping(address => uint256) public userRewardPerTokenPaid;
+mapping(address => uint256) public rewards;
+
+modifier updateReward(address account) {
+    rewardPerTokenStored = rewardPerToken();
+    lastUpdateTime = block.timestamp;
+    if (account != address(0)) {
+        rewards[account] = earned(account);
+        userRewardPerTokenPaid[account] = rewardPerTokenStored;
+    }
+    _;
+}
+
+function earned(address account) public view returns (uint256) {
+    return balances[account] * 
+        (rewardPerToken() - userRewardPerTokenPaid[account]) / 1e18 +
+        rewards[account];
+}
+```
+
+### 2. Deposit/Withdrawal Timing
+
+**Attack Vectors:**
+- Stake just before rewards, unstake right after
+- Flash loan staking
+- MEV on reward distribution
+
+**Checklist:**
+- [ ] Is there a minimum stake duration?
+- [ ] Are rewards distributed over time (not lump sum)?
+- [ ] Can someone stake in same block as reward distribution?
+- [ ] Is there unstaking delay/cooldown?
+
+```solidity
+// VULNERABLE: Instant stake and claim
+function distributeReward(uint256 amount) external {
+    rewardToken.transferFrom(msg.sender, address(this), amount);
+    rewardPerTokenStored += amount * 1e18 / totalStaked;
+    // Flash staker can stake before this, claim after
+}
+
+// SECURE: Drip rewards over time
+function notifyRewardAmount(uint256 reward) external {
+    if (block.timestamp >= periodFinish) {
+        rewardRate = reward / DURATION;
+    } else {
+        uint256 remaining = periodFinish - block.timestamp;
+        uint256 leftover = remaining * rewardRate;
+        rewardRate = (reward + leftover) / DURATION;
+    }
+    lastUpdateTime = block.timestamp;
+    periodFinish = block.timestamp + DURATION;
+}
+```
+
+### 3. Token Accounting
+
+**Attack Vectors:**
+- Donation attacks (direct transfer)
+- Rebase token issues
+- Fee-on-transfer tokens
+
+**Checklist:**
+- [ ] Are direct token transfers handled?
+- [ ] Is actual received amount checked (fee-on-transfer)?
+- [ ] Are rebase tokens supported? If so, how?
+- [ ] Is totalStaked always equal to sum of balances?
+
+```solidity
+// VULNERABLE: Assumes full amount received
+function stake(uint256 amount) external {
+    stakingToken.transferFrom(msg.sender, address(this), amount);
+    balances[msg.sender] += amount;  // Wrong for fee-on-transfer!
+    totalStaked += amount;
+}
+
+// SECURE: Check actual amount received
+function stake(uint256 amount) external {
+    uint256 balanceBefore = stakingToken.balanceOf(address(this));
+    stakingToken.transferFrom(msg.sender, address(this), amount);
+    uint256 received = stakingToken.balanceOf(address(this)) - balanceBefore;
+    
+    balances[msg.sender] += received;
+    totalStaked += received;
+}
+```
+
+### 4. Lock/Unlock Mechanisms
+
+**Attack Vectors:**
+- Bypassing lock periods
+- Lock period manipulation
+- Emergency withdrawal exploits
+
+**Checklist:**
+- [ ] Is lock timestamp immutable after staking?
+- [ ] Can partial unlocks bypass full lock?
+- [ ] Is emergency withdrawal penalized appropriately?
+- [ ] Are there reentrancy risks in unlock?
+
+```solidity
+// VULNERABLE: Lock can be extended/reset incorrectly
+function stake(uint256 amount) external {
+    balances[msg.sender] += amount;
+    lockEnd[msg.sender] = block.timestamp + LOCK_PERIOD;  // Resets lock!
+}
+
+// SECURE: Don't reset existing locks
+function stake(uint256 amount) external {
+    balances[msg.sender] += amount;
+    if (lockEnd[msg.sender] < block.timestamp) {
+        lockEnd[msg.sender] = block.timestamp + LOCK_PERIOD;
+    }
+    // Existing lock preserved
+}
+```
+
+### 5. Reward Token Handling
+
+**Attack Vectors:**
+- Same token for stake and reward (inflation)
+- Reward token donation manipulation
+- Insufficient reward balance
+
+**Checklist:**
+- [ ] Is stake token different from reward token?
+- [ ] Is there sufficient reward balance for all claims?
+- [ ] Can reward distribution be griefed?
+- [ ] Are multiple reward tokens handled correctly?
+
+---
+
+## Common Vulnerabilities
+
+### Reentrancy in Claim
+
+```solidity
+// VULNERABLE: External call before state update
+function claim() external {
+    uint256 reward = earned(msg.sender);
+    rewardToken.transfer(msg.sender, reward);  // External call first
+    rewards[msg.sender] = 0;  // State update after
+}
+```
+
+### Division Before Multiplication
+
+```solidity
+// VULNERABLE: Precision loss
+function rewardPerToken() public view returns (uint256) {
+    if (totalStaked == 0) return rewardPerTokenStored;
+    return rewardPerTokenStored + 
+        (rewardRate / totalStaked) * (block.timestamp - lastUpdate);  // Wrong order!
+}
+
+// SECURE
+function rewardPerToken() public view returns (uint256) {
+    if (totalStaked == 0) return rewardPerTokenStored;
+    return rewardPerTokenStored + 
+        rewardRate * (block.timestamp - lastUpdate) * 1e18 / totalStaked;
+}
+```
+
+---
+
+## Testing Checklist
+
+### Unit Tests
+- [ ] Stake/unstake accounting
+- [ ] Reward accrual over time
+- [ ] Multiple stakers, proportional rewards
+- [ ] Claim resets user state correctly
+
+### Integration Tests
+- [ ] Multiple reward periods
+- [ ] Stakers joining mid-period
+- [ ] Edge cases (first staker, last staker)
+
+### Invariant Tests
+- [ ] totalStaked = sum(balances)
+- [ ] Rewards claimable ≤ reward balance
+- [ ] No user can claim more than entitled
+
+### Attack Tests
+- [ ] Flash stake attack
+- [ ] Double claim attempt
+- [ ] Donation manipulation
+
+---
+
+## References
+
+- [Synthetix Staking Rewards](https://github.com/Synthetixio/synthetix/blob/develop/contracts/StakingRewards.sol)
+- [Convex Staking](https://github.com/convex-eth/platform)
+- [MasterChef (SushiSwap)](https://github.com/sushiswap/sushiswap/blob/master/contracts/MasterChef.sol)