Skip to main content

Diamond Upgrade Module

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

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

Storage​

State Variables​

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

FacetReplacement​

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

Definition
struct FacetReplacement {
  address oldFacet;
  address newFacet;
}

Functions​

getDiamondStorage​

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

Returns:

PropertyTypeDescriptionsDiamondStorageThe DiamondStorage struct in storage.

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:

PropertyTypeDescription_addFacetsaddress[]Facet addresses to add_replaceFacetsFacetReplacement[](oldFacet, newFacet) pairs to replace_removeFacetsaddress[]Facet addresses to remove_delegateaddressOptional contract to delegatecall (address(0) to skip)_delegateCalldatabytesOptional calldata to execute on _delegate_tagbytes32Optional arbitrary metadata, such as release version_metadatabytesOptional arbitrary metadata

addFacets​

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

Behavior:
1
Import selectors
Each facet in _facets is queried via exportSelectors().
2
Validate uniqueness
All exported selectors must be new to the diamond.
3
Link facet node
The first selector of each facet becomes the facet linked-list node id.
4
Emit event
Emits FacetAdded once per successfully added facet.
function addFacets(address[] calldata _facets);

Parameters:

PropertyTypeDescription_facetsaddress[]Facet addresses to add. Each facet must implement exportSelectors().

removeFacets​

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

Behavior:
1
Validate facet
Checks the first exported selector currently maps to that facet.
2
Unlink facet
Removes the facet from the facet linked list.
3
Delete selectors
Deletes all selectors exported by the facet.
4
Emit event
Emits FacetRemoved once per removed facet.
function removeFacets(address[] calldata _facets);

Parameters:

PropertyTypeDescription_facetsaddress[]Facet addresses to remove.

replaceFacets​

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

Behavior:
1
Compare selector sets
Replacement is selector-set based, not just an address swap.
2
Update shared selectors
Selectors present in both facets are re-routed to newFacet.
3
Add new selectors
Selectors present only in newFacet are added.
4
Remove stale selectors
Selectors present only in oldFacet are removed.
5
Emit event
Emits FacetReplaced(oldFacet, newFacet) for each replacement pair.
function replaceFacets(FacetReplacement[] calldata _replaceFacets);

Parameters:

PropertyTypeDescription_replaceFacetsFacetReplacement[](oldFacet, newFacet) pairs to replace old with new.

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

Used internally by addFacets, replaceFacets and removeFacets. 
function importSelectors(address _facet) view returns (bytes memory selectors);

Parameters:

PropertyTypeDescription_facetaddressContract address implementing exportSelectors() that returns ABI-encoded bytes of 4-byte function selectors.

Returns:

PropertyTypeDescriptionselectorsbytesPacked 4-byte function selectors (length is a multiple of 4). Same memory layout as returned by exportSelectors(); may point into the staticcall return buffer.

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:

PropertyTypeDescriptionselectorsbytesPacked array of 4-byte function selectors (length must be a multiple of 4).indexuint256Zero-based index of the selector to read (0 = first selector, 1 = second, etc.).

Returns:

PropertyTypeDescriptionselectorbytes4The function selector at the given index.

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:
PropertyTypeDescription_facetaddressThe 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:
PropertyTypeDescription_facetaddressThe address of the facet that previously handled function calls to the diamond.

Emitted when an existing facet is replaced with a new facet.

The function selectors handled by these facets can be retrieved by calling:

Signature:
event FacetReplaced(address indexed _oldFacet, address indexed _newFacet);
Parameters:
PropertyTypeDescription_oldFacetaddressThe address of the facet that previously handled function calls to the diamond._newFacetaddressThe 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:
PropertyTypeDescription_delegateaddressThe contract that was delegatecalled._delegateCalldatabytesThe 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:
PropertyTypeDescription_tagbytes32Arbitrary metadata, such as a release version._databytesArbitrary metadata.

Errors​

Best Practices​

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:

Newsletter

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

No spam. Unsubscribe anytime.