Designing Upgradeable Smart Contracts using the Proxy Pattern

Smart contracts are fundamentally defined by their immutability, which ensures that once a program is deployed to a blockchain, its behavior is predictable and permanent. This security model is excellent for trust but presents a massive challenge when a critical security vulnerability is discovered or when business requirements evolve. In a traditional software stack, developers push a patch to a server, but on a decentralized ledger, the original code is locked forever at its specific address.

The primary goal of upgradeable architecture is to decouple the location of a contract from its specific business logic. By separating the entry point where users interact from the engine that processes data, developers can maintain a consistent interface while swapping out the underlying mechanics. This separation is essential for any decentralized application that intends to scale and survive in a rapidly changing technical landscape.

When we talk about upgrading a contract, we are not actually changing the existing code on the blockchain. Instead, we are changing the reference point that an entry contract uses to find its instructions. This mental model shifts our focus from editing files to managing pointers and storage layouts, ensuring that user balances and historical data remain intact across multiple iterations of the software.

The technical foundation of any upgradeable contract is the delegatecall opcode provided by the Ethereum Virtual Machine. This specialized instruction allows one contract to execute code from another contract while maintaining the original context of the caller. Crucially, the storage, balance, and sender identity of the calling contract are preserved during the execution of the remote code.

When a proxy contract uses delegatecall, it is telling the blockchain to run the code from the implementation contract but to treat the proxy as the owner of all the data. Any changes made to variables like a user balance are written to the storage slots of the proxy, not the implementation contract. This enables the implementation contract to be entirely stateless and easily replaceable without losing any data.

1// This function is triggered whenever the proxy is called
2fallback() external payable {
3    address _impl = implementationAddress;
4    assembly {
5        // Copy the incoming call data
6        calldatacopy(0, 0, calldatasize())
7        // Execute the call to the implementation contract
8        let result := delegatecall(gas(), _impl, 0, calldatasize(), 0, 0)
9        // Copy the return data back to the caller
10        returndatacopy(0, 0, returndatasize())
11        // Check if the call was successful
12        switch result
13        case 0 { revert(0, returndatasize()) }
14        default { return(0, returndatasize()) }
15    }
16}

A major risk in this design is the potential for storage collisions, which occur when the proxy and the logic contract expect variables to be in different memory locations. Because the proxy is managing the memory, the implementation contract must have an identical storage layout to avoid overwriting critical system flags or administrative pointers. Most developers solve this by following strict storage standards or using reserved slots defined by the community.

The Transparent Proxy Pattern was developed to solve a specific problem called the function selector clash. This occurs when a logic contract has a function with the same four-byte identifier as an administrative function in the proxy contract. If a clash occurs, the proxy might accidentally execute an upgrade command when a user simply intended to call a standard business function.

To resolve this, the Transparent Proxy acts differently depending on who is calling it. If the caller is the designated administrator, the proxy only exposes administrative functions like upgrading to a new logic address. If the caller is anyone else, the proxy ignores the administrative functions and delegates all calls to the implementation logic, ensuring no overlap can occur.

• Security: Eliminates the risk of function selector clashes by separating administrative and user access.
• Complexity: Requires the deployment of an additional ProxyAdmin contract to manage the upgrade process.
• Gas Cost: Every call to the proxy requires an additional check of the msg.sender, which slightly increases transaction fees for users.

While this pattern is robust and has been the industry standard for years, it does come with a gas overhead. Every time a user interacts with the contract, the proxy must load the admin address from storage and compare it to the caller. For high-frequency applications, these small gas costs can add up, leading developers to look for more optimized alternatives.

The UUPS pattern is an evolution of the proxy architecture that moves the upgrade logic from the proxy contract into the implementation contract itself. This shift simplifies the proxy contract significantly, reducing it to a lean wrapper that only contains the delegation code. Because the proxy is smaller, it costs much less gas to deploy and slightly less gas to execute user transactions.

In a UUPS setup, the logic contract must inherit a specific interface that includes a function for upgrading the implementation. This means that every version of your software must explicitly include the code required to perform an upgrade. This design gives the developer more control over how upgrades are handled, but it also introduces a new set of risks regarding the lifecycle of the contract.

If you deploy a UUPS logic contract that lacks an upgrade function, or if the upgrade function is broken, the proxy becomes permanently immutable and can never be updated again.

This architectural style is often preferred for modern decentralized applications because of its gas efficiency. By removing the identity check required in Transparent Proxies, UUPS allows the EVM to jump straight to the logic execution. However, the developer must be extremely diligent in their testing to ensure that the upgrade path is never accidentally removed from the system.

Implementing an upgradeable contract requires a shift in how we handle constructors and variable initialization. In the EVM, a constructor is only executed during the deployment of the contract, which means a proxy cannot see the values initialized in the implementation contract's constructor. Instead, we use an initializer function that is manually called immediately after the proxy is deployed to set the starting state.

This initializer function must be protected so that it can only be called once, similar to how a constructor behaves. If the initializer is left open, an attacker could re-initialize the contract and take ownership of the administrative roles. OpenZeppelin provides a base contract called Initializable that handles this logic safely, preventing the function from being executed a second time.

Another critical safety measure is the use of storage gaps in base contracts. When building complex inheritance structures, adding a new variable to a base contract in the future can shift the storage slots of all child contracts, leading to massive data corruption. By including a large array of unused storage slots in your base contracts, you create a buffer that allows you to add variables later without shifting the memory layout of the rest of the system.