Diamond Upgrade Module

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

Module providing the internal functions to extend the diamond's upgrade functionality by adding, replacing, or removing facets.

Key Features

• Manages facet lifecycle (add, replace, remove) within a diamond.
• Updates selector routing so subsequent calls dispatch to the new facet.

Use this module in your project

You can use modules to wrap around you own project logic while using the default Compose building blocks. Modules provides all the necessary internal helpers for maximum integration

Storage follows the diamond slot layout in this file; any code using the same STORAGE_POSITION or related positions reads and writes shared state.

See Facets & Modules for more information.

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

FacetReplacement​

This struct is used to replace old facets with new facets.

struct FacetReplacement {
  address oldFacet;
  address newFacet;
}

Functions​

getDiamondStorage​

function getDiamondStorage() pure returns (DiamondStorage storage s);

Returns:

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.

addFacets​

Adds new facets to a diamond and maps their exported selectors to the facet address.

function addFacets(address[] calldata _facets);

Parameters:

removeFacets​

Removes facets from a diamond and unregisters the selectors they previously exported.

function removeFacets(address[] calldata _facets);

Parameters:

replaceFacets​

Replaces facets in a diamond using (oldFacet, newFacet) pairs.

function replaceFacets(FacetReplacement[] calldata _replaceFacets);

Parameters:

importSelectors​

Retrieves the function selectors exposed by a facet by calling its exportSelectors(). Validates the returned ABI-encoded bytes (offset, length, and that the payload length is a multiple of 4) and returns the packed selectors without copying (zero-copy decode).

function importSelectors(address _facet) view returns (bytes memory selectors);

Parameters:

Returns:

at​

Returns the 4-byte function selector at the given index in a packed bytes array of selectors (e.g. from importSelectors or other selector packing).

function at(bytes memory selectors, uint256 index) pure returns (bytes4 selector);

Parameters:

Returns:

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​

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.
• 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 (contract + calldata).

Security Considerations​

This module doesn't provide any access control logic, when using it into your own facet, it is your responsibility to implement proper checks.

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

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

Integration Notes​

This module interacts directly with the diamond's shared storage at the DIAMOND_STORAGE_POSITION, which is identified by keccak256("erc8153.diamond"). All functions within this module read from and write to this shared storage.

Changes made through upgradeDiamond, addFacets, replaceFacets, and removeFacets are immediately visible to the diamond and all facet that access the shared storage.

Last updated:March 13, 2026

Newsletter

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

Subscribe

No spam. Unsubscribe anytime.