DiamondUpgradeFacet

Manage diamond upgrades and facet additions

Key Features

• Manages diamond functional surface area through facet composition.
• Supports adding, replacing, and removing functions via selector mapping.
• Enables diamond upgradeability by allowing facet deployments and reconfigurations.
• Facilitates metadata updates associated with diamond state changes.

Overview

This facet provides core functionality for upgrading diamond proxies by adding, replacing, and removing facets. It allows for delegate calls and metadata updates, integrating directly with the diamond storage pattern. Developers use this facet to manage the diamond's functional surface area and upgrade its components.

---

Storage

OwnerStorage

Definition

struct OwnerStorage {
  address owner;
}

---

FacetAndPosition

Definition

struct FacetAndPosition {
  address facet;
  uint32 position;
}

---

DiamondStorage

Definition

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

---

FacetFunctions

Definition

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

State Variables

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

Functions

upgradeDiamond

---

Function Changes:

---

DelegateCall:

---

Metadata:

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

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 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 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 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 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 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 NoSelectorsProvidedForFacet(address _facet);

Signature:

error NoBytecodeAtAddress(address _contractAddress);

Signature:

error CannotAddFunctionToDiamondThatAlreadyExists(bytes4 _selector);

Signature:

error CannotReplaceFunctionThatDoesNotExist(bytes4 _selector);

Signature:

error CannotRemoveFunctionThatDoesNotExist(bytes4 _selector);

Signature:

error CannotReplaceFunctionWithTheSameFacet(bytes4 _selector);

Signature:

error DelegateCallReverted(address _delegate, bytes _functionCall);

Signature:

error CannotReplaceImmutableFunction(bytes4 _selector);

Signature:

error CannotRemoveImmutableFunction(bytes4 _selector);

Best Practices

Best Practice

• Initialize diamond storage ownership using the owner field if applicable.
• Ensure that selectors for adding or replacing functions do not conflict with immutable functions.
• Verify that facet bytecode exists at the provided address before attempting to add or replace functions.

Security Considerations

Security

All state-modifying functions (addFunctions, replaceFunctions, removeFunctions, Metadata) must be protected by appropriate access control, typically owner-only, to prevent unauthorized modifications. The Metadata function emits an event, ensuring transparency for metadata changes. Input validation is crucial to prevent errors like NoSelectorsProvidedForFacet, NoBytecodeAtAddress, or conflicts with immutable functions.

Related Documentation

📦

DiamondUpgradeMod

Module used by DiamondUpgradeFacet

💎

DiamondInspectFacet

Related facet in diamond

💎

ExampleDiamond

Related facet in diamond

Was this helpful?

Last updated:December 30, 2025