Diamond Upgrade Facet

Orchestrates upgrade functionality, enabling the addition, replacement, and removal of facets.

Key Features

• Manages facet lifecycle (add, replace, remove) within a diamond.
• Owner-gated upgrade entrypoint (ERC-173 owner).
• Optional delegatecall for post-upgrade initialization/state migration.
• Updates selector routing so subsequent calls dispatch to the new facet.
• Emits events for all facet changes and delegate calls.

Storage

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"))

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

Owner Storage

Definition

/** storage-location: erc8042:erc173.owner */
struct OwnerStorage {
  address owner;
}

---

FacetReplacement

Definition

struct FacetReplacement {
  address oldFacet;
  address newFacet;
}

Functions

upgradeDiamond

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

Execution order is always: addFacets, replaceFacets, removeFacets

Then, if _delegate != address(0), the diamond performs a delegatecall 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

Facet Requirement

Facets must implement exportSelectors() in order to make their selectors discoverable by diamonds. Only the exported selectors will be added to the diamond.

interface IFacet {
    function exportSelectors() external pure returns (bytes memory);
}

See Facet-Based Diamond EIP-8153 for more details.

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

• Ensure all diamond upgrade operations are performed by authorized accounts.
• 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 (delegate contract + calldata).

Security Considerations

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

It is protected by Owner checks, and it optionally executes an unrestricted delegatecall after facet updates. Treat _delegate and _delegateCalldata as fully trusted: that code can modify diamond storage and may introduce complex control flow.

Was this helpful?

Last updated:March 13, 2026