agentic-team-templates 0.3.0

package/templates/blockchain/CLAUDE.md

@@ -0,0 +1,389 @@
+# Blockchain Development Guide
+
+Staff-level guidelines for blockchain and Web3 development. This guide covers smart contract development, DeFi protocols, and decentralized application architecture.
+
+---
+
+## Overview
+
+This guide applies to:
+
+- Smart contract development (Solidity, Vyper)
+- DeFi protocols (AMMs, lending, yield strategies)
+- Token implementations (ERC-20, ERC-721, ERC-1155, ERC-4626)
+- Web3 frontend applications
+- Cross-chain and L2 integrations
+
+### Key Principles
+
+1. **Security Is Non-Negotiable** - Immutable code handling real value
+2. **Gas Efficiency Matters** - Users pay for every operation
+3. **Composability Is King** - Build for the ecosystem
+4. **Defense in Depth** - Multiple layers of protection
+
+### Technology Stack
+
+| Layer | Technology |
+|-------|------------|
+| Smart Contracts | Solidity 0.8.x, OpenZeppelin |
+| Testing | Foundry (Forge), Hardhat |
+| Static Analysis | Slither, Mythril |
+| Web3 Frontend | Viem, Wagmi, React |
+| Wallet Connection | ConnectKit, RainbowKit |
+| Oracles | Chainlink, Uniswap TWAP |
+
+---
+
+## Smart Contract Patterns
+
+### File Structure
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.20;
+
+// Imports (interfaces → libraries → contracts)
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+
+contract Protocol is ReentrancyGuard {
+    using SafeERC20 for IERC20;
+
+    // State: constants → immutables → storage
+    uint256 public constant MAX_FEE = 1000;
+    address public immutable i_owner;
+    uint256 private s_totalDeposits;
+
+    // Events
+    event Deposited(address indexed user, uint256 amount);
+
+    // Errors
+    error InsufficientBalance(uint256 requested, uint256 available);
+
+    // External → Public → Internal → Private → View/Pure
+}
+```
+
+### Checks-Effects-Interactions Pattern
+
+```solidity
+function withdraw(uint256 amount) external nonReentrant {
+    // 1. CHECKS
+    if (s_balances[msg.sender] < amount) {
+        revert InsufficientBalance(amount, s_balances[msg.sender]);
+    }
+
+    // 2. EFFECTS
+    s_balances[msg.sender] -= amount;
+
+    // 3. INTERACTIONS
+    IERC20(token).safeTransfer(msg.sender, amount);
+}
+```
+
+### Input Validation
+
+```solidity
+function deposit(address token, uint256 amount, address recipient) external {
+    if (token == address(0)) revert ZeroAddress();
+    if (amount == 0) revert ZeroAmount();
+    if (!s_allowedTokens[token]) revert TokenNotAllowed(token);
+
+    IERC20(token).safeTransferFrom(msg.sender, address(this), amount);
+    s_balances[recipient] += amount;
+}
+```
+
+---
+
+## Security Checklist
+
+### Attack Vectors to Test
+
+| Attack | Prevention |
+|--------|------------|
+| Reentrancy | CEI pattern + ReentrancyGuard |
+| Flash Loan Manipulation | TWAP oracles, not spot prices |
+| Front-Running/MEV | Commit-reveal, slippage protection |
+| Integer Overflow | Solidity 0.8+ (careful with unchecked) |
+| Access Control | Role-based access, no tx.origin |
+| DoS | Pull over push, pagination |
+
+### Before Deployment
+
+- [ ] Slither reports zero high/medium findings
+- [ ] Fuzz tests with >100k runs
+- [ ] Invariant tests for protocol properties
+- [ ] Mainnet fork tests pass
+- [ ] External audit completed
+- [ ] Bug bounty program ready
+
+---
+
+## Gas Optimization
+
+### Storage Optimization
+
+```solidity
+// Pack variables into 32-byte slots
+struct UserData {
+    uint128 balance;     // 16 bytes
+    uint64 lastUpdate;   // 8 bytes
+    uint32 nonce;        // 4 bytes
+    bool isActive;       // 1 byte
+    // Total: 29 bytes = 1 slot
+}
+
+// Cache storage in memory
+function process() external {
+    uint256 counter = s_counter;  // Read once
+    for (uint256 i = 0; i < 10;) {
+        counter++;
+        unchecked { ++i; }
+    }
+    s_counter = counter;  // Write once
+}
+```
+
+### Calldata vs Memory
+
+```solidity
+// Bad: Copies to memory
+function processBad(uint256[] memory data) external { }
+
+// Good: Read from calldata
+function processGood(uint256[] calldata data) external { }
+```
+
+### Custom Errors
+
+```solidity
+// Bad: String storage is expensive
+require(balance >= amount, "Insufficient balance");
+
+// Good: Custom errors are cheaper
+error InsufficientBalance(uint256 requested, uint256 available);
+if (balance < amount) revert InsufficientBalance(amount, balance);
+```
+
+---
+
+## Testing Strategy
+
+### Test Types
+
+| Type | Coverage | Purpose |
+|------|----------|---------|
+| Unit | 100% branches | Individual functions |
+| Fuzz | 10,000+ runs | Edge cases |
+| Invariant | 10,000+ calls | System properties |
+| Fork | Critical paths | Real integrations |
+
+### Foundry Test Example
+
+```solidity
+function testFuzz_deposit(uint256 amount) public {
+    amount = bound(amount, 1, INITIAL_BALANCE);
+
+    vm.prank(user);
+    vault.deposit(amount, user);
+
+    assertEq(vault.balanceOf(user), amount);
+}
+
+function invariant_noShareInflation() public view {
+    assertGe(token.balanceOf(address(vault)), vault.totalSupply());
+}
+```
+
+### Useful Cheatcodes
+
+```solidity
+vm.prank(user);           // Next call from user
+vm.warp(block.timestamp + 1 days);  // Time travel
+deal(address(token), user, amount);  // Set balance
+vm.expectRevert(Error.selector);     // Expect revert
+```
+
+---
+
+## Web3 Frontend Integration
+
+### Wagmi + Viem Setup
+
+```typescript
+import { useReadContract, useWriteContract, useWaitForTransactionReceipt } from 'wagmi';
+
+export function useDeposit() {
+  const { data: hash, writeContract, isPending } = useWriteContract();
+  const { isLoading, isSuccess } = useWaitForTransactionReceipt({ hash });
+
+  const deposit = (amount: bigint) => {
+    writeContract({
+      address: VAULT_ADDRESS,
+      abi: vaultAbi,
+      functionName: 'deposit',
+      args: [amount],
+    });
+  };
+
+  return { deposit, isPending, isLoading, isSuccess };
+}
+```
+
+### Transaction States
+
+```typescript
+type TransactionState =
+  | 'idle'        // No transaction
+  | 'pending'     // Waiting for wallet
+  | 'confirming'  // In mempool
+  | 'confirmed'   // Success
+  | 'failed';     // Reverted
+
+// Always show clear feedback for each state
+```
+
+### Error Handling
+
+```typescript
+import { ContractFunctionRevertedError } from 'viem';
+
+function parseError(error: unknown): string {
+  if (error instanceof ContractFunctionRevertedError) {
+    const errorName = error.data?.errorName ?? 'Unknown';
+    const messages: Record<string, string> = {
+      InsufficientBalance: "You don't have enough balance",
+      SlippageExceeded: 'Price moved too much, try again',
+    };
+    return messages[errorName] ?? errorName;
+  }
+  return 'An unexpected error occurred';
+}
+```
+
+---
+
+## DeFi Patterns
+
+### Token Standards
+
+| Standard | Use Case |
+|----------|----------|
+| ERC-20 | Fungible tokens (currencies, rewards) |
+| ERC-721 | NFTs (unique items) |
+| ERC-1155 | Multi-token (gaming, bulk NFTs) |
+| ERC-4626 | Yield-bearing vaults |
+
+### MEV Protection
+
+```solidity
+function swap(
+    uint256 amountIn,
+    uint256 minAmountOut,  // Slippage protection
+    uint256 deadline       // Expiry protection
+) external {
+    if (block.timestamp > deadline) revert Expired();
+    uint256 amountOut = _calculateOutput(amountIn);
+    if (amountOut < minAmountOut) revert SlippageExceeded();
+    _executeSwap(amountIn, amountOut);
+}
+```
+
+### Oracle Best Practices
+
+```solidity
+// Always validate oracle data
+function getPrice(address feed) public view returns (uint256) {
+    (, int256 price,, uint256 updatedAt,) = AggregatorV3Interface(feed).latestRoundData();
+
+    // Staleness check
+    if (block.timestamp - updatedAt > 1 hours) revert StalePrice();
+
+    // Sanity check
+    if (price <= 0) revert InvalidPrice();
+
+    return uint256(price);
+}
+```
+
+---
+
+## Definition of Done
+
+### Smart Contract
+
+- [ ] All functions have NatSpec documentation
+- [ ] Unit tests cover all branches (>95% coverage)
+- [ ] Fuzz tests for external functions
+- [ ] Invariant tests for protocol properties
+- [ ] Slither: zero high/medium findings
+- [ ] Gas benchmarks documented
+- [ ] Mainnet fork tests pass
+- [ ] External audit (for mainnet)
+
+### Web3 Frontend
+
+- [ ] Works with multiple wallet types
+- [ ] Handles all transaction states
+- [ ] Meaningful error messages
+- [ ] Network switching works
+- [ ] Mobile wallet compatible
+- [ ] Transaction simulation before signing
+
+---
+
+## Common Pitfalls
+
+### 1. Trusting Spot Prices
+
+```solidity
+// Bad: Manipulable in same transaction
+uint256 price = amm.getSpotPrice();
+
+// Good: Resistant to manipulation
+uint256 price = oracle.getTwapPrice(1 hours);
+```
+
+### 2. Missing Slippage Protection
+
+```solidity
+// Bad: No protection
+function swap(uint256 amountIn) external;
+
+// Good: User specifies minimum acceptable output
+function swap(uint256 amountIn, uint256 minAmountOut, uint256 deadline) external;
+```
+
+### 3. Floating Pragma
+
+```solidity
+// Bad
+pragma solidity ^0.8.0;
+
+// Good
+pragma solidity 0.8.20;
+```
+
+### 4. Unbounded Loops
+
+```solidity
+// Bad: Can run out of gas
+for (uint256 i = 0; i < users.length; i++) { }
+
+// Good: Paginated
+function processBatch(uint256 start, uint256 count) external { }
+```
+
+---
+
+## Resources
+
+- [Solidity Documentation](https://docs.soliditylang.org/)
+- [OpenZeppelin Contracts](https://docs.openzeppelin.com/contracts)
+- [Foundry Book](https://book.getfoundry.sh/)
+- [Wagmi Documentation](https://wagmi.sh/)
+- [Viem Documentation](https://viem.sh/)
+- [OWASP Smart Contract Security](https://scs.owasp.org/)
+- [Ethereum Security Best Practices](https://ethereum.org/en/developers/docs/smart-contracts/security/)