Diamond Module

This module provides core internal functions and storage management for diamond proxies.

Key Features

• Provides functions for diamond proxy operations.
• Manages diamond storage using a dedicated storage slot ("erc8153.diamond").
• Supports facet registration and retrieval through internal mechanisms.

Storage

State Variables

Property	Type	Description
DIAMOND_STORAGE_POSITION	bytes32	Storage slot position for the diamond. Value: keccak256("erc8153.diamond")

Diamond Storage

Definition

/** storage-location: erc8042:erc8153.diamond */
struct DiamondStorage {
  mapping(bytes4 functionSelector => FacetNode) facetNodes;
  FacetList facetList;
}

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

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

Functions

getDiamondStorage

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

Returns:

Property	Type	Description
s	DiamondStorage	The DiamondStorage struct in storage.

---

addFacets

Registers one or more facets to a diamond. For each facet, selectors are discovered by calling exportSelectors(). Each selector is then mapped to the facet in diamond storage. Reverts if any selector is already registered on the diamond.

function addFacets(address[] memory _facets) ;

Parameters:

Property	Type	Description
_facets	address[]	The facet addresses to add. Each must implement IFacet and return selectors from exportSelectors().

---

importSelectors

Retrieves the function selectors exposed by a facet by calling its exportSelectors(). Validates the returned ABI-encoded bytes (offset, length, and that the payload length is a multiple of 4) and returns the packed selectors without copying (zero-copy decode). Used internally by addFacets.

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

Parameters:

Property	Type	Description
_facet	address	Contract address implementing exportSelectors() that returns ABI-encoded bytes of 4-byte function selectors.

Returns:

Property	Type	Description
selectors	bytes	Packed 4-byte function selectors (length is a multiple of 4). Same memory layout as returned by exportSelectors(); may point into the staticcall return buffer.

---

at

Returns the 4-byte function selector at the given index in a packed bytes array of selectors (e.g. from importSelectors or other selector packing).

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

Parameters:

Property	Type	Description
selectors	bytes	Packed array of 4-byte function selectors (length must be a multiple of 4).
index	uint256	Zero-based index of the selector to read (0 = first selector, 1 = second, etc.).

Returns:

Property	Type	Description
selector	bytes4	The function selector at the given index.

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 previously 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

Thrown by addFacets when a selector from one of the facets is already registered to another facet on the diamond.

Signature:

error CannotAddFunctionToDiamondThatAlreadyExists(bytes4 _selector);

Thrown when a selector is looked up in the diamond but has no facet registered (e.g. during delegatecall dispatch).

Signature:

error FunctionNotFound(bytes4 _selector);

Thrown by importSelectors when the staticcall to _facet.exportSelectors() fails.

Signature:

error FunctionSelectorsCallFailed(address _facet);

Thrown by importSelectors when the facet returns data that is not valid ABI-encoded bytes (e.g. wrong offset, length not a multiple of 4, or length exceeds payload).

Signature:

error IncorrectSelectorsEncoding(address _facet);

Thrown by importSelectors when _facet has no code (e.g. EOA or uninitialized contract).

Signature:

error NoBytecodeAtAddress(address _contractAddress);

Thrown by importSelectors when the facet returns fewer than 4 bytes of selectors (i.e. no valid selector).

Signature:

error NoSelectorsForFacet(address _facet);

Best Practices

• 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

This module interacts directly with the diamond's shared storage at the DIAMOND_STORAGE_POSITION, which is identified by keccak256("erc8153.diamond").

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