# ERC-7201: Namespaced Storage Layout

Source: https://www.eipsfordesigners.com/standards/ERC-7201
Agent brief: https://www.eipsfordesigners.com/standards/ERC-7201/agent.md
Machine-readable JSON: https://www.eipsfordesigners.com/api/standards/ERC-7201
Last reviewed: 2026-05-25
Last updated: 2026-05-25

| Field | Value |
| --- | --- |
| Status | Final |
| Chain | both |
| Category | Infrastructure |
| Journey stages | Infrastructure |
| Detailed guide | Yes |
| Official specification | https://eips.ethereum.org/EIPS/erc-7201 |
| Discussion search | https://ethereum-magicians.org/search?q=ERC-7201 |

## UX Impact

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.

## Summary

Storage is organized into named namespaces preventing upgrade collisions — enables safer contract evolution.

## For Designers

- 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

### When to Use

- Developer tools for upgradeable contracts using ERC-7201.
- Upgrade simulation before mainnet deploy.
- Storage layout documentation products.

### When to Avoid

- End-user consumer wallets with no upgrade tools.
- Non-upgradeable contracts.
- No dev mode in product.

## Problems It Solves

### Storage collision brick upgrades

Impact: critical

Old way: Cryptic storage overlap revert on mainnet

New way: Namespace ids prevent collision; sim catches early

### User-facing upgrade failures

Impact: high

Old way: Surprise reverts after bad upgrade

New way: Dev tooling blocks bad deploys first

### Opaque storage layouts

Impact: medium

Old way: Raw slot hex in explorers

New way: Namespace annotations in dev tools

## Anti-Patterns

### Generic storage collision hex error

Severity: critical

Devs cannot fix

Instead: Name both conflicting namespaces

### Deploy enabled despite sim conflict

Severity: critical

User-facing reverts ship

Instead: Hard block deploy until clean sim

### Namespace jargon on wallet confirm

Severity: high

Confuses retail users

Instead: Dev tools only

## Design Decisions

### Show namespaces to end users?

Recommendation: Never on send/confirm flows.

Rationale: 7201 is implementation detail.

### Conflict error copy?

Recommendation: Namespace [name] already used by [module] — pick new id.

Rationale: Actionable dev errors reduce incidents.

### Integrate with Tenderly-style sim?

Recommendation: Yes — conflict gate before deploy button enables.

Rationale: Simulation is the UX surface.

## States to Design

### Clean upgrade sim

Trigger: No namespace conflict.

User need: Deploy confidence.

Design response: Safe to upgrade green state.

### Namespace conflict

Trigger: Collision detected.

User need: Fix before ship.

Design response: Block deploy; name conflicting namespaces.

### Storage explorer browse

Trigger: Dev inspects contract.

User need: Map variables to namespaces.

Design response: Labeled namespace groups.

### Post-upgrade

Trigger: Upgrade live.

User need: End users unaffected.

Design response: No change to retail confirm UI.

### Missing annotation

Trigger: Legacy contract.

User need: Graceful fallback.

Design response: Unlabeled storage with docs link.

## Vocabulary

- Use "Storage section" instead of "Namespace id 0x...": Dev-friendly grouping term.

- Use "Conflict between sections" instead of "Storage slot collision": Plain error headline.

- Use "Upgrade simulation" instead of "dry-run diamondCut": Dev action language.

## What to Prototype First

### Storage namespace explorer

Devs inspect layout before upgrade.

Covers: Multiple namespaces, Single namespace

- Namespace id label
- Slot ranges
- Variable names

### Upgrade simulation conflict

Catch collision pre-deploy.

Covers: Conflict detected, Clean sim

- Red conflict banner
- Colliding namespaces named
- Fix suggestion

### Upgrade diff preview

Show which namespaces change.

Covers: Namespace added, Unchanged

- Diff table
- Safe badge
- Deploy blocked if conflict

### End-user tx (unchanged)

Confirm dev tools do not leak to retail.

Covers: Normal send

- Standard confirm — no namespace UI

## Mental Model

### Namespace

Isolated storage bucket with unique id.

### Collision

Two layouts claim same namespace — upgrade unsafe.

### Simulation

Test upgrade off-chain before users hit reverts.

### End user

Never sees namespaces — feels single contract.

### Annotation

Dev tools label slots by namespace for readability.

## Seen in the Wild

- Tenderly: Upgrade simulation and storage inspection. (https://tenderly.co/)

- OpenZeppelin Defender: Upgrade admin tooling patterns. (https://www.openzeppelin.com/defender)

- Etherscan: Contract read/write tab for devs. (https://etherscan.io/)

## On Monad

### Upgrade tooling

Ethereum: Same dev UX need

Monad: Namespace layout equally critical on Monad deploys

Design implication: Include Monad in upgrade simulators day one.

### Sim speed

Ethereum: Slow sim loops

Monad: Fast sim encourages pre-deploy checks

Design implication: Inline sim on every upgrade PR on Monad.

## UX Patterns

### Namespace Storage Explorer

Dev view of labeled storage namespaces.

Components: NamespaceLabel, SlotTable, VariableRow

User flow:

- Open dev explorer
- Browse namespaces
- Inspect slots

Mockup registry key: `concept/proxy-pattern` (React UI on the live standard page).

### Upgrade Conflict Gate

Block deploy on namespace collision.

Components: SimResult, ConflictBanner, DeployBlock

User flow:

- Run upgrade sim
- Conflict found
- Error shown
- Fix and retry

Mockup registry key: `concept/typed-data` (React UI on the live standard page).

## Related Standards

- ERC-2535: Diamond upgrades use namespaced storage

- EIP-1967: Proxy storage standard family

## Technical Notes

ERC-7201 is dev-facing; never expose namespace ids in end-user transaction UI.