Forem: Sebastien Levy

Deep Dive in Transparent Proxy Code

Sebastien Levy — Fri, 07 Nov 2025 10:01:26 +0000

Intro

In a previous article I made a presentation on Transparent Upgradeable Proxies in Solidity; what they are, why they are useful and key concepts about how they work.

I let readers to dive in at their leisure in the code in this repository should they wish to know more.

I had some feedback though telling me it could be valuable to expose this proxy implementation code alongside precise explanations about how it works.

So here we are, 100% proxy, 100% focus.

Context

Let's keep something that is working by taking some code from The Nifty repository :

Study of TransparentUpgradeableProxy.sol

This is the actual transparent proxy implementation.
In this section I'll make a parallel between concepts I exposed in this article and the actual code.

Storage Slots

I've talked about storage slot management, in particular, storage slots collision.
Remember, a proxy call effectively calls an underlying implementation contract function but all state management is done within the proxy. This is the basis of how delegatecall works.

You see, this proxy implementation has also some states to manage:

the address of the current administrator of the proxy
the address of the current implementation contract to call functions of.

If those states were declared as they are in the implementation contract (or any normal contract), they would collide together and things would get very hot, very soon.

But wait... there are no state member within this proxy contract.

The only thing you have are:

weird constants whose values are provided (for gas optimizations)
a modifier and functions using those weird constants through a weird type named ProxyStorage

Weird constants

You can see they are result of hashing a string. In fact, the result of this hashing will give us the slot number where to store state of this proxy.

Therefore, ADMIN_SLOT will be the slot where we'll store the address of the proxy admin and IMPLEMENTATION_SLOT, the slot where we'll store the current underlying implenetation contract.

The library

Let's take a look at the ProxyStorage.sol file.

It defines a solidity library. A library can be seen as a base contract whose exposed function are delegatecalled somehow, allowing those called function to modify the state of the caller contract (libraries in solidity).

This library only expose one function which gives us a reference on a stored struct object.

Keep in mind the stored struct object lies in the caller contracts in our case: TransparentUpgradeableProxy.

This function is quite low level as it uses inlined assembly directive.
This is to override the default compiler behavior.
By default, the compiler store states of the contract at the first slot available starting at 0 and going forward (at leat for value types).
With this function, we can choose the slot (the location) of the TransparentUpgrageableProxy state variables thus, avoiding collisions with underlying implementation contract whose layout is deduced by the compiler default behavior I told just before.

assembly ("memory-safe") { // memory-safe indeed, we just change a slot number
      r.slot := slot // define the slot number of the returned struct object
}

Therefore, in the transparent proxy implementation a function such as

function getAdmin_() private view returns (address) {
    // returns the value (address) stored in the ADMIN_SLOT slot number
    return ProxyStorage.getAddressSlot(ADMIN_SLOT).value;
}

ensures we do not collide with any underlying implementation contract state.

Call delegation

This key concept of transparent proxy deserves a bit of explanation.
To put simply, the proxy effectively use of delegatecall but it is fine tuned for several reasons. Let's explore them:

Gas efficiency
- Any, I say any non-admin function calls to an underlying implementation contract pass through the proxy. Gas saving is paramount. This is why assembly construct is used here as we'll see
call delegation through fallback function
- The fallback function is a particular beast. It does not return any value. But proxy delegated calls must work with functions returning values. Once more, assembly to the rescue!
standardization
- In fact, this implementation of delegated call is the same as the one in the OpenZeppelin repository. Understand that it's a super standard way to implement transparent proxy. I did not invent anything new here.

Here's the code:

function fallback_(address implementationContract) private {
    // we'll see why in the next section about transparency
    require(msg.sender != getAdmin_(), InvalidAdminCall());

    assembly {
      // Copy msg.data.
      // gas saving (no bytes allocation)
      // no harm due to scratch pad over-writing because there is no solidity code after this inline assembly block
      calldatacopy(0x00, 0x00, calldatasize())

      // this is the actual delegatecall
      // Call the implementation.
      // offset 0 and size unknown
      let result := delegatecall(gas(), implementationContract, 0x00, calldatasize(), 0x00, 0x00)

      // copy return data starting from offset 0 using return data size we know at this point
      returndatacopy(0x00, 0x00, returndatasize())

      // either returns or revert, using return data size
      switch result
      case 0 { revert(0x00, returndatasize()) }
      default { return(0x00, returndatasize()) }
    }
}

Transparency

In this project, the proxy must behave differently depending who's using it. Put simply:

If the sender is the proxy admin, call proxy function without forwarding to the underlying implementation. Calling an unexisting function leads to revert.
If the sender is not the proxy admin, delegate function call to the underlying implementation even if this function exists in the proxy.

In the code, this is represented by the onlyAdmin modifier used in proxy getter functions (admin and implementation):

modifier onlyAdmin() {
    if (getAdmin_() == msg.sender) {
      _; // call of the proxy function
    } else {
      // delegatecall to underlying implementation      
      fallback_(ProxyStorage.getAddressSlot(IMPLEMENTATION_SLOT).value);
    }
}

Some experts reader might say writing modifier like this is an anti-pattern. I understand. Specify if-else construct might obscure the intent of such modifier this is true. But in my case, I find it acceptable and it removes duplication; proxy are truly very specific and this code is not intended to change a lot.

Conclusion

I hope this deep tech dive into transparent proxy code is clear.
I'd like to remind you though this implementation is functional, it is largely imperfect and can be enhanced a lot. Always prefer stardardized solution such as Open Zeppelin for your proxy needs.

Thanks

@christopherkade for it's banner generator
Open Zeppelin hard work that inspired me
Ethereum ecosystem and community for the hard work they have been providing.

How to deploy you NFT on Sepolia - Simple and 100% under control

Sebastien Levy — Thu, 06 Nov 2025 15:45:54 +0000

In a previous article about Transparent Upgradeable Proxy in solidity, I showed how this pattern has been used in a real NFT project.

In this article, let's focus on how this kind of project can easily and efficiently be deployed on a testnet to ensure it works well before jumping to mainnet.

Why bother with testnets?

Deploying smart contracts on a testnet offers several advantages over skipping this step entirely. Testnets provide a realistic simulation of the Ethereum Mainnet environment, allowing developers to test contract functionality, interactions, and user flows in a live blockchain setting without risking real funds.
This enables thorough end-to-end testing and allows beta testers to evaluate the application under real-world conditions.

In contrast, skipping testnet deployment means missing out on these critical validation steps. Without testing on a testnet, developers risk deploying untested logic to the mainnet, where bugs could lead to irreversible financial losses or security vulnerabilities.

While local development networks are useful for initial testing, they do not fully replicate the behavior of the Ethereum Virtual Machine (EVM) or the dynamics of a live network, making testnet deployment a necessary intermediate step before mainnet release.

You should not skip this kind of deployment for any serious project.

The project

To illustrate, let's focus on the NFT project I've already talked about: Nifty.

This is a complete NFT project thoroughly tested and able to be deployed at will on sepolia, provided you have the necessary API key from etherscan, a node provider for instance alchemy giving you an access to the test network as well as test ethers you can obtain from a faucet such as chainlink.

Tooling used

Developping and deploying a blockchain project has never been so easy with todays's tooling.

Though you've to keep in mind that some configuration is necessary, in this article I'll briefly cover 2 tools I use on an every day basis when I develop blockchain projects.

Foundry

Must have. Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.

Nideovim

A tool I made.
You can see it as an attempt to provide isolated and deterministic development environments for any kind of project.
It combines the power of several well-known technologies such as Linux, Docker and Neovim that are fuelled by an evergrowing community that get them more and more powerful.

I'll do a dedicated article on nideovim should you be interested (let me know in comments).

Setup before deployments

Let keep things simple.

Clone the repository:
- git clone https://github.com/MetaBarj0/Nifty.git
Go to the contracts directory:
- cd contracts
Ensure the project can be deployed by running tests:
- make test
- everything should be green
Edit the .env configuration file to allow deployement on the test network:
- set the MAINNET_URL variable to a RPC endpoint of your chosing (I use alchemy as a node provider but any other can do)
- set the SEPOLIA_URL variable using the same way as for the MAINNET_URL variable.
- set the MAINNET_FORK_BLOCK to a valid block number for instance 23739277 but any valid block number is ok. You can get a valid block number of the homepage of etherscan
- setup the PRIVATE_KEY variable using the private key of a wallet containing enough test ETH to deploy the contract. (NEVER EVER use a wallet containing other non test token, you should have a test wallet for these kind of purposes)
- setup the ETHERSCAN_API_KEY to an etherscan API key you or your organization own (you can create one for free).

That's it for tedious configuration steps. The next part is the actual deployment.

Simply deploy

Only one command to rule the deployment:

make sepolia_deploy.

It will deploy the entire set of smart contract to sepolia that are:

The NFT (Nifty contract)
The crowd sale (Crowdsale contract)
a pair of proxies (TransparentUpgradeableProxy contract)
- one for Nifty contract
- one for the Crowdsale contract

This step can take few minutes to complete. Once it's successful, you should see something like All (4) contracts were verified!

Etherscan post deploy steps

As I said, 4 contracts have been deployed and 2 of them are proxies. The next things to do is to get the 2 proxies deployed contract addresses and tell to sepolia that those contract are proxies.

Getting the contract addresses

Go to the broadcast deployment directory: cd broadcast/SepoliaDeploy.s.sol/11155111
look into the run-latest.json file to get addresses of the 2 proxy contracts:
- look for these 2 lines in the file : "contractName": "TransparentUpgradeableProxy"
- get the 2 addresses in the field: contractAddress of the object you found.

Setup proxies

Go to sepolia etherscan
in the search bar, put one of the 2 addresses you got from run-latest.json file
go to the contract tab
sepolia etherscan should tell you this contract may be a proxy (and he's right)
then setup this contract as a proxy
- at the right of the contract source code line there is a more options dropdown, click on it.
- click on is this a proxy?
- on the new page click on verify
- once done you'll get notified the address of the implementation contract
- click save and go back to the proxy contract page
- repeat the same process for the other proxy

Deployment done

Once those steps are done, in the contract tab you can see 2 new buttons: read as proxy and write as proxy allowing you to interact with the proxy contract as if it were the underlying implementation contract (Nifty or Crowdsale).

Next steps

Now contracts have been deployed on a public test net, you can interact with them freely using any mean (RPC endpoint using a Node provider, Remix IDE, ...)

Play with deployed contracts

As an exercise left to the reader, make few transactions to deployed contracts using Remix.

I let you same addresses of a previous deployment I made here, should you have any issue deploying yourself:

Nifty at 0x4a6e3713ce9cc0b18de00e195a0d6ab4d09c2175
Crowdsale at 0xe51979cea418896991f17e7a432db652094d6271
Nifty proxy at 0xdb03331289ceae8ceb3ca9d3888c45d24e5b72a4
Crowdsale proxy at 0xc2c46f98946b5373b489542f07f42e1993020821

Conclusion

I hope this article has been clear enough and is relevant enough to prove you can deploy projects on test nets to ensure things are going well before deploying it to main net.

Let me know about your thoughts in comment.

Thanks

@christopherkade for it's banner generator
Brave Leo's AI to have helped me to build arguments chapter regarding why bother about deploying on test net
contributor to fantastic dev tools I use every day to build.
all the community for all invaluable resources I consume every day to be able to make something eventually useful

Understanding Solidity Transparent Upgradeable Proxy Pattern - A Practical Guide

Sebastien Levy — Tue, 04 Nov 2025 14:56:52 +0000

Smart contract development presents a unique challenge: once deployed to the
blockchain, your code becomes immutable. This immutability, while providing
security and trust guarantees, creates significant difficulties when you need
to upgrade your contract logic or fix critical vulnerabilities. Enter the
Transparent Upgradeable Proxy Pattern - an elegant solution that allows
smart contracts to be upgraded while maintaining their state and address.

The Immutability Challenge

Why Smart Contracts Can't Be Changed

When you deploy a smart contract to Ethereum or any EVM-compatible blockchain,
the bytecode is permanently stored on the blockchain. This immutability
provides several benefits:

Trust: Users can verify the contract code and know it won't change unexpectedly
Security: No single party can maliciously modify the contract logic
Decentralization: The contract operates independently without central control

However, this immutability creates significant challenges:

Difficulties in Upgrading Smart Contract Logic

Bug Fixes: If you discover a critical bug in your contract, you can't simply patch it like traditional software
Feature Updates: Adding new functionality requires deploying a completely new contract
State Migration: Moving user data from old contracts to new ones is complex and expensive
Address Changes: A new deployment means a new contract address, breaking integrations and user bookmarks

The Vulnerability Problem

Consider this scenario: You've deployed a popular DeFi protocol with millions
of dollars locked in it. Suddenly, a security researcher discovers a critical
vulnerability that could drain all funds. In traditional software, you'd push a
hotfix immediately. But with immutable smart contracts, you're stuck with three
bad options:

Deploy a new contract - Users must migrate manually, often with significant friction
Live with the vulnerability - Hope nobody exploits it while you work on a migration
Use a kill switch - Pause the contract, but this defeats the purpose of decentralization

Enter the Transparent Upgradeable Proxy Pattern

The proxy pattern solves these problems by separating storage from
logic. Here's how it works:

Proxy Contract: Holds all the state/storage and delegates function calls to the implementation
Implementation Contract: Contains the business logic but no state
Admin: Can upgrade the implementation while preserving the proxy's state and address

Key Components

Delegatecall: The proxy uses delegatecall to execute implementation code in proxy's context
Storage Slots: Carefully managed to avoid collisions between proxy and implementation
Transparency: Admin calls access proxy functions, user calls are forwarded to implementation

Building a Practical Implementation with Foundry

Let's build a real-world transparent upgradeable proxy using Test-Driven
Development (TDD) with Foundry. We'll use a practical example from an NFT
contract system.

To get a full grasp on the implementation, go to Nifty
repository.
All code examples here exist in this repository and you could test it and even
deploy it on a test network if you want to play a bit.

A first look

When I start a project, one of the first thing I do is executing tests to see
if everything is in order with a fresh clone on a new environment.

With Nifty, it's pretty simple:

Go to the contracts subdirectory and run: make test

Everything should be green.
If not, please, report in comments and I'll do my best to get it in the right
color for you.

Now let's focus on the contracts/test/proxy/TransparentUpgradeableProxy.t.sol
file.

Feel free to browse all tests in this suite but for now, let's focus on those
that are designed to ensure the tricky part of the proxy are well implemented.

Deep diving in most important cases

test_constructor_throws_withFailingInitializableImplementation

This test ensures a TransparentUpgradeableProxy contract cannot be deployed if
the underlying implementation fails to initialize with an existing initialize
function.

This is very important because proxy deployments cannot use constructors to
initialize their state. Thus, they rely on an initialization function that
MUST be in the implementation contract.

In this test the implementation contract is
FailingInitializableImplementation located in the contracts/test/Mocks.sol.
The initialize function just revert. As simple as that.

test_constructor_initializes_triviallyConstructibleContract

Should the underlying implementation be simple enough to not have specific
initialization logic, this test ensure a proxy can handle it. No call to an
initialize function is needed.

test_admin_returnsProxyAdmin_ifAdmin

The TransparentUpgradeableProxy pattern imposes specific behaviors regarding
which function to call depending on who's calling:

if the sender is the proxy admin, there is no routing to underlying implementation and proxy functions are directly called
If the sender is someone else, a forward is done using delegatecall. Proxy functions will never be called. Should an in-existing function called, the transaction is reverted.

test_admin_returnsImplementationAdmin_ifNotAdmin

The reciprocal of above, in this case, the test will call the admin function
of the implementation contract TestImplementation located in
contracts/test/Mocks.sol

test_stateChangesOccurInProxyStorage_forNotAdminCalls

This one ensures all state changes occur in the proxy slots instead of the
implementation contract slots. This test also proves there is no collision
between proxy storage slots and implementation contract storage slots.

A real wold application: Nifty

This ERC721 token implementation fully use the transparent upgradeable proxy
pattern at its core. To get further, all features of this token (and also the
associated Crowdsale contract) are tested both:

directly (using contract functions)
through a transparent upgradeable proxy

Take a look in the contracts/test/Nifty.t.sol for a very concise overview on
how it works.

A powerful Foundry feature is leveraged here: table testing, allowing to
parameterize test.

In a nutshell, each test is executed twice:

using the Nifty contract directly
by calling Nifty contract functions through a proxy

Conclusion

There would be so much to say about this fantastic pattern but I think I
covered the most important aspects here.

I hope this article could be seen as both a concise explanation on what
transparent upgradeable proxies are in solidity and how to use them practically
in a real world project using proven development methodologies.

I'd love some feedbacks of the community to improve both this article and the
Nifty implementation.