This post is adapted from an article originally published on my Substack, and is reposted here because ERC-8109 directly informs the architecture and goals of Compose.
While working on Compose, I decided to revisit parts of ERC-2535 Diamonds to see how the standard could be improved. Initially, I thought this would be limited to terminology changes, which led to my post Revising ERC-2535 Diamonds to Simplify and Improve the Terminology.
However, that effort revealed deeper opportunities for improvement — enough that I ultimately decided to propose a new standard for diamond contracts.
The primary issue I wanted to address is complexity.
Too many articles and discussions imply that diamonds are inherently complex, or that they should only be used when building complicated systems. That narrative is backwards.
Diamonds should be used when you want to build large systems that remain simple — systems that are easy to understand, reason about, test, audit, and evolve.
Any powerful tool can be used well or poorly. Diamonds can reduce complexity, or they can increase it if misapplied.
Let’s do this right.
Diamonds reduce complexity in two fundamental ways:
A single contract address A diamond exposes a large surface area of functionality through one address, simplifying deployment, integration, tooling, and user interfaces.
Decomposition into focused facets Large contracts are broken into small, purpose-built facets. Each facet is independently testable and understandable. The diamond then wires these facets together in a systematic, efficient, and documented manner.
The benefits of modularity are well understood in software engineering — and diamonds bring those benefits on-chain.
The new standard, ERC-8109: Diamonds, Simplified, focuses on reducing complexity while preserving the full power of diamond contracts. It does so by:
Only two introspection functions are required:
Replaces the monolithic DiamondCut event with per-function events:
These events simplify the implementation of functions that add/replace/remove functions and are easier for block explorers, indexers, and other tooling to consume.
An explicitly specified, optional, upgrade function, including metadata support, to ensure consistent behavior across tooling.
Existing ERC-2535 diamonds can adopt the new standard.
Compose goes beyond standards and documentation. Compose is the practical application of the ideas behind ERC-8109.
Together with maxnorm and others, I’m building Compose to help developers use ERC-8109 Diamonds to construct modular smart-contract systems. Compose will provide:
Compose is intended to make the right way to build diamond systems the easy way.
Please read the new standard here: ERC-8109: Diamonds, Simplified
Share your feedback here: Feedback for ERC-8109: Diamonds, Simplified
If you care about building large smart contract systems that remain simple, understandable, and robust, I invite your collaboration.
]]>The following sections use metaphors to clarify diamond architectural intent and design philosophy.
Where monolithic contracts blur responsibility, diamonds draw sharp edges. Each facet isolates a single concern, reducing complexity through separation. Bound by a single address and storage, the result is a structured, unified whole.
A diamond is not defined by excess, but by intention. Every facet exists for a reason, cut precisely to serve the whole. This standard favors deliberate structure over accidental complexity, ensuring that each function has a clear place and purpose.
To support flawless architecture, this standard discourages immutable functions. Like imperfections within a diamond, they cloud structural clarity and cannot be polished away.
An immutable diamond is cut once, with no margin for error. Every facet must be placed with intention, for no edge can be reworked after the stone is set. Its strength comes from certainty, not change.
Immutability improves clarity. When no future changes are possible, the design is complete. Nothing is deferred, and nothing is concealed behind upgrade intent.
An immutable diamond is still modular. Its facets are cut separately, inspected individually, and set only once. Immutability does not remove structure — it freezes a structure already proven.
True permanence is chosen, not imposed. A diamond may be set forever, but only after it has been examined, and graded. This standard preserves the freedom to refine before committing to final form.
Software, like a rough stone, requires shaping. This standard grants the freedom to polish and refine, turning a raw idea into a flawless diamond through the iterative process of upgrades.
A diamond is not perfected in a single strike. It is shaped through measured cuts, evaluated under light, and refined over time. This standard embraces evolution, allowing systems to improve without disturbing what already shines.
Behind many facets stands a solitary, enduring interface. It presents a singular, cohesive identity to the world, regardless of the depth of logic beneath the surface.
Deployed facets may be reused, recombined, and set into new designs. From a shared library of facets, countless diamonds may emerge — distinct in purpose, consistent in form. Reuse strengthens the ecosystem, as proven facets bring their clarity wherever they are set.
True value requires transparency. Unlike opaque proxies that hide their functions, this standard ensures the architecture remains crystal clear, granting users an unobstructed view of its composition.
A diamond is judged by how it handles light. This standard ensures the architecture remains pure, allowing the light of public scrutiny to pass through every facet without obstruction or distortion.
Light reveals flaws before it reveals brilliance. By making structure explicit and changes observable, this standard invites scrutiny as a form of strength, not risk. Trust emerges not from obscurity, but from clarity.
Trends fade, tooling changes, but structure endures. A diamond that is well cut today will remain sound tomorrow. This standard aims not for novelty, but for designs that withstand time, upgrades, and inspection.
]]>We're excited to share our journey with you.
Compose will be a powerful smart contract library that helps developers create beautiful, maintainable onchain applications with ease.
Stay tuned for more updates, and feel free to reach out if you have questions or suggestions!
Huge thanks to all the current & future contributors to Compose! 🩵
]]>