ERC-7201, previously known as EIP-7201, establishes a framework for organizing storage variables within smart contracts. This standard employs namespaces, which are unique identifiers that group related variables together. The aim is to simplify the management of these variables during contract upgrades by providing clear documentation through NatSpec annotations.
It is important to note that the word Namespace is not pioneered by solidity or EIP-720, as it is commonly used to describe a way to group related functions, classes, or modules in programming languages. This pattern has been seen in the past with the diamond proxy pattern (ERC-2535). However, it is entirely independent of the ERC-720.
Namespaced storage, introduced by ERC-7201, mitigates conflicts that can occur with data storage in EVM contracts. This approach offers a structured and organized method for handling state variables, which is particularly beneficial in large, complex software systems. A namespace comprises a set of ordered variables, which may include dynamic arrays or mappings, arranged according to the same principles as the default storage layout but rooted in a location other than slot 0. This systematic organization ensures efficient and conflict-free management of storage variables.
Contracts using namespaced storage categorize state variables into groups, represented as structs, and assign these groups to specific namespaces. This isolation of variables within namespaces prevents conflicts and collisions when new variables are introduced, or existing ones are modified or deprecated. A namespace identifier (ID) is a string used to identify a namespace within a contract. This identifier must not contain whitespace characters to ensure clarity and consistency. Using this methodology, developers can maintain the integrity and stability of smart contracts during updates.
It is important to note that the word Namespace is not pioneered by solidity or EIP-720, as it is commonly used to describe a way to group related functions, classes, or modules in programming languages. This pattern has been seen in the past with the diamond proxy pattern (ERC-2535). However, it is entirely independent of the ERC-720.
Namespaced storage, introduced by ERC-7201, mitigates conflicts that can occur with data storage in EVM contracts. This approach offers a structured and organized method for handling state variables, which is particularly beneficial in large, complex software systems. A namespace comprises a set of ordered variables, which may include dynamic arrays or mappings, arranged according to the same principles as the default storage layout but rooted in a location other than slot 0. This systematic organization ensures efficient and conflict-free management of storage variables.
Contracts using namespaced storage categorize state variables into groups, represented as structs, and assign these groups to specific namespaces. This isolation of variables within namespaces prevents conflicts and collisions when new variables are introduced, or existing ones are modified or deprecated. A namespace identifier (ID) is a string used to identify a namespace within a contract. This identifier must not contain whitespace characters to ensure clarity and consistency. Using this methodology, developers can maintain the integrity and stability of smart contracts during updates.
(Example from original EIP)
The formula for calculating namespace-based storage roots
The ERC-7201 standard defines a specific formula to calculate the storage root for a namespace:
Formula: erc7201(id: string) = keccak256(keccak256(id) - 1) & ~0xff
Solidity Expression:
`keccak256(abi.encode(uint256(keccak256(bytes(id))) - 1)) & ~bytes32(uint256(0xff))`
This formula ensures that the storage location for each namespace is unique and consistent. The annotation for this formula is @custom :storage-location erc7201:<NAMESPACE_ID>.
For example, @custom :storage-location erc7201:foobar is used to annotate the namespace with ID "foobar".
Why should you use this?
Well, to be totally honest, the use-case of such an implementation is rather cosmetical in my opinion. It kind of takes the same approach from the diamond proxy pattern but translates this into one single contract. If your contract exposes different functionalities, you may want to split the storage for each functionality. However, i've rarely seen anyone doing this.
Here's a breakdown of how this works:
Double Hashing with Adjustment: By taking the keccak256 hash of the namespace ID and then adjusting it (subtracting 1), the formula generates a unique identifier that is unlikely to collide with typical storage slot addresses.
Masking with ~0xff: The bitwise AND operation with ~0xff (which inverts the last byte to zeros) further reduces the likelihood of collision with the default storage slots, which are usually sequential and straightforward.
