New to blockchain software development? Read my beginners guide here

How upgradable contracts work in Solidity

Created on September 2022 • Tags: solidityguides

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.


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.

Further reading

This post is incomplete and a work-in-progress
I'll update it soon and flesh it out with more info!

Spotted a typo or have a suggestion to make this crypto dev article better? Please let me know!

See all posts (70+ more)

See all posts (70+ more)

Was this post helpful? 📧

If you liked this content and want to receive emails about future posts like this, enter your email. I'll never spam you.

Or follow me on @CryptoGuide_Dev on twitter

By using this site, you agree that you have read and understand its Privacy Policy and Terms of Use.
Use any information on this site at your own risk, I take no responsibility for the accuracy of safety of the information on this site.