From 2b55bbbf73dc46c1df9766181401c11ee3a385c2 Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Fri, 22 Sep 2023 16:55:43 -0300 Subject: [PATCH 1/8] add note about other formulas --- EIPS/eip-7201.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/EIPS/eip-7201.md b/EIPS/eip-7201.md index 0ca264c6590b2..aec7db0064b57 100644 --- a/EIPS/eip-7201.md +++ b/EIPS/eip-7201.md @@ -28,9 +28,11 @@ A _namespace_ consists of a set of ordered variables, some of which may be dynam A _namespace id_ is a string that uniquely identifies a namespace in a contract. It should not contain any whitespace characters. -The storage location for a namespace is defined as `ns_loc(id: string) = keccak256(keccak256(id) - 1) & ~0xff`. +The storage location for an ERC-7201 namespace is defined as `erc7201(id: string) = keccak256(keccak256(id) - 1) & ~0xff`. In Solidity, this corresponds to the expression `keccak256(abi.encode(uint256(keccak256(id)) - 1)) & ~bytes32(uint256(0xff))`. -A Solidity contract using namespaced storage can annotate a struct with the NatSpec tag `@custom:storage-location erc7201:` to identify it as a namespace with 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. +A Solidity contract using namespaced storage can annotate a struct with the NatSpec tag `@custom:storage-location :` to identify it as a namespace. `` identifies the formula used to compute the location based on the namespace id. The formula specified in this ERC can be identified as `erc7201`. For example, an ERC-7201 namespace with id `foobar` would be annotated as `@custom:storage-location erc7201:foobar`. _(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. + +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`. ## Rationale From 56a69b525845a2a0f877910286a7284607b1b0f1 Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Fri, 22 Sep 2023 17:06:07 -0300 Subject: [PATCH 2/8] add security considerations --- EIPS/eip-7201.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-7201.md b/EIPS/eip-7201.md index aec7db0064b57..56a9ec644b095 100644 --- a/EIPS/eip-7201.md +++ b/EIPS/eip-7201.md @@ -84,7 +84,7 @@ contract Example { ## Security Considerations -Needs discussion. +Namespaces should avoid collisions with other namespaces or with standard Solidity or Vyper storage layout. ERC-7201 guarantees this property for arbitrary namespace ids under the assumption of keccak256 collision resistance, as discussed in Rationale. ## Copyright From 5f8c7661658a18a47766f439e74b01718669131a Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Fri, 22 Sep 2023 17:38:12 -0300 Subject: [PATCH 3/8] improve specification --- EIPS/eip-7201.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/EIPS/eip-7201.md b/EIPS/eip-7201.md index 56a9ec644b095..53b93d040a930 100644 --- a/EIPS/eip-7201.md +++ b/EIPS/eip-7201.md @@ -24,13 +24,13 @@ These storage usage patterns are invisible to the Solidity and Vyper compilers b ## Specification -A _namespace_ consists of a set of ordered variables, some of which may be dynamic arrays or mappings, with its values laid out following the same rules as the default storage layout but rooted in some location that is not necessarily slot 0. It should be implemented as a struct. +A _namespace_ consists of a set of ordered variables, some of which may be dynamic arrays or mappings, with its values laid out following the same rules as the default storage layout but rooted in some location that is not necessarily slot 0. A contract using namespaces to organize storage is said to use _namespaced storage_. -A _namespace id_ is a string that uniquely identifies a namespace in a contract. It should not contain any whitespace characters. +A _namespace id_ is a string that identifies a namespace in a contract. It should not contain any whitespace characters. -The storage location for an ERC-7201 namespace is defined as `erc7201(id: string) = keccak256(keccak256(id) - 1) & ~0xff`. In Solidity, this corresponds to the expression `keccak256(abi.encode(uint256(keccak256(id)) - 1)) & ~bytes32(uint256(0xff))`. +A namespace in a contract is usually implemented as a struct type. Solidity contracts using namespaced storage should annotate a struct with the NatSpec tag `@custom:storage-location :` if it is used as a namespace, where `` 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. -A Solidity contract using namespaced storage can annotate a struct with the NatSpec tag `@custom:storage-location :` to identify it as a namespace. `` identifies the formula used to compute the location based on the namespace id. The formula specified in this ERC can be identified as `erc7201`. For example, an ERC-7201 namespace with id `foobar` would be annotated as `@custom:storage-location erc7201:foobar`. _(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. +The formula identified by `erc7201` is defined as `erc7201(id: string) = keccak256(keccak256(id) - 1) & ~0xff`. In Solidity, this corresponds to the expression `keccak256(abi.encode(uint256(keccak256(id)) - 1)) & ~bytes32(uint256(0xff))`. When using this formula the annotation becomes `@custom:storage-location erc7201:`, for example `@custom:storage-location erc7201:foobar` for id `"foobar"`. 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`. From 0b370fd1d33fa2f7703c7742be04c7ec0871497d Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Fri, 22 Sep 2023 17:42:37 -0300 Subject: [PATCH 4/8] improve spec --- EIPS/eip-7201.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-7201.md b/EIPS/eip-7201.md index 53b93d040a930..b735b93449bb5 100644 --- a/EIPS/eip-7201.md +++ b/EIPS/eip-7201.md @@ -28,7 +28,7 @@ A _namespace_ consists of a set of ordered variables, some of which may be dynam A _namespace id_ is a string that identifies a namespace in a contract. It should not contain any whitespace characters. -A namespace in a contract is usually implemented as a struct type. Solidity contracts using namespaced storage should annotate a struct with the NatSpec tag `@custom:storage-location :` if it is used as a namespace, where `` 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. +A namespace in a contract should be implemented as a struct type. These structs should be annotated with the NatSpec tag `@custom:storage-location :`, where `` 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. The formula identified by `erc7201` is defined as `erc7201(id: string) = keccak256(keccak256(id) - 1) & ~0xff`. In Solidity, this corresponds to the expression `keccak256(abi.encode(uint256(keccak256(id)) - 1)) & ~bytes32(uint256(0xff))`. When using this formula the annotation becomes `@custom:storage-location erc7201:`, for example `@custom:storage-location erc7201:foobar` for id `"foobar"`. From 707c09c9536856b50cc631b84f3a962d3784756c Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Fri, 22 Sep 2023 17:44:52 -0300 Subject: [PATCH 5/8] improve example --- EIPS/eip-7201.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-7201.md b/EIPS/eip-7201.md index b735b93449bb5..2ad6a617e9dd6 100644 --- a/EIPS/eip-7201.md +++ b/EIPS/eip-7201.md @@ -30,7 +30,7 @@ A _namespace id_ is a string that identifies a namespace in a contract. It shoul A namespace in a contract should be implemented as a struct type. These structs should be annotated with the NatSpec tag `@custom:storage-location :`, where `` 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. -The formula identified by `erc7201` is defined as `erc7201(id: string) = keccak256(keccak256(id) - 1) & ~0xff`. In Solidity, this corresponds to the expression `keccak256(abi.encode(uint256(keccak256(id)) - 1)) & ~bytes32(uint256(0xff))`. When using this formula the annotation becomes `@custom:storage-location erc7201:`, for example `@custom:storage-location erc7201:foobar` for id `"foobar"`. +The formula identified by `erc7201` is defined as `erc7201(id: string) = keccak256(keccak256(id) - 1) & ~0xff`. In Solidity, this corresponds to the expression `keccak256(abi.encode(uint256(keccak256(id)) - 1)) & ~bytes32(uint256(0xff))`. When using this formula the annotation becomes `@custom:storage-location erc7201:`. For example, `@custom:storage-location erc7201:foobar` annotates a namespace with id `"foobar"` rooted at `erc7201("foobar")`. 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`. From be9597a7fdd01fc368a1f730b5172d518a45a6c6 Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Fri, 22 Sep 2023 18:47:26 -0300 Subject: [PATCH 6/8] add other security consideration --- EIPS/eip-7201.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/EIPS/eip-7201.md b/EIPS/eip-7201.md index 2ad6a617e9dd6..5c9e0c9e0e2fb 100644 --- a/EIPS/eip-7201.md +++ b/EIPS/eip-7201.md @@ -86,6 +86,8 @@ contract Example { Namespaces should avoid collisions with other namespaces or with standard Solidity or Vyper storage layout. ERC-7201 guarantees this property for arbitrary namespace ids under the assumption of keccak256 collision resistance, as discussed in Rationale. +`@custom:storage-location` is a NatSpec annotation that is currently ignored by compilers. The contract developer is responsible for implementing the pattern and using the namespace as claimed in the annotation. + ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md). From 03d793d5e417eb280fb1d16f19c9067f4a256290 Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Fri, 22 Sep 2023 18:49:00 -0300 Subject: [PATCH 7/8] fix --- EIPS/eip-7201.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-7201.md b/EIPS/eip-7201.md index 5c9e0c9e0e2fb..cb61a8bca4eb3 100644 --- a/EIPS/eip-7201.md +++ b/EIPS/eip-7201.md @@ -84,7 +84,7 @@ contract Example { ## Security Considerations -Namespaces should avoid collisions with other namespaces or with standard Solidity or Vyper storage layout. ERC-7201 guarantees this property for arbitrary namespace ids under the assumption of keccak256 collision resistance, as discussed in Rationale. +Namespaces 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. `@custom:storage-location` is a NatSpec annotation that is currently ignored by compilers. The contract developer is responsible for implementing the pattern and using the namespace as claimed in the annotation. From 277047163ee2a692cc5e6f4b8fbc740a5b0cbda9 Mon Sep 17 00:00:00 2001 From: Francisco Giordano Date: Fri, 22 Sep 2023 19:09:56 -0300 Subject: [PATCH 8/8] improve --- EIPS/eip-7201.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-7201.md b/EIPS/eip-7201.md index cb61a8bca4eb3..1befd3dd500be 100644 --- a/EIPS/eip-7201.md +++ b/EIPS/eip-7201.md @@ -86,7 +86,7 @@ contract Example { Namespaces 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. -`@custom:storage-location` is a NatSpec annotation that is currently ignored by compilers. The contract developer is responsible for implementing the pattern and using the namespace as claimed in the annotation. +`@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. ## Copyright