This is a simple example implementation for EIP-2535 Diamond Standard. To learn about other implementations go here: https://github.com/mudgen/diamond
The standard loupe functions have been gas-optimized in this implementation and can be called in on-chain transactions. However keep in mind that a diamond can have any number of functions and facets so it is still possible to get out-of-gas errors when calling loupe functions. Except for the facetAddress loupe function which has a fixed gas cost.
- Clone this repo:
git clone https://github.com/Timidan/diamond-3-hardhat.git- Install NPM packages:
cd diamond-3-hardhat
npm install or yarn installnpx hardhat run scripts/deploy.tsnpx hardhat testCheck the scripts/deploy.ts and or the test/diamondTest.ts file for examples of upgrades.
Note that upgrade functionality is optional. It is possible to deploy a diamond that can't be upgraded, which is a 'Single Cut Diamond'. It is also possible to deploy an upgradeable diamond and at a later date remove its diamondCut function so it can't be upgraded any more.
Note that any number of functions from any number of facets can be added/replaced/removed on a diamond in a single transaction. In addition an initialization function can be executed in the same transaction as an upgrade to initialize any state variables required for an upgrade. This 'everything done in a single transaction' capability ensures a diamond maintains a correct and consistent state during upgrades.
The contracts/Diamond.sol file shows an example of implementing a diamond.
The contracts/facets/DiamondCutFacet.sol file shows how to implement the diamondCut external function.
The contracts/facets/DiamondLoupeFacet.sol file shows how to implement the four standard loupe functions.
The contracts/libraries/LibDiamond.sol file shows how to implement Diamond Storage and a diamondCut internal function.
The scripts/deploy.ts file shows how to deploy a diamond.
The test/diamondTest.ts file gives tests for the diamondCut function and the Diamond Loupe functions.
-
Reading and understand EIP-2535 Diamonds. If something is unclear let me know!
-
Use a diamond reference implementation. You are at the right place because this is the README for a diamond reference implementation.
This diamond implementation is boilerplate code that makes a diamond compliant with EIP-2535 Diamonds.
Specifically you can copy and use the DiamondCutFacet.sol and DiamondLoupeFacet.sol contracts. They implement the diamondCut function and the loupe functions.
The Diamond.sol contract could be used as is, or it could be used as a starting point and customized. This contract is the diamond. Its deployment creates a diamond. It's address is a stable diamond address that does not change.
The LibDiamond.sol library could be used as is. It shows how to implement Diamond Storage. This contract includes contract ownership which you might want to change if you want to implement DAO-based ownership or other form of contract ownership. Go for it. Diamonds can work with any kind of contract ownership strategy. This library contains an internal function version of diamondCut that can be used in the constructor of a diamond or other places.
In order to call a function that exists in a diamond you need to use the ABI information of the facet that has the function.
Here is an example that uses ethers.js:
let myUsefulFacet = await ethers.getContract(facetName,diamondDeployedAddress) as facetNameType;string result = MyUsefulFacet(address(diamondContract)).getResult()If you need help or would like to discuss diamonds then send me a message on twitter, or email me. Or join the EIP-2535 Diamonds Discord server.
- Introduction to the Diamond Standard, EIP-2535 Diamonds
- EIP-2535 Diamonds
- Understanding Diamonds on Ethereum
- Solidity Storage Layout For Proxy Contracts and Diamonds
- New Storage Layout For Proxy Contracts and Diamonds
- Upgradeable smart contracts using the Diamond Standard
- buidler-deploy supports diamonds
This example implementation was written by Nick Mudge.
Contact:
MIT license. See the license file. Anyone can use or modify this software for their purposes.