Diamond Module

Internal functions and storage for diamond proxy functionality.

Key Features

• Exposes internal functions for diamond proxy operations.
• Manages diamond storage using a dedicated storage slot (DIAMOND_STORAGE_POSITION).
• Supports facet registration and retrieval through internal mechanisms.
• No external dependencies, ensuring minimal on-chain footprint.

Module Usage

This module provides internal functions for use in your custom facets. Import it to access shared logic and storage.

Overview

This module provides core internal functions and storage management for diamond proxies. It enables facets to interact with shared diamond storage and manage facet registrations. Changes made through this module are immediately visible to all facets utilizing the diamond storage pattern.

Storage

DiamondStorage

storage-location: erc8042:erc8153.diamond

Definition

struct DiamondStorage {
  mapping(bytes4 functionSelector => FacetNode) facetNodes;
  FacetList facetList;
}

---

FacetList

Definition

struct FacetList {
  bytes4 headFacetNodeId;
  bytes4 tailFacetNodeId;
  uint32 facetCount;
  uint32 selectorCount;
}

---

FacetNode

Definition

struct FacetNode {
  address facet;
  bytes4 prevFacetNodeId;
  bytes4 nextFacetNodeId;
}

State Variables

Property	Type	Description
DIAMOND_STORAGE_POSITION	bytes32	Diamond storage slot position for this module (Value: keccak256("erc8153.diamond"))

Functions

addFacets

function addFacets(address[] memory _facets) ;

Parameters:

Property	Type	Description
_facets	address[]	-

---

at

function at(bytes memory selectors, uint256 index) pure returns (bytes4 selector);

Parameters:

Property	Type	Description
selectors	bytes	-
index	uint256	-

---

diamondFallback

Find facet for function that is called and execute the function if a facet is found and return any value.

function diamondFallback() ;

---

getDiamondStorage

function getDiamondStorage() pure returns (DiamondStorage storage s);

---

importSelectors

function importSelectors(address _facet) view returns (bytes memory selectors);

Parameters:

Property	Type	Description
_facet	address	-

Events

Emitted when a diamond's constructor function or function from a facet makes a delegatecall.

Signature:

event DiamondDelegateCall(address indexed _delegate, bytes _delegateCalldata);

Parameters:

Property	Type	Description
_delegate	address	The contract that was delegatecalled.
_delegateCalldata	bytes	The function call, including function selector and any arguments.

Emitted to record information about a diamond. This event records any arbitrary metadata. The format of _tag and _data are not specified by the standard.

Signature:

event DiamondMetadata(bytes32 indexed _tag, bytes _data);

Parameters:

Property	Type	Description
_tag	bytes32	Arbitrary metadata, such as a release version.
_data	bytes	Arbitrary metadata.

Emitted when a facet is added to a diamond. The function selectors this facet handles can be retrieved by calling IFacet(_facet).exportSelectors()

Signature:

event FacetAdded(address indexed _facet);

Parameters:

Property	Type	Description
_facet	address	The address of the facet that handles function calls to the diamond.

Emitted when a facet is removed from a diamond. The function selectors this facet handles can be retrieved by calling IFacet(_facet).exportSelectors()

Signature:

event FacetRemoved(address indexed _facet);

Parameters:

Property	Type	Description
_facet	address	The address of the facet that previouly handled function calls to the diamond.

Emitted when an existing facet is replaced with a new facet. - Selectors that are present in the new facet but not in the old facet are added to the diamond. - Selectors that are present in both the new and old facet are updated to use the new facet. - Selectors that are not present in the new facet but are present in the old facet are removed from the diamond. The function selectors handled by these facets can be retrieved by calling: - IFacet(_oldFacet).exportSelectors() - IFacet(_newFacet).exportSelectors()

Signature:

event FacetReplaced(address indexed _oldFacet, address indexed _newFacet);

Parameters:

Property	Type	Description
_oldFacet	address	The address of the facet that previously handled function calls to the diamond.
_newFacet	address	The address of the facet that now handles function calls to the diamond.

Errors

Signature:

error CannotAddFunctionToDiamondThatAlreadyExists(bytes4 _selector);

Signature:

error FunctionNotFound(bytes4 _selector);

Signature:

error FunctionSelectorsCallFailed(address _facet);

Signature:

error IncorrectSelectorsEncoding(address _facet);

Signature:

error NoBytecodeAtAddress(address _contractAddress);

The upgradeDiamond function below detects and reverts with the following errors.

Signature:

error NoSelectorsForFacet(address _facet);

Best Practices

Best Practice

• Ensure that facet registration functions (like addFacets and importSelectors) are called only during diamond initialization or controlled upgrade processes.
• Verify that the DiamondStorage struct is correctly defined and that any new fields are added at the end to maintain storage compatibility.
• Handle custom errors such as CannotAddFunctionToDiamondThatAlreadyExists and NoSelectorsForFacet to ensure robust error management.

Integration Notes

Shared Storage

This module interacts directly with the diamond's shared storage at the DIAMOND_STORAGE_POSITION, which is identified by keccak256("erc8153.diamond"). The DiamondStorage struct, which includes a FacetList field, resides here. All functions within this module read from and write to this shared storage. Changes to the facetList or other storage elements are immediately visible to any facet that accesses the same storage slot.

Was this helpful?

Last updated:March 13, 2026