Diamond Upgrade Module

Module providing the internal functions to extend the diamond's upgrade functionality by adding, replacing, or removing facets.

Key Features

• Manages facet lifecycle (add, replace, remove) within a diamond.
• Updates selector routing so subsequent calls dispatch to the new facet.
• Emits events for all facet changes and any post-upgrade delegatecall.
• Emits DiamondMetadata for tagged upgrades and associated data.

Module Usage

Import this module into facets or shared setup code. Its functions are internal (including Solidity file-level helpers). Use them through your facet’s external entrypoints.

Storage follows the diamond slot layout in this file; any code using the same STORAGE_POSITION or related positions reads and writes shared state.

See Facets & Modules for more information.

Storage

State Variables

Property	Type	Description
DIAMOND_STORAGE_POSITION	bytes32	Diamond storage slot position for this module (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;
}

---

FacetReplacement

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

Definition

struct FacetReplacement {
  address oldFacet;
  address newFacet;
}

Functions

getDiamondStorage

Returns a pointer to the module's diamond storage layout.

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

---

upgradeDiamond

Upgrade the diamond by adding, replacing, and/or removing facets.

Execution order is always:

1. addFacets(_addFacets)
2. replaceFacets(_replaceFacets)
3. removeFacets(_removeFacets)

Then, if _delegate != address(0), the diamond performs a delegatecall to _delegate with _delegateCalldata and emits DiamondDelegateCall.

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

Parameters:

Property	Type	Description
_addFacets	address[]	Facet addresses to add
_replaceFacets	FacetReplacement[]	(oldFacet, newFacet) pairs to replace
_removeFacets	address[]	Facet addresses to remove
_delegate	address	Optional contract to delegatecall (address(0) to skip)
_delegateCalldata	bytes	Optional calldata to execute on _delegate
_tag	bytes32	Optional arbitrary metadata, such as release version
_metadata	bytes	Optional arbitrary metadata

---

addFacets

Adds new facets to a diamond and maps their exported selectors to the facet address.

function addFacets(address[] calldata _facets);

Parameters:

Property	Type	Description
_facets	address[]	Facet addresses to add. Each facet must implement exportSelectors().

---

removeFacets

Removes facets from a diamond and unregisters the selectors they previously exported.

function removeFacets(address[] calldata _facets);

Parameters:

Property	Type	Description
_facets	address[]	Facet addresses to remove.

---

replaceFacets

Replaces facets in a diamond using (oldFacet, newFacet) pairs.

function replaceFacets(FacetReplacement[] calldata _replaceFacets);

Parameters:

Property	Type	Description
_replaceFacets	FacetReplacement[]	(oldFacet, newFacet) pairs to replace old with new.

---

at

Reads the selector at index from a packed bytes array of selectors.

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.

---

importSelectors

Discovers the function selectors exposed by _facet by calling its exportSelectors() implementation.

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

Parameters:

Property	Type	Description
_facet	address	Facet contract address that implements exportSelectors().

Events

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

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

Errors

Signature:

error NoSelectorsForFacet(address _facet);

Signature:

error NoBytecodeAtAddress(address _contractAddress);

Signature:

error CannotAddFunctionToDiamondThatAlreadyExists(bytes4 _selector);

Signature:

error CannotRemoveFacetThatDoesNotExist(address _facet);

Signature:

error CannotReplaceFacetWithSameFacet(address _facet);

Signature:

error FacetToReplaceDoesNotExist(address _oldFacet);

Signature:

error DelegateCallReverted(address _delegate, bytes _delegateCalldata);

Signature:

error ExportSelectorsCallFailed(address _facet);

Signature:

error IncorrectSelectorsEncoding(address _facet);

Signature:

error CannotReplaceFunctionFromNonReplacementFacet(bytes4 _selector);

Best Practices

• Diamonds upgrades should be considered as a critical operation and always ensure proper access control.
• Verify facet logic contracts are immutable and trusted before adding or replacing.
• Ensure each facet’s exportSelectors() returns a valid packed selector list in deterministic order.
• Carefully audit any optional post-upgrade delegatecall (contract + calldata).

Security Considerations

The upgradeDiamond function is critical: this function mutates the diamond’s selector routing and facet linked list.

It optionally executes an unrestricted delegatecall after facet updates. Make sure _delegate and _delegateCalldata are fully trusted before calling it.

Shared Storage

This module writes to the diamond’s shared storage at DIAMOND_STORAGE_POSITION (conceptually keccak256("erc8153.diamond")).

Changes made through upgradeDiamond, addFacets, replaceFacets, and removeFacets are immediately visible to the diamond and all facet that access the shared storage.

Was this helpful?

Last updated:March 13, 2026