ERC-7201 — Namespaced Storage Layout

Back to Infrastructure & Patterns

ERC-7201: Namespaced Storage Layout

ERC-7201 standardises how upgradeable Solidity contracts compute non-colliding storage slots: hash the namespace string with keccak256 and store everything under that root. Without this, two facets in a diamond proxy can collide on slot 0 and silently corrupt each other.

Required Convention

// keccak256(abi.encode(uint256(keccak256("erc7201:my.namespace")) - 1))
//   & ~bytes32(uint256(0xff))
bytes32 constant MY_STORAGE = 0xa1b2c3...;

struct MyStorage { uint256 totalSupply; mapping(address => uint256) balances; }

function _store() private pure returns (MyStorage storage $) {
    assembly { $.slot := MY_STORAGE }
}

Neo Equivalent

The Neo storage model is byte-prefix based by convention — every contract picks a single-byte prefix per logical map. Collision is structurally avoided because prefix bytes are short, hand-picked, and visible in the source. The "port" below just demonstrates the canonical Neo idiom.

Live on Neo TestNet

Both implementations are deployed on Neo N3 TestNet (network magic 894710606).

Implementation	Contract Hash	Deploy Tx
Solidity (neo-solc)	0xbb2553c79f3a740113bf22fbadb6828a9bdbdf32	(reused — see 0xbb2553c79f3a740113bf22fbadb6828a9bdbdf32)
Neo C# (nccs)	0x0932ad78b3d71c7af06468604f1d00ef89c3205d	(reused — see 0x0932ad78b3d71c7af06468604f1d00ef89c3205d)

Cross-implementation invocations match on all read methods. Source pairs under docs/standards-mirror/deployments/erc-7201/.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

abstract contract MyContract {
    // ERC-7201 namespace: keccak256("my.demo.storage") - 1, masked
    bytes32 private constant STORAGE_LOCATION =
        0xc7d3a4b2c8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8090a1b2c3d4e00;

    struct Storage {
        uint256 totalSupply;
        mapping(address => uint256) balances;
        mapping(address => mapping(address => uint256)) allowances;
    }

    function _store() private pure returns (Storage storage $) {
        assembly { $.slot := STORAGE_LOCATION }
    }

    function totalSupply() public view returns (uint256) {
        return _store().totalSupply;
    }

    function balanceOf(address a) public view returns (uint256) {
        return _store().balances[a];
    }
}

using System;
using System.ComponentModel;
using System.Numerics;
using Neo;
using Neo.SmartContract.Framework;
using Neo.SmartContract.Framework.Attributes;
using Neo.SmartContract.Framework.Native;
using Neo.SmartContract.Framework.Services;

namespace R3E.Examples;

/// <summary>
/// Idiomatic Neo storage namespacing: every logical collection gets a unique
/// single-byte prefix. Prefixes are short, hand-picked, and visible at the
/// top of the contract — no hashing dance required. Collision is structurally
/// impossible: when a developer adds a new collection, they pick the next free byte.
/// </summary>
[DisplayName("DemoToken")]
[ContractPermission("*", "*")]
public class DemoToken : SmartContract
{
    // === Storage namespace ======================================================
    // Prefix layout (visible at-a-glance in source):
    //   0x00  TotalSupply scalar
    //   0x01  Balances map      (account -> BigInteger)
    //   0x02  Allowances map    (owner+spender -> BigInteger)
    //   0xfe  Version
    //   0xff  Owner
    private const byte Prefix_TotalSupply = 0x00;
    private const byte Prefix_Balance     = 0x01;
    private const byte Prefix_Allowance   = 0x02;

    public static BigInteger TotalSupply()
        => (BigInteger)(Storage.Get(Storage.CurrentContext,
                                    new byte[] { Prefix_TotalSupply }) ?? ByteString.Empty);

    public static BigInteger BalanceOf(UInt160 a)
        => (BigInteger)(Storage.Get(Storage.CurrentContext,
                                    new byte[] { Prefix_Balance }.Concat(a)) ?? ByteString.Empty);

    public static BigInteger AllowanceOf(UInt160 owner, UInt160 spender)
        => (BigInteger)(Storage.Get(Storage.CurrentContext,
                                    new byte[] { Prefix_Allowance }.Concat(owner).Concat(spender))
                       ?? ByteString.Empty);
}

Why Hashing Isn't Needed

In Solidity, slots are 256-bit integers and storage is one big array indexed by slot. The compiler picks slot 0, slot 1, etc. unless you override. Two contracts using slot 0 in a diamond will collide unless you hash to a "random" slot, hence ERC-7201.

In Neo, storage is a key-value store keyed by arbitrary byte arrays. Prefix bytes are explicit — you SEE the namespace. There's nothing to overwrite, nothing to hash. Storage layout is part of the source, not derived by the compiler.