How to Audit Stablecoin Proxy Contracts: My Hard-Learned Lessons with Transparent vs UUPS Patterns

// This innocent-looking function caused a 6-hour debugging session
function admin() external view returns (address) {
    return _admin();
}

// The implementation also had this function
function admin() external view returns (address) {
    return owner(); // Different admin entirely!
}

// I always verify these critical functions are properly isolated
bytes4 private constant ADMIN_SLOT = bytes4(keccak256("admin()"));
bytes4 private constant UPGRADE_SLOT = bytes4(keccak256("upgradeTo(address)"));

// This test saved me from missing a collision last month
function testNoSelectorCollisions() external {
    // Map all implementation function selectors
    // Verify no overlap with proxy admin functions
}

// I create this mapping for every contract I audit
contract StorageLayout {
    // Slot 0: Often the owner/admin
    address private _owner;          // slot 0
    
    // Slot 1: Usually paused state for stablecoins
    bool private _paused;           // slot 1
    
    // Slots 2-51: Reserved for future use
    uint256[50] private __gap;      // slots 2-51
    
    // Slot 52: ERC20 totalSupply typically starts here
    uint256 private _totalSupply;   // slot 52
}

contract StablecoinV1 is ERC20Upgradeable, UUPSUpgradeable, OwnableUpgradeable {
    function _authorizeUpgrade(address newImplementation) 
        internal 
        override 
        onlyOwner 
    {
        // Empty function - authorization happens in modifier
    }
}

// I always check if the implementation can selfdestruct
function emergencyDestruct() external onlyOwner {
    // If this exists in the implementation, all proxies die
    selfdestruct(payable(owner()));
}

// Vulnerable implementation I found last quarter
function _authorizeUpgrade(address newImplementation) 
    internal 
    override 
{
    // This allows anyone to upgrade!
    require(msg.sender != address(0), "Cannot be zero address");
}

// Correct implementation
function _authorizeUpgrade(address newImplementation) 
    internal 
    override 
    onlyOwner 
{
    // Additional checks I recommend:
    require(newImplementation != address(0), "Invalid implementation");
    require(newImplementation.code.length > 0, "Not a contract");
    emit UpgradeAuthorized(newImplementation, msg.sender);
}

// I always verify the inheritance chain maintains storage compatibility
contract StablecoinV2 is StablecoinV1 {
    // New variables must go AFTER parent contract storage
    uint256 public newFeature;     // Safe: appends to storage
    
    // NEVER reorganize existing storage
    // mapping(address => uint256) private _balances; // DANGEROUS if moved
}

# I run these checks first to understand what I'm dealing with
$ forge inspect StablecoinProxy storage-layout
$ forge inspect StablecoinImplementation storage-layout

# Then compare storage slots for potential collisions
$ node scripts/compare-storage-layouts.js

// My standard inheritance mapping process
contract AuditHelper {
    function mapInheritance(address implementation) external view {
        // Check each parent contract for:
        // 1. Storage variable declarations
        // 2. Function selector overlaps  
        // 3. Modifier interactions
        // 4. Event signature conflicts
    }
}

// I wrote this script after manually checking storage layouts became unbearable
const storageAudit = {
    async checkCollisions(proxyAddress, implementationAddress) {
        const proxyLayout = await getStorageLayout(proxyAddress);
        const implLayout = await getStorageLayout(implementationAddress);
        
        // Flag any overlapping slots
        const collisions = findCollisions(proxyLayout, implLayout);
        if (collisions.length > 0) {
            console.log("🚨 CRITICAL: Storage collisions detected:", collisions);
        }
    }
};

// I test every possible upgrade path
function testUpgradeAccessControl() external {
    // Can only authorized addresses upgrade?
    vm.expectRevert("Ownable: caller is not the owner");
    vm.prank(address(0xdead));
    proxy.upgradeTo(maliciousImplementation);
    
    // Can the implementation be set to zero address?
    vm.expectRevert("Invalid implementation");
    proxy.upgradeTo(address(0));
    
    // Can we upgrade to a non-contract?
    vm.expectRevert("Not a contract");
    proxy.upgradeTo(address(0x123));
}

// Simulate emergency upgrade under attack conditions
function testEmergencyUpgrade() external {
    // Pause the contract
    stablecoin.pause();
    
    // Verify upgrade still works when paused
    address newImpl = address(new EmergencyImplementation());
    proxy.upgradeTo(newImpl);
    
    // Test that emergency functions work immediately
    EmergencyImplementation(address(proxy)).emergencyWithdraw();
}

// The problematic inheritance chain
contract TokenV1 is ERC20Upgradeable {
    uint256 private _totalSupply;    // slot 0
    mapping(address => uint256) private _balances; // slot 1
}

contract TokenV2 is TokenV1, PausableUpgradeable {
    // PausableUpgradeable declared _paused in slot 0!
    // This overwrote _totalSupply silently
}

// Hidden in a utility function
function setMetadata(bytes32 key, address value) external {
    if (key == keccak256("admin")) {
        // Oops! This bypasses proxy admin controls
        _setAdmin(value);
    }
    metadata[key] = bytes32(uint256(uint160(value)));
}

// Buried in emergency functions
function emergencyMigration() external onlyOwner {
    // Transfer all tokens to new contract
    IERC20(newTokenAddress).transfer(owner(), totalSupply());
    
    // Then destroy the implementation
    selfdestruct(payable(owner())); // Kills ALL proxy instances!
}

# My custom detector for storage collisions
class StorageCollisionDetector(AbstractDetector):
    def _detect(self):
        # Check for overlapping storage slots in inheritance chain
        # Flag potential selector collisions
        # Identify missing storage gaps
        pass

contract ProxyAuditTests is Test {
    function testStorageLayout() external {
        // Verify storage slots match expected layout
    }
    
    function testUpgradesSafely() external {
        // Test upgrade preserves state
    }
    
    function testAdminFunctions() external {
        // Verify admin isolation in transparent proxies
    }
    
    function testEmergencyScenarios() external {
        // Test paused contract upgrades
    }
}

// This inheritance chain took me 2 days to fully audit
contract Stablecoin is 
    ERC20Upgradeable,
    PausableUpgradeable, 
    OwnableUpgradeable,
    UUPSUpgradeable,
    BlacklistableUpgradeable,
    RescuableUpgradeable {
    // Storage collision nightmare waiting to happen
}

// Red flag: custom delegatecall logic
function customDelegatecall(bytes calldata data) external {
    // Usually missing storage isolation
    (bool success,) = implementation.delegatecall(data);
    require(success, "Call failed");
}

// Instant red flag - no room for future upgrades
contract TokenV1 is ERC20Upgradeable {
    uint256 private _totalSupply;
    mapping(address => uint256) private _balances;
    // No __gap array = future upgrade disasters
}

contract StablecoinStorage {
    // Core ERC20 storage
    uint256 private _totalSupply;
    mapping(address => uint256) private _balances;
    mapping(address => mapping(address => uint256)) private _allowances;
    
    // Stablecoin-specific storage  
    bool private _paused;
    mapping(address => bool) private _blacklisted;
    
    // Reserve 50 slots for future features
    uint256[50] private __gap;
}

contract UpgradeTest is Test {
    function testUpgradePreservesState() external {
        // Set initial state
        stablecoin.mint(alice, 1000e18);
        stablecoin.blacklist(bob);
        
        // Upgrade to V2
        proxy.upgradeTo(address(new StablecoinV2()));
        
        // Verify state preserved
        assertEq(stablecoin.balanceOf(alice), 1000e18);
        assertTrue(stablecoin.isBlacklisted(bob));
    }
    
    function testNewFunctionality() external {
        // Upgrade and test new features work
    }
    
    function testDowngradeProtection() external {
        // Ensure we can't downgrade accidentally
    }
}