Diamonds

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.

Understanding Diamonds

Calling a Facet

Removing a Function

Adding Functions

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

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.