ERC-8110 Diamond domain storage structure (Domain Architecture for Diamonds)
Draft · Other · created 2025-12-20
Defines a structural convention for organizing and naming a Diamond-pattern contract's storage by role-based domain rather than by facet. This reduces storage collisions and upgrade mistakes.
Why it is needed
The ERC-2535 Diamond standard provides modularity through facets but does not specify how storage should be organized. As a result, storage structures vary by team, and storage identifiers are not consistently validated or reused across facets, which can lead to unexpected collisions or state corruption during upgrades. ERC-8042 introduced human-readable storage identifiers, but it did not define how those identifiers should be structured and grouped in large projects. Without a common structure, tooling and auditing become difficult, and it is unclear which facet actually owns which state, increasing maintenance risk.
What to implement
function equipmentStorage() pure returns (EquipmentStorage storage s): Returns the location of the dedicated storage slot for the Equipment domain.function characterStorage() pure returns (CharacterStorage storage s): Returns the location of the main storage slot for the Character domain.function characterMountedStorage() pure returns (CharacterMountedStorage storage s): Returns the location of the storage slot for the mount status subdomain of the Character domain.function gameSettingsStorage() pure returns (GameSettingStorage storage s): Returns the location of the game-wide settings storage slot shared by multiple facets.
In depth
Domain definition
A domain is a conceptual unit of ownership over storage space. One domain corresponds exactly to one storage struct and one identifier. Multiple function selectors may read or write a single domain together, and domains are independent of facets, so multiple facets MAY handle the same domain. Domains SHOULD be defined according to business or system responsibility, not facet names.
Identifier naming convention
A storage identifier is a human-readable string whose keccak256 hash determines the storage location. The minimal form is {project}.{domain-name}.{version}, and the extended form is {org}.{project}.{domain-type}.{domain-name}.{version}. domain-type SHOULD be one of diamond (core diamond protocol), system (shared functionality such as reentrancy guards, pausing, access control), or business (app-specific functionality such as tokens, guards, modules). Omitting version implies v1, and it MUST only be bumped when the layout changes in a way that is no longer append-only.
Domain struct rules
Each domain MUST have exactly one storage struct and one identifier, and SHOULD be implemented in a dedicated directory named after the domain. Fields MUST always be added only at the end of the struct, preserving append-only status.
Subdomain
A subdomain is a vertical extension that belongs to an existing domain but has isolated storage. Its identifier takes the form {project}.{domain-name}.{version}.{sub-domain}, where the version refers only to the parent domain's version at the time the subdomain was introduced, not an independent versioning scheme. A subdomain MUST have its own ERC-8042 identifier and storage layout, MUST NOT modify or append to the parent domain's storage, and MUST always remain conceptually subordinate to the parent domain.
Storage declaration requirements
The storage struct for each domain MUST be marked with the ERC-8042 NatSpec comment ///@custom:storage-location erc8042:<NAMESPACE_ID>. The standard itself does not newly define a storage location calculation formula; its purpose is to let tooling automatically locate and unambiguously identify domain storage through this comment.
Directory Convention
The directory structure SHOULD reflect domain ownership. Each domain is a logical namespace for storage ownership, and the directory is its physical representation. A facet is merely a logic container that does not own storage, and MAY be placed next to or inside a domain directory. Both the directory name and the storage identifier must carry domain information so that tooling and static analysis can automatically connect selectors, domains, and storage layout.
Upgrade Scenarios
Upgrades are classified not by facet but by the effect a new selector has on domain and storage. Case 1 requires no new storage and is simply added to an existing facet or domain. Case 2 is a horizontal upgrade that introduces state not belonging to any existing domain, which MUST create a new domain, identifier, and storage. Case 3 is a vertical upgrade that requires new variables belonging to an existing domain, and MAY choose between appending fields to the end of the existing struct (Option A) or creating a new sub-domain (Option B). Case 4 is a breaking layout change, which MUST create a newly versioned identifier and layout, and data migration MUST be handled by the project itself.
Proposal status
This standard is currently in Draft status, a proposal that has not yet been finalized and whose content may change or be discontinued.
Things to watch out for
- Reduced storage collisions: Using explicit, deterministic storage identifiers per domain reduces the risk of storage collisions between unrelated facets or upgrades.
- Prevents mistakes from identifier reuse: Enforcing a consistent naming convention reduces human error from inconsistent or reused identifiers.
- Append-only layout and state preservation: When each domain owns its own ERC-8042 identifier and extends its storage layout in an append-only manner, storage can evolve safely without touching existing state.