How upgradable contracts work in Solidity

Created on September 2022 • Tags: solidity guides

A guide to the various ways you can have upgradable smart contracts, and the pros and cons about them

Table of Contents for How upgradable contracts work in Solidity

Smart contracts are immutable. Once you have deployed it, the code can’t change. You can however change the data stored in the smart contract (storage data), and you can use clever tricks to change what code is executed.

This is known as upgrading your smart contract.

There are a few well known and well used patterns when it comes to upgrading your smart contracts.

Split into two layers: Proxy layer (storage) & Implementation layer (code)

A basic upgradable smart contract pattern that you often see is where one smart contract just acts as a proxy, and forwards all calls to an actual implementation contract.

Proxy (storage layer)

The proxy smart contract is initially deployed with a variable pointing to the (first) implementation contract address.

Implementation (code layer)

All function calls gets proxied through the proxy, and are called on the implementation contract address.

This will often use delegatecall so the code executes in the context of the proxy.

Upgrading

Then when it is time to upgrade, a new implementation is deployed, and new calls to the proxy will run the new implementation code. There are a few ways the upgrade often happens, described below.

Transparent vs UUPS proxy

Transparent proxies were the original ones seen in smart contracts
“Universal Upgradeable Proxy” or just UUPS, were introduced in EIP-1822
In UUPS the upgrading of implementation is handled by the (current) implementation, and also has an option of being removed.
Transparent proxies handle the upgrade in the proxy (not implementation).
Because in UUPS the implementations handle the upgrading, it is important that every upgraded smart contract has logic in the new implementation to allow future upgrades. This means more complex implementations.
transparent proxy deployments are more expensive, as they hold more logic about upgrading
transparent proxies are also easier to work with, and if you are reading this as an introduction to upgrading smart contracts I’d recommend you play with transparent proxies first.