Prevent Smart Contract Disasters: Best Practices That Saved My $2M Project

// Personal note: I create this threat model BEFORE writing any contract code
// This saved me from a $500K design flaw in a lending protocol

/**
 * @title Threat Model Template
 * @dev Fill this out before implementing ANY smart contract
 */

// ASSETS AT RISK
// - User deposited tokens (ERC20: USDC, DAI)
// - Protocol treasury funds
// - Governance voting power
// Total Value: Estimate $X in initial 6 months

// THREAT ACTORS
// 1. External attackers (reentrancy, front-running, flashloan attacks)
// 2. Malicious admin/governance (rug pull risk)
// 3. Compromised private keys
// 4. Economic exploits (oracle manipulation, MEV)

// TRUST BOUNDARIES
// - Who has admin privileges? (Multisig 3/5, timelock 48h)
// - Can users lose funds without transaction? (NO - all state changes require signature)
// - Are there any DELEGATECALL patterns? (YES - in proxy, requires review)

// FAILURE MODES
// - Circuit breakers: Pause mechanism for emergency
// - Upgrade paths: UUPS proxy with 48h timelock
// - Maximum loss scenarios: Calculate worst-case per attack vector

// SECURITY PATTERN 1: Checks-Effects-Interactions (CEI)
// This pattern prevented a reentrancy attack in my staking contract

contract SecureStaking {
    mapping(address => uint256) public stakes;
    
    function withdraw(uint256 amount) external nonReentrant {
        // ❌ WRONG - Effects after interaction
        // token.transfer(msg.sender, amount);
        // stakes[msg.sender] -= amount;
        
        // ✅ RIGHT - Follow CEI pattern
        
        // 1. CHECKS
        require(stakes[msg.sender] >= amount, "Insufficient balance");
        require(amount > 0, "Amount must be positive");
        
        // 2. EFFECTS (Update state BEFORE external calls)
        stakes[msg.sender] -= amount;
        
        // 3. INTERACTIONS (External calls last)
        require(token.transfer(msg.sender, amount), "Transfer failed");
        
        emit Withdrawal(msg.sender, amount);
    }
}

// SECURITY PATTERN 2: Access Control Defense in Depth
// Watch out: Single owner = single point of failure

contract SecureGovernance {
    // Layer 1: Role-based access control
    bytes32 public constant ADMIN_ROLE = keccak256("ADMIN_ROLE");
    bytes32 public constant OPERATOR_ROLE = keccak256("OPERATOR_ROLE");
    
    // Layer 2: Timelock for critical operations
    uint256 public constant TIMELOCK_DURATION = 48 hours;
    mapping(bytes32 => uint256) public pendingActions;
    
    // Layer 3: Emergency pause mechanism
    bool public paused;
    
    function criticalOperation(bytes calldata data) external {
        // Multiple checks create defense in depth
        require(hasRole(ADMIN_ROLE, msg.sender), "Not admin");
        require(!paused, "System paused");
        require(
            block.timestamp >= pendingActions[keccak256(data)],
            "Timelock not expired"
        );
        
        // Execute operation
        // ...
    }
}

// SECURITY PATTERN 3: Input Validation on EVERY function
// Don't skip this validation - learned the hard way

function stake(uint256 amount, address referrer) external {
    // Validate numeric inputs
    require(amount > 0, "Amount must be positive");
    require(amount <= MAX_STAKE, "Amount exceeds maximum");
    
    // Validate address inputs (critical!)
    require(referrer != address(0), "Invalid referrer");
    require(referrer != msg.sender, "Cannot self-refer");
    
    // Validate state conditions
    require(!paused, "Staking paused");
    require(totalStaked + amount <= POOL_CAP, "Pool full");
    
    // Additional business logic validation
    require(stakes[msg.sender] + amount >= MIN_STAKE, "Below minimum");
    
    // Now safe to proceed
    _stake(msg.sender, amount, referrer);
}

// TEST STRATEGY 1: Unit Tests (Basic Coverage)
// forge test --match-contract StakingTest

contract StakingTest is Test {
    StakingPool public pool;
    MockERC20 public token;
    address user = makeAddr("user");
    
    function setUp() public {
        token = new MockERC20("Test", "TEST", 18);
        pool = new StakingPool(address(token));
        
        // Give user tokens
        token.mint(user, 1000 ether);
    }
    
    function testStakeBasic() public {
        vm.startPrank(user);
        token.approve(address(pool), 100 ether);
        pool.stake(100 ether);
        vm.stopPrank();
        
        assertEq(pool.stakes(user), 100 ether);
    }
    
    // Personal note: This test saved me from a rounding error
    // that would have slowly drained the pool
    function testStakePrecisionAttack() public {
        vm.startPrank(user);
        token.approve(address(pool), 1000 ether);
        
        // Try to exploit rounding with tiny stakes
        for(uint i = 0; i < 100; i++) {
            pool.stake(1); // Stake 1 wei at a time
        }
        vm.stopPrank();
        
        // User should have exactly 100 wei staked
        // If more, there's a rounding exploit
        assertEq(pool.stakes(user), 100);
    }
}

// TEST STRATEGY 2: Fuzzing (Find Edge Cases)
// This caught a bug in my bounds checking

contract StakingFuzzTest is Test {
    StakingPool public pool;
    
    /// forge-config: default.fuzz.runs = 10000
    function testFuzz_StakeAmount(uint256 amount) public {
        // Bound inputs to valid range
        amount = bound(amount, 1, type(uint96).max);
        
        vm.assume(amount > 0);
        vm.assume(amount <= pool.MAX_STAKE());
        
        // Setup
        address user = makeAddr("user");
        token.mint(user, amount);
        
        vm.startPrank(user);
        token.approve(address(pool), amount);
        pool.stake(amount);
        vm.stopPrank();
        
        // Invariant: User balance should match stake
        assertEq(pool.stakes(user), amount);
    }
    
    // Watch out: This test found an integer overflow
    // in production code during audit
    function testFuzz_MultipleStakes(
        uint96 amount1,
        uint96 amount2,
        uint96 amount3
    ) public {
        // Test accumulation without overflow
        uint256 total = uint256(amount1) + amount2 + amount3;
        vm.assume(total <= pool.POOL_CAP());
        
        // Execute multiple stakes
        // ... stake logic
        
        // Invariant: Total should equal sum
        assertEq(pool.totalStaked(), total);
    }
}

// TEST STRATEGY 3: Invariant Testing (Critical)
// THIS is what caught the $2M bug

contract StakingInvariantTest is Test {
    StakingPool public pool;
    Handler public handler;
    
    function setUp() public {
        pool = new StakingPool(address(token));
        handler = new Handler(pool);
        
        // Target handler for invariant testing
        targetContract(address(handler));
    }
    
    // CRITICAL INVARIANT: Contract balance >= sum of all stakes
    function invariant_ContractSolvent() public {
        uint256 contractBalance = token.balanceOf(address(pool));
        uint256 totalStakes = pool.totalStaked();
        
        // This failed and caught our reentrancy bug
        assertGe(
            contractBalance,
            totalStakes,
            "CONTRACT INSOLVENT: More owed than held"
        );
    }
    
    // CRITICAL INVARIANT: User can always withdraw their stake
    function invariant_UsersCanWithdraw() public {
        address[] memory users = handler.getUsers();
        
        for(uint i = 0; i < users.length; i++) {
            address user = users[i];
            uint256 stake = pool.stakes(user);
            
            if(stake > 0) {
                vm.prank(user);
                // This should never revert
                pool.withdraw(stake);
            }
        }
        
        // After all withdrawals, pool should be empty
        assertEq(pool.totalStaked(), 0);
    }
}

// TEST STRATEGY 4: Integration Tests on Forked Mainnet
// Don't skip this - caught gas issues that made functions unusable

contract StakingForkTest is Test {
    uint256 mainnetFork;
    
    function setUp() public {
        // Fork mainnet at specific block
        mainnetFork = vm.createFork(
            "https://eth-mainnet.g.alchemy.com/v2/...",
            18000000
        );
        vm.selectFork(mainnetFork);
        
        // Deploy against real mainnet state
        pool = new StakingPool(REAL_USDC_ADDRESS);
    }
    
    function testRealWorldGasCosts() public {
        // Test with actual mainnet gas prices
        uint256 gasBefore = gasleft();
        
        pool.stake(1000e6); // 1000 USDC
        
        uint256 gasUsed = gasBefore - gasleft();
        
        // Personal note: Caught a function that cost
        // $50 in gas at peak times
        assertLt(gasUsed, 100000, "Gas too high for production");
    }
}

// DEPLOYMENT PATTERN: UUPS Proxy with Timelock
// This saved us when we found a bug 3 days after launch

// Implementation contract
contract StakingPoolV1 is Initializable, UUPSUpgradeable, AccessControlUpgradeable {
    bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE");
    
    /// @custom:oz-upgrades-unsafe-allow constructor
    constructor() {
        _disableInitializers();
    }
    
    function initialize(address _token) public initializer {
        __AccessControl_init();
        __UUPSUpgradeable_init();
        
        _grantRole(DEFAULT_ADMIN_ROLE, msg.sender);
        _grantRole(UPGRADER_ROLE, msg.sender);
        
        token = IERC20(_token);
    }
    
    // Only accounts with UPGRADER_ROLE can upgrade
    function _authorizeUpgrade(address newImplementation)
        internal
        override
        onlyRole(UPGRADER_ROLE)
    {
        // Additional safety: Require timelock approval
        require(
            timelock.isOperationReady(
                keccak256(abi.encode(newImplementation))
            ),
            "Upgrade not ready"
        );
    }
    
    // Emergency pause for disasters
    function pause() external onlyRole(DEFAULT_ADMIN_ROLE) {
        _pause();
        emit EmergencyPause(msg.sender, block.timestamp);
    }
}

// Deployment script with safety checks
// script/Deploy.s.sol

contract DeployStaking is Script {
    function run() external {
        uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");
        address deployer = vm.addr(deployerPrivateKey);
        
        console.log("Deploying from:", deployer);
        console.log("Balance:", deployer.balance);
        
        vm.startBroadcast(deployerPrivateKey);
        
        // PRE-DEPLOYMENT CHECKS
        require(deployer.balance > 0.1 ether, "Insufficient gas");
        require(block.chainid == 1, "Not mainnet"); // Safety check
        
        // Deploy implementation
        StakingPoolV1 implementation = new StakingPoolV1();
        console.log("Implementation:", address(implementation));
        
        // Deploy proxy
        bytes memory initData = abi.encodeWithSelector(
            StakingPoolV1.initialize.selector,
            USDC_ADDRESS
        );
        
        ERC1967Proxy proxy = new ERC1967Proxy(
            address(implementation),
            initData
        );
        console.log("Proxy:", address(proxy));
        
        // POST-DEPLOYMENT VERIFICATION
        StakingPoolV1 pool = StakingPoolV1(address(proxy));
        
        // Verify initialization
        require(
            pool.hasRole(pool.DEFAULT_ADMIN_ROLE(), deployer),
            "Admin role not set"
        );
        
        // Verify upgrade safety
        require(
            pool.hasRole(pool.UPGRADER_ROLE(), TIMELOCK_ADDRESS),
            "Upgrader not timelock"
        );
        
        // Transfer admin to multisig
        pool.grantRole(pool.DEFAULT_ADMIN_ROLE(), MULTISIG_ADDRESS);
        pool.revokeRole(pool.DEFAULT_ADMIN_ROLE(), deployer);
        
        console.log("Deployment complete. Verify at:");
        console.log("Etherscan: https://etherscan.io/address/%s", address(proxy));
        
        vm.stopBroadcast();
        
        // FINAL CHECKLIST OUTPUT
        console.log("\n=== DEPLOYMENT VERIFICATION ===");
        console.log("1. Implementation deployed: %s", address(implementation));
        console.log("2. Proxy deployed: %s", address(proxy));
        console.log("3. Admin transferred to multisig: %s", MULTISIG_ADDRESS);
        console.log("4. Upgrade rights: Timelock only (48h delay)");
        console.log("5. Emergency pause: Multisig only");
        console.log("\n=== POST-DEPLOYMENT TASKS ===");
        console.log("[ ] Verify contract on Etherscan");
        console.log("[ ] Test all functions on mainnet with small amounts");
        console.log("[ ] Set up monitoring alerts");
        console.log("[ ] Announce contract address");
    }
}

// Tenderly alert configuration
// This caught an attack in progress at 3 AM

{
  "name": "Unusual Withdrawal Pattern",
  "alerts": [
    {
      "trigger": "function_call",
      "contract": "0x...", // Your contract
      "function": "withdraw",
      "conditions": [
        {
          "field": "value",
          "operator": "gt",
          "value": "100000000000000000000" // 100 tokens
        },
        {
          "field": "from",
          "operator": "not_in",
          "value": ["0x...", "0x..."] // Whitelist
        }
      ]
    }
  ],
  "notifications": {
    "pagerduty": true,
    "telegram": "@security_team",
    "email": "security@company.com"
  }
}

// Emergency response function
// Personal note: Practice this process before you need it

contract EmergencyResponse {
    // Multi-sig controlled pause
    function emergencyPause() external onlyMultisig {
        require(!paused, "Already paused");
        
        _pause();
        
        // Log detailed state for forensics
        emit EmergencyPause({
            caller: msg.sender,
            timestamp: block.timestamp,
            totalValueLocked: getTVL(),
            lastBlockProcessed: block.number
        });
        
        // Alert monitoring systems
        // External notification via events
    }
    
    // Time-delayed recovery
    function proposeRecovery(address newImplementation) 
        external 
        onlyMultisig 
    {
        bytes32 proposalId = keccak256(
            abi.encode(newImplementation, block.timestamp)
        );
        
        recoveryProposals[proposalId] = RecoveryProposal({
            implementation: newImplementation,
            proposedAt: block.timestamp,
            executed: false
        });
        
        // 24 hour timelock for community review
        emit RecoveryProposed(proposalId, newImplementation);
    }
}

# Security Incident - [TIMESTAMP]

## Status: [Active Incident / Contained / Resolved]

## What Happened
- Detected unusual activity at [TIME]
- Contract automatically paused at [TIME]
- [X] ETH / [Y] tokens secured

## User Impact
- All funds are safe and secured
- Contract is paused - no transactions possible
- Expected resolution: [TIMEFRAME]

## Our Response
1. ✅ Contract paused (Block: #12345678)
2. ✅ Funds secured in timelock
3. ⏳ Root cause analysis in progress
4. ⏳ Fix development and testing
5. ⏳ Community review period (24h)
6. ⏳ Deployment of fix

## What Users Should Do
- DO NOT interact with any unofficial contracts
- Official contract: 0x... (verify on etherscan)
- Wait for official announcement before depositing
- Questions: security@[company].com

## Next Update
- Expected in [X] hours
- Will post to: Twitter, Discord, Website

## Transparency
- Incident report will be published within 7 days
- Root cause analysis will be public
- Changes will be audited before deployment