A modern implementation of the EIP-2535 Diamond Standard using Hardhat v3 and Viem
- Overview
- Features
- Architecture
- Quick Start
- Project Structure
- Usage Guide
- Testing
- Diamond Upgrading
- Contributing
- Resources
This repository provides a production-ready implementation of the EIP-2535 Diamond Standard, also known as the "Multi-Facet Proxy" pattern. Diamonds enable smart contracts to exceed the 24KB bytecode limit while providing fine-grained upgradeability control.
- 🚀 Gas Optimized: Loupe functions optimized for on-chain transactions
- 🔧 Modern Stack: Built with Hardhat v3, Viem, and TypeScript
- 📦 Modular Design: Easy to add, replace, or remove functionality
- 🛡️ Battle Tested: Comprehensive test coverage for all diamond operations
- ⚡ Fast Development: Uses pnpm package manager for blazing fast builds
- EIP-2535 Compliant: Full implementation of the Diamond Standard
- Loupe Functions: All four standard loupe functions included
- Role-Based Access Control: Advanced permission system with multiple roles
- TypeScript Support: Full type safety for scripts and tests
- Gas Efficient: Optimized storage patterns and function selectors
- Flexible Upgrades: Add, replace, or remove functions in a single transaction
┌─────────────────────────────────────────────────────────────┐
│ User/DApp │
└──────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Diamond Proxy │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Fallback Function │ │
│ │ (Delegates to Facet Functions) │ │
│ └─────────────────────────────────────────────────────┘ │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ DiamondCut │ │ DiamondLoupe │ │ Roles │
│ Facet │ │ Facet │ │ Facet │
└──────────────┘ └──────────────┘ └──────────────┘
│
┌────────┴────────┐
▼ ▼
┌──────────────┐ ┌──────────────┐
│ Custom Facet │ │ Custom Facet │
│ #1 │ │ #2 │
└──────────────┘ └──────────────┘
# Clone the repository
git clone git@github.com:xxxijustwei/erc2535-hardhat.git
cd erc2535-hardhat
# Install dependencies
pnpm installerc2535-hardhat/
│
├── 📁 contracts/ # Smart contracts
│ ├── 💎 Diamond.sol # Main diamond proxy contract
│ ├── 📁 facets/ # Facet implementations
│ │ ├── DiamondCutFacet.sol # Diamond upgrade functions facet
│ │ ├── DiamondLoupeFacet.sol # Introspection functions facet
│ │ ├── RoleFacet.sol # Role-based access control facet
│ │ ├── Test1Facet.sol # Test1 facet (for testing)
│ │ └── Test2Facet.sol # Test2 facet (for testing)
│ ├── 📁 interfaces/ # Contract interfaces
│ │ ├── IDiamondCut.sol # Diamond cut interface
│ │ ├── IDiamondLoupe.sol # Diamond loupe interface
│ │ └── IERC165.sol # ERC165 interface
│ ├── 📁 libraries/ # Shared libraries
│ │ ├── LibDiamond.sol # Diamond storage and helpers
│ │ └── LibAccessControl.sol # Role-based access control storage
│ └── 📁 upgradeInitializers/ # Initialization contracts
│ └── DiamondInit.sol # Diamond initialization logic
│
├── 📁 ignition/ # Hardhat Ignition deployment
│ └── 📁 modules/
│ └── diamond.ts # Diamond deployment module
│
├── 📁 scripts/ # Deployment scripts and utilities
│ ├── deploy.ts # Programmatic deployment script
│ └── utils.ts # Helper functions (selectors, etc.)
│
├── 📁 test/ # Test suite
│ ├── cacheBug.test.ts # Cache bug tests
│ ├── diamond.test.ts # Comprehensive diamond tests
│ └── rbac.test.ts # Role-based access control tests
│
├── ⚙️ hardhat.config.ts # Hardhat configuration
├── 📦 package.json # Dependencies
├── 📝 biome.json # Biome linter configuration
└── 📝 README.md # This file
This project supports two deployment methods:
Use ignition/modules/diamond.ts for declarative, reproducible deployments:
# Deploy to local network
npx hardhat ignition deploy ignition/modules/diamond.ts
# Deploy to specific network
npx hardhat ignition deploy ignition/modules/diamond.ts --network <network-name>Use scripts/deploy.ts for more control over the deployment process:
npx hardhat run scripts/deploy.ts --network <network-name>Both methods follow the same deployment flow:
- Deploy DiamondCutFacet - Provides the
diamondCutfunction for upgrades - Deploy Diamond - Creates the main proxy with owner and DiamondCutFacet address
- Deploy DiamondInit - Initialization contract for setting initial state
- Deploy Facets - Deploy additional facets (DiamondLoupeFacet, RoleFacet, etc.)
- Execute diamondCut - Add all facet functions to the diamond and call init function in one transaction
// contracts/facets/MyFacet.sol
contract MyFacet {
// Using diamond storage pattern
bytes32 constant STORAGE_POSITION = keccak256("my.facet.storage");
struct MyStorage {
uint256 value;
mapping(address => bool) users;
}
function getStorage() internal pure returns (MyStorage storage ms) {
bytes32 position = STORAGE_POSITION;
assembly {
ms.slot := position
}
}
function setValue(uint256 _value) external {
MyStorage storage ms = getStorage();
ms.value = _value;
}
}import { getContractAt } from "@nomicfoundation/hardhat-viem";
// Get diamond instance with specific facet ABI
const diamondAddress = "0x...";
const myFacet = await getContractAt("MyFacet", diamondAddress);
// Call function through diamond proxy
const tx = await myFacet.setValue(42);
await tx.wait();Run the comprehensive test suite:
# Run all tests
pnpm test
# Run all tests with coverage
pnpm test --coverage
# Run all tests with gas stats
pnpm test --gas-stats
# Run specific test file
pnpm test test/diamond.test.ts- ✅ Diamond deployment
- ✅ Facet addition/replacement/removal
- ✅ Function selector management
- ✅ Loupe function queries
- ✅ Role-based access control
- ✅ Initialization patterns
- ✅ Edge cases and error handling
const { request } = await publicClient.simulateContract({
address: diamondAddress,
abi: dCutFacet.abi,
functionName: "diamondCut",
args: [
[
{
facetAddress: facet.address,
action: FacetCutAction.Add,
functionSelectors: selectors,
},
],
zeroAddress,
zeroHash,
],
});
const tx = await walletClient.writeContract(request);
await publicClient.waitForTransactionReceipt({ hash: tx });const { request } = await publicClient.simulateContract({
address: diamondAddress,
abi: dCutFacet.abi,
functionName: "diamondCut",
args: [
[
{
facetAddress: addr,
action: FacetCutAction.Replace,
functionSelectors: selectors,
},
],
zeroAddress,
zeroHash,
],
});
const tx = await walletClient.writeContract(request);
await publicClient.waitForTransactionReceipt({ hash: tx });const { request } = await publicClient.simulateContract({
address: diamondAddress,
abi: dCutFacet.abi,
functionName: "diamondCut",
args: [
[
{
facetAddress: zeroAddress,
action: FacetCutAction.Remove,
functionSelectors: selectors,
},
],
zeroAddress,
zeroHash,
],
});
const tx = await walletClient.writeContract(request);
await publicClient.waitForTransactionReceipt({ hash: tx });- ⚡ All changes happen in a single transaction
- 🔒 Optional upgrade functionality (can create immutable diamonds)
- 🎯 Initialization function can be called during upgrades
- ✨ Maintains consistent state throughout the upgrade process
The Diamond Storage pattern allows facets to share storage without conflicts:
library LibAppStorage {
bytes32 constant STORAGE_POSITION = keccak256("app.storage");
struct AppStorage {
uint256 totalSupply;
mapping(address => uint256) balances;
address admin;
}
function appStorage() internal pure returns (AppStorage storage ds) {
bytes32 position = STORAGE_POSITION;
assembly {
ds.slot := position
}
}
}- 🔐 Access Control: Role-based system protects critical functions
- 🛡️ Facet Validation: Verify facet addresses before adding
⚠️ Selector Clashes: Ensure no function selector conflicts- 🔍 Audit Trail: Log all diamond upgrades for transparency
We welcome contributions! Please follow these steps:
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
- Write comprehensive tests for new features
- Follow existing code style and conventions
- Update documentation as needed
- Ensure all tests pass before submitting PR
- 📝 Introduction to the Diamond Standard
- 🎓 Understanding Diamonds on Ethereum
- 🔧 Solidity Storage Layout For Proxy Contracts
- 💡 Upgradeable Smart Contracts Guide
- Nick Mudge - Original Implementation - @mudgen
- xxxijustwei - Hardhat v3 Migration - @xxxijustwei