About EIP-2535 Diamonds
High-level overview of EIP-2535 Diamonds
Overview
EIP-2535 Diamonds is a contract standard that standardizes contract interfaces and implementation details to implement the diamond pattern. The standardization makes integration with tools and other software possible.
The diamond pattern is a contract that uses a fallback function to delegate function calls to multiple other contracts called facets. Conceptually a diamond can be thought of as a contract that gets its external functions from other contracts. A diamond has four standard functions (called the loupe) that report what functions and facets a diamond has. A diamond has a DiamondCut event that reports all functions/facets that are added/replaced/removed on a diamond, making upgrades on diamonds transparent.
The diamond pattern is a code implementation and organization strategy. The diamond pattern makes it possible to implement a lot of contract functionality that is compartmented into separate areas of functionality, but still using the same Ethereum address. The code is further simplified and saves gas because state variables are shared between facets.
Diamonds are not limited by the maximum contract size which is 24KB.
Facets can be deployed once and reused by any number of diamonds.
Diamonds can be upgradeable or immutable. They can be upgradeable and at a later date become immutable. Diamonds support fine-grained upgrades which means it is possible to add/replace/remove only the parts desired. Everything does not have to be redeployed in order to make a change. A diamond does not solve all upgrade issues and problems but makes some things easier and better.
See the standard and the standard's reference section for more information about diamonds.
Aavegotchi Diamond
Aavegotchi is implemented with the AavegotchiDiamond contract. It is a diamond that implements EIP-2535 Diamond Standard.
When deployed AavegotchiDiamond adds all the external functions from all the facets listed in the documentation to itself.
AavegotchiDiamond provides a single Ethereum address for Aavegotchi functionality. All contract interaction with Aavegotchis is done with AavegotchiDiamond.
Information about the AavegotchiDiamond can be seen in louper.dev, a user interface for diamonds.
Facets
A facet is a contract whose external functions are added to a diamond to give the diamond functionality.
All the functions from the facets documented on this website, such as AavegotchiFacet, CollateralFacet, ItemsFacet etc, are added to AavegotchiDiamond when it is deployed.
The external functions defined in the facets can be called on the AavegotchiDiamond Ethereum address.
Facets that are added to the same diamond can share the same state variables.
Loupe Functions
In the diamond industry a loupe is a small magnifying glass used to look at diamonds.
To find out what functions and facets the AavegotchiDiamond has the loupe functions can be called.
The
facetAddresses()function returns all the Ethereum addresses of all facets used by a diamond.The
facetFunctionSelectors(address _facet)function is used to return all the 4-byte function selectors of a facet that is used by a diamond. The 4-byte function selectors and the ABI of a facet are used to get the function names and arguments.The
facetAddress(bytes4 _functionSelector)function returns the facet address used by a diamond for the 4-byte function selector that is provided.The
facets()function returns all the facet addresses and function selectors used by a diamond.
Loupe Resources:
Upgradeability
EIP-2535 Diamond Standard specifies the diamondCut function to upgrade diamonds.
The diamondCut function can be used to add and/or replace and/or remove any number of functions in a single transactions. This enables a number of specific changes to occur at the same time which prevents a diamond from getting into a bad or inconsistent state.
Anytime functions are added/replaced/removed the DiamondCut event is emitted. This provides a historical and transparent record of all changes to a diamond over time.
The standard does allow custom upgrade functions to be implemented for diamonds. But in any case the DiamondCut event must be emitted for all functions that are added, replaced or removed.
AavegotchiDiamond is upgradeable and has the standard diamondCut function. It has no custom upgrade functions. See the governance section about upgrading AavegotchiDiamond.
Last updated