Diamond Upgrade Facet

@perfect-abstractions/compose/diamond/DiamondUpgradeFacet.solCopy

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​

Diamond Storage​

/** 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​

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

FacetReplacement​

struct FacetReplacement {
  address oldFacet;
  address newFacet;
}

Functions​

upgradeDiamond​

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

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:

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​

FacetAdded

event FacetAdded(address indexed _facet);

FacetRemoved

event FacetRemoved(address indexed _facet);

FacetReplaced

event FacetReplaced(address indexed _oldFacet, address indexed _newFacet);

DiamondDelegateCall

event DiamondDelegateCall(address indexed _delegate, bytes _delegateCalldata);

DiamondMetadata

event DiamondMetadata(bytes32 indexed _tag, bytes _data);

Errors​

OwnerUnauthorizedAccount

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

Signature:

error OwnerUnauthorizedAccount();

CannotAddFunctionToDiamondThatAlreadyExists

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

Signature:

error CannotAddFunctionToDiamondThatAlreadyExists(bytes4 _selector);

CannotRemoveFacetThatDoesNotExist

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

Signature:

error CannotRemoveFacetThatDoesNotExist(address _facet);

CannotReplaceFacetWithSameFacet

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

Signature:

error CannotReplaceFacetWithSameFacet(address _facet);

CannotReplaceFunctionFromNonReplacementFacet

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

Signature:

error CannotReplaceFunctionFromNonReplacementFacet(bytes4 _selector);

FacetToReplaceDoesNotExist

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

Signature:

error FacetToReplaceDoesNotExist(address _oldFacet);

DelegateCallReverted

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

Signature:

error DelegateCallReverted(address _delegate, bytes _delegateCalldata);

ExportSelectorsCallFailed

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

Signature:

error ExportSelectorsCallFailed(address _facet);

IncorrectSelectorsEncoding

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

NoBytecodeAtAddress

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

Signature:

error NoBytecodeAtAddress(address _contractAddress);

NoSelectorsForFacet

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​

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

Newsletter

Get notified about releases, feature announcements, and technical deep-dives on building smart contracts with Compose.

Subscribe

No spam. Unsubscribe anytime.