<h1 id="history-of-callcode-and-delegatecall">History of Callcode and Delegatecall</h1>
<h2 id="callcode-opcode">Callcode opcode</h2>
<p>If you read the <a href="https://docs.soliditylang.org/en/latest/introduction-to-smart-contracts.html#deactivate-and-self-destruct">solidity docs about <code class="inline-code-block">selfdestruct</code></a>, you will find a note saying that <code class="inline-code-block">delegatecall</code> and <code class="inline-code-block">callcode</code> can provide a way to <code class="inline-code-block">selfdestruct</code> a contract that does not contain the <code class="inline-code-block">selfdestruct</code> opcode. What is <code class="inline-code-block">callcode</code> and how similar is it to <code class="inline-code-block">delegatecall</code>? <code class="inline-code-block">callcode</code> is the same as <code class="inline-code-block">delegatecall</code> but it does not propagate <code class="inline-code-block">msg.sender</code> or <code class="inline-code-block">msg.value</code>. <code class="inline-code-block">callcode</code> was deprecated <a href="https://docs.soliditylang.org/en/latest/050-breaking-changes.html#functions">in Solidity 0.5.0</a>. <a href="https://eips.ethereum.org/EIPS/eip-2488">EIP-2488</a> proposed to fully deprecate <code class="inline-code-block">callcode</code> but the EIP did not get far. Even though you will still see the callcode opcode (0xF2) on <a href="https://www.evm.codes/">evm.codes</a>, if you write a contract with the <code class="inline-code-block">callcode</code> opcode and a solidity version of 0.5.X or newer, you will get an error preventing the contract from compiling with the message <code class="inline-code-block">TypeError: "callcode" has been deprecated in favour of "delegatecall".</code> Similar cases of deprecated opcodes are found in this table for <a href="https://swcregistry.io/docs/SWC-111">SWC-111</a>.</p>
<h2 id="delegatecall-opcode">Delegatecall opcode</h2>
<p><a href="https://eips.ethereum.org/EIPS/eip-7">EIP-7</a> introduced the <code class="inline-code-block">delegatecall</code> opcode as a bug fix to <code class="inline-code-block">callcode</code>, which was introduced in the <a href="https://ethereum.org/en/history/#homestead">Homestead hard fork in 2016</a>. Because proxy development only started gathering momentum in 2017, <code class="inline-code-block">callcode</code> was never used for proxies, which is why <code class="inline-code-block">delegatecall</code> is the opcode that we all associate with proxies today.</p>
<h2 id="comparison-between-callcode-and-delegatecall">Comparison between Callcode and Delegatecall</h2>
<p>Below is a diagram comparing proxies built with <code class="inline-code-block">callcode</code> and <code class="inline-code-block">delegatecall</code> (<em>Note: it is not recommended to use <code class="inline-code-block">callcode</code> in proxies</em>).</p>
<p><img src="/proxies/Comparison_Callcode_Delegatecall.png" alt="Comparison with Proxy"></p>
<p>Both <code class="inline-code-block">callcode</code> and <code class="inline-code-block">delegatecall</code> have the same behavior on storage. That is, both of them can execute the implementation's code and perform operations with proxy's storage. The difference between them is in <code class="inline-code-block">msg.value</code> and <code class="inline-code-block">msg.sender</code>. In <code class="inline-code-block">callcode</code>, <code class="inline-code-block">msg.value</code> can be customized to hold a new value in the implementation contract and <code class="inline-code-block">msg.sender</code> is changed to Proxy's address. In <code class="inline-code-block">delegatecall</code>, both <code class="inline-code-block">msg.value</code> and <code class="inline-code-block">msg.sender</code> remain the same in the proxy and implementation contracts.</p>

History of Callcode and Delegatecall

Proxies Deep Dive

<h1 id="proxies-storage">Proxies Storage</h1>
<p>Note: If you are new to understanding how smart contract storage slots work, review an entry level guide first, like the <a href="https://docs.soliditylang.org/en/latest/internals/layout_in_storage.html#layout-of-state-variables-in-storage">solidity docs</a>.</p>
<p>Storing state variables is important for any smart contract, but especially so for proxies. Checking the values stored at specific storage slots in a contract is a useful way to check if the proxy is working as expected. Once the storage slot for a variable is known, a tool like <a href="https://github.com/dapphub/dapptools/tree/master/src/seth#seth-storage">seth</a>, <a href="https://book.getfoundry.sh/reference/cast/cast-storage">cast</a>, or your favorite web3 JS/Python library (<a href="https://docs.ethers.io/v5/api/providers/provider/#Provider-getStorageAt">ethersJS</a>, etc.) can pull the data at that location directly from the blockchain. These tools can help identify the storage slot of the variables found in the deployed contract.</p>
<h2 id="storage-slot-analysis-for-verified-contracts">Storage Slot Analysis for Verified Contracts</h2>
<ul>
<li><a href="https://github.com/crytic/slither/blob/master/slither/tools/read_storage/README.md">slither-read-storage</a>: A slither tool to retrieve storage slots for verified contracts. A <a href="https://blog.trailofbits.com/2022/07/28/shedding-smart-contract-storage-with-slither/">blog post</a> was published with more examples.</li>
<li><a href="https://github.com/naddison36/sol2uml">sol2uml</a>: A visualizer of storage slot usage for a verified contract</li>
<li><a href="https://book.getfoundry.sh/reference/forge/forge-inspect?highlight=layout">forge inspect</a>: Lists the storage slots for variables in a contract. If the code is verified on-chain, it can be downloaded to your local system using <a href="https://www.npmjs.com/package/ethereum-sources-downloader">ethereum-sources-downloader</a>.</li>
<li><a href="https://github.com/aurora-is-near/hardhat-storage-layout">hardhat-storage-layout</a>: A hardhat plugin to view storage slots of variables.</li>
<li><a href="https://docs.soliditylang.org/en/latest/using-the-compiler.html#input-description">solc --storage-layout</a>: Similar to foundry, can output the storage slot and offset for each state variable.</li>
<li><a href="https://chrome.google.com/webstore/detail/metadock/fkhgpeojcbhimodmppkbbliepkpcgcoo">MetaDock Chrome Extension</a> enhances etherscan and other blockchain scanners to show the values of private variables that normally cannot be accessed on etherscan.</li>
</ul>
<h2 id="storage-slot-analysis-for-unverified-contracts-and-verified-contracts">Storage Slot Analysis for Unverified Contracts (and Verified Contracts)</h2>
<ul>
<li><a href="https://library.dedaub.com/">Contract Library</a>: When viewing a contract, can navigate to the "Read/Write" tab and choose "Storage dump" to see all values stored in all storage slots. Doesn't require a verified contract. The decompiler is also very helpful.</li>
<li><a href="https://github.com/tintinweb/smart-contract-storage-viewer">smart-contract-storage-viewer</a>: Useful tool from tintinweb to view what a contract has stored in specific storage slots. This tool is only useful if you already know the storage slot value locations to view or want to view a range of many sequential storage slot values.</li>
<li><a href="https://etherscan.io/">Etherscan</a>: The "Switch to Opcodes View" button next to the contract creation code and review all the SLOAD operations to identify storage slots that hold (or held) values.</li>
</ul>

Proxies Storage

<h1 id="proxies-table">Proxies Table</h1>
<table>
<thead>
<tr>
<th>Type</th>
<th>Summary</th>
<th>Pros</th>
<th>Cons</th>
<th>Gotchas</th>
<th>Who should implement</th>
<th>Known Vulnerabilities</th>
<th>Upgradeable?</th>
<th>Can be made immutable?</th>
</tr>
</thead>
<tbody>
<tr>
<td>Proxy</td>
<td>Calls made to the proxy contract are forwarded to the implementation contract using <code class="inline-code-block">delegatecall</code>.  Address of the implementation contract is immutable in the proxy. This is the basis for just about all proxy types with the exception of Metamorphic.  One example of this proxy type is EIP1167 Minimal Proxy Clones.  An improvement over Minimal Proxy Clones is Clones with Immutables</td>
<td>Simple</td>
<td>Costs gas to do the delegate call</td>
<td></td>
<td>Shims to avoid deploying many of the same contract and can deploy new shims that point to an existing contract.  When there's a 1-1 relationship between proxy and impl contracts.</td>
<td>delegatecall in implementation or selfdestruct in implementation</td>
<td>No</td>
<td>Yes, by design.</td>
</tr>
<tr>
<td>Upgradeable Proxy</td>
<td>Similar to proxy except the address of the impl contract is kept in storage in the proxy.  Permissioned upgrade logic is also located in the proxy.</td>
<td>Simple.</td>
<td>Extra care is required for the upgrade logic (access control) as it resides in the implementation contract. Costs gas to do the delegate call, Vulnerable to function collisions</td>
<td>Storage collisions can be avoided by EIP1967, admin != caller</td>
<td>Not widely used anymore.  There are better patterns.</td>
<td>Function collision with proxy, storage collision, delegatecall in implementation, or selfdestruct in implementation</td>
<td>Yes</td>
<td>Yes, by admin revoking ownership of the proxy.</td>
</tr>
<tr>
<td>Transparent Proxy (TPP)</td>
<td>Similar to Upgradeable proxy for non-admin callers, but when the admin calls the proxy the proxy's functions are used</td>
<td>Comparatively easy and simpler to implement; widely used</td>
<td>Waste gas on delegatecall and checking storage to see if caller is admin</td>
<td>Storage collisions can be avoided by EIP1967 , admin != caller, using a UUPS compliant implementation with a TransparentUpgradeableProxy might allow non-admins to perform upgrade operations</td>
<td>Still used for its simplicity especially when there is a 1:1 relationship between the proxy and impl contracts.</td>
<td>function collision with proxy, delegatecall in implementation, or selfdestruct in implementation, storage slot collision with proxy,  uninitialize proxies, gas guzzler</td>
<td>Yes</td>
<td>Yes, by admin revoking ownership of the proxy.</td>
</tr>
<tr>
<td>Universal Upgradeable Proxy Standard (UUPS) - EIP1822</td>
<td>Similar to Transparent proxy except the <code class="inline-code-block">upgrade</code> logic is stored in the implementation contract so there is no need to check if the caller is admin in the proxy (saving gas). UUPS proxies also contain a check  to ensure the new impl contract is also upgradeable.</td>
<td>More gas efficient.  Reduces function conflicts w proxy since upgrade fns are in impl.</td>
<td>Still have overhead of delegate call</td>
<td>Storage collisions can be avoided by EIP1967 , admin != caller</td>
<td>For a more gas efficient proxy and when there are many different proxy contracts pointing to the same implementation.</td>
<td>delegatecall in implementation, or selfdestruct in implementation, uninitialized proxy</td>
<td>Yes</td>
<td>Yes by admin revoking ownership or by upgrading to an impl contract that does not contain impl logic.</td>
</tr>
<tr>
<td>Beacon Proxy (aka Dharma Beacon Proxy)</td>
<td>Instead of storing the impl contract address the proxy stores the address of a beacon.  The beacon contract stores the address of the implementation contract.</td>
<td>Can upgrade many different proxies pointing to the beacon.</td>
<td>Gas overhead of calling Beacon contract and getting the impl contract address from storage, as well as the delegate call</td>
<td>Storage collisions can be avoided by EIP1967, admin != caller</td>
<td>When more control is desired with more complex systems of upgradeability.  Sets of proxies can point to one beacon while other types can point to a different beacon.</td>
<td>delegatecall in implementation, or selfdestruct in implementation, uninitialized proxy</td>
<td>Yes</td>
<td>Technically yes, but if the goal was immutability then choose a different type.</td>
</tr>
<tr>
<td>Upgradeable Beacon Proxy</td>
<td>Same as Dharma Beacon proxy except the Beacon address is settable in the proxy.</td>
<td>Even the Beacon contract can be upgraded.</td>
<td>Complex.  Gas guzzler.</td>
<td>Storage collisions can be avoided by EIP1967 , admin != caller</td>
<td>Even more complex patterns can be used when the beacon address is also upgradable.</td>
<td>delegatecall in implementation, or selfdestruct in implementation, uninitialized proxy</td>
<td>Yes</td>
<td>Technically yes, but if the goal was immutability then choose a different type.</td>
</tr>
<tr>
<td>Storageless Upgradeable Beacon Proxy</td>
<td>The Beacon contract stores the implementation contract in the code instead of in storage, saving gas. <a href="https://forum.openzeppelin.com/t/a-more-gas-efficient-upgradeable-proxy-by-not-using-storage/4111">https://forum.openzeppelin.com/t/a-more-gas-efficient-upgradeable-proxy-by-not-using-storage/4111</a></td>
<td>More gas efficient than TPP, UUPS, Dharma Beacon</td>
<td>Complexity. Little to no adoption.</td>
<td>The upgrade process involves self-destructing the beacon so there is a 1 block down time for the beacon.  As such a backup beacon is utilized.</td>
<td>This is more of an experiment and there are no known implementations of this in the wild.</td>
<td>delegatecall in implementation, or selfdestruct in implementation, uninitialized proxy</td>
<td>Yes</td>
<td>Technically yes, but if the goal was immutability then choose a different type.</td>
</tr>
<tr>
<td>Diamond Proxy</td>
<td>An upgradeable proxy pattern in which there are multiple logic contracts (instead of just one) called facets. Additionally, this pattern uses a separate contract for storage.</td>
<td>Can create powerful, modular combinations. Helps to battle the 24KB size limit via modularity; incremental upgradeability</td>
<td>Complexity.  Slow adoption.</td>
<td>More complex to implement and maintain; uses new terminologies that can be harder for newcomers to understand; as of this writing, not supported by tools like Etherscan</td>
<td>When you need the control and flexibility offered by having multiple logic contracts or separate storage.</td>
<td>delegatecall in implementation, or selfdestruct in implementation, uninitialized proxy</td>
<td>Yes</td>
<td>Yes</td>
</tr>
<tr>
<td>Metamorphic Contract</td>
<td>A contract that is deployed with CREATE2 and in the constructor, it retrieves the address for the contract code from the storage of an external registry contract.  To upgrade, the contract is selfdestructed.</td>
<td>No delegatecall so this is the most gas efficient.</td>
<td>Complex, little adoption in the wild.</td>
<td>The selfdestruct opcode may be removed in the future.</td>
<td>Optimizooors, those who like living on the edge.</td>
<td>?</td>
<td>Yes</td>
<td>Yes, by removing self destruct from the upgrade.</td>
</tr>
</tbody>
</table>

Proxies Table

<h1 id="yaudit-proxies-research">yAudit Proxies Research</h1>
<p>In Web3, the <strong>Proxy</strong> or <strong>Proxy Delegate</strong> is a <a href="https://en.wikipedia.org/wiki/Delegation_pattern">delegation pattern</a> commonly used to introduce upgradability in smart contracts. While it can be extremely <em>powerful</em>, it is also <em>commonly misunderstood</em> - leading to incorrect implementations and security issues.</p>
<p>This research effort compiles proxy knowledge with the goal of improving the correctness of proxy implementations and providing a useful resource for security reviews of proxy contracts. By sharing knowledge, we hope to improve the security of smart contracts and the greater ecosystem.</p>
<h2 id="research-goals">Research Goals</h2>
<ul>
<li>Improve the correctness of proxy implementations</li>
<li>Provide useful resources for security reviews of proxy contracts</li>
<li>Share knowledge to improve smart contract security ecosystem</li>
</ul>
<h2 id="getting-started">Getting Started</h2>
<p>Browse the documentation using the sidebar navigation or use the search functionality to find specific topics.</p>
<h2 id="contributing">Contributing</h2>
<p>We welcome contributions from the community. If you have feedback, corrections, or would like to contribute to our research, please reach out through our official channels.</p>
<p>**<em>Research by <a href="https://twitter.com/bl4ckb1rd71">engn33r</a> and <a href="https://github.com/devtooligan">devtooligan</a> of <a href="https://yaudit.dev">yAudit</a>.</em></p>

proxies

<h1 id="proxy-identification-guide">Proxy Identification Guide</h1>
<h2 id="basic-delegatecall-proxy-identifiers">Basic delegatecall Proxy Identifiers</h2>
<ul>
<li>Does not need to follow EIP-1967. The proxy may instead use a regular storage variable to store the external contract address used with <code class="inline-code-block">delegatecall</code>.</li>
<li>May use <a href="https://eips.ethereum.org/EIPS/eip-1167">EIP-1167</a> minimal proxy bytecode. The bytecode for the Uniswap V1 proxy is <code class="inline-code-block">0x3660006000376110006000366000732157a7894439191e520825fe9399ab8655e0f7085af41558576110006000f3</code>. For example, see contract <a href="https://etherscan.io/address/0xa2881a90bf33f03e7a3f803765cd2ed5c8928dfb#code">0xa2881a90bf33f03e7a3f803765cd2ed5c8928dfb</a>.</li>
</ul>
<h2 id="transparent-proxy-tpp-identifiers">Transparent Proxy (TPP) Identifiers</h2>
<ul>
<li>The proxy contract fallback function will act differently if the admin (or similar privileged role) calls the contract, so look for an if statement in the proxy contract that checks if msg.sender is the admin. One example of a modifier to do this check is <a href="https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/proxy/transparent/TransparentUpgradeableProxy.sol#L45-L51">in the OpenZeppelin library</a>.</li>
<li>The proxy contract often has an upgrade function and a function to change the address of the proxy admin. These functions should be protected with an access control modifier.</li>
</ul>
<h2 id="uups-proxy-identifiers">UUPS Proxy Identifiers</h2>
<ul>
<li>Normally imports a contract with the letters "UUPS" <a href="https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/proxy/utils/UUPSUpgradeable.sol">from OpenZeppelin</a> or a similar library.</li>
<li>Contains an initialize function</li>
<li>May include the number 1822 in a comment of the contract or an imported contract (from <a href="https://eips.ethereum.org/EIPS/eip-1822">EIP-1822</a>, the UUPS EIP).</li>
</ul>
<h2 id="metamorphic-contract-identifiers">Metamorphic Contract Identifiers</h2>
<ul>
<li>Contains <code class="inline-code-block">selfdestruct</code> (or <code class="inline-code-block">delegatecall</code> to call <code class="inline-code-block">selfdestruct</code> in another contract) to allow the existing code to be removed and replaced by another contract that will be deployed at the same address.</li>
<li>Often does not have a <code class="inline-code-block">delegatecall</code></li>
<li>Contract was created with CREATE2 from another contract, not an EOA. You can find the creation transaction on etherscan (manually in the "Contract Creator" information field of etherscan or automatically with <a href="https://docs.etherscan.io/api-endpoints/contracts#get-contract-creator-and-creation-tx-hash">the etherscan API</a>).</li>
</ul>
<h2 id="diamond-proxy-identifiers">Diamond Proxy Identifiers</h2>
<ul>
<li>Most likely has contract names that include the words "diamond", "facet", "loupe".</li>
<li>Per the <a href="https://eips.ethereum.org/EIPS/eip-2535">EIP-2535</a> spec, the IDiamondLoupe interface must be implemented with these four functions: <code class="inline-code-block">facets()</code>, <code class="inline-code-block">facetFunctionSelectors(address _facet)</code>, <code class="inline-code-block">facetAddresses()</code>, <code class="inline-code-block">facetAddress(bytes4 _functionSelector)</code></li>
<li>The function which contains <code class="inline-code-block">delegatecall</code> will allow the user to specify an argument to identify the facet that should be called by delegatecall. This argument specifying the facet may not necessarily be a function argument but could, for example, be <code class="inline-code-block">msg.data</code>.</li>
</ul>

Proxy Identification Guide

Security Guide to Proxy Vulns

<h1 id="proxy-basics">Proxy Basics</h1>
<p><strong>Warning:</strong> this research assumes you are familiar with how <code class="inline-code-block">delegatecall</code> works and how the logic of the callee contract applies the caller's context. If you are unfamiliar with how <code class="inline-code-block">delegatecall</code> works, consult in-depth explanations such as <a href="https://medium.com/coinmonks/delegatecall-calling-another-contract-function-in-solidity-b579f804178c">this one</a>, <a href="https://blog.openzeppelin.com/ethereum-in-depth-part-1-968981e6f833/">this one</a>, or <a href="https://docs.soliditylang.org/en/latest/introduction-to-smart-contracts.html#delegatecall-and-libraries">this one</a>.</p>
<h2 id="why-do-i-need-a-proxy-and-how-do-i-use-it">Why do I need a proxy and how do I use it?</h2>
<p>By design, contract code on a blockchain is <strong>immutable</strong>. Though a key feature, it leads to difficulty when considering upgradeability. Newer entrants may wonder why "upgrading" on a blockchain is necessary. Inevitabilities requiring code changes still remain, including: bug fixes, patches, optimizations, feature releases, etc.</p>
<p>The <strong>Proxy</strong> or <strong>Proxy Delegate</strong> pattern allows for this upgradeability. Put simply, there are two main approaches for proxies:</p>
<ol>
<li>A lightweight, entry-point caller contract <code class="inline-code-block">A</code> to use the logic of a callee contract <code class="inline-code-block">B</code> through <code class="inline-code-block">delegatecall</code>:</li>
</ol>
<ul>
<li><code class="inline-code-block">A</code> stores the address of <code class="inline-code-block">B</code> in a state variable that can be changed.</li>
<li>If an upgrade is desired, a new callee contract <code class="inline-code-block">C</code> is deployed at a different address.</li>
<li><code class="inline-code-block">A</code> updates the state variable to point to the new callee contract, <code class="inline-code-block">C</code>.</li>
</ul>
<ol start="2">
<li>A factory contract <code class="inline-code-block">A</code> that creates a logic contract <code class="inline-code-block">B</code> with opcode <code class="inline-code-block">CREATE2</code>:</li>
</ol>
<ul>
<li><code class="inline-code-block">B</code> contains a <code class="inline-code-block">selfdestruct</code> to allow the contract to be destroyed.
<ul>
<li><em>Note: This is normally protected so only an admin or authorized account can call it.</em></li>
</ul>
</li>
<li>If an upgrade is desired, <code class="inline-code-block">B</code> is destroyed, and the factory can use <code class="inline-code-block">CREATE2</code> to deploy a new contract at the same address as <code class="inline-code-block">B</code>.</li>
</ul>
<p>Additional reading for the proxy pattern can be found <a href="https://docs.openzeppelin.com/upgrades-plugins/1.x/proxies">here</a>, and <a href="https://fravoll.github.io/solidity-patterns/proxy_delegate.html">here</a>.</p>
<h2 id="can-smart-contracts-be-upgraded-without-proxies">Can smart contracts be upgraded without proxies?</h2>
<p>Yes, contract logic can be designed in such a way to allow a protocol to be upgraded without using <code class="inline-code-block">delegatecall</code> or <code class="inline-code-block">CREATE2</code>. An alternative approach is called the "data separation" pattern in <a href="https://blog.trailofbits.com/2018/09/05/contract-upgrade-anti-patterns/">this Trail of Bits blog post</a> and another is <a href="https://blog.trailofbits.com/2018/10/29/how-contract-migration-works/">contract migration</a>.</p>
<h3 id="data-separation-pattern">Data Separation Pattern</h3>
<p>This pattern works by using a primary contract <code class="inline-code-block">A</code> to serve as the entry-point, and doesn't contain complex logic besides calling external contracts. Calls to external contracts <strong>only use</strong> <code class="inline-code-block">call</code>, <strong>not</strong> <code class="inline-code-block">delegatecall</code>.</p>
<p>Addresses of the external contracts are stored in state variables that have restrictive setter functions, allowing only the owner to ever mutate their state. This allows <code class="inline-code-block">A</code> to update the state variables to point to new contract addresses whenever an upgrade is desired.</p>
<p>One example of this "data separation pattern" reviewed by yAudit previously is <a href="https://github.com/fei-protocol/tribe-turbo/blob/main/src/TurboMaster.sol">Tribe Turbo</a>.</p>

← Back to Research

Proxy Basics

Why do I need a proxy and how do I use it?

Can smart contracts be upgraded without proxies?

Data Separation Pattern