Version: 1.0
Framework: ERC-2535 Diamond Standard
Solidity: ^0.8.20
Last Updated: April 2026
- Architecture Overview
- Core Concepts
- Storage Layout
- Initialization Pattern
- Diamond Cut Operation
- Ownership & Access Control
- Extension Guide
- Security Assumptions
- Design Decisions
graph TB
User["User/External Contract"]
Diamond["Diamond Proxy<br/>(Persistent Address)"]
Fallback["Fallback Router<br/>selector β facet lookup"]
DCut["DiamondCutFacet<br/>Modify structure"]
DLoupe["DiamondLoupeFacet<br/>Introspect"]
Own["OwnableFacet<br/>Ownership"]
ERC165F["ERC165Facet<br/>Interfaces"]
Custom["Custom Facets<br/>User logic"]
DiamondLib["DiamondLib<br/>Storage & cuts"]
OwnableLib["OwnableLib<br/>Owner state"]
ERC165Lib["ERC165Lib<br/>Interface registry"]
SharedStorage["Shared Storage<br/>Diamond + Libraries"]
User -->|Call| Diamond
Diamond --> Fallback
Fallback -->|selector| DCut
Fallback -->|selector| DLoupe
Fallback -->|selector| Own
Fallback -->|selector| ERC165F
Fallback -->|selector| Custom
DCut --> DiamondLib
DLoupe --> DiamondLib
Own --> OwnableLib
Custom --> DiamondLib
Custom --> OwnableLib
DiamondLib --> SharedStorage
OwnableLib --> SharedStorage
ERC165Lib --> SharedStorage
sequenceDiagram
participant User
participant Diamond
participant Storage
participant Facet
User->>Diamond: call selector(args)
Diamond->>Diamond: fallback() executes
Diamond->>Storage: lookup selector β facet address
Storage-->>Diamond: return facet address
Diamond->>Facet: delegatecall(selector, args)
Facet->>Storage: read/write Diamond state
Storage-->>Facet: return/store
Facet-->>Diamond: return results
Diamond-->>User: return results
stateDiagram-v2
[*] --> NotExist
NotExist --> Deployed: Deploy facet contract
Deployed --> Active: diamondCut(Add)
Active --> Modified: diamondCut(Replace)
Modified --> Active: diamondCut(Replace)
Active --> Inactive: diamondCut(Remove all selectors)
Inactive --> [*]
A function selector is the first 4 bytes of a function's signature hash.
bytes4 selector = bytes4(keccak256("transfer(address,uint256)"));
// Result: 0xa9059cbbWhy selectors matter:
- Compact representation (4 bytes vs full signature)
- Gas-efficient lookup in calldata
- EVM native: handled by fallback routing
- Enables function replacement without bytecode changes
- Uniquely identifies a function within the Diamond
A facet is a separate contract containing related functions that execute in the Diamond's storage context.
Critical property: All code executes in Diamond's storage via delegatecall, not in the facet's storage.
// Facet code
function doSomething() external {
// msg.sender = original caller
// this = Diamond address
// Storage = Diamond's storage (not facet's)
}When to create a facet:
- Group related functions (e.g., all token functions)
- Manage bytecode size (55KB Ethereum limit)
- Separate concerns (governance, tokens, markets)
- Enable independent upgrades of functionality
A diamond cut is an atomic transaction that modifies which functions the Diamond exposes.
Three operations:
| Operation | Purpose | Constraints |
|---|---|---|
| Add | Introduce new functions | Selector must not exist, facet must have bytecode |
| Replace | Change function implementation | Selector must exist, different facet required |
| Remove | Delete function | Facet address must be zero |
Atomicity guarantee: All operations execute together; if any fails, entire cut reverts.
Loupe (jeweler's inspection tool) provides read-only introspection into Diamond composition.
function facets() external view returns (Facet[] memory);
function facetFunctionSelectors(address facet) external view returns (bytes4[] memory);
function facetAddresses() external view returns (address[] memory);
function facetAddress(bytes4 selector) external view returns (address);Use cases:
- Verify upgrades were applied correctly
- Determine which facet implements a selector
- Monitor available functionality
- Audit Diamond composition history (with events)
Initialization differs from constructors because Diamond is a proxy:
Why not use constructor:
- Constructor runs when facet is deployed, not Diamond
msg.sender= facet deployer, not Diamond creator- State goes to facet storage, not Diamond storage
Solution: Delegatecall-based initialization:
// Concrete diamond: cut facets and run the init contract atomically at deployment
contract MyDiamond is Diamond {
constructor(FacetCut[] memory _facetCuts, address _init, bytes memory _calldata) {
DiamondLib.diamondCut(_facetCuts, _init, _calldata);
}
}The init contract runs in the Diamond's delegatecall context, so initialization happens in the right storage. For factory/CREATE2/clone deployments where a constructor cannot run per-instance, expose an initializer-guarded initialize function in your concrete diamond instead (see test/mocks/MockDiamond.sol for a reference).
This library uses ERC-7201 to prevent storage collisions between components.
Why ERC-7201:
- Each component gets isolated namespace
- Storage location is deterministically computable
- Future-proof for composability
- Prevents accidental overwrites
Formula:
uint256 slot = uint256(keccak256(abi.encode(uint256(keccak256("namespace")) - 1))) & ~bytes32(uint256(0xff));Namespace: "diamond.lib.storage"
Location: 0x6d5a93fec60e12d72b781fe97b2b5406e385b9eaa23d3ec2fbfa067f9d0dc000
struct DiamondStorage {
mapping(bytes4 selector => FacetAddressAndPosition) selectorToFacetAndPosition;
mapping(address facet => FacetFunctionSelectorsAndPosition) facetToSelectorsAndPosition;
address[] facetAddresses;
}
struct FacetAddressAndPosition {
address facetAddress;
uint96 functionSelectorPosition;
}
struct FacetFunctionSelectorsAndPosition {
bytes4[] functionSelectors;
uint256 facetAddressPosition;
}Design rationale:
selectorToFacetAndPosition: O(1) selector β facet lookup (essential for fallback)facetToSelectorsAndPosition: Enables facet removal without linear scanfacetAddresses: Lists all facets for loupe functionsuint96positions: Sufficient for array indices, saves storage space
Namespace: Owner state (internal to OwnableLib)
Location: 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffff74873927
Single 32-byte slot:
Bits 0-159: Owner address (20 bytes, padded)
Bit 255: Flag (1 if owner is zero address)
Why single slot:
- Minimal gas overhead (single SLOAD per check)
- Atomic state transitions (single SSTORE)
- Storage efficiency
Namespace: "diamond.lib.storage.ERC165"
Location: 0x9ca7f3e2e2bfb15fdf072b85dde92837cddacee6cf2f6b38cd06c9457c1c4200
struct ERC165Storage {
mapping(bytes4 interfaceId => bool supported) supportedInterfaces;
}Registered interfaces:
0x01ffc9a7= ERC1650x7f5828d0= ERC173 (ownership)0x1f931c1c= IDiamondCut0x48e2b093= IDiamondLoupe
sequenceDiagram
participant Deployer
participant Diamond
participant DiamondLib
participant InitContract
Deployer->>Diamond: constructor(cuts, initAddr, initData)
Diamond->>DiamondLib: diamondCut(cuts)
DiamondLib->>DiamondLib: validate & apply all cuts
DiamondLib->>Diamond: emit DiamondCut event
Diamond->>InitContract: delegatecall(initData)
InitContract->>Diamond: write state (owner, etc)
InitContract-->>Diamond: return
Running the cut in the constructor is atomic: the diamond is never observable in a facetless, ownerless state, and there is no separate initialize transaction to front-run.
For multiple sequential initializers:
MultiInit.multiInit(
[address(init1), address(init2), address(init3)],
[data1, data2, data3]
);Behavior:
- Each initializer runs sequentially in Diamond's context
- Zero addresses revert
MultiInit__ZeroInit(index)instead of terminating the batch - Missing code reverts
NoBytecodeAtAddress(index, initAddress) - Reverted steps report
MultiInit__StepFailed(index, init, reason), preserving the original revert bytes - Step indexes are zero-based; matching empty arrays remain a no-op
- Any failure reverts entire transaction
- Atomic: all succeed or none
flowchart TD
Start["diamondCut called<br/>with FacetCut[] array"]
ValidateAll["Validate all cuts"]
ValidAdd["Check Add:<br/>- facet != 0<br/>- has bytecode<br/>- selector not exists"]
ValidReplace["Check Replace:<br/>- facet != 0<br/>- selector exists<br/>- different facet"]
ValidRemove["Check Remove:<br/>- facet == 0<br/>- selector exists<br/>- not immutable"]
UpdateStorage["Update storage:<br/>selector β facet mappings<br/>Add/remove facets"]
Initialization["Call initializer<br/>if provided"]
Emit["Emit DiamondCut event"]
Success["Diamond ready<br/>with new functions"]
Start --> ValidateAll
ValidateAll --> ValidAdd
ValidAdd --> ValidReplace
ValidReplace --> ValidRemove
ValidRemove --> UpdateStorage
UpdateStorage --> Initialization
Initialization --> Emit
Emit --> Success
Input:
selector: 0x12345678
facet: NewFacet
action: Add
Before:
selectorToFacet: {0xaaaa β FacetA}
facetAddresses: [FacetA]
Validation:
NewFacet != 0x0 β
NewFacet has bytecode β
0x12345678 not in use β
Update Storage:
Add NewFacet to facetAddresses
Map 0x12345678 β NewFacet
Track selector position in NewFacet
After:
selectorToFacet: {0xaaaa β FacetA, 0x12345678 β NewFacet}
facetAddresses: [FacetA, NewFacet]
Result: Future calls to 0x12345678 route to NewFacet
The library implements single-owner access control (EIP-173 compatible).
Owner capabilities:
- Execute
diamondCut()to modify facets - Call any function in Diamond through facets
- Transfer ownership (2-step process)
Limitations:
- No role-based access control
- No delegation
- No time delays/timelocks
- Single point of failure
Why two-step:
- Prevents accidental transfer to wrong address
- New owner can verify they have access
- Time window for cancellation
- Follows industry best practices
stateDiagram-v2
[*] --> NoHandover
NoHandover --> Requested: requestOwnershipHandover(newOwner)
Requested --> Requested: time passes
Requested --> NoHandover: cancelOwnershipHandover()
Requested --> Transferred: completeOwnershipHandover(newOwner)
Transferred --> Transferred: ownership changed
Requested --> Expired: 48 hours pass
Expired --> NoHandover: handover expires
Time limits:
- Valid for 48 hours after request
- Automatically expires after 48 hours
- Can be cancelled before expiry
// 1. Import required libraries
import {DiamondLib} from "@diamond/libraries/DiamondLib.sol";
import {OwnableLib} from "@diamond/libraries/OwnableLib.sol";
// 2. Create facet contract
contract MyCustomFacet {
// 3. Implement access control
modifier onlyOwner() {
OwnableLib.checkOwner();
_;
}
// 4. Implement your functions
function myFunction(uint256 value) external onlyOwner {
// Your logic here
// msg.sender = original caller
// this = Diamond address
// Storage = Diamond's storage
}
}
// 5. Prepare for diamond cut
bytes4[] memory selectors = new bytes4[](1);
selectors[0] = bytes4(keccak256("myFunction(uint256)"));
// 6. Create cut array
FacetCut[] memory cuts = new FacetCut[](1);
cuts[0] = FacetCut({
facetAddress: address(myCustomFacet),
action: FacetCutAction.Add,
functionSelectors: selectors
});
// 7. Execute cut (owner only)
diamondCut(cuts, address(0), "");Use ERC-7201 to avoid conflicts:
// MyStorage.sol - Define isolated namespace
library MyStorage {
// Compute: keccak256(abi.encode(uint256(keccak256("my.storage")) - 1)) & ~bytes32(uint256(0xff))
bytes32 constant STORAGE_LOCATION = 0x...;
struct MyData {
uint256 counter;
mapping(address => uint256) balances;
}
function getStorage() internal pure returns (MyData storage s) {
assembly {
s.slot := STORAGE_LOCATION
}
}
}
// MyFacet.sol - Use storage library
contract MyFacet {
function increment() external {
MyStorage.getStorage().counter++;
}
}// Deploy improved version
contract ImprovedMyFacet {
// Enhanced implementation with bug fixes
}
// Propose replacement
FacetCut[] memory cuts = new FacetCut[](1);
cuts[0] = FacetCut({
facetAddress: address(improvedMyFacet),
action: FacetCutAction.Replace,
functionSelectors: selectors // Same selectors, new code
});
diamondCut(cuts, address(0), "");FacetCut[] memory cuts = new FacetCut[](1);
cuts[0] = FacetCut({
facetAddress: address(0), // Must be zero for removal
action: FacetCutAction.Remove,
functionSelectors: selectorsToRemove
});
diamondCut(cuts, address(0), "");| Component | Trust Level | Assumption |
|---|---|---|
| Owner | HIGH | Trusted to act in Diamond's interest |
| Facet code | HIGH | Audited before adding to Diamond |
| Function selectors | MEDIUM | Caller provides correct selectors |
| Delegatecall targets | HIGH | Must not create loops back to Diamond |
| Custom storage | MEDIUM | Must use ERC-7201 to avoid conflicts |
- Selector uniqueness: No duplicate active selectors
- Facet persistence: Facets remain deployed unless explicitly removed
- Initialization atomicity: All-or-nothing initialization
- Reentry prevention: Initialization guards prevent accidental reentrancy
- Storage isolation: ERC-7201 prevents component collisions
- Test all diamond cuts in staging before production
- Audit facet code before adding to Diamond
- Plan ownership strategy (consider decentralized upgrades)
- Monitor DiamondCut and Initialization events
- Document selector β function mapping
- Verify facet bytecode before cuts
- Test storage layout doesn't conflict
- Plan for owner key management
Decision: Use assembly for storage access, delegatecall, events
Rationale:
- Gas efficiency: Eliminates Solidity wrapper overhead
- Direct control: Precise operation ordering
- Library scope: Low-level patterns benefit most from optimization
Safety: All marked memory-safe and follow standard patterns.
Decision: Namespaced storage instead of inheritance
Rationale:
- Composable: Facets coexist without inheritance chains
- Transparent: Anyone computes storage locations
- Future-proof: New facets won't corrupt existing state
- Isolated: Each component has private namespace
Decision: Only owner-based access control in core
Rationale:
- Minimal: Keeps library focused and auditable
- Flexible: Applications add roles via facets
- Simple: Single point of authorization
- Auditable: Easier to verify security
Decision: Require request β complete steps for ownership transfer
Rationale:
- Safety: Prevents accidental loss
- Verification: New owner confirms access
- Recovery: Time window to cancel
- Standard: Industry best practice
Decision: Track versions and prevent reinitialization to same/lower
Rationale:
- Upgrade safety: Allows intentional reinitializations
- Reentrancy prevention: Guards against accidental reentrancy
- State machine: Clear initialization transitions
- Flexibility: Supports one-time or versioned patterns
- EIP-2535 Diamond Standard
- ERC-7201 Namespaced Storage
- EIP-165 Interface Detection
- EIP-173 Ownership Standard
- Solady Library Patterns
End of Specification Document