agentic-team-templates 0.3.0

package/templates/blockchain/.cursorrules/security.md

@@ -0,0 +1,318 @@
+# Smart Contract Security
+
+Comprehensive security guidelines covering attack vectors, defense patterns, and audit preparation.
+
+## Common Attack Vectors
+
+### Reentrancy
+
+**Vulnerability**: External calls allow malicious contracts to re-enter your function before state updates complete.
+
+```solidity
+// Vulnerable
+function withdraw() external {
+    uint256 balance = balances[msg.sender];
+    (bool success,) = msg.sender.call{value: balance}("");  // Attacker re-enters here
+    require(success);
+    balances[msg.sender] = 0;  // Too late!
+}
+
+// Secure: CEI + ReentrancyGuard
+function withdraw() external nonReentrant {
+    uint256 balance = balances[msg.sender];
+    balances[msg.sender] = 0;  // State update first
+    (bool success,) = msg.sender.call{value: balance}("");
+    if (!success) revert TransferFailed();
+}
+```
+
+### Flash Loan Attacks
+
+**Vulnerability**: On-chain price oracles can be manipulated within a single transaction.
+
+```solidity
+// Vulnerable: Using spot price
+function getCollateralValue(address user) public view returns (uint256) {
+    uint256 tokenBalance = collateral[user];
+    uint256 spotPrice = amm.getSpotPrice();  // Can be manipulated!
+    return tokenBalance * spotPrice;
+}
+
+// Secure: Time-weighted average price (TWAP)
+function getCollateralValue(address user) public view returns (uint256) {
+    uint256 tokenBalance = collateral[user];
+    uint256 twapPrice = oracle.getTwapPrice(1 hours);  // Resistant to manipulation
+    return tokenBalance * twapPrice;
+}
+```
+
+### Front-Running / MEV
+
+**Vulnerability**: Transactions in the mempool can be observed and exploited.
+
+**Defenses**:
+
+```solidity
+// Commit-reveal for sensitive operations
+mapping(bytes32 => uint256) public commits;
+
+function commit(bytes32 hash) external {
+    commits[hash] = block.timestamp;
+}
+
+function reveal(uint256 value, bytes32 salt) external {
+    bytes32 hash = keccak256(abi.encode(msg.sender, value, salt));
+    if (commits[hash] == 0) revert NotCommitted();
+    if (block.timestamp < commits[hash] + MIN_DELAY) revert TooEarly();
+
+    delete commits[hash];
+    // Execute with revealed value
+}
+
+// Slippage protection
+function swap(
+    address tokenIn,
+    address tokenOut,
+    uint256 amountIn,
+    uint256 minAmountOut,  // User specifies minimum acceptable output
+    uint256 deadline       // Transaction expires
+) external {
+    if (block.timestamp > deadline) revert Expired();
+
+    uint256 amountOut = _executeSwap(tokenIn, tokenOut, amountIn);
+    if (amountOut < minAmountOut) revert SlippageExceeded();
+
+    // Transfer tokens
+}
+```
+
+### Integer Overflow/Underflow
+
+Solidity 0.8+ has built-in checks, but be aware of `unchecked` blocks:
+
+```solidity
+// Safe by default in 0.8+
+uint256 a = type(uint256).max;
+uint256 b = a + 1;  // Reverts
+
+// Dangerous: unchecked arithmetic
+unchecked {
+    uint256 c = a + 1;  // Wraps to 0!
+}
+
+// Only use unchecked when you've proven overflow is impossible
+function incrementCounter() external {
+    unchecked {
+        // Safe because we check first
+        if (counter >= type(uint256).max) revert CounterOverflow();
+        counter++;
+    }
+}
+```
+
+### Access Control Bypass
+
+```solidity
+// Vulnerable: tx.origin
+function withdraw() external {
+    require(tx.origin == owner);  // Can be bypassed via phishing!
+}
+
+// Secure: msg.sender
+function withdraw() external {
+    require(msg.sender == owner);
+}
+
+// Even better: Role-based access control
+function withdraw() external onlyRole(ADMIN_ROLE) {
+    // Only admins can call
+}
+```
+
+### Denial of Service
+
+```solidity
+// Vulnerable: Unbounded loop
+function distributeRewards() external {
+    for (uint256 i = 0; i < recipients.length; i++) {
+        payable(recipients[i]).transfer(rewards[i]);  // One failure stops all
+    }
+}
+
+// Secure: Pull pattern with pagination
+function claimReward() external {
+    uint256 reward = pendingRewards[msg.sender];
+    if (reward == 0) revert NoReward();
+
+    pendingRewards[msg.sender] = 0;
+    (bool success,) = msg.sender.call{value: reward}("");
+    if (!success) revert TransferFailed();
+}
+```
+
+### Storage Collision (Upgradeable Contracts)
+
+```solidity
+// Vulnerable: Adding variables incorrectly
+contract V1 {
+    uint256 public value;      // Slot 0
+}
+
+contract V2 is V1 {
+    address public newAdmin;   // Slot 1
+    uint256 public newValue;   // Slot 2
+}
+
+// If you add a variable in the middle, it corrupts storage!
+contract V2Bad is V1 {
+    uint256 public newValue;   // Slot 1 - OVERWRITES existing data!
+    address public newAdmin;   // Slot 2
+}
+
+// Secure: Storage gaps
+contract V1 {
+    uint256 public value;
+    uint256[49] private __gap;  // Reserve slots for future use
+}
+```
+
+## Security Checklist
+
+### Before Writing Code
+
+- [ ] Threat model documented
+- [ ] Attack vectors identified
+- [ ] Trust assumptions explicit
+- [ ] Upgrade strategy decided
+
+### During Development
+
+- [ ] Checks-Effects-Interactions pattern
+- [ ] Reentrancy guards on state-changing functions
+- [ ] Input validation on all external functions
+- [ ] Access control on sensitive functions
+- [ ] Events emitted for all state changes
+- [ ] No floating pragma
+- [ ] No assembly without documentation
+- [ ] No `tx.origin` for authentication
+- [ ] No `selfdestruct` unless absolutely necessary
+
+### Before Deployment
+
+- [ ] Slither reports zero high/medium findings
+- [ ] Mythril analysis complete
+- [ ] Fuzz tests with >100k runs
+- [ ] Mainnet fork tests pass
+- [ ] External audit completed
+- [ ] Bug bounty program ready
+
+### After Deployment
+
+- [ ] Monitoring alerts configured
+- [ ] Incident response plan documented
+- [ ] Admin keys secured (multisig, hardware wallet)
+- [ ] Gradual rollout (testnet → limited mainnet → full)
+
+## Secure Development Workflow
+
+### 1. Static Analysis
+
+Run on every commit:
+
+```bash
+# Slither - detects 40+ vulnerability patterns
+slither . --exclude-dependencies
+
+# Mythril - symbolic execution
+myth analyze contracts/MyContract.sol
+```
+
+### 2. Invariant Testing
+
+Define properties that must always hold:
+
+```solidity
+// test/invariant/VaultInvariant.t.sol
+function invariant_totalSharesMatchesDeposits() public {
+    uint256 totalAssets = vault.totalAssets();
+    uint256 totalShares = vault.totalSupply();
+
+    // Total shares should always be <= total assets (no inflation)
+    assert(totalShares <= totalAssets + 1);  // +1 for rounding
+}
+
+function invariant_noFreeShares() public {
+    // Can't get shares without depositing
+    assert(vault.balanceOf(attacker) == 0 || deposits[attacker] > 0);
+}
+```
+
+### 3. Fuzz Testing
+
+```solidity
+function testFuzz_deposit(uint256 amount) public {
+    amount = bound(amount, 1, type(uint96).max);  // Reasonable bounds
+
+    token.mint(user, amount);
+    vm.startPrank(user);
+    token.approve(address(vault), amount);
+
+    uint256 sharesBefore = vault.balanceOf(user);
+    vault.deposit(amount, user);
+    uint256 sharesAfter = vault.balanceOf(user);
+
+    assertGt(sharesAfter, sharesBefore);
+}
+```
+
+### 4. Mainnet Fork Testing
+
+```solidity
+function testFork_integrationWithUniswap() public {
+    // Fork mainnet at specific block
+    vm.createSelectFork(vm.envString("ETH_RPC_URL"), 18_000_000);
+
+    // Test against real Uniswap contracts
+    IUniswapV3Router router = IUniswapV3Router(UNISWAP_ROUTER);
+    // ... test integration
+}
+```
+
+## Audit Preparation
+
+### Documentation Required
+
+1. **System Overview**: Architecture diagram, trust assumptions
+2. **Contract Descriptions**: Purpose of each contract
+3. **External Interactions**: All protocols you integrate with
+4. **Access Control Matrix**: Who can call what
+5. **Known Issues**: Things you've accepted as tradeoffs
+6. **Test Coverage Report**: What's tested, what's not
+
+### Code Organization
+
+```
+docs/
+├── architecture.md       # System design
+├── threat-model.md       # Security assumptions
+├── access-control.md     # Roles and permissions
+└── deployment.md         # Deploy process
+
+contracts/
+├── src/                  # Clean, well-documented code
+├── test/                 # Comprehensive tests
+└── script/               # Deployment scripts
+```
+
+### Common Audit Findings to Pre-Check
+
+1. Missing zero-address checks
+2. Missing input validation
+3. Centralization risks (admin keys)
+4. Lack of events for state changes
+5. Inconsistent error handling
+6. Missing NatSpec documentation
+7. Unused code/imports
+8. Hardcoded addresses
+9. Missing reentrancy protection
+10. Unsafe external calls

package/templates/blockchain/.cursorrules/smart-contracts.md

@@ -0,0 +1,364 @@
+# Smart Contract Development
+
+Solidity patterns and best practices for secure, maintainable smart contracts.
+
+## Solidity Style Guide
+
+### File Structure
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+// 1. Imports (interfaces first, then libraries, then contracts)
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+
+// 2. Interfaces
+
+// 3. Libraries
+
+// 4. Contracts
+contract MyContract is Ownable {
+    // a. Type declarations (using, struct, enum)
+    using SafeERC20 for IERC20;
+
+    // b. State variables
+    uint256 public constant MAX_SUPPLY = 1_000_000e18;
+    uint256 private s_totalDeposits;
+    mapping(address => uint256) private s_balances;
+
+    // c. Events
+    event Deposited(address indexed user, uint256 amount);
+
+    // d. Errors
+    error InsufficientBalance(uint256 requested, uint256 available);
+
+    // e. Modifiers
+
+    // f. Constructor
+
+    // g. External functions
+
+    // h. Public functions
+
+    // i. Internal functions
+
+    // j. Private functions
+
+    // k. View/Pure functions
+}
+```
+
+### Naming Conventions
+
+```solidity
+// Constants: SCREAMING_SNAKE_CASE
+uint256 public constant MAX_FEE = 1000;
+
+// Immutables: i_ prefix
+address private immutable i_owner;
+
+// Storage variables: s_ prefix
+uint256 private s_totalSupply;
+mapping(address => uint256) private s_balances;
+
+// Function parameters: no prefix
+function deposit(uint256 amount, address recipient) external;
+
+// Local variables: no prefix
+uint256 balance = s_balances[msg.sender];
+
+// Events: PastTense
+event Deposited(address indexed user, uint256 amount);
+event FeeUpdated(uint256 oldFee, uint256 newFee);
+
+// Errors: DescriptiveError
+error InsufficientBalance(uint256 requested, uint256 available);
+error Unauthorized(address caller);
+```
+
+## Security Patterns
+
+### Checks-Effects-Interactions
+
+Always follow this order to prevent reentrancy:
+
+```solidity
+// Good: CEI pattern
+function withdraw(uint256 amount) external {
+    // 1. CHECKS - Validate inputs and state
+    if (s_balances[msg.sender] < amount) {
+        revert InsufficientBalance(amount, s_balances[msg.sender]);
+    }
+
+    // 2. EFFECTS - Update state
+    s_balances[msg.sender] -= amount;
+
+    // 3. INTERACTIONS - External calls
+    (bool success,) = msg.sender.call{value: amount}("");
+    if (!success) revert TransferFailed();
+}
+
+// Bad: Reentrancy vulnerable
+function withdrawBad(uint256 amount) external {
+    require(s_balances[msg.sender] >= amount);
+    (bool success,) = msg.sender.call{value: amount}("");  // External call first!
+    require(success);
+    s_balances[msg.sender] -= amount;  // State update after!
+}
+```
+
+### Reentrancy Guards
+
+Use for complex functions even with CEI:
+
+```solidity
+import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+
+contract Vault is ReentrancyGuard {
+    function complexWithdraw(uint256 amount) external nonReentrant {
+        // Safe from reentrancy even with multiple external calls
+    }
+}
+```
+
+### Access Control
+
+```solidity
+import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";
+
+contract Protocol is AccessControl {
+    bytes32 public constant ADMIN_ROLE = keccak256("ADMIN_ROLE");
+    bytes32 public constant OPERATOR_ROLE = keccak256("OPERATOR_ROLE");
+
+    constructor() {
+        _grantRole(DEFAULT_ADMIN_ROLE, msg.sender);
+        _grantRole(ADMIN_ROLE, msg.sender);
+    }
+
+    function emergencyPause() external onlyRole(ADMIN_ROLE) {
+        // Only admins can pause
+    }
+
+    function processQueue() external onlyRole(OPERATOR_ROLE) {
+        // Operators can process
+    }
+}
+```
+
+### Input Validation
+
+```solidity
+function deposit(address token, uint256 amount) external {
+    // Validate address
+    if (token == address(0)) revert ZeroAddress();
+
+    // Validate amount
+    if (amount == 0) revert ZeroAmount();
+
+    // Validate token is allowed
+    if (!s_allowedTokens[token]) revert TokenNotAllowed(token);
+
+    // Validate limits
+    if (amount > MAX_DEPOSIT) revert ExceedsMaxDeposit(amount, MAX_DEPOSIT);
+
+    // Safe to proceed
+    IERC20(token).safeTransferFrom(msg.sender, address(this), amount);
+}
+```
+
+## Common Patterns
+
+### Pull Over Push
+
+Prefer pull payments over push to avoid DoS:
+
+```solidity
+// Good: Pull pattern
+mapping(address => uint256) private s_pendingWithdrawals;
+
+function claimRewards() external {
+    uint256 amount = s_pendingWithdrawals[msg.sender];
+    if (amount == 0) revert NothingToClaim();
+
+    s_pendingWithdrawals[msg.sender] = 0;
+    IERC20(rewardToken).safeTransfer(msg.sender, amount);
+}
+
+// Bad: Push pattern (can be DoS'd)
+function distributeRewards(address[] calldata recipients) external {
+    for (uint256 i = 0; i < recipients.length; i++) {
+        // If one transfer fails, all fail
+        IERC20(rewardToken).safeTransfer(recipients[i], rewards[i]);
+    }
+}
+```
+
+### Emergency Stops
+
+```solidity
+import {Pausable} from "@openzeppelin/contracts/utils/Pausable.sol";
+
+contract Protocol is Pausable, Ownable {
+    function deposit(uint256 amount) external whenNotPaused {
+        // Normal operation
+    }
+
+    function withdraw(uint256 amount) external {
+        // Withdrawals always work (no whenNotPaused)
+    }
+
+    function pause() external onlyOwner {
+        _pause();
+    }
+
+    function unpause() external onlyOwner {
+        _unpause();
+    }
+}
+```
+
+### Timelock for Sensitive Operations
+
+```solidity
+uint256 public constant TIMELOCK_DURATION = 2 days;
+
+struct PendingChange {
+    uint256 value;
+    uint256 executeAfter;
+}
+
+mapping(bytes32 => PendingChange) public pendingChanges;
+
+function proposeFeeChange(uint256 newFee) external onlyOwner {
+    bytes32 id = keccak256(abi.encode("FEE", newFee));
+    pendingChanges[id] = PendingChange({
+        value: newFee,
+        executeAfter: block.timestamp + TIMELOCK_DURATION
+    });
+    emit FeeChangeProposed(newFee, block.timestamp + TIMELOCK_DURATION);
+}
+
+function executeFeeChange(uint256 newFee) external onlyOwner {
+    bytes32 id = keccak256(abi.encode("FEE", newFee));
+    PendingChange memory change = pendingChanges[id];
+
+    if (change.executeAfter == 0) revert ChangeNotProposed();
+    if (block.timestamp < change.executeAfter) revert TimelockNotExpired();
+
+    delete pendingChanges[id];
+    s_fee = newFee;
+    emit FeeChanged(newFee);
+}
+```
+
+## OpenZeppelin Contracts
+
+### Recommended Imports
+
+```solidity
+// Tokens
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol";
+import {ERC1155} from "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";
+
+// Security
+import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+import {Pausable} from "@openzeppelin/contracts/utils/Pausable.sol";
+
+// Access
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";
+
+// Utils
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+
+// Upgradeable (use with caution)
+import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+import {UUPSUpgradeable} from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
+```
+
+## NatSpec Documentation
+
+```solidity
+/// @title Vault - A yield-bearing token vault
+/// @author Protocol Team
+/// @notice Allows users to deposit tokens and earn yield
+/// @dev Implements ERC-4626 tokenized vault standard
+contract Vault is ERC4626 {
+    /// @notice Deposits assets and mints shares to receiver
+    /// @dev Emits Deposit event
+    /// @param assets Amount of underlying tokens to deposit
+    /// @param receiver Address to receive the minted shares
+    /// @return shares Amount of shares minted
+    function deposit(uint256 assets, address receiver)
+        public
+        override
+        returns (uint256 shares)
+    {
+        // Implementation
+    }
+}
+```
+
+## Anti-Patterns to Avoid
+
+### Unchecked External Calls
+
+```solidity
+// Bad: Ignoring return value
+token.transfer(recipient, amount);
+
+// Good: Using SafeERC20
+IERC20(token).safeTransfer(recipient, amount);
+
+// Good: Checking return value explicitly
+bool success = token.transfer(recipient, amount);
+if (!success) revert TransferFailed();
+```
+
+### Unbounded Loops
+
+```solidity
+// Bad: Can run out of gas
+function processAll() external {
+    for (uint256 i = 0; i < users.length; i++) {
+        processUser(users[i]);
+    }
+}
+
+// Good: Paginated processing
+function processBatch(uint256 start, uint256 count) external {
+    uint256 end = Math.min(start + count, users.length);
+    for (uint256 i = start; i < end; i++) {
+        processUser(users[i]);
+    }
+}
+```
+
+### Floating Pragma
+
+```solidity
+// Bad: Any 0.8.x version
+pragma solidity ^0.8.0;
+
+// Good: Specific version
+pragma solidity 0.8.20;
+```
+
+### Magic Numbers
+
+```solidity
+// Bad: Magic numbers
+if (fee > 10000) revert();
+
+// Good: Named constants
+uint256 public constant MAX_FEE_BPS = 10_000; // 100%
+uint256 public constant FEE_DENOMINATOR = 10_000;
+
+if (fee > MAX_FEE_BPS) revert FeeExceedsMax(fee, MAX_FEE_BPS);
+```