How mudgen/diamond-2-hardhat works
Project type and purpose
• This is a Solidity/Hardhat reference implementation of the EIP-2535 “Diamond” proxy pattern.
• Its goal is to provide a gas-optimized diamondCut upgrade mechanism and standard “loupe” introspection functions for on-chain contracts.
File structure
Top-level directories and files:
• contracts/ – all Solidity source code
– Diamond.sol (core proxy contract)
– facets/ (each facet adds or exposes functions)
• DiamondCutFacet.sol (implements diamondCut)
• DiamondLoupeFacet.sol (implements loupe functions)
…
– interfaces/ (EIP-2535 standard interfaces)
– libraries/ (LibDiamond.sol: proxy storage & internal diamondCut)
– upgradeInitializers/ (DiamondInit.sol: state initialization)
• scripts/
– deploy.js (deploys and wires up Diamond, facets, initializers)
– libraries/diamond.js (helper for facet cuts)
• test/ – JavaScript tests exercising upgrade, loupe, selectors, payable behavior
• Hardhat config, package.json, license, README
README for architectural insights
• Describes a multi-contract proxy (“diamond”) pattern where one stable proxy contract (Diamond.sol) holds function selectors mapped to facet addresses.
• Explains deployment flow: deploy DiamondCutFacet → deploy Diamond (with owner & cut facet) → deploy DiamondInit → deploy other facets → call diamondCut (delegatecall into LibDiamond) + delegatecall into DiamondInit.
Detailed breakdown of components & interactions
1. Developer Machine (Hardhat CLI)
– runs deploy.js → calls JSON-RPC → deploys contracts
– runs test suite → simulates upgrades & introspection calls
2. Ethereum Node (Hardhat Network / Infura)
– accepts JSON-RPC from scripts & tests
3. Diamond Proxy (Diamond.sol linked with LibDiamond)
– stores mapping: selector → facet address
– fallback() forwards calls based on selector
4. DiamondCutFacet
– external diamondCut(...) on Diamond
– delegatecalls into LibDiamond to mutate storage
5. DiamondLoupeFacet
– read-only loupe functions for introspection
6. DiamondInit
– contains init() called via delegatecall during first upgrade
7. Additional Facets
– user’s own modules that implement business logic
8. Off-chain Clients
– use ABI of specific facets + Diamond address to call functions
– use loupe functions to discover available functions
Guideline summary:
• Critical patterns: “delegatecall → LibDiamond”, “diamondCut atomic upgrade”.
• Avoid over-simplification; show each major contract, script, and client interaction to reflect the boilerplate’s composable nature.