DeFi Protocol Development: Production-Ready Architecture Patterns for 2025

This is the exact pattern used by Aave V3, Compound V3, and other protocols managing billions in TVL. Notice how it separates admin functions from user functions to prevent selector clashing attacks.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol";
import "@openzeppelin/contracts/proxy/transparent/ProxyAdmin.sol";

/**
 * @title DeFi Protocol Proxy
 * @notice Transparent proxy pattern for upgradeable protocol
 * @dev Separates admin functions from user functions to prevent
 *      selector clashing attacks
 */
contract ProtocolProxy is TransparentUpgradeableProxy {
    constructor(
        address implementation,
        address admin,
        bytes memory data
    ) TransparentUpgradeableProxy(implementation, admin, data) {}
}

/**
 * @title Protocol Implementation V1
 * @notice Core protocol logic - upgradeable
 */
contract ProtocolImplementationV1 {
    // Storage layout must remain consistent across upgrades
    mapping(address => uint256) public userBalances;
    mapping(address => bool) public isWhitelisted;
    address public treasury;
    bool public paused;
    
    // Storage gap for future upgrades
    uint256[50] private __gap;
    
    event Deposit(address indexed user, uint256 amount);
    event Withdraw(address indexed user, uint256 amount);
    
    modifier whenNotPaused() {
        require(!paused, "Protocol is paused");
        _;
    }
    
    function deposit() external payable whenNotPaused {
        require(msg.value > 0, "Must deposit some ETH");
        userBalances[msg.sender] += msg.value;
        emit Deposit(msg.sender, msg.value);
    }
    
    function withdraw(uint256 amount) external whenNotPaused {
        require(userBalances[msg.sender] >= amount, "Insufficient balance");
        userBalances[msg.sender] -= amount;
        (bool success, ) = msg.sender.call{value: amount}("");
        require(success, "Transfer failed");
        emit Withdraw(msg.sender, amount);
    }
}

This pattern separates different types of permissions: emergency roles (immediate), admin roles (governance), and operator roles (daily operations). Notice the timelock mechanism that prevents instant malicious changes.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts-upgradeable/access/AccessControlUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/security/PausableUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";

/**
 * @title DeFi Protocol with Role-Based Access Control
 * @notice Implements multi-signature governance with time delays
 */
contract DeFiProtocol is 
    Initializable,
    AccessControlUpgradeable,
    PausableUpgradeable 
{
    // Define roles - each has specific permissions
    bytes32 public constant ADMIN_ROLE = keccak256("ADMIN_ROLE");
    bytes32 public constant OPERATOR_ROLE = keccak256("OPERATOR_ROLE");
    bytes32 public constant EMERGENCY_ROLE = keccak256("EMERGENCY_ROLE");
    bytes32 public constant GOVERNANCE_ROLE = keccak256("GOVERNANCE_ROLE");
    
    uint256 public constant TIMELOCK_DELAY = 2 days;
    
    mapping(bytes32 => uint256) public pendingActions;
    
    event ActionScheduled(bytes32 indexed actionId, uint256 executeTime);
    event ActionExecuted(bytes32 indexed actionId);
    
    function initialize(address admin, address governance) 
        public 
        initializer 
    {
        __AccessControl_init();
        __Pausable_init();
        
        _grantRole(DEFAULT_ADMIN_ROLE, admin);
        _grantRole(ADMIN_ROLE, admin);
        _grantRole(GOVERNANCE_ROLE, governance);
        
        // Admin role can grant operator and emergency roles
        _setRoleAdmin(OPERATOR_ROLE, ADMIN_ROLE);
        _setRoleAdmin(EMERGENCY_ROLE, ADMIN_ROLE);
    }
    
    /**
     * @notice Schedule a critical action with timelock
     * @dev Prevents instant malicious changes - users have 48h to exit
     */
    function scheduleAction(bytes32 actionId) 
        external 
        onlyRole(GOVERNANCE_ROLE) 
    {
        uint256 executeTime = block.timestamp + TIMELOCK_DELAY;
        pendingActions[actionId] = executeTime;
        emit ActionScheduled(actionId, executeTime);
    }
    
    /**
     * @notice Execute a scheduled action after timelock expires
     */
    function executeAction(bytes32 actionId) 
        external 
        onlyRole(GOVERNANCE_ROLE) 
    {
        uint256 executeTime = pendingActions[actionId];
        require(executeTime > 0, "Action not scheduled");
        require(block.timestamp >= executeTime, "Timelock not expired");
        
        delete pendingActions[actionId];
        emit ActionExecuted(actionId);
        
        // Execute the actual action here
    }
    
    /**
     * @notice Emergency pause - no timelock for security incidents
     * @dev Only emergency role can pause immediately
     */
    function emergencyPause() 
        external 
        onlyRole(EMERGENCY_ROLE) 
    {
        _pause();
    }
    
    function unpause() 
        external 
        onlyRole(ADMIN_ROLE) 
    {
        _unpause();
    }
}