The Diamond Standard: A new paradigm for upgradeability

Ainsley Sutherland
Aug 26, 2020 · 6 min read

DerivaDEX is the first major project to implement the Diamond Standard, authored by Nick Mudge. We are extremely excited to have Nick as a smart contract advisor to DerivaDEX. The Diamond Standard is a pattern for upgradeability that overcomes existing limitations around storage and contract size, as well as provides exceptional modularity. We believe that the Diamond Standard will become the de-facto approach to smart contract upgradeability, an area which has not seen extensive improvement in several years. We also like our stack to be on the cutting edge ;).

image by Milky

→ Join us on Discord to ask questions and learn more about DerivaDEX!

A “diamond” is a contract that gets its external functions from other contracts (called “facets” in the standard). Any number of facets can be added to a diamond. After deployment, the DerivaDEX Diamond contract will have ownership of the DDX token contract, and the governance contract will be added to the diamond as a facet. Thus, additional facets can be added, removed, and modified in the future only via governance. We think this is exciting for several reasons:

  1. Safety & agility. We expect our code to be easier to read, and audit, due to the separation of concerns between different facets. Related to this, we also expect to be able to easily respond to new product requirements by extending functionality quickly and safely via facets.
  2. Community. Our facets will be reusable. Because of how Diamond Storage works, these facets are reusable contracts. We, and other projects, can use existing deployed facets to build new applications — cutting down on the cost and complexity involved in deploying new contracts.
  3. Transparency. The Diamond Standard brings excellent transparency to code used in diamonds and facets, providing a permission-less history of all upgrades and modifications to the attached logic contracts. This is critical for upgradeable contracts, and diamond contracts contain a history of all modifications made over time, as well as clearly describe all functions currently accessible to the diamond.

The Diamond Standard is new. For this reason, we’ve hired Trail of Bits to perform a security audit of the Diamond Standard contracts. Trail of Bits is a well-known and respected security firm, and we’re thrilled to have their insight. Trail of Bits’ findings will be made publicly available following the audit.

How DerivaDEX uses the Diamond Standard

  • The DerivaDEX Diamond owns the DDX token contract
  • The diamond also owns itself
  • Governance contracts and exchange- related contracts are added to the diamond as facets
  • The diamond can add, remove, and modify any of its facets via governance
The deployment flow for the DerivaDEX Diamond

As the above diagram illustrates, the process of launching the DerivaDEX Diamond contract involves first deploying both the token contract and the diamond contract. Then, ownership of the DDX token contract is transferred to the diamond. Next, governance contracts are added as facets to the diamond. Finally, ownership of the diamond is transferred to itself, making governance the sole method by which the diamond and its facets can be further modified. Any additional facets, such as the exchange-related contracts, can be added to (and removed from) the diamond via governance.

What are proxy contracts?

One of the features of smart contracts after they have been deployed on-chain is that they can’t be later upgraded. In many ways, this is a feature: a malicious upgrade could result in lost funds or other bad outcomes. However, it is also a deterrent to development. If a team wants to make an upgrade to a contract that is beneficial, how can they do that? Enter proxy contracts.

“Although it is not possible to upgrade the code of your already deployed smart contract, it is possible to set-up a proxy contract architecture that will allow you to use new deployed contracts as if your main logic had been upgraded.”

— Open Zeppelin

Many projects build in some form of contract upgradeability and extensibility, in order to meet new product requirements, extend functionality, or incorporate new technical capabilities. We are using the Diamond Standard to meet our needs for upgrades and modifications to the protocol.

Wait! Aren’t contracts supposed to be immutable?

Sometimes immutability is good, and sometimes what you really need is transparency. Transparency can ensure, for example, that only non-malicious and tested upgrades take place. Transparency can be achieved via controlling all upgrades with governance. In order for an upgrade to take place, a change must be proposed and then voted into production.

Importantly these decisions aren’t permanent: if it ever becomes necessary to end upgradeability for a contract, that functionality can be removed. A diamond that includes the diamondCut function is upgradeable. If that function (and other functions that can add, replace, or remove functions) are removed, a diamond can no longer be upgraded.

What is the Diamond Standard?

The Diamond Standard proposes that a diamond (similar to a proxy contract) is upgraded by adding and removing facets. These facets extend contract functionality in a very granular and modular way. A single upgrade can add/remove multiple functions in the same transaction. Additionally, each facet can be reusable, thanks to Diamond Storage. We mentioned above some of the key reasons we’re excited about using the Diamond Standard, and we’ll go into greater detail now.

Safety and agility

The core contract (known as the diamond) is similar to a “proxy contract”. In the Diamond Standard, individual diamonds are upgraded via adding and removing facets. Each facet can contain code related to a specific domain: for example, one facet could control trading competition rewards. Another facet could contain all code relating to an insurance fund staking program. By restricting relevant code to a facet, we create a modular and logically separated codebase. This means that our code will be more legible. It also means that we’re more able to easily modify and upgrade the protocol simply by adding a facet. This type of agility means we can bridge the positive elements of decentralized applications (like transparency), with a responsive and adaptable approach to product.


Due to Diamond Storage, and the modular nature of facets, each facet can be reused. If we deploy a facet to be used by the DerivaDEX Diamond, it can also be used by other diamonds, without needing to be re-deployed. DerivaDEX and other projects can all use the same facet, once deployed. This both enables us to bootstrap and build resources for a community of Diamond Standard users, as well as reduce the costs associated with deploying contracts (as each facet need only be deployed once).

Additionally, we’re backing an in-depth audit of the Diamond Standard, and plan for findings to be released publicly. Our goal is to help foster adoption and bring down the cost of security for other projects.


Upgradeability is treated as a “necessary evil” in decentralized applications. We appreciate that the Diamond Standard provides a “spectrum” of immutability. It will be possible to “freeze” a diamond at some point and end upgradeability, if that is what the community desires. However, we’re even more excited about the transparency the Diamond Standard builds in. To define this more clearly: what we mean when we say transparency is a permission-less history of all upgrades and modifications to the attached logic contracts (accomplished via the events that must be emitted by a diamondCut function). The DiamondLoupe facet can enable users to see at a glance what functions are enabled by a diamond and its facets. A record of all modifications is maintained and visible, thus managing trust via transparency.

We’re delighted to share this background with our community, and hope that our analysis is helpful to other projects curious about the Diamond Standard. We also hope this sheds some light on how we’re approaching upgradeability at DerivaDEX.

If you’re interested in helping us test our product, sign up to be first in line for DerivaDEX’s testnet competitions, insurance mining, and other opportunities pre-launch!

DDX enables users to participate in the governance and operations of the exchange. It is not a fundraising device nor an investment opportunity. U.S. residents will be blocked from trading.

We’re on Discord!

Further reading:


Next generation of derivatives trading