ERC-2535, the Diamond Standard, lets one contract address (the “diamond”) delegate each function selector to one of many implementation contracts called facets. Facets can be added, replaced or removed through a diamondCut operation, and loupe functions let anyone inspect which facet handles which function. It solves the 24 KB contract-size limit and enables highly modular, upgradeable systems — at the cost of significant complexity.
Key takeaways
- One address, many facets — e.g. issuance, compliance, marketplace, distributions, admin.
diamondCutadds/replaces/removes selectors;DiamondCutevents record every change.- Loupe functions (
facets,facetFunctionSelectors,facetAddress) make the routing transparent. - Shared storage must be carefully namespaced (diamond storage / app storage patterns).
- Best for large platforms; for a single token, a standard ERC-1967 proxy is simpler.
How a diamond works
- A call arrives at the diamond.
- The fallback function looks up the selector in a mapping to find the facet address.
- It
delegatecalls the facet, which operates on the diamond’s storage. - Governance can perform a
diamondCutto change mappings.
When diamonds make sense for tokenization
- Platform contracts combining issuance, order books, auctions, escrow, distributions and fee logic that would exceed size limits.
- Feature evolution — adding secondary-market features after a primary-only launch without migrating state.
- Shared state across modules — e.g. investor registry used by marketplace and distribution facets.
When to avoid them
- Simple tokens — investors, custodians and venues prefer recognisable standard proxies.
- Teams new to the pattern — storage mistakes in diamonds can be catastrophic.
- Audit budgets — more moving parts mean more review time.
Governance and transparency
Every diamondCut can change behaviour, so apply the same safeguards as other upgradeable systems: multisig control, timelocks, published change logs, audits of each new facet and monitoring of DiamondCut events. Consider freezing critical facets (e.g. token balances) once stable.
Example facet layout for a tokenization marketplace
| Facet | Functions |
|---|---|
DiamondCutFacet |
diamondCut (governed by multisig + timelock) |
DiamondLoupeFacet |
facets, facetFunctionSelectors, facetAddresses, facetAddress |
ListingFacet |
Create, update and cancel listings of asset tokens |
OrderFacet |
Bids, RFQ responses, order matching |
SettlementFacet |
DvP escrow, payment confirmation, release |
DistributionFacet |
Income snapshots and claims |
ComplianceFacet |
Eligibility checks against identity registries |
AdminFacet |
Fees, pausing, role management |
Storage patterns
- Diamond storage: each facet keeps its own struct at a hashed storage position, avoiding collisions.
- AppStorage: one shared struct used by all facets, simpler but requires discipline when appending fields.
- Namespaced storage (ERC-7201): a standardised way to define storage namespaces, increasingly used in both diamonds and regular proxies.
Diamond cut example
// Adding a new facet with two functions (illustrative).
IDiamondCut.FacetCut[] memory cut = new IDiamondCut.FacetCut[](1);
bytes4[] memory selectors = new bytes4[](2);
selectors[0] = RfqFacet.requestQuote.selector;
selectors[1] = RfqFacet.respondQuote.selector;
cut[0] = IDiamondCut.FacetCut({facetAddress: address(rfqFacet), action: IDiamondCut.FacetCutAction.Add, functionSelectors: selectors});
IDiamondCut(diamond).diamondCut(cut, address(0), "");
Frequently asked questions
It removes the contract-size limit for large systems and allows fine-grained, modular upgrades behind a single address.
Yes. Auditors must review each facet, storage layout and the upgrade process.
It can, but most token holders, explorers and integrators expect standard tokens behind simple proxies. We generally keep tokens simple and use diamonds for platform logic.
Through loupe functions and verified facet source code on explorers.
Yes. Facets are stateless logic contracts, so several diamonds can reuse them.
Not directly — explorers and tools need diamond-aware support (loupe functions) to display all facets.
NUVZ is the RWA and Web3 engineering brand of ESS ENN Associates (est. 1993). Our team has designed and shipped tokenization platforms for real estate, education loans, solar PPAs, energy, carbon credits, bank deposits and trade documents. About us · Case studies
This article is for general information only and is not legal, tax or investment advice. Token standards evolve — always confirm the current status of an ERC at eips.ethereum.org and take advice from qualified counsel in each jurisdiction before issuing tokens.
