Diamond Upgrade Module

Upgrade diamond by adding, replacing, or removing facets

Key Features

• Supports adding, replacing, and removing facets on a diamond.
• Emits FacetAdded, FacetReplaced, and FacetRemoved events for upgrade tracking.
• Optionally executes a delegatecall for complex initialization or state manipulation.
• Emits DiamondMetadata for tagged upgrades and associated data.

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 functions for managing diamond facets, enabling upgrades according to ERC-2535 and ERC-8153. It allows adding new facets, replacing existing ones, and removing facets. State changes are managed through diamond storage, ensuring visibility across all facets. Optionally, it supports delegate calls for complex initialization or state modifications during upgrades.

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;
}

---

FacetReplacement

This struct is used to replace old facets with new facets.

Definition

struct FacetReplacement {
  address oldFacet;
  address newFacet;
}

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[] calldata _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	-

---

getDiamondStorage

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

---

importSelectors

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

Parameters:

Property	Type	Description
_facet	address	-

---

removeFacets

function removeFacets(address[] calldata _facets) ;

Parameters:

Property	Type	Description
_facets	address[]	-

---

replaceFacets

function replaceFacets(FacetReplacement[] calldata _replaceFacets) ;

Parameters:

Property	Type	Description
_replaceFacets	FacetReplacement[]	-

---

upgradeDiamond

Upgrade the diamond by adding, replacing, or removing facets. Facets are added first, then replaced, then removed. These events are emitted to record changes to facets: - FacetAdded(address indexed _facet) - FacetReplaced(address indexed _oldFacet, address indexed _newFacet) - FacetRemoved(address indexed _facet) If _delegate is non-zero, the diamond performs a delegatecall to _delegate using _delegateCalldata. The DiamondDelegateCall event is emitted. The delegatecall is done to alter a diamond's state or to initialize, modify, or remove state after an upgrade. However, if _delegate is zero, no delegatecall is made and no DiamondDelegateCall event is emitted. If _tag is non-zero or if _metadata.length > 0 then the DiamondMetadata event is emitted.

function upgradeDiamond(
address[] calldata _addFacets,
FacetReplacement[] calldata _replaceFacets,
address[] calldata _removeFacets,
address _delegate,
bytes calldata _delegateCalldata,
bytes32 _tag,
bytes calldata _metadata
) ;

Parameters:

Property	Type	Description
_addFacets	address[]	Facets to add.
_replaceFacets	FacetReplacement[]	(oldFacet, newFacet) pairs, to replace old with new.
_removeFacets	address[]	Facets to remove.
_delegate	address	Optional contract to delegatecall (zero address to skip).
_delegateCalldata	bytes	Optional calldata to execute on _delegate.
_tag	bytes32	Optional arbitrary metadata, such as release version.
_metadata	bytes	Optional arbitrary data.

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

Signature:

error CannotAddFunctionToDiamondThatAlreadyExists(bytes4 _selector);

Signature:

error CannotRemoveFacetThatDoesNotExist(address _facet);

Signature:

error CannotReplaceFacetWithSameFacet(address _facet);

This error means that a function to replace exists in a facet other than the facet that was given to be replaced.

Signature:

error CannotReplaceFunctionFromNonReplacementFacet(bytes4 _selector);

Signature:

error DelegateCallReverted(address _delegate, bytes _delegateCalldata);

Signature:

error ExportSelectorsCallFailed(address _facet);

Signature:

error FacetToReplaceDoesNotExist(address _oldFacet);

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 the caller possesses the necessary permissions to perform diamond upgrades.
• Carefully review the _delegate and _delegateCalldata parameters to prevent unintended state changes or reentrancy risks during delegate calls.
• Verify that facet bytecode exists at the provided addresses before attempting to add or replace them to avoid NoBytecodeAtAddress errors.

Integration Notes

Shared Storage

This module interacts with the diamond's central storage, identified by DIAMOND_STORAGE_POSITION and conceptually mapped to keccak256(\"erc8153.diamond\"). It modifies the facetList within the DiamondStorage struct. Changes made through upgradeDiamond, addFacets, replaceFacets, and removeFacets are immediately visible to all facets that access this shared storage. The upgradeDiamond function orchestrates the sequence of operations: additions, then replacements, then removals.

Was this helpful?

Last updated:March 13, 2026