Diamonds

Contracts that use delegate calls to emulate upgradeability are called upgradeable proxies. In this quest, learn the basic upgradeable proxy pattern and implement your own upgradeable contract.

Basic Proxies

The factory pattern is a useful design pattern for organizing multiple instances of the same complex object. An advanced variant of this pattern is the clone factory, which uses minimal proxies to minimize the high gas cost required to initialize a new object.

In this quest, discover what the clone factory is and how it can be implemented.

Clone Factories

Having learned the notion and interacted with a diamond, it is time to implement one ourselves. Study the implementation of the basic diamond and add interesting functionality on top of it.

Building Diamonds

Diamond contracts use libraries unusually. Aside from standard library features, they embed state variables into their libraries. Discover how and why this is done.

Stateful Libraries

The sea is a harsh mistress, and the voyage has not been easy. In fact, it’s been the hardest sea voyage you’ve ever experienced. But now the true challenge awaits, for the terrifying Hydra will not be an easy foe to defeat. And if you fail, a watery grave awaits you…

The EIP-2535 interface standardizes the diamond ABI. This allows external parties like blockchain explorers and development tools to build diamond-friendly features. In this quest, be exposed to the interface and the introductory concept of the diamond.

It is best to prepare before the challenging the hydra. Let us do some preliminary reading.

Imagine you are programming a complex game on the EVM. You might want to implement several features (e.g. battle mechanics, trading, inventory, player stats, etc.). This would likely require a very large contract.

Writing big contracts on the EVM poses a few issues. For example:

There are several solutions to avoid huge monolithic contracts. We can use inheritance to organise code into 'layers'. Or we can use libraries to separate logic into external contracts. We can try to employ these solutions, but in their own ways, you will see that they have their imperfections.

EIP-2535 Diamonds offers a standardized pattern to emulate modular smart contracts. Diamonds are essentially proxy contracts with multiple implementation contracts (aka facets).

large_Diamonds.webp

medium_Diamonds.webp

small_Diamonds.webp

thumbnail_Diamonds.webp

Diamonds have several advantages over the previously suggested solutions:

Read the description above and what a diamond proxy is.

Understanding Diamonds

To go up against the sea monster, knowledge will be half the battle.

The Diamean Hydra is a contract that complies to the EIP-2535 Diamond standard. Like how a hydra has many heads, the Diamean Hydra has many facets.

One of its facets is a contract employing the ERC173 standard.

Claim ownership of the hydra to continue.

shieldWarning

Calling a Facet

Defend the ship against the onslaught of the great sea serpent.

We can add and remove specific functions from diamonds by using a <code class="richtext rt-inlinecode">DiamondCut</code> function. It could be smart to remove functions from the hydra that are dangerous to the ship.

Remove the following functions from the hydra to continue.

Removing a Function

The Diamean Hydra is too dangerous to be fought in a head-on battle. It must be weakened somehow.

To recap, we can add new functions onto a diamond by:

Using the diamond storage pattern, we would like to add the following state variables into the hydra contract.

Subsequently, we would like to add the following function to the hydra diamond.

By deploying and adding a facet into the hydra diamond:

Additionally, initialize the facet upon adding it by:

Adding Functions

The hydra has been weakened, but it still seems as vigorous as before. What if we give it a head that eats the surrounding fish to quell its hunger?

Fighting to concentrate as the creature strikes at your ship, you manage to cast an elaborate spell to give the Hydra yet another head, but this time one that has an inexhaustible appetite for the local sea life. Immediately, it dives into the ocean, gorging itself on the nearby schools of fish.

Within minutes you notice the difference. With its belly full, the Hydra becomes sluggish, its movements weaker. Not even the fabled Diamean Hydra is immune to the aftermath of a heavy meal.

Seize the opportunity and take the multi-headed serpent down!

The world is oddly quiet as the ocean begins to churn around you. You realize there is not a single seabird in sight as a feeling of trepidation permeates the salty air. The crew braces itself. 

Then there is an abrupt impact on the ship’s hull, sending it rocking to the side. You run to the railings and look in the direction the knock came from.

HYDRA COMING WINDWARD! HYDRA COMING WINDWARD!

From the swirling waters emerges a multitude of serpentine heads, each nearly as large as the ship. They twist overhead, sending a spray of salt water down upon you. The stench of rotted fish washes over you as the movement of the creature’s necks churn the seas and surround the ship. 

The crew rushes to their battle positions, losing and readying the ship’s cannons. You stand by Cap’n Fisheye, ready to do your part. This battle will be difficult but not impossible. 

Slay the Diamean Hydra, and return home safe!

Diamonds are proxy contracts with multiple logic contracts called facets. Compartmentalizing functionalities into separate contracts offers the following benefits:

In this quest, we have exposed ourselves to the core functionality of a basic diamond.

Diamond Cut functions are used to mutate the diamond’s functionality.

Diamond Loupe functions are used to inspect the diamond, with its available facets and functions.

We have also experimented with the diamond storage pattern. A diamond has multiple implementation contracts that might each have different state variables. To prevent these state variables from clashing, we can store them in designated regions in the storage state, generated by hashing a unique id string for each set of variables.

We have seen how to use diamonds and the functionality expected from them. Perhaps it is time to see how to implement one now.

Using Diamonds

prelude