Diamond Upgrade Facet

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

Key Features

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

Storage

State Variables

Property	Type	Description
DIAMOND_STORAGE_POSITION	bytes32	Diamond storage slot position in the proxy (Value: keccak256("erc8153.diamond"))
OWNER_STORAGE_POSITION	bytes32	Owner storage slot position in the proxy (Value: keccak256("erc173.owner"))

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:

1

Add Facets

Attach new facet contracts and register their function selectors.

2

Replace Facets

Swap existing selectors to point to updated facet implementations.

3

Remove Facets

Unregister selectors that are no longer needed in the diamond.

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

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

Thrown by upgradeDiamond when msg.sender is not the current diamond owner.

Signature:

error OwnerUnauthorizedAccount();

Thrown by addFacets when a selector exported by a facet already exists in the diamond.

Signature:

error CannotAddFunctionToDiamondThatAlreadyExists(bytes4 _selector);

Thrown by removeFacets when the facet being removed is not currently part of the diamond.

Signature:

error CannotRemoveFacetThatDoesNotExist(address _facet);

Thrown by replaceFacets when a replacement pair provides the same address for both oldFacet and newFacet.

Signature:

error CannotReplaceFacetWithSameFacet(address _facet);

Thrown by replaceFacets when a selector in newFacet is already owned by a facet other than the specified oldFacet.

Signature:

error CannotReplaceFunctionFromNonReplacementFacet(bytes4 _selector);

Thrown by replaceFacets when the provided oldFacet does not match the facet currently registered in the diamond.

Signature:

error FacetToReplaceDoesNotExist(address _oldFacet);

Thrown by upgradeDiamond when the optional post-upgrade delegatecall fails without returning revert data.

Signature:

error DelegateCallReverted(address _delegate, bytes _delegateCalldata);

Thrown by importSelectors when the staticcall to _facet.exportSelectors() fails.

Signature:

error ExportSelectorsCallFailed(address _facet);

Thrown by importSelectors when the facet returns data that is not valid ABI-encoded bytes (e.g. wrong offset, length not a multiple of 4, or length exceeds payload).

Signature:

error IncorrectSelectorsEncoding(address _facet);

Thrown by importSelectors when the facet address has no code (e.g. EOA or uninitialized contract).

Signature:

error NoBytecodeAtAddress(address _contractAddress);

Thrown by importSelectors when the facet returns fewer than 4 bytes of selectors (i.e. no valid selector).

Signature:

error NoSelectorsForFacet(address _facet);

Best Practices

• Ensure all diamond upgrade operations are performed by authorized wallet. This facet is configure to use the unique owner, use the Upgrade Module to wrap around your own access control logic.
• Always verify facet logic contracts are immutable and trusted before using it inside a diamond.
• 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: this function mutates the diamond’s selector routing and facet list.

Although this facet protected by Owner checks, it can optionally execute an unrestricted delegatecall after facet updates. Allowing changes to the diamond storage.

That being said, make sure to provide verified and trusted contract addresses to avoid any unwanted changes or vulnerabilities

Last updated:May 1, 2026