solidity-argus 0.1.0

package/skills/protocol-patterns/bridges-cross-chain/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: bridges-cross-chain
+description: Cross-chain bridge security guidance for message verification, replay prevention, and validator risk.
+---
+<!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->
+
+# Cross-Chain Bridge Security Guide
+
+## Overview
+
+Bridges transfer assets/messages between blockchains. They are the highest-value targets in DeFi — $2B+ stolen from bridges. Core security concerns: message verification, validator security, and replay attacks.
+
+---
+
+## Architecture
+
+```
+┌─────────────────┐                      ┌─────────────────┐
+│   Chain A       │                      │   Chain B       │
+│                 │                      │                 │
+│  ┌───────────┐  │      Message         │  ┌───────────┐  │
+│  │  Bridge   │  │ ──────────────────►  │  │  Bridge   │  │
+│  │ Contract  │  │                      │  │ Contract  │  │
+│  └───────────┘  │                      │  └───────────┘  │
+│       │         │                      │       │         │
+│  Lock/Burn      │    ┌──────────────┐  │  Mint/Unlock    │
+│  Tokens         │    │  Validators  │  │  Tokens         │
+│                 │    │  / Relayers  │  │                 │
+└─────────────────┘    └──────────────┘  └─────────────────┘
+                              │
+                    Sign attestations
+```
+
+---
+
+## Critical Security Areas
+
+### 1. Message Verification
+
+**Attack Vectors:**
+- Forged signatures
+- Invalid merkle proofs
+- Malformed message data
+
+**Checklist:**
+- [ ] Is signature verification correct for all edge cases?
+- [ ] Are all required fields validated?
+- [ ] Is the source chain verified?
+- [ ] Is the source contract verified?
+- [ ] Are merkle proofs validated correctly?
+
+```solidity
+// VULNERABLE: Incomplete verification
+function processMessage(
+    bytes32 messageHash,
+    bytes[] calldata signatures
+) external {
+    uint256 validSigs;
+    for (uint i; i < signatures.length; i++) {
+        address signer = recoverSigner(messageHash, signatures[i]);
+        if (isValidator[signer]) validSigs++;
+    }
+    require(validSigs >= threshold, "Not enough sigs");
+    // Missing: Check for duplicate signers!
+}
+
+// SECURE: Track used signatures
+function processMessage(
+    bytes32 messageHash,
+    bytes[] calldata signatures
+) external {
+    uint256 validSigs;
+    address lastSigner;
+    
+    for (uint i; i < signatures.length; i++) {
+        address signer = recoverSigner(messageHash, signatures[i]);
+        require(signer > lastSigner, "Invalid sig order");  // Prevents duplicates
+        if (isValidator[signer]) validSigs++;
+        lastSigner = signer;
+    }
+    require(validSigs >= threshold, "Not enough sigs");
+}
+```
+
+### 2. Replay Protection
+
+**Attack Vectors:**
+- Replay same message multiple times
+- Replay across chains (chainId not included)
+- Replay after upgrade
+
+**Checklist:**
+- [ ] Is each message marked as processed?
+- [ ] Is chainId included in message hash?
+- [ ] Is nonce/sequence number enforced?
+- [ ] Is contract address included in hash?
+
+```solidity
+// VULNERABLE: No replay protection
+function executeMessage(bytes calldata message, bytes calldata proof) external {
+    require(verifyProof(message, proof), "Invalid proof");
+    _execute(message);  // Can be called again with same message!
+}
+
+// SECURE: Mark as processed
+mapping(bytes32 => bool) public processedMessages;
+
+function executeMessage(bytes calldata message, bytes calldata proof) external {
+    bytes32 messageHash = keccak256(message);
+    require(!processedMessages[messageHash], "Already processed");
+    require(verifyProof(message, proof), "Invalid proof");
+    
+    processedMessages[messageHash] = true;
+    _execute(message);
+}
+```
+
+### 3. Validator/Guardian Security
+
+**Attack Vectors:**
+- Compromised validator keys
+- Collusion attack (threshold too low)
+- Single point of failure
+
+**Checklist:**
+- [ ] Is validator set distributed (different orgs, geographies)?
+- [ ] Is threshold sufficient (e.g., 5/9 minimum)?
+- [ ] Is there key rotation mechanism?
+- [ ] Are validators timelock-protected for removal?
+
+### 4. Token Accounting
+
+**Attack Vectors:**
+- Mint more tokens than locked
+- Unlock without corresponding lock
+- Fee accounting errors
+
+**Checklist:**
+- [ ] Can bridge mint more than total locked?
+- [ ] Is there 1:1 backing for wrapped tokens?
+- [ ] Are fees handled correctly?
+- [ ] Is there a way to pause minting?
+
+```solidity
+// Ideal invariant
+assert(wrappedTokenSupply <= originalTokenLockedAmount);
+```
+
+### 5. Upgrade Security
+
+**Attack Vectors:**
+- Malicious upgrade bypassing governance
+- Storage collision on upgrade
+- Uninitialized implementation
+
+**Checklist:**
+- [ ] Is upgrade path protected by timelock?
+- [ ] Is implementation initializer protected?
+- [ ] Are storage slots carefully managed?
+- [ ] Is there emergency pause?
+
+---
+
+## Real Exploits
+
+### Ronin Bridge (Mar 2022) — $625M
+
+**What happened:**
+- Attackers compromised 5 of 9 validator keys
+- Signed fraudulent withdrawal messages
+- Drained ETH and USDC
+
+**Root cause:** Insufficient validator distribution + social engineering
+
+### Wormhole (Feb 2022) — $326M
+
+**What happened:**
+- Attacker exploited Solana signature verification bug
+- Forged guardian signatures
+- Minted 120k wETH without deposit
+
+**Root cause:** Invalid signature verification on Solana side
+
+### Nomad (Aug 2022) — $190M
+
+**What happened:**
+- Routine upgrade set trusted root to 0x00
+- Zero was treated as "valid" proof
+- Anyone could submit fake messages as proven
+
+**Root cause:** Zero initialization treated as valid state
+
+```solidity
+// The Nomad bug pattern
+mapping(bytes32 => uint256) public messages;
+
+function process(bytes memory _message) public {
+    bytes32 _messageHash = keccak256(_message);
+    // messages[_messageHash] == 0 was treated as confirmed!
+    require(acceptableRoot(messages[_messageHash]), "not accepted");
+}
+```
+
+### Poly Network (Aug 2021) — $611M
+
+**What happened:**
+- Attacker exploited cross-chain contract call
+- Changed keeper to attacker address
+- Drained all chains
+
+**Root cause:** Insufficient validation of cross-chain call targets
+
+---
+
+## Bridge Types & Specific Risks
+
+### Lock & Mint
+- Risk: Minting without lock
+- Check: Mint events should have corresponding lock
+
+### Burn & Unlock
+- Risk: Unlocking without burn
+- Check: Burn verification before unlock
+
+### Liquidity Networks (Hop, Across)
+- Risk: LP manipulation
+- Check: Bonder collateral, fees
+
+### Optimistic Bridges (Nomad-style)
+- Risk: Challenge period bypass
+- Check: Fraud proof implementation
+
+---
+
+## Testing Checklist
+
+### Unit Tests
+- [ ] Message encoding/decoding
+- [ ] Signature verification
+- [ ] Replay protection
+- [ ] Access control on critical functions
+
+### Integration Tests
+- [ ] Full message flow (both directions)
+- [ ] Multiple concurrent messages
+- [ ] Fee handling
+
+### Attack Tests
+- [ ] Message replay attempt
+- [ ] Forged signature
+- [ ] Duplicate signer attack
+- [ ] Cross-chain replay
+
+### Invariant Tests
+- [ ] Wrapped supply ≤ locked amount
+- [ ] Each message processed exactly once
+- [ ] Validator count ≥ threshold
+
+---
+
+## Secure Patterns
+
+### Message Structure
+
+```solidity
+struct Message {
+    uint256 srcChainId;
+    uint256 dstChainId;
+    address srcContract;
+    address dstContract;
+    uint256 nonce;
+    bytes payload;
+}
+
+function hashMessage(Message memory m) internal pure returns (bytes32) {
+    return keccak256(abi.encode(
+        m.srcChainId,
+        m.dstChainId,
+        m.srcContract,
+        m.dstContract,
+        m.nonce,
+        keccak256(m.payload)
+    ));
+}
+```
+
+### Ordered Signatures (Prevents Duplicates)
+
+```solidity
+function verifySignatures(
+    bytes32 hash,
+    bytes[] calldata sigs
+) internal view returns (bool) {
+    address lastSigner = address(0);
+    uint256 valid;
+    
+    for (uint i; i < sigs.length; i++) {
+        address signer = ECDSA.recover(hash, sigs[i]);
+        require(signer > lastSigner, "Signatures not ordered");
+        
+        if (guardians[signer]) valid++;
+        lastSigner = signer;
+    }
+    
+    return valid >= threshold;
+}
+```
+
+---
+
+## References
+
+- [L2Beat Bridge Risk Framework](https://l2beat.com/bridges/risk)
+- [Rekt Bridge Leaderboard](https://rekt.news/leaderboard/)
+- [LayerZero Security Model](https://layerzero.gitbook.io/docs/faq/security)
+- [Wormhole Post-Mortem](https://wormholecrypto.medium.com/wormhole-incident-report-02-02-22-ad9b8f21eec6)
+- [Nomad Post-Mortem](https://medium.com/nomad-xyz-blog/nomad-bridge-hack-root-cause-analysis-875ad2e5aacd)

package/skills/protocol-patterns/dao-governance/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: dao-governance
+description: Governance security patterns for voting, timelocks, proposal execution, and quorum safety.
+---
+<!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->
+
+# Governance Protocol Security Guide
+
+## Overview
+
+Governance protocols enable token-based decision making. Core security concerns: voting manipulation, flash loan attacks, proposal execution, and timelock bypasses.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    GOVERNANCE SYSTEM                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│   PROPOSE      →      VOTE        →      EXECUTE            │
+│   ────────            ────               ───────            │
+│   Create proposal     Cast votes         After timelock     │
+│   Meet threshold      Snapshot power     Run actions        │
+│                                                             │
+│   ┌──────────────────────────────────────────────────────┐  │
+│   │                    TIMELOCK                          │  │
+│   │   Queue → Wait (e.g., 2 days) → Execute              │  │
+│   └──────────────────────────────────────────────────────┘  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Critical Security Areas
+
+### 1. Flash Loan Voting
+
+**Attack Vectors:**
+- Borrow tokens, vote, return in same block
+- Acquire governance majority temporarily
+
+**Checklist:**
+- [ ] Is voting power snapshot-based (past block)?
+- [ ] Is there delay between proposal and voting start?
+- [ ] Can voting power be acquired and used in same transaction?
+
+```solidity
+// VULNERABLE: Current balance for voting
+function vote(uint256 proposalId, bool support) external {
+    uint256 votes = token.balanceOf(msg.sender);  // Flashloanable!
+    _castVote(proposalId, msg.sender, support, votes);
+}
+
+// SECURE: Historical balance (ERC20Votes)
+function vote(uint256 proposalId, bool support) external {
+    uint256 votes = token.getPastVotes(
+        msg.sender, 
+        proposals[proposalId].snapshot  // Block when proposal created
+    );
+    _castVote(proposalId, msg.sender, support, votes);
+}
+```
+
+### 2. Proposal Execution
+
+**Attack Vectors:**
+- Malicious calldata
+- Reentrancy during execution
+- State manipulation between queue and execute
+
+**Checklist:**
+- [ ] Is there a timelock between queue and execute?
+- [ ] Are proposal actions validated?
+- [ ] Is there reentrancy protection?
+- [ ] Can proposal be executed multiple times?
+
+```solidity
+// VULNERABLE: No execution state check
+function execute(uint256 proposalId) external {
+    Proposal storage p = proposals[proposalId];
+    require(p.state == ProposalState.Succeeded, "Not succeeded");
+    // Missing: p.state = ProposalState.Executed;
+    
+    for (uint256 i; i < p.targets.length; i++) {
+        p.targets[i].call(p.calldatas[i]);
+    }
+    // Can be called again!
+}
+```
+
+### 3. Quorum & Threshold Manipulation
+
+**Attack Vectors:**
+- Lowering quorum via governance
+- Manipulating total supply for quorum calculation
+- Emergency actions without proper threshold
+
+**Checklist:**
+- [ ] Is quorum based on total supply or snapshot?
+- [ ] Can quorum/threshold be changed to dangerous levels?
+- [ ] Are there bounds on governance parameters?
+- [ ] Is total supply snapshot-based?
+
+```solidity
+// VULNERABLE: Quorum based on current supply
+function quorum() public view returns (uint256) {
+    return token.totalSupply() * 4 / 100;  // Can be manipulated
+}
+
+// SECURE: Quorum at snapshot
+function quorum(uint256 blockNumber) public view returns (uint256) {
+    return token.getPastTotalSupply(blockNumber) * 4 / 100;
+}
+```
+
+### 4. Timelock Security
+
+**Attack Vectors:**
+- Bypassing timelock via emergency functions
+- Timelock too short for community response
+- Admin can cancel queued proposals
+
+**Checklist:**
+- [ ] Is timelock long enough (24h minimum, 48h+ recommended)?
+- [ ] Are emergency bypasses properly restricted?
+- [ ] Can queued proposals be canceled maliciously?
+- [ ] Is there grace period after timelock?
+
+```solidity
+uint256 public constant MINIMUM_DELAY = 2 days;
+uint256 public constant MAXIMUM_DELAY = 30 days;
+uint256 public constant GRACE_PERIOD = 14 days;
+
+function setDelay(uint256 delay) external {
+    require(msg.sender == address(this), "Only self");
+    require(delay >= MINIMUM_DELAY, "Too short");
+    require(delay <= MAXIMUM_DELAY, "Too long");
+    delay_ = delay;
+}
+```
+
+### 5. Delegation & Voting Power
+
+**Attack Vectors:**
+- Double voting via delegation
+- Delegation to zero address
+- Vote power not updating on transfer
+
+**Checklist:**
+- [ ] Is delegation handled correctly (no double counting)?
+- [ ] Does voting power update on token transfer?
+- [ ] Can users delegate to themselves?
+- [ ] Is there delegation chain/depth limit?
+
+---
+
+## Common Vulnerabilities
+
+### Beanstalk Attack Pattern
+
+```solidity
+// Attack flow:
+// 1. Flash loan governance tokens
+// 2. Create proposal (if allowed in same tx)
+// 3. Vote with flash-loaned tokens
+// 4. Execute proposal immediately (no timelock)
+// 5. Proposal drains funds
+// 6. Return flash loan
+
+// ALL of these should fail:
+// - Snapshot should be from past block
+// - Voting delay should prevent same-block voting
+// - Timelock should delay execution
+```
+
+### Proposal Front-Running
+
+```solidity
+// VULNERABLE: Proposal can be front-run
+function propose(
+    address[] memory targets,
+    bytes[] memory calldatas,
+    string memory description
+) public returns (uint256) {
+    uint256 proposalId = hashProposal(targets, calldatas, keccak256(bytes(description)));
+    // Attacker can front-run with same proposal, different description
+}
+```
+
+### Unsafe Delegatecall in Execution
+
+```solidity
+// VULNERABLE: delegatecall in governor
+function execute(...) external {
+    for (uint i; i < targets.length; i++) {
+        (bool success,) = targets[i].delegatecall(calldatas[i]);
+        // delegatecall in governance = CRITICAL RISK
+    }
+}
+```
+
+---
+
+## Secure Patterns
+
+### OpenZeppelin Governor
+
+```solidity
+import "@openzeppelin/contracts/governance/Governor.sol";
+import "@openzeppelin/contracts/governance/extensions/GovernorVotes.sol";
+import "@openzeppelin/contracts/governance/extensions/GovernorTimelockControl.sol";
+
+contract SecureGovernor is Governor, GovernorVotes, GovernorTimelockControl {
+    function votingDelay() public pure override returns (uint256) {
+        return 1 days;  // Time before voting starts
+    }
+    
+    function votingPeriod() public pure override returns (uint256) {
+        return 1 weeks;  // Voting duration
+    }
+}
+```
+
+### Vote Escrow (veToken)
+
+```solidity
+// Lock tokens for voting power (Curve model)
+// Longer lock = more voting power
+// Prevents flash loan attacks by requiring locked tokens
+
+struct LockedBalance {
+    uint256 amount;
+    uint256 unlockTime;
+}
+
+function votingPower(address user) public view returns (uint256) {
+    LockedBalance memory lock = locked[user];
+    if (lock.unlockTime <= block.timestamp) return 0;
+    
+    uint256 timeLeft = lock.unlockTime - block.timestamp;
+    return lock.amount * timeLeft / MAX_LOCK_TIME;
+}
+```
+
+---
+
+## Testing Checklist
+
+### Unit Tests
+- [ ] Proposal creation with correct threshold
+- [ ] Voting with snapshot balances
+- [ ] Quorum calculation
+- [ ] Execution after timelock
+
+### Integration Tests
+- [ ] Full proposal lifecycle
+- [ ] Delegation and vote casting
+- [ ] Multiple proposals concurrent
+
+### Attack Tests
+- [ ] Flash loan voting attempt
+- [ ] Same-block propose + vote
+- [ ] Proposal re-execution attempt
+- [ ] Quorum manipulation
+
+### Invariant Tests
+- [ ] Total votes ≤ total voting power at snapshot
+- [ ] Executed proposals can't re-execute
+- [ ] Timelock always enforced
+
+---
+
+## References
+
+- [OpenZeppelin Governor](https://docs.openzeppelin.com/contracts/governance)
+- [Compound Governor Bravo](https://github.com/compound-finance/compound-protocol/blob/master/contracts/Governance/GovernorBravoDelegate.sol)
+- [Beanstalk Exploit Analysis](https://rekt.news/beanstalk-rekt/)
+- [Nouns DAO Fork](https://github.com/nounsDAO/nouns-monorepo)