{"id":"ERC-7201","name":"Namespaced Storage Layout","status":"Final","chain":"both","category":{"id":"infrastructure","name":"Infrastructure","description":"Foundational patterns enabling other standards"},"journeyStages":[{"id":"infra","name":"Infrastructure","description":"Foundational patterns"}],"uxImpact":"ERC-7201 defines named storage namespaces and their location formula. Correct implementations can reduce storage-collision risk, while developer tools can explain the checks performed. A namespace check alone does not prove that an upgrade is safe.","officialUrl":"https://ercs.ethereum.org/ERCS/erc-7201","lastReviewed":"2026-09-18","lastUpdated":"2026-09-18","kind":"proposal","hasDetailedContent":true,"content":{"id":"ERC-7201","specConstraints":[{"id":"namespace-storage-safety","constraint":"Namespaced storage should avoid collisions and follow the namespace annotation claimed by the contract developer.","appliesTo":"account-implementation","normativity":"security-considerations","specQuote":"## Security Considerations\n\nNamespaces should avoid collisions with other namespaces or with standard Solidity or Vyper storage layout. The formula defined in this ERC guarantees this property for arbitrary namespace ids under the assumption of keccak256 collision resistance, as discussed in Rationale.\n\n`@custom:storage-location` is a NatSpec annotation that current compilers don't enforce any rules for or ascribe any meaning to. The contract developer is responsible for implementing the pattern and using the namespace as claimed in the annotation.","specSection":"Security Considerations","specUrl":"https://ercs.ethereum.org/ERCS/erc-7201#security-considerations","designImplication":"This is an implementation integration boundary, not a user-facing setting. Do not infer application permissions or state from an unchecked storage annotation."},{"id":"namespace-annotation","constraint":"Namespaces SHOULD be implemented as structs annotated with @custom:storage-location FORMULA_ID:NAMESPACE_ID.","appliesTo":"account-implementation","normativity":"normative","specSection":"Specification > @custom:storage-location","specUrl":"https://ercs.ethereum.org/ERCS/erc-7201#customstorage-location","designImplication":"Developer tools can surface the namespace ID and formula from the struct annotation, while flagging missing or outside-contract annotations instead of treating them as detected namespaces.","specQuote":"A namespace in a contract should be implemented as a struct type. These structs should be annotated with the NatSpec tag `@custom:storage-location <FORMULA_ID>:<NAMESPACE_ID>`, where `<FORMULA_ID>` identifies a formula used to compute the storage location where the namespace is rooted, based on the namespace id. _(Note: The Solidity compiler includes this annotation in the AST since v0.8.20, so this is recommended as the minimum compiler version when using this pattern.)_ Structs with this annotation found outside of contracts are not considered to be namespaces for any contract in the source code."},{"id":"namespace-compiler-support","constraint":"Solidity compiler version 0.8.20 or newer is RECOMMENDED for this pattern's AST annotation support.","appliesTo":"infrastructure","normativity":"normative","specSection":"Specification > @custom:storage-location","specUrl":"https://ercs.ethereum.org/ERCS/erc-7201#customstorage-location","designImplication":"Show compiler-version support or an annotation-unavailable state in storage tooling; do not infer that a namespace is absent solely from an older compiler.","specQuote":"A namespace in a contract should be implemented as a struct type. These structs should be annotated with the NatSpec tag `@custom:storage-location <FORMULA_ID>:<NAMESPACE_ID>`, where `<FORMULA_ID>` identifies a formula used to compute the storage location where the namespace is rooted, based on the namespace id. _(Note: The Solidity compiler includes this annotation in the AST since v0.8.20, so this is recommended as the minimum compiler version when using this pattern.)_ Structs with this annotation found outside of contracts are not considered to be namespaces for any contract in the source code."},{"id":"formula-identifier-convention","constraint":"Future formulas MAY use unique identifiers, and identifiers are RECOMMENDED to follow the erc1234 convention.","appliesTo":"infrastructure","normativity":"normative","specSection":"Specification > Formula","specUrl":"https://ercs.ethereum.org/ERCS/erc-7201#formula","designImplication":"Allow unknown future formula IDs and display the formula used rather than assuming every namespace uses erc7201.","specQuote":"Future EIPs may define new formulas with unique formula identifiers. It is recommended to follow the convention set in this EIP and use an identifier of the format `erc1234`."}],"sources":[{"label":"Official specification","url":"https://ercs.ethereum.org/ERCS/erc-7201","type":"official-spec"}],"lastReviewed":"2026-09-18","lastUpdated":"2026-09-18","summary":"ERC-7201 defines named storage namespaces and their location formula. Correct implementations can reduce storage-collision risk, while developer tools can explain the checks performed. A namespace check alone does not prove that an upgrade is safe.","designerTakeaways":["Label documented storage namespaces in developer tools.","Report storage checks the upgrade tooling actually performs, including limitations.","Keep namespace details in developer and audit views unless a user decision depends on them."],"applicability":{"whenToUse":["Developer tools for upgradeable contracts using ERC-7201.","Upgrade simulation before mainnet deploy.","Storage layout documentation products."],"whenToAvoid":["The contract does not use ERC-7201 namespaces.","The product cannot inspect the layout or state what its analyzer actually checks."]},"prototypeFirst":[{"screen":"Storage namespace explorer","why":"Devs inspect layout before upgrade.","covers":["Multiple namespaces","Single namespace"],"include":["Namespace id label","Slot ranges","Variable names"]},{"screen":"Upgrade simulation conflict","why":"Catch collision pre-deploy.","covers":["Conflict detected","Clean sim"],"include":["Red conflict banner","Colliding namespaces named","Fix suggestion"]},{"screen":"Upgrade diff preview","why":"Show which namespaces change.","covers":["Namespace added","Unchanged"],"include":["Diff table","No namespace conflict detected label","Deploy blocked if conflict"]},{"screen":"End-user tx (unchanged)","why":"Confirm dev tools do not leak to retail.","covers":["Normal send"],"include":["Standard confirm — no namespace UI"]}],"mentalModel":[{"label":"Namespace","description":"Isolated storage bucket with unique id."},{"label":"Collision","description":"An analyzer may detect incompatible layouts or namespace use. Diagnose the actual storage conflict; reuse of an intended namespace across versions is not itself an error."},{"label":"Simulation","description":"Use a compatible layout analyzer and simulations for their documented checks; neither the annotation nor one successful simulation proves upgrade safety."},{"label":"End user","description":"Most users need the upgrade's behavioral effect and control changes; detailed namespace views serve implementation review."},{"label":"Annotation","description":"Dev tools label slots by namespace for readability."}],"statesToDesign":[{"state":"Clean upgrade sim","trigger":"No namespace conflict.","userNeed":"Deploy confidence.","designResponse":"No namespace conflict detected. Show the checks performed and any layout or authorization checks still required."},{"state":"Namespace conflict","trigger":"Collision detected.","userNeed":"Fix before ship.","designResponse":"Block deploy; name conflicting namespaces."},{"state":"Storage explorer browse","trigger":"Dev inspects contract.","userNeed":"Map variables to namespaces.","designResponse":"Labeled namespace groups."},{"state":"Post-upgrade","trigger":"Upgrade live.","userNeed":"Know whether this upgrade changes behavior or control.","designResponse":"Report verified user-facing changes separately from storage implementation details."},{"state":"Missing annotation","trigger":"Legacy contract.","userNeed":"Graceful fallback.","designResponse":"Unlabeled storage with docs link."}],"designDecisions":[{"question":"Show namespaces to end users?","recommendation":"Never on send/confirm flows.","rationale":"7201 is implementation detail."},{"question":"What should a namespace conflict message recommend?","recommendation":"Identify the affected namespace, variables, and failed compatibility check. Require a storage-preserving correction or an explicitly reviewed migration.","rationale":"Renaming an existing namespace changes its storage location and can disconnect the contract from existing state."},{"question":"Which pre-deployment checks should the UI show?","recommendation":"Use tooling with documented ERC-7201 layout validation. Show separate results for layout, authorization, and simulation, including unsupported checks.","rationale":"A generic simulation does not necessarily detect namespace or layout incompatibility."}],"problemsSolved":[{"problem":"Storage collision brick upgrades","oldWay":"An incompatible upgrade can corrupt or misread existing state, sometimes without reverting.","newWay":"Correct namespace implementation reduces collision risk; a compatible analyzer can detect some layout conflicts","impact":"critical"},{"problem":"Opaque storage layouts","oldWay":"Raw slot hex in explorers","newWay":"Namespace annotations in dev tools","impact":"medium"},{"problem":"User-facing upgrade failures","oldWay":"Surprise reverts after bad upgrade","newWay":"Compatible tooling can detect covered layout conflicts before deployment; its scope and unresolved checks remain visible.","impact":"high"}],"uxPatterns":[{"name":"Namespace Storage Explorer","description":"Dev view of labeled storage namespaces.","components":["NamespaceLabel","SlotTable","VariableRow"],"userFlow":["Open dev explorer","Browse namespaces","Inspect slots"]},{"name":"Upgrade Conflict Gate","description":"Gate deployment on the documented storage-compatibility checks, with an explicit unsupported or unknown result.","components":["SimResult","ConflictBanner","DeployBlock"],"userFlow":["Run documented layout validation and relevant simulation","Inspect any incompatible variables or namespace locations","Preserve existing storage or review an explicit migration","Re-run required checks before enabling deployment"]}],"antiPatterns":[{"pattern":"Namespace jargon on wallet confirm","why":"Confuses retail users","instead":"Dev tools only","severity":"high"},{"pattern":"Generic storage collision hex error","why":"Devs cannot fix","instead":"Name both conflicting namespaces","severity":"critical"},{"pattern":"Treating a clean simulation as complete upgrade validation","why":"Unexercised state and unsupported layout or authorization checks can remain wrong.","instead":"Show the exact checks completed and require relevant compatibility checks; keep unknown results distinct from pass.","severity":"critical"}],"vocabulary":[{"use":"Storage section","avoid":"Namespace id 0x...","why":"Dev-friendly grouping term."},{"use":"Conflict between sections","avoid":"Storage slot collision","why":"Plain error headline."},{"use":"Upgrade simulation","avoid":"dry-run diamondCut","why":"Dev action language."}],"technicalNotes":"ERC-7201 defines the @custom:storage-location annotation and namespace-root formula. Compilers do not enforce the annotation, so developers must implement and use the declared namespace correctly. An analyzer or simulator is separate tooling. Report what it checked and unknown results; absence of a namespace conflict does not prove compatibility, correct authorization or overall upgrade safety.","relatedStandards":[{"id":"ERC-2535","relationship":"Diamond implementations can use namespaced storage; ERC-2535 does not require ERC-7201."},{"id":"ERC-1967","relationship":"Proxy storage standard family"}]},"sources":[{"label":"Official specification","url":"https://ercs.ethereum.org/ERCS/erc-7201","type":"official-spec"},{"label":"Discussion search","url":"https://ethereum-magicians.org/search?q=ERC-7201","type":"discussion"}],"urls":{"canonical":"https://www.eipsfordesigners.com/standards/ERC-7201","markdown":"https://www.eipsfordesigners.com/standards/ERC-7201/content.md","agent":"https://www.eipsfordesigners.com/standards/ERC-7201/agent.md","api":"https://www.eipsfordesigners.com/api/standards/ERC-7201","official":"https://ercs.ethereum.org/ERCS/erc-7201","discussion":"https://ethereum-magicians.org/search?q=ERC-7201"},"freshness":{"lastReviewed":"2026-09-18","lastUpdated":"2026-09-18"}}