{"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":"Storage is organized into named namespaces preventing upgrade collisions — enables safer contract evolution. Design implications: in developer tools, show storage namespace annotations, display namespace IDs in storage explorers, indicate namespace-safe upgrades. Design decisions: mostly invisible to end users but critical for developer UX; surface namespace conflicts as clear errors during upgrade simulations rather than cryptic storage collision warnings.","hasDetailedContent":true,"content":{"id":"ERC-7201","sources":[{"label":"Official specification","url":"https://eips.ethereum.org/EIPS/erc-7201","type":"official-spec"}],"lastReviewed":"2026-05-25","lastUpdated":"2026-05-25","summary":"Storage is organized into named namespaces preventing upgrade collisions — enables safer contract evolution.","designerTakeaways":["You can annotate storage views with namespace labels in developer explorers.","Your upgrade simulator can block publish on namespace conflict with plain English error.","You can keep end-user transaction UI unchanged — 7201 is dev-facing infrastructure."],"applicability":{"whenToUse":["Developer tools for upgradeable contracts using ERC-7201.","Upgrade simulation before mainnet deploy.","Storage layout documentation products."],"whenToAvoid":["End-user consumer wallets with no upgrade tools.","Non-upgradeable contracts.","No dev mode in product."]},"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","Safe badge","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":"Two layouts claim same namespace — upgrade unsafe."},{"label":"Simulation","description":"Test upgrade off-chain before users hit reverts."},{"label":"End user","description":"Never sees namespaces — feels single contract."},{"label":"Annotation","description":"Dev tools label slots by namespace for readability."}],"statesToDesign":[{"state":"Clean upgrade sim","trigger":"No namespace conflict.","userNeed":"Deploy confidence.","designResponse":"Safe to upgrade green state."},{"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":"End users unaffected.","designResponse":"No change to retail confirm UI."},{"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":"Conflict error copy?","recommendation":"Namespace [name] already used by [module] — pick new id.","rationale":"Actionable dev errors reduce incidents."},{"question":"Integrate with Tenderly-style sim?","recommendation":"Yes — conflict gate before deploy button enables.","rationale":"Simulation is the UX surface."}],"problemsSolved":[{"problem":"Storage collision brick upgrades","oldWay":"Cryptic storage overlap revert on mainnet","newWay":"Namespace ids prevent collision; sim catches early","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":"Dev tooling blocks bad deploys first","impact":"high"}],"uxPatterns":[{"name":"Namespace Storage Explorer","description":"Dev view of labeled storage namespaces.","mockup":"concept/proxy-pattern","components":["NamespaceLabel","SlotTable","VariableRow"],"userFlow":["Open dev explorer","Browse namespaces","Inspect slots"]},{"name":"Upgrade Conflict Gate","description":"Block deploy on namespace collision.","mockup":"concept/typed-data","components":["SimResult","ConflictBanner","DeployBlock"],"userFlow":["Run upgrade sim","Conflict found","Error shown","Fix and retry"]}],"seenInTheWild":[{"app":"Tenderly","url":"https://tenderly.co/","note":"Upgrade simulation and storage inspection."},{"app":"OpenZeppelin Defender","url":"https://www.openzeppelin.com/defender","note":"Upgrade admin tooling patterns."},{"app":"Etherscan","url":"https://etherscan.io/","note":"Contract read/write tab for devs."}],"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":"Deploy enabled despite sim conflict","why":"User-facing reverts ship","instead":"Hard block deploy until clean sim","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."}],"onMonad":[{"aspect":"Upgrade tooling","ethereum":"Same dev UX need","monad":"Namespace layout equally critical on Monad deploys","designImplication":"Include Monad in upgrade simulators day one."},{"aspect":"Sim speed","ethereum":"Slow sim loops","monad":"Fast sim encourages pre-deploy checks","designImplication":"Inline sim on every upgrade PR on Monad."}],"technicalNotes":"ERC-7201 is dev-facing; never expose namespace ids in end-user transaction UI.","relatedStandards":[{"id":"ERC-2535","relationship":"Diamond upgrades use namespaced storage"},{"id":"EIP-1967","relationship":"Proxy storage standard family"}]},"sources":[{"label":"Official specification","url":"https://eips.ethereum.org/EIPS/erc-7201","type":"official-spec"},{"label":"Discussion","url":"https://ethereum-magicians.org/search?q=ERC-7201","type":"discussion"},{"label":"Official specification","url":"https://eips.ethereum.org/EIPS/erc-7201","type":"official-spec"}],"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://eips.ethereum.org/EIPS/erc-7201","discussion":"https://ethereum-magicians.org/search?q=ERC-7201"},"freshness":{"lastReviewed":"2026-05-25","lastUpdated":"2026-05-25"}}