DiamondUpgradeMod

Upgrade diamond with add, replace, and remove functions

Key Features

• Manages facet additions, replacements, and removals within a diamond.
• Supports optional delegatecall for state modification or initialization during upgrades.
• Emits events for all function changes (DiamondFunctionAdded, DiamondFunctionReplaced, DiamondFunctionRemoved).
• Includes specific errors to prevent invalid upgrade operations.

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 functions to upgrade a diamond's facet implementations. It allows adding new functions, replacing existing ones, and removing functions entirely, all managed through diamond storage. The upgradeDiamond function orchestrates these changes, optionally performing a delegatecall for state modifications or initialization.

---

Storage

DiamondStorage

storage-location: erc8042:erc8109.diamond

Definition

struct DiamondStorage {
  mapping(bytes4 functionSelector => FacetAndPosition) facetAndPosition;
  /**
  * Array of all function selectors that can be called in the diamond
  */
  bytes4[] selectors;
}

---

FacetAndPosition

Data stored for each function selector Facet address of function selector Position of selector in the 'bytes4[] selectors' array

Definition

struct FacetAndPosition {
  address facet;
  uint32 position;
}

---

FacetFunctions

Definition

struct FacetFunctions {
  address facet;
  bytes4[] selectors;
}

State Variables

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

Functions

addFunctions

function addFunctions(address _facet, bytes4[] calldata _functionSelectors) ;

Parameters:

Property	Type	Description
_facet	address	-
_functionSelectors	bytes4[]	-

---

getDiamondStorage

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

---

removeFunctions

function removeFunctions(bytes4[] calldata _functionSelectors) ;

Parameters:

Property	Type	Description
_functionSelectors	bytes4[]	-

---

replaceFunctions

function replaceFunctions(address _facet, bytes4[] calldata _functionSelectors) ;

Parameters:

Property	Type	Description
_facet	address	-
_functionSelectors	bytes4[]	-

---

upgradeDiamond

Upgrade the diamond by adding, replacing, or removing functions. - _addFunctions maps new selectors to their facet implementations. - _replaceFunctions updates existing selectors to new facet addresses. - _removeFunctions removes selectors from the diamond. Functions added first, then replaced, then removed. These events are emitted to record changes to functions: - DiamondFunctionAdded - DiamondFunctionReplaced - DiamondFunctionRemoved If _delegate is non-zero, the diamond performs a delegatecall to _delegate using _functionCall. 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(
FacetFunctions[] calldata _addFunctions,
FacetFunctions[] calldata _replaceFunctions,
bytes4[] calldata _removeFunctions,
address _delegate,
bytes calldata _functionCall,
bytes32 _tag,
bytes calldata _metadata
) ;

Parameters:

Property	Type	Description
_addFunctions	FacetFunctions[]	Selectors to add, grouped by facet.
_replaceFunctions	FacetFunctions[]	Selectors to replace, grouped by facet.
_removeFunctions	bytes4[]	Selectors to remove.
_delegate	address	Optional contract to delegatecall (zero address to skip).
_functionCall	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 _functionCall);

Parameters:

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

Emitted when a function is added to a diamond.

Signature:

event DiamondFunctionAdded(bytes4 indexed _selector, address indexed _facet);

Parameters:

Property	Type	Description
_selector	bytes4	The function selector being added.
_facet	address	The facet address that will handle calls to _selector.

Emitted when a function is removed from a diamond.

Signature:

event DiamondFunctionRemoved(bytes4 indexed _selector, address indexed _oldFacet);

Parameters:

Property	Type	Description
_selector	bytes4	The function selector being removed.
_oldFacet	address	The facet address that previously handled _selector.

Emitted when changing the facet that will handle calls to a function.

Signature:

event DiamondFunctionReplaced(bytes4 indexed _selector, address indexed _oldFacet, address indexed _newFacet);

Parameters:

Property	Type	Description
_selector	bytes4	The function selector being affected.
_oldFacet	address	The facet address previously responsible for _selector.
_newFacet	address	The facet address that will now handle calls to _selector.

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.

Errors

Signature:

error CannotAddFunctionToDiamondThatAlreadyExists(bytes4 _selector);

Signature:

error CannotRemoveFunctionThatDoesNotExist(bytes4 _selector);

Signature:

error CannotRemoveImmutableFunction(bytes4 _selector);

Signature:

error CannotReplaceFunctionThatDoesNotExist(bytes4 _selector);

Signature:

error CannotReplaceFunctionWithTheSameFacet(bytes4 _selector);

Signature:

error CannotReplaceImmutableFunction(bytes4 _selector);

Signature:

error DelegateCallReverted(address _delegate, bytes _functionCall);

Signature:

error NoBytecodeAtAddress(address _contractAddress);

The functions below detect and revert with the following errors.

Signature:

error NoSelectorsProvidedForFacet(address _facet);

Best Practices

Best Practice

• Ensure the diamond's access control mechanism permits the caller to execute upgrade functions.
• Verify that _addFunctions, _replaceFunctions, and _removeFunctions do not conflict with immutable functions.
• Handle the DelegateCallReverted error if a delegatecall is performed and reverts.

Integration Notes

Shared Storage

This module interacts with diamond storage at DIAMOND_STORAGE_POSITION, identified by keccak256("erc8109.diamond"). The DiamondStorage struct, though empty in this definition, serves as the root for diamond state. Functions added, replaced, or removed by this module directly modify the diamond's function selector-to-facet mapping, making these changes immediately visible to all facets interacting with the diamond proxy.

Related Documentation

📦

DiamondMod

Related module in diamond

Was this helpful?

Last updated:December 30, 2025