Diamond Upgrade Facet

Diamond upgrade and management facet

Key Features

• Manages facet lifecycle (add, replace, remove) within a diamond.
• Supports optional delegatecall for post-upgrade operations.
• Emits events for all facet changes and delegate calls.
• Provides selector discovery mechanism via exportSelectors.

Overview

This facet provides core diamond upgrade functionality, enabling the addition, replacement, and removal of facets. It orchestrates these operations through the diamond proxy and can optionally perform delegate calls for initialization or state modification. The facet also supports exporting its selectors for discovery.

Storage

OwnerStorage

Definition

struct OwnerStorage {
  address owner;
}

---

FacetNode

Definition

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

---

FacetList

Definition

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

---

DiamondStorage

Definition

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

---

FacetReplacement

Definition

struct FacetReplacement {
  address oldFacet;
  address newFacet;
}

State Variables

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

Functions

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
) external;

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.

---

exportSelectors

Exports the function selectors of the DiamondUpgradeFacet This function is use as a selector discovery mechanism for diamonds

function exportSelectors() external pure returns (bytes memory);

Returns:

Property	Type	Description
-	bytes	selectors The exported function selectors of the DiamondUpgradeFacet

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 OwnerUnauthorizedAccount();

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

Best Practice

• Ensure all diamond upgrade operations are performed by authorized accounts.
• Verify facet logic contracts have correct bytecode before adding or replacing.
• Safely manage the delegatecall functionality for initialization or state modification after an upgrade.

Security Considerations

Security

The upgradeDiamond function is critical and must be protected by robust access control to prevent unauthorized modifications. The facet uses delegatecall, which requires careful validation of the _delegate address and _delegateCalldata to prevent reentrancy or unintended state changes. Input validation for facet addresses and selector data is crucial. Potential risks include OwnerUnauthorizedAccount, NoSelectorsForFacet, NoBytecodeAtAddress, and DelegateCallReverted errors if inputs are invalid or delegate calls fail.

Was this helpful?

Last updated:March 13, 2026