# mudgen/diamond-2-hardhat architecture

> Architecture diagram of the GitHub repository mudgen/diamond-2-hardhat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mudgen/diamond-2-hardhat
- Repository: https://github.com/mudgen/diamond-2-hardhat

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Development Tools"
    Dev["Developer Machine (Hardhat CLI)"]:::dev
    DeployScript["deploy.js"]:::dev
    FacetHelper["diamond.js"]:::dev
    DiamondTest["diamondTest.js"]:::dev
    PayableTest["payableSelectorBugTest.js"]:::dev
    CacheBugTest["cacheBugTest.js"]:::dev
    HardhatConfig["hardhat.config.js"]:::dev
    Package["package.json & package-lock.json"]:::dev
    Readme["README.md"]:::dev
  end

  subgraph "Deployment Infrastructure"
    Node["Ethereum Node (Hardhat Network / Infura)"]:::deploy
  end

  subgraph "On-chain Components"
    subgraph "Core Proxy"
      DiamondProxy["Diamond Proxy (Diamond.sol)"]:::core
      LibDiamond["LibDiamond (library)"]:::lib
    end
    subgraph "Facets"
      DiamondCutFacet["DiamondCutFacet"]:::facet
      DiamondLoupeFacet["DiamondLoupeFacet"]:::facet
      AdditionalFacets["Additional Facets"]:::facet
    end
    DiamondInit["DiamondInit"]:::init
    Interfaces["EIP-2535 Interfaces"]:::core
  end

  subgraph "Off-chain Clients"
    OffClients["Web3.js / Ethers.js Clients"]:::offclient
  end

  Dev -->|runs| DeployScript
  Dev -->|runs| FacetHelper
  Dev -->|runs| DiamondTest
  Dev -->|runs| PayableTest
  Dev -->|runs| CacheBugTest
  Dev -->|reads| HardhatConfig
  Dev -->|reads| Package
  Dev -->|reads| Readme

  DeployScript -->|calls JSON-RPC| Node
  FacetHelper -->|used by| DeployScript
  DiamondTest -->|calls JSON-RPC| Node
  PayableTest -->|calls JSON-RPC| Node
  CacheBugTest -->|calls JSON-RPC| Node

  DeployScript -->|deploys| DiamondProxy
  DeployScript -->|deploys| DiamondCutFacet
  DeployScript -->|deploys| DiamondInit
  DeployScript -->|deploys| DiamondLoupeFacet
  DeployScript -->|deploys| AdditionalFacets

  DiamondProxy -->|links at compile time| LibDiamond
  DiamondCutFacet -->|delegatecall diamondCut| DiamondProxy
  DiamondInit -->|delegatecall init| DiamondProxy
  DiamondProxy -->|fallback forward| DiamondCutFacet
  DiamondProxy -->|fallback forward| DiamondLoupeFacet
  DiamondProxy -->|fallback forward| AdditionalFacets
  OffClients -->|invoke loupe| DiamondProxy

  click DiamondProxy "https://github.com/mudgen/diamond-2-hardhat/blob/main/contracts/Diamond.sol"
  click DiamondCutFacet "https://github.com/mudgen/diamond-2-hardhat/blob/main/contracts/facets/DiamondCutFacet.sol"
  click DiamondLoupeFacet "https://github.com/mudgen/diamond-2-hardhat/blob/main/contracts/facets/DiamondLoupeFacet.sol"
  click AdditionalFacets "https://github.com/mudgen/diamond-2-hardhat/tree/main/contracts/facets/"
  click Interfaces "https://github.com/mudgen/diamond-2-hardhat/tree/main/contracts/interfaces/"
  click LibDiamond "https://github.com/mudgen/diamond-2-hardhat/blob/main/contracts/libraries/LibDiamond.sol"
  click DiamondInit "https://github.com/mudgen/diamond-2-hardhat/blob/main/contracts/upgradeInitializers/DiamondInit.sol"
  click DeployScript "https://github.com/mudgen/diamond-2-hardhat/blob/main/scripts/deploy.js"
  click FacetHelper "https://github.com/mudgen/diamond-2-hardhat/blob/main/scripts/libraries/diamond.js"
  click DiamondTest "https://github.com/mudgen/diamond-2-hardhat/blob/main/test/diamondTest.js"
  click PayableTest "https://github.com/mudgen/diamond-2-hardhat/blob/main/test/payableSelectorBugTest.js"
  click CacheBugTest "https://github.com/mudgen/diamond-2-hardhat/blob/main/test/cacheBugTest.js"
  click HardhatConfig "https://github.com/mudgen/diamond-2-hardhat/blob/main/hardhat.config.js"
  click Package "https://github.com/mudgen/diamond-2-hardhat/blob/main/package.json"
  click Package "https://github.com/mudgen/diamond-2-hardhat/blob/main/package-lock.json"
  click Readme "https://github.com/mudgen/diamond-2-hardhat/blob/main/README.md"

  classDef dev fill:#f9f,stroke:#333,stroke-width:1px
  classDef deploy fill:#ff9,stroke:#333,stroke-width:1px
  classDef core fill:#9f9,stroke:#333,stroke-width:1px
  classDef facet fill:#9cf,stroke:#333,stroke-width:1px
  classDef lib fill:#fc9,stroke:#333,stroke-width:1px
  classDef init fill:#c9f,stroke:#333,stroke-width:1px
  classDef offclient fill:#cff,stroke:#333,stroke-width:1px
```
