From b04b6a8e3cbf8a1b296f5cb1fa156b757d750e90 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 24 Jul 2023 15:52:21 +0100
Subject: [PATCH 1/6] chore(deps-dev): bump word-wrap from 1.2.3 to 1.2.4 in
 /implementations (#228)

Bumps [word-wrap](https://github.com/jonschlinkert/word-wrap) from 1.2.3 to 1.2.4.
- [Release notes](https://github.com/jonschlinkert/word-wrap/releases)
- [Commits](https://github.com/jonschlinkert/word-wrap/compare/1.2.3...1.2.4)

---
updated-dependencies:
- dependency-name: word-wrap
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 implementations/package-lock.json | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/implementations/package-lock.json b/implementations/package-lock.json
index 51dba26c..f85b4c53 100644
--- a/implementations/package-lock.json
+++ b/implementations/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@erc725/smart-contracts",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "@erc725/smart-contracts",
-      "version": "5.0.0",
+      "version": "5.1.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@openzeppelin/contracts": "^4.9.2",
@@ -14577,9 +14577,9 @@
       }
     },
     "node_modules/word-wrap": {
-      "version": "1.2.3",
-      "resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.3.tgz",
-      "integrity": "sha512-Hz/mrNwitNRh/HUAtM/VT/5VH+ygD6DV7mYKZAtHOrbs8U7lvPS6xf7EJKMF0uW1KJCl0H701g3ZGus+muE5vQ==",
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.4.tgz",
+      "integrity": "sha512-2V81OA4ugVo5pRo46hAoD2ivUJx8jXmWXfUkY4KFNw0hEptvN0QfH3K4nHiwzGeKl5rFKedV48QVoqYavy4YpA==",
       "dev": true,
       "engines": {
         "node": ">=0.10.0"
@@ -26171,9 +26171,9 @@
       }
     },
     "word-wrap": {
-      "version": "1.2.3",
-      "resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.3.tgz",
-      "integrity": "sha512-Hz/mrNwitNRh/HUAtM/VT/5VH+ygD6DV7mYKZAtHOrbs8U7lvPS6xf7EJKMF0uW1KJCl0H701g3ZGus+muE5vQ==",
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.4.tgz",
+      "integrity": "sha512-2V81OA4ugVo5pRo46hAoD2ivUJx8jXmWXfUkY4KFNw0hEptvN0QfH3K4nHiwzGeKl5rFKedV48QVoqYavy4YpA==",
       "dev": true
     },
     "wordwrap": {

From a8582c0258aa0fa3da3b3f799b1306c99b591855 Mon Sep 17 00:00:00 2001
From: Jean Cvllr <31145285+CJ42@users.noreply.github.com>
Date: Tue, 25 Jul 2023 08:09:06 +0100
Subject: [PATCH 2/6] docs: improve Natspec comments of smart contracts (#229)

* docs: improve Natspec for interfaces

* docs: update Natspec for implementation and errors

* docs: move `@custom` tags outside of interfaces

* style: apply prettier
---
 implementations/CHANGELOG.md                  |  2 +-
 implementations/contracts/ERC725.sol          | 23 ++++---
 implementations/contracts/ERC725Init.sol      | 26 ++++---
 .../contracts/ERC725InitAbstract.sol          | 21 ++++--
 implementations/contracts/ERC725X.sol         | 23 ++++---
 implementations/contracts/ERC725XCore.sol     | 41 ++++++++----
 implementations/contracts/ERC725XInit.sol     | 28 +++++---
 .../contracts/ERC725XInitAbstract.sol         | 24 +++++--
 implementations/contracts/ERC725Y.sol         | 21 +++---
 implementations/contracts/ERC725YCore.sol     | 49 ++++++++++++--
 implementations/contracts/ERC725YInit.sol     | 26 ++++---
 .../contracts/ERC725YInitAbstract.sol         | 22 ++++--
 implementations/contracts/errors.sol          | 44 ++++++------
 .../contracts/interfaces/IERC725X.sol         | 67 +++++++------------
 .../contracts/interfaces/IERC725Y.sol         | 52 +++++++-------
 15 files changed, 282 insertions(+), 187 deletions(-)

diff --git a/implementations/CHANGELOG.md b/implementations/CHANGELOG.md
index f94421fb..ea9806da 100644
--- a/implementations/CHANGELOG.md
+++ b/implementations/CHANGELOG.md
@@ -16,7 +16,7 @@ All notable changes to this project will be documented in this file. See [standa
 
 - Upgrade to 0.8.17 for default solc compiler version ([#221](https://github.com/ERC725Alliance/ERC725/pull/221))
 
-- Upgrade `@openzeppelin/contracts` to 4.9.2  ([#224](https://github.com/ERC725Alliance/ERC725/pull/224))
+- Upgrade `@openzeppelin/contracts` to 4.9.2 ([#224](https://github.com/ERC725Alliance/ERC725/pull/224))
 
 ## [5.0.0](https://github.com/ERC725Alliance/ERC725/compare/v4.2.0...v5.0.0) (2023-04-26)
 
diff --git a/implementations/contracts/ERC725.sol b/implementations/contracts/ERC725.sol
index 15e1e8b0..4c8c0c9f 100644
--- a/implementations/contracts/ERC725.sol
+++ b/implementations/contracts/ERC725.sol
@@ -11,24 +11,27 @@ import {ERC725YCore} from "./ERC725YCore.sol";
 import {_INTERFACEID_ERC725X, _INTERFACEID_ERC725Y} from "./constants.sol";
 
 /**
- * @title ERC725 bundle
+ * @title ERC725 bundle.
  * @author Fabian Vogelsteller <fabian@lukso.network>
- * @dev Bundles ERC725X and ERC725Y together into one smart contract.
- * This implementation does not have by default a:
- *  - `receive() external payable {}`
- *  - or `fallback() external payable {}`
+ * @dev Bundle ERC725X and ERC725Y together into one smart contract.
+ *
+ * @custom:warning This implementation does not have by default a `receive()` or `fallback()` function.
  */
 contract ERC725 is ERC725XCore, ERC725YCore {
     /**
-     * @notice Sets the owner of the contract
-     * @param newOwner the owner of the contract
+     * @notice Deploying an ERC725 smart contract and setting address `initialOwner` as the contract owner.
+     * @dev Deploy a new ERC725 contract with the provided `initialOwner` as the contract {owner}.
+     * @param initialOwner the owner of the contract.
+     *
+     * @custom:requirements
+     * - `initialOwner` CANNOT be the zero address.
      */
-    constructor(address newOwner) payable {
+    constructor(address initialOwner) payable {
         require(
-            newOwner != address(0),
+            initialOwner != address(0),
             "Ownable: new owner is the zero address"
         );
-        OwnableUnset._setOwner(newOwner);
+        OwnableUnset._setOwner(initialOwner);
     }
 
     /**
diff --git a/implementations/contracts/ERC725Init.sol b/implementations/contracts/ERC725Init.sol
index b1738201..d8eb2259 100644
--- a/implementations/contracts/ERC725Init.sol
+++ b/implementations/contracts/ERC725Init.sol
@@ -5,26 +5,34 @@ pragma solidity ^0.8.0;
 import {ERC725InitAbstract} from "./ERC725InitAbstract.sol";
 
 /**
- * @title Deployable Proxy Implementation of ERC725 bundle
+ * @title Deployable Proxy Implementation of ERC725 bundle.
  * @author Fabian Vogelsteller <fabian@lukso.network>
  * @dev Bundles ERC725XInit and ERC725YInit together into one smart contract.
- * This implementation does not have by default a:
- *  - `receive() external payable {}`
- *  - or `fallback() external payable {}`
+ *
+ * @custom:warning This implementation does not have by default a `receive()` or `fallback()` function.
  */
 contract ERC725Init is ERC725InitAbstract {
     /**
-     * @dev Deploy + lock base contract deployment on deployment
+     * @notice Deploying an ERC725Init smart contract to be used as base contract behind proxy.
+     *
+     * @dev Deploy + lock base contract on deployment, so that the base implementation contract is not owned and controlled by anyone.
+     * (nobody can call the public {initialize} function.
      */
     constructor() {
         _disableInitializers();
     }
 
     /**
-     * @notice Sets the owner of the contract
-     * @param newOwner the owner of the contract
+     * @notice Initialize an ERC725Init smart contract and setting address `initialOwner` as the contract owner.
+     * @dev Initialize a new ERC725Init contract with the provided `initialOwner` as the contract {owner}.
+     * @param initialOwner the owner of the contract.
+     *
+     * @custom:requirements
+     * - `initialOwner` CANNOT be the zero address.
      */
-    function initialize(address newOwner) public payable virtual initializer {
-        ERC725InitAbstract._initialize(newOwner);
+    function initialize(
+        address initialOwner
+    ) public payable virtual initializer {
+        ERC725InitAbstract._initialize(initialOwner);
     }
 }
diff --git a/implementations/contracts/ERC725InitAbstract.sol b/implementations/contracts/ERC725InitAbstract.sol
index a626754d..6d00d479 100644
--- a/implementations/contracts/ERC725InitAbstract.sol
+++ b/implementations/contracts/ERC725InitAbstract.sol
@@ -16,23 +16,32 @@ import {_INTERFACEID_ERC725X, _INTERFACEID_ERC725Y} from "./constants.sol";
 /**
  * @title Inheritable Proxy Implementation of ERC725 bundle
  * @author Fabian Vogelsteller <fabian@lukso.network>
- * @dev Bundles ERC725XInit and ERC725YInit together into one smart contract
+ * @dev Bundles ERC725XInit and ERC725YInit together into one smart contract.
+ *
+ * @custom:warning This implementation does not have by default a `receive()` or `fallback()` function.
  */
 abstract contract ERC725InitAbstract is
     Initializable,
     ERC725XCore,
     ERC725YCore
 {
-    function _initialize(address newOwner) internal virtual onlyInitializing {
+    /**
+     * @dev Internal function to initialize the contract with the provided `initialOwner` as the contract {owner}.
+     * @param initialOwner the owner of the contract.
+     *
+     * @custom:requirements
+     * - `initialOwner` CANNOT be the zero address.
+     */
+    function _initialize(
+        address initialOwner
+    ) internal virtual onlyInitializing {
         require(
-            newOwner != address(0),
+            initialOwner != address(0),
             "Ownable: new owner is the zero address"
         );
-        OwnableUnset._setOwner(newOwner);
+        OwnableUnset._setOwner(initialOwner);
     }
 
-    // NOTE this implementation has not by default: receive() external payable {}
-
     /**
      * @inheritdoc ERC165
      */
diff --git a/implementations/contracts/ERC725X.sol b/implementations/contracts/ERC725X.sol
index b3d40ebd..49d2f962 100644
--- a/implementations/contracts/ERC725X.sol
+++ b/implementations/contracts/ERC725X.sol
@@ -6,22 +6,27 @@ import {OwnableUnset} from "./custom/OwnableUnset.sol";
 import {ERC725XCore} from "./ERC725XCore.sol";
 
 /**
- * @title ERC725 X executor
+ * @title Deployable implementation with `constructor` of ERC725X, a generic executor.
  * @author Fabian Vogelsteller <fabian@lukso.network>
- * @dev Implementation of a contract module which provides the ability to call arbitrary functions at any other smart contract and itself,
- * including using `delegatecall`, `staticcall` as well creating contracts using `create` and `create2`
- * This is the basis for a smart contract based account system, but could also be used as a proxy account system
+ * @dev ERC725X provides the ability to call arbitrary functions on any other smart contract (including itself).
+ * It allows to use different type of message calls to interact with addresses such as `call`, `staticcall` and `delegatecall`.
+ * It also allows to deploy and create new contracts via both the `create` and `create2` opcodes.
+ * This is the basis for a smart contract based account system, but could also be used as a proxy account system.
  */
 contract ERC725X is ERC725XCore {
     /**
-     * @notice Sets the owner of the contract
-     * @param newOwner the owner of the contract
+     * @notice Deploying an ERC725X smart contract and setting address `initialOwner` as the contract owner.
+     * @dev Deploy a new ERC725X contract with the provided `initialOwner` as the contract {owner}.
+     * @param initialOwner the owner of the contract.
+     *
+     * @custom:requirements
+     * - `initialOwner` CANNOT be the zero address.
      */
-    constructor(address newOwner) payable {
+    constructor(address initialOwner) payable {
         require(
-            newOwner != address(0),
+            initialOwner != address(0),
             "Ownable: new owner is the zero address"
         );
-        OwnableUnset._setOwner(newOwner);
+        OwnableUnset._setOwner(initialOwner);
     }
 }
diff --git a/implementations/contracts/ERC725XCore.sol b/implementations/contracts/ERC725XCore.sol
index c988f17d..a514f053 100644
--- a/implementations/contracts/ERC725XCore.sol
+++ b/implementations/contracts/ERC725XCore.sol
@@ -27,15 +27,24 @@ import {
 import "./errors.sol";
 
 /**
- * @title Core implementation of ERC725X executor
+ * @title Core implementation of ERC725X sub-standard, a generic executor.
  * @author Fabian Vogelsteller <fabian@lukso.network>
- * @dev Implementation of a contract module which provides the ability to call arbitrary functions at any other smart contract and itself,
- * including using `delegatecall`, `staticcall` as well creating contracts using `create` and `create2`
- * This is the basis for a smart contract based account system, but could also be used as a proxy account system
+ * It allows to use different type of message calls to interact with addresses such as `call`, `staticcall` and `delegatecall`.
+ * It also allows to deploy and create new contracts via both the `create` and `create2` opcodes.
+ * This is the basis for a smart contract based account system, but could also be used as a proxy account system.
  */
 abstract contract ERC725XCore is OwnableUnset, ERC165, IERC725X {
     /**
      * @inheritdoc IERC725X
+     * @custom:requirements
+     * - SHOULD only be callable by the {owner} of the contract.
+     * - if a `value` is provided, the contract MUST have at least this amount to transfer to `target` from its balance and execute successfully.
+     * - if the operation type is `STATICCALL` (`3`) or `DELEGATECALL` (`4`), `value` transfer is disallowed and SHOULD be 0.
+     * - `target` SHOULD be `address(0)` when deploying a new contract via `operationType` `CREATE` (`1`), or `CREATE2` (`2`).
+     *
+     * @custom:events
+     * - {Executed} event when a call is made with `operationType` 0 (CALL), 3 (STATICCALL) or 4 (DELEGATECALL).
+     * - {ContractCreated} event when deploying a new contract with `operationType` 1 (CREATE) or 2 (CREATE2).
      */
     function execute(
         uint256 operationType,
@@ -48,6 +57,14 @@ abstract contract ERC725XCore is OwnableUnset, ERC165, IERC725X {
 
     /**
      * @inheritdoc IERC725X
+     * @custom:requirements
+     * - All the array parameters provided MUST be equal and have the same length.
+     * - SHOULD only be callable by the {owner} of the contract.
+     * - The contract MUST have in its balance **at least the sum of all the `values`** to transfer and execute successfully each calldata payloads.
+     *
+     * @custom:events
+     * - {Executed} event, when a call is made with `operationType` 0 (CALL), 3 (STATICCALL) or 4 (DELEGATECALL)
+     * - {ContractCreated} event, when deploying a contract with `operationType` 1 (CREATE) or 2 (CREATE2)
      */
     function executeBatch(
         uint256[] memory operationsType,
@@ -70,8 +87,7 @@ abstract contract ERC725XCore is OwnableUnset, ERC165, IERC725X {
     }
 
     /**
-     * @dev check the `operationType` provided and perform the associated low-level opcode.
-     * see `IERC725X.execute(uint256,address,uint256,bytes)`.
+     * @dev check the `operationType` provided and perform the associated low-level opcode after checking for requirements (see {execute}).
      */
     function _execute(
         uint256 operationType,
@@ -125,8 +141,7 @@ abstract contract ERC725XCore is OwnableUnset, ERC165, IERC725X {
     }
 
     /**
-     * @dev same as `_execute` but for batch execution
-     * see `IERC725X,execute(uint256[],address[],uint256[],bytes[])`
+     * @dev check each `operationType` provided in the batch and perform the associated low-level opcode after checking for requirements (see {executeBatch}).
      */
     function _executeBatch(
         uint256[] memory operationsType,
@@ -165,7 +180,7 @@ abstract contract ERC725XCore is OwnableUnset, ERC165, IERC725X {
     }
 
     /**
-     * @dev perform low-level call (operation type = 0)
+     * @dev Perform low-level call (operation type = 0)
      * @param target The address on which call is executed
      * @param value The value to be sent with the call
      * @param data The data to be sent with the call
@@ -195,7 +210,7 @@ abstract contract ERC725XCore is OwnableUnset, ERC165, IERC725X {
     }
 
     /**
-     * @dev perform low-level staticcall (operation type = 3)
+     * @dev Perform low-level staticcall (operation type = 3)
      * @param target The address on which staticcall is executed
      * @param data The data to be sent with the staticcall
      * @return result The data returned from the staticcall
@@ -217,7 +232,7 @@ abstract contract ERC725XCore is OwnableUnset, ERC165, IERC725X {
     }
 
     /**
-     * @dev perform low-level delegatecall (operation type = 4)
+     * @dev Perform low-level delegatecall (operation type = 4)
      * @param target The address on which delegatecall is executed
      * @param data The data to be sent with the delegatecall
      * @return result The data returned from the delegatecall
@@ -239,7 +254,7 @@ abstract contract ERC725XCore is OwnableUnset, ERC165, IERC725X {
     }
 
     /**
-     * @dev deploy a contract using the CREATE opcode (operation type = 1)
+     * @dev Deploy a contract using the `CREATE` opcode (operation type = 1)
      * @param value The value to be sent to the contract created
      * @param creationCode The contract creation bytecode to deploy appended with the constructor argument(s)
      * @return newContract The address of the contract created as bytes
@@ -280,7 +295,7 @@ abstract contract ERC725XCore is OwnableUnset, ERC165, IERC725X {
     }
 
     /**
-     * @dev deploy a contract using the CREATE2 opcode (operation type = 2)
+     * @dev Deploy a contract using the `CREATE2` opcode (operation type = 2)
      * @param value The value to be sent to the contract created
      * @param creationCode The contract creation bytecode to deploy appended with the constructor argument(s) and a bytes32 salt
      * @return newContract The address of the contract created as bytes
diff --git a/implementations/contracts/ERC725XInit.sol b/implementations/contracts/ERC725XInit.sol
index d7b0499a..165d768f 100644
--- a/implementations/contracts/ERC725XInit.sol
+++ b/implementations/contracts/ERC725XInit.sol
@@ -5,25 +5,35 @@ pragma solidity ^0.8.0;
 import {ERC725XInitAbstract} from "./ERC725XInitAbstract.sol";
 
 /**
- * @title Deployable Proxy Implementation of ERC725 X Executor
+ * @title Deployable Proxy Implementation of ERC725X, a generic executor.
  * @author Fabian Vogelsteller <fabian@lukso.network>
- * @dev Implementation of a contract module which provides the ability to call arbitrary functions at any other smart contract and itself,
- * including using `delegatecall`, `staticcall` as well creating contracts using `create` and `create2`
- * This is the basis for a smart contract based account system, but could also be used as a proxy account system
+ * @dev ERC725X provides the ability to call arbitrary functions on any other smart contract (including itself).
+ * It allows to use different type of message calls to interact with addresses such as `call`, `staticcall` and `delegatecall`.
+ * It also allows to deploy and create new contracts via both the `create` and `create2` opcodes.
+ * This is the basis for a smart contract based account system, but could also be used as a proxy account system.
  */
 contract ERC725XInit is ERC725XInitAbstract {
     /**
-     * @dev Deploy + lock base contract deployment on deployment
+     * @notice Deploying an ERC725XInit smart contract to be used as base contract behind proxy.
+     *
+     * @dev Deploy + lock base contract on deployment, so that the base implementation contract is not owned and controlled by anyone.
+     * (nobody can call the public {initialize} function.
      */
     constructor() {
         _disableInitializers();
     }
 
     /**
-     * @notice Sets the owner of the contract
-     * @param newOwner the owner of the contract
+     * @notice Initialize an ERC725XInit smart contract and setting address `initialOwner` as the contract owner.
+     * @dev Initialize a new ERC725XInit contract with the provided `initialOwner` as the contract {owner}.
+     * @param initialOwner the owner of the contract.
+     *
+     * @custom:requirements
+     * - `initialOwner` CANNOT be the zero address.
      */
-    function initialize(address newOwner) public payable virtual initializer {
-        ERC725XInitAbstract._initialize(newOwner);
+    function initialize(
+        address initialOwner
+    ) public payable virtual initializer {
+        ERC725XInitAbstract._initialize(initialOwner);
     }
 }
diff --git a/implementations/contracts/ERC725XInitAbstract.sol b/implementations/contracts/ERC725XInitAbstract.sol
index 5f3539d9..30c611ea 100644
--- a/implementations/contracts/ERC725XInitAbstract.sol
+++ b/implementations/contracts/ERC725XInitAbstract.sol
@@ -9,18 +9,28 @@ import {OwnableUnset} from "./custom/OwnableUnset.sol";
 import {ERC725XCore} from "./ERC725XCore.sol";
 
 /**
- * @title Inheritable Proxy Implementation of ERC725 X Executor
+ * @title Inheritable Proxy Implementation of ERC725X, a generic executor.
  * @author Fabian Vogelsteller <fabian@lukso.network>
- * @dev Implementation of a contract module which provides the ability to call arbitrary functions at any other smart contract and itself,
- * including using `delegatecall`, `staticcall` as well creating contracts using `create` and `create2`
- * This is the basis for a smart contract based account system, but could also be used as a proxy account system
+ * @dev ERC725X provides the ability to call arbitrary functions on any other smart contract (including itself).
+ * It allows to use different type of message calls to interact with addresses such as `call`, `staticcall` and `delegatecall`.
+ * It also allows to deploy and create new contracts via both the `create` and `create2` opcodes.
+ * This is the basis for a smart contract based account system, but could also be used as a proxy account system.
  */
 abstract contract ERC725XInitAbstract is Initializable, ERC725XCore {
-    function _initialize(address newOwner) internal virtual onlyInitializing {
+    /**
+     * @dev Internal function to initialize the contract with the provided `initialOwner` as the contract {owner}.
+     * @param initialOwner the owner of the contract.
+     *
+     * @custom:requirements
+     * - `initialOwner` CANNOT be the zero address.
+     */
+    function _initialize(
+        address initialOwner
+    ) internal virtual onlyInitializing {
         require(
-            newOwner != address(0),
+            initialOwner != address(0),
             "Ownable: new owner is the zero address"
         );
-        OwnableUnset._setOwner(newOwner);
+        OwnableUnset._setOwner(initialOwner);
     }
 }
diff --git a/implementations/contracts/ERC725Y.sol b/implementations/contracts/ERC725Y.sol
index f8597172..789ce426 100644
--- a/implementations/contracts/ERC725Y.sol
+++ b/implementations/contracts/ERC725Y.sol
@@ -7,22 +7,25 @@ import {OwnableUnset} from "./custom/OwnableUnset.sol";
 import {ERC725YCore} from "./ERC725YCore.sol";
 
 /**
- * @title ERC725Y General data key/value store
+ * @title Deployable implementation with `constructor` of ERC725Y, a generic data key/value store.
  * @author Fabian Vogelsteller <fabian@lukso.network>
- * @dev Contract module which provides the ability to set arbitrary data key/value pairs that can be changed over time
- * It is intended to standardise certain data key/value pairs to allow automated read and writes
- * from/to the contract storage
+ * @dev ERC725Y provides the ability to set arbitrary data key/value pairs that can be changed over time.
+ * It is intended to standardise certain data key/value pairs to allow automated read and writes from/to the contract storage.
  */
 contract ERC725Y is ERC725YCore {
     /**
-     * @notice Sets the owner of the contract
-     * @param newOwner the owner of the contract
+     * @notice Deploying an ERC725Y smart contract and setting address `initialOwner` as the contract owner.
+     * @dev Deploy a new ERC725Y contract with the provided `initialOwner` as the contract {owner}.
+     * @param initialOwner the owner of the contract.
+     *
+     * @custom:requirements
+     * - `initialOwner` CANNOT be the zero address.
      */
-    constructor(address newOwner) payable {
+    constructor(address initialOwner) payable {
         require(
-            newOwner != address(0),
+            initialOwner != address(0),
             "Ownable: new owner is the zero address"
         );
-        OwnableUnset._setOwner(newOwner);
+        OwnableUnset._setOwner(initialOwner);
     }
 }
diff --git a/implementations/contracts/ERC725YCore.sol b/implementations/contracts/ERC725YCore.sol
index 3abfbac1..47eb370f 100644
--- a/implementations/contracts/ERC725YCore.sol
+++ b/implementations/contracts/ERC725YCore.sol
@@ -15,15 +15,14 @@ import {_INTERFACEID_ERC725Y} from "./constants.sol";
 import "./errors.sol";
 
 /**
- * @title Core implementation of ERC725Y General data key/value store
+ * @title Core implementation of ERC725Y sub-standard, a general data key/value store.
  * @author Fabian Vogelsteller <fabian@lukso.network>
- * @dev Contract module which provides the ability to set arbitrary data key/value pairs that can be changed over time
- * It is intended to standardise certain data key/value pairs to allow automated read and writes
- * from/to the contract storage
+ * @dev ERC725Y provides the ability to set arbitrary data key/value pairs that can be changed over time.
+ * It is intended to standardise certain data key/value pairs to allow automated read and writes from/to the contract storage.
  */
 abstract contract ERC725YCore is OwnableUnset, ERC165, IERC725Y {
     /**
-     * @dev Map the dataKeys to their dataValues
+     * @dev Map `bytes32` data keys to their `bytes` data values.
      */
     mapping(bytes32 => bytes) internal _store;
 
@@ -58,6 +57,14 @@ abstract contract ERC725YCore is OwnableUnset, ERC165, IERC725Y {
 
     /**
      * @inheritdoc IERC725Y
+     * @custom:requirements
+     * - SHOULD only be callable by the {owner}.
+     *
+     * @custom:warning
+     * **Note for developers:** despite the fact that this function is set as `payable`, if the function is not intended to receive value
+     * (= native tokens), **an additional check should be implemented to ensure that `msg.value` sent was equal to 0**.
+     *
+     * @custom:events {DataChanged} event.
      */
     function setData(
         bytes32 dataKey,
@@ -69,6 +76,14 @@ abstract contract ERC725YCore is OwnableUnset, ERC165, IERC725Y {
 
     /**
      * @inheritdoc IERC725Y
+     * @custom:requirements
+     * - SHOULD only be callable by the {owner} of the contract.
+     *
+     * @custom:warning
+     * **Note for developers:** despite the fact that this function is set as `payable`, if the function is not intended to receive value
+     * (= native tokens), **an additional check should be implemented to ensure that `msg.value` sent was equal to 0**.
+     *
+     * @custom:events {DataChanged} event **for each data key/value pair set**.
      */
     function setDataBatch(
         bytes32[] memory dataKeys,
@@ -95,12 +110,36 @@ abstract contract ERC725YCore is OwnableUnset, ERC165, IERC725Y {
         }
     }
 
+    /**
+     * @dev Read the value stored under a specific `dataKey` inside the underlying ERC725Y storage,
+     *  represented as a mapping of `bytes32` data keys mapped to their `bytes` data values.
+     *
+     * ```solidity
+     * mapping(bytes32 => bytes) _store
+     * ```
+     *
+     * @param dataKey A bytes32 data key to read the associated `bytes` value from the store.
+     * @return dataValue The `bytes` value associated with the given `dataKey` in the ERC725Y storage.
+     */
     function _getData(
         bytes32 dataKey
     ) internal view virtual returns (bytes memory dataValue) {
         return _store[dataKey];
     }
 
+    /**
+     * @dev Write a `dataValue` to the underlying ERC725Y storage, represented as a mapping of
+     * `bytes32` data keys mapped to their `bytes` data values.
+     *
+     * ```solidity
+     * mapping(bytes32 => bytes) _store
+     * ```
+     *
+     * @param dataKey A bytes32 data key to write the associated `bytes` value to the store.
+     * @param dataValue The `bytes` value to associate with the given `dataKey` in the ERC725Y storage.
+     *
+     * @custom:events {DataChanged} event emitted after a successful `setData` call.
+     */
     function _setData(
         bytes32 dataKey,
         bytes memory dataValue
diff --git a/implementations/contracts/ERC725YInit.sol b/implementations/contracts/ERC725YInit.sol
index f86b16cd..5c53d989 100644
--- a/implementations/contracts/ERC725YInit.sol
+++ b/implementations/contracts/ERC725YInit.sol
@@ -5,25 +5,33 @@ pragma solidity ^0.8.0;
 import {ERC725YInitAbstract} from "./ERC725YInitAbstract.sol";
 
 /**
- * @title Deployable Proxy Implementation of ERC725Y General data key/value store
+ * @title Deployable Proxy Implementation of ERC725Y, a generic data key/value store.
  * @author Fabian Vogelsteller <fabian@lukso.network>
- * @dev Contract module which provides the ability to set arbitrary data key/value pairs that can be changed over time
- * It is intended to standardise certain data key/value pairs to allow automated read and writes
- * from/to the contract storage
+ * @dev ERC725Y provides the ability to set arbitrary data key/value pairs that can be changed over time.
+ * It is intended to standardise certain data key/value pairs to allow automated read and writes from/to the contract storage.
  */
 contract ERC725YInit is ERC725YInitAbstract {
     /**
-     * @dev Deploy + lock base contract deployment on deployment
+     * @notice Deploying an ERC725YInit smart contract to be used as base contract behind proxy.
+     *
+     * @dev Deploy + lock base contract on deployment, so that the base implementation contract is not owned and controlled by anyone.
+     * (nobody can call the public {initialize} function.
      */
     constructor() {
         _disableInitializers();
     }
 
     /**
-     * @notice Sets the owner of the contract
-     * @param newOwner the owner of the contract
+     * @notice Initializing an ERC725YInit smart contract and setting address `initialOwner` as the contract owner.
+     * @dev Initialize a new ERC725YInit contract with the provided `initialOwner` as the contract {owner}.
+     * @param initialOwner the owner of the contract.
+     *
+     * @custom:requirements
+     * - `initialOwner` CANNOT be the zero address.
      */
-    function initialize(address newOwner) public payable virtual initializer {
-        ERC725YInitAbstract._initialize(newOwner);
+    function initialize(
+        address initialOwner
+    ) public payable virtual initializer {
+        ERC725YInitAbstract._initialize(initialOwner);
     }
 }
diff --git a/implementations/contracts/ERC725YInitAbstract.sol b/implementations/contracts/ERC725YInitAbstract.sol
index 86f857f3..07010041 100644
--- a/implementations/contracts/ERC725YInitAbstract.sol
+++ b/implementations/contracts/ERC725YInitAbstract.sol
@@ -9,18 +9,26 @@ import {OwnableUnset} from "./custom/OwnableUnset.sol";
 import {ERC725YCore} from "./ERC725YCore.sol";
 
 /**
- * @title Inheritable Proxy Implementation of ERC725Y General data key/value store
+ * @title Inheritable Proxy Implementation of ERC725Y, a generic data key/value store
  * @author Fabian Vogelsteller <fabian@lukso.network>
- * @dev Contract module which provides the ability to set arbitrary data key/value pairs that can be changed over time
- * It is intended to standardise certain data key/value pairs to allow automated read and writes
- * from/to the contract storage
+ * @dev ERC725Y provides the ability to set arbitrary data key/value pairs that can be changed over time.
+ * It is intended to standardise certain data key/value pairs to allow automated read and writes from/to the contract storage.
  */
 abstract contract ERC725YInitAbstract is Initializable, ERC725YCore {
-    function _initialize(address newOwner) internal virtual onlyInitializing {
+    /**
+     * @dev Internal function to initialize the contract with the provided `initialOwner` as the contract {owner}.
+     * @param initialOwner the owner of the contract.
+     *
+     * @custom:requirements
+     * - `initialOwner` CANNOT be the zero address.
+     */
+    function _initialize(
+        address initialOwner
+    ) internal virtual onlyInitializing {
         require(
-            newOwner != address(0),
+            initialOwner != address(0),
             "Ownable: new owner is the zero address"
         );
-        OwnableUnset._setOwner(newOwner);
+        OwnableUnset._setOwner(initialOwner);
     }
 }
diff --git a/implementations/contracts/errors.sol b/implementations/contracts/errors.sol
index 977d2471..664829ad 100644
--- a/implementations/contracts/errors.sol
+++ b/implementations/contracts/errors.sol
@@ -2,72 +2,72 @@
 pragma solidity ^0.8.0;
 
 /**
- * @dev reverts when trying to send more native tokens `value` than available in current `balance`.
- * @param balance the balance of the ERC725X contract.
- * @param value the amount of native tokens sent via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)`.
+ * @dev Reverts when trying to send more native tokens `value` than available in current `balance`.
+ * @param balance The balance of native tokens of the ERC725X smart contract.
+ * @param value The amount of native tokens sent via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)` that is greater than the contract's `balance`.
  */
 error ERC725X_InsufficientBalance(uint256 balance, uint256 value);
 
 /**
- * @dev reverts when the `operationTypeProvided` is none of the default operation types available.
+ * @dev Reverts when the `operationTypeProvided` is none of the default operation types available.
  * (CALL = 0; CREATE = 1; CREATE2 = 2; STATICCALL = 3; DELEGATECALL = 4)
+ * @param operationTypeProvided The unrecognised operation type number provided to `ERC725X.execute(...)`/`ERC725X.executeBatch(...)`.
  */
 error ERC725X_UnknownOperationType(uint256 operationTypeProvided);
 
 /**
- * @dev the `value` parameter (= sending native tokens) is not allowed when making a staticcall
- * via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)` because sending native tokens is a state changing operation.
+ * @dev Reverts when trying to send native tokens (`value` / `values[]` parameter of {execute} or {executeBatch} functions) while making a `staticcall` (`operationType == 3`).
+ * Sending native tokens via `staticcall` is not allowed because it is a state changing operation.
  */
 error ERC725X_MsgValueDisallowedInStaticCall();
 
 /**
- * @dev the `value` parameter (= sending native tokens) is not allowed when making a delegatecall
- * via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)` because msg.value is persisting.
+ * @dev Reverts when trying to send native tokens (`value` / `values[]` parameter of {execute} or {executeBatch} functions) while making a `delegatecall` (`operationType == 4`).
+ * Sending native tokens via `staticcall` is not allowed because `msg.value` is persisting.
  */
 error ERC725X_MsgValueDisallowedInDelegateCall();
 
 /**
- * @dev reverts when passing a `to` address while deploying a contract va `ERC725X.execute(...)`/`ERC725X.executeBatch(...)`
- * whether using operation type 1 (CREATE) or 2 (CREATE2).
+ * @dev Reverts when passing a `to` address that is not `address(0)` (= address zero) while deploying a contract via {execute} or {executeBatch} functions.
+ * This error can occur using either operation type 1 (`CREATE`) or 2 (`CREATE2`).
  */
 error ERC725X_CreateOperationsRequireEmptyRecipientAddress();
 
 /**
- * @dev reverts when contract deployment via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)` failed.
- * whether using operation type 1 (CREATE) or 2 (CREATE2).
+ * @dev Reverts when contract deployment failed via {execute} or {executeBatch} functions,
+ * This error can occur using either operation type 1 (`CREATE`) or 2 (`CREATE2`).
  */
 error ERC725X_ContractDeploymentFailed();
 
 /**
- * @dev reverts when no contract bytecode was provided as parameter when trying to deploy a contract
- * via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)`, whether using operation type 1 (CREATE) or 2 (CREATE2).
+ * @dev Reverts when no contract bytecode was provided as parameter when trying to deploy a contract via {execute} or {executeBatch}.
+ * This error can occur using either operation type 1 (`CREATE`) or 2 (`CREATE2`).
  */
 error ERC725X_NoContractBytecodeProvided();
 
 /**
- * @dev reverts when there is not the same number of operation, to addresses, value, and data.
+ * @dev Reverts when there is not the same number of elements in the `operationTypes`, `targets` addresses, `values`, and `datas`
+ * array parameters provided when calling the {executeBatch} function.
  */
 error ERC725X_ExecuteParametersLengthMismatch();
 
 /**
- * @dev reverts when one of the array parameter provided to
- * `executeBatch(uint256[],address[],uint256[],bytes[]) is an empty array
+ * @dev Reverts when one of the array parameter provided to the {executeBatch} function is an empty array.
  */
 error ERC725X_ExecuteParametersEmptyArray();
 
 /**
- * @dev reverts when there is not the same number of elements in the lists of data keys and data values
- * when calling setDataBatch.
+ * @dev Reverts when there is not the same number of elements in the `datakeys` and `dataValues`
+ * array parameters provided when calling the {setDataBatch} function.
  */
 error ERC725Y_DataKeysValuesLengthMismatch();
 
 /**
- * @dev reverts when one of the array parameter provided to
- * `setDataBatch` is an empty array
+ * @dev Reverts when one of the array parameter provided to {setDataBatch} function is an empty array.
  */
 error ERC725Y_DataKeysValuesEmptyArray();
 
 /**
- * @dev reverts when sending value to the `setData(..)` functions
+ * @dev Reverts when sending value to the {setData} or {setDataBatch} function.
  */
 error ERC725Y_MsgValueDisallowed();
diff --git a/implementations/contracts/interfaces/IERC725X.sol b/implementations/contracts/interfaces/IERC725X.sol
index b78e5cdd..bce92073 100644
--- a/implementations/contracts/interfaces/IERC725X.sol
+++ b/implementations/contracts/interfaces/IERC725X.sol
@@ -5,17 +5,20 @@ pragma solidity ^0.8.0;
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 
 /**
- * @title The interface for ERC725X General executor
- * @dev ERC725X provides the ability to call arbitrary functions at any other smart contract and itself,
- * including using `delegatecall`, `staticcall`, as well as creating contracts using `create` and `create2`
- * This is the basis for a smart contract based account system, but could also be used as a proxy account system
+ * @title The interface for the ERC725X sub-standard, a generic executor.
+ * @dev ERC725X provides the ability to call arbitrary functions on any other smart contract (including itself).
+ * It allows to use different type of message calls to interact with addresses such as `call`, `staticcall` and `delegatecall`.
+ * It also allows to deploy and create new contracts via both the `create` and `create2` opcodes.
+ * This is the basis for a smart contract based account system, but could also be used as a proxy account system.
  */
 interface IERC725X is IERC165 {
     /**
-     * @notice Emitted when deploying a contract
-     * @param operationType The opcode used to deploy the contract (CREATE or CREATE2)
-     * @param contractAddress The created contract address
-     * @param value The amount of native tokens (in Wei) sent to fund the created contract address
+     * @notice Deployed new contract at address `contractAddress` and funded with `value` wei (deployed using opcode: `operationType`).
+     * @dev Emitted when a new contract was created and deployed.
+     * @param operationType The opcode used to deploy the contract (`CREATE` or `CREATE2`).
+     * @param contractAddress The created contract address.
+     * @param value The amount of native tokens (in Wei) sent to fund the created contract on deployment.
+     * @param salt The salt used to deterministically deploy the contract (`CREATE2` only). If `CREATE` opcode is used, the salt value will be `bytes32(0)`.
      */
     event ContractCreated(
         uint256 indexed operationType,
@@ -25,11 +28,12 @@ interface IERC725X is IERC165 {
     );
 
     /**
-     * @notice Emitted when calling an address (EOA or contract)
-     * @param operationType The low-level call opcode used to call the `to` address (CALL, STATICALL or DELEGATECALL)
+     * @notice Called address `target` using `operationType` with `value` wei and `data`.
+     * @dev Emitted when calling an address `target` (EOA or contract) with `value`.
+     * @param operationType The low-level call opcode used to call the `target` address (`CALL`, `STATICALL` or `DELEGATECALL`).
      * @param target The address to call. `target` will be unused if a contract is created (operation types 1 and 2).
-     * @param value The amount of native tokens transferred with the call (in Wei)
-     * @param selector The first 4 bytes (= function selector) of the data sent with the call
+     * @param value The amount of native tokens transferred along the call (in Wei).
+     * @param selector The first 4 bytes (= function selector) of the data sent with the call.
      */
     event Executed(
         uint256 indexed operationType,
@@ -39,26 +43,18 @@ interface IERC725X is IERC165 {
     );
 
     /**
+     * @notice Calling address `target` using `operationType`, transferring `value` wei and data: `data`.
+     *
      * @param operationType The operation type used: CALL = 0; CREATE = 1; CREATE2 = 2; STATICCALL = 3; DELEGATECALL = 4
      * @param target The address of the EOA or smart contract.  (unused if a contract is created via operation type 1 or 2)
      * @param value The amount of native tokens to transfer (in Wei)
-     * @param data The call data, or the creation bytecode of the contract to deploy
+     * @param data The call data, or the creation bytecode of the contract to deploy if `operationType` is `1` or `2`.
      *
      * @dev Generic executor function to:
      *
      * - send native tokens to any address.
      * - interact with any contract by passing an abi-encoded function call in the `data` parameter.
      * - deploy a contract by providing its creation bytecode in the `data` parameter.
-     *
-     * Requirements:
-     *
-     * - SHOULD only be callable by the owner of the contract set via ERC173.
-     * - if a `value` is provided, the contract MUST have at least this amount in its balance to execute successfully.
-     * - if the operation type is STATICCALL or DELEGATECALL, `value` SHOULD be 0.
-     * - `target` SHOULD be address(0) when deploying a contract.
-     *
-     * Emits an {Executed} event, when a call is made with `operationType` 0 (CALL), 3 (STATICCALL) or 4 (DELEGATECALL)
-     * Emits a {ContractCreated} event, when deploying a contract with `operationType` 1 (CREATE) or 2 (CREATE2)
      */
     function execute(
         uint256 operationType,
@@ -68,27 +64,14 @@ interface IERC725X is IERC165 {
     ) external payable returns (bytes memory);
 
     /**
-     * @param operationsType The list of operations type used: CALL = 0; CREATE = 1; CREATE2 = 2; STATICCALL = 3; DELEGATECALL = 4
-     * @param targets The list of addresses to call. `targets` will be unused if a contract is created (operation types 1 and 2).
-     * @param values The list of native token amounts to transfer (in Wei)
-     * @param datas The list of call data, or the creation bytecode of the contract to deploy
+     * @notice Calling multiple addresses `targets` using `operationsType`, transferring `values` wei and data: `datas`.
      *
-     * @dev Generic batch executor function to:
+     * @dev Batch executor function that behaves the same as {execute} but allowing multiple operations in the same transaction.
      *
-     * - send native tokens to any address.
-     * - interact with any contract by passing an abi-encoded function call in the `datas` parameter.
-     * - deploy a contract by providing its creation bytecode in the `datas` parameter.
-     *
-     * Requirements:
-     *
-     * - The length of the parameters provided MUST be equal
-     * - SHOULD only be callable by the owner of the contract set via ERC173.
-     * - if a `values` is provided, the contract MUST have at least this amount in its balance to execute successfully.
-     * - if the operation type is STATICCALL or DELEGATECALL, `values` SHOULD be 0.
-     * - `targets` SHOULD be address(0) when deploying a contract.
-     *
-     * Emits an {Executed} event, when a call is made with `operationType` 0 (CALL), 3 (STATICCALL) or 4 (DELEGATECALL)
-     * Emits a {ContractCreated} event, when deploying a contract with `operationType` 1 (CREATE) or 2 (CREATE2)
+     * @param operationsType The list of operations type used: `CALL = 0`; `CREATE = 1`; `CREATE2 = 2`; `STATICCALL = 3`; `DELEGATECALL = 4`
+     * @param targets The list of addresses to call. `targets` will be unused if a contract is created (operation types 1 and 2).
+     * @param values The list of native token amounts to transfer (in Wei).
+     * @param datas The list of calldata, or the creation bytecode of the contract to deploy if `operationType` is `1` or `2`.
      */
     function executeBatch(
         uint256[] memory operationsType,
diff --git a/implementations/contracts/interfaces/IERC725Y.sol b/implementations/contracts/interfaces/IERC725Y.sol
index 9ee3a0eb..53815fae 100644
--- a/implementations/contracts/interfaces/IERC725Y.sol
+++ b/implementations/contracts/interfaces/IERC725Y.sol
@@ -5,30 +5,32 @@ pragma solidity ^0.8.0;
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 
 /**
- * @title The interface for ERC725Y General data key/value store
- * @dev ERC725Y provides the ability to set arbitrary data key/value pairs that can be changed over time
- * It is intended to standardise certain data key/value pairs to allow automated read and writes
- * from/to the contract storage
+ * @title The interface for ERC725Y sub-standard, a generic data key/value store.
+ * @dev ERC725Y provides the ability to set arbitrary data key/value pairs that can be changed over time.
+ * It is intended to standardise certain data key/value pairs to allow automated read and writes from/to the contract storage.
  */
 interface IERC725Y is IERC165 {
     /**
-     * @notice Emitted when data at a key is changed
-     * @param dataKey The data key which data value is set
-     * @param dataValue The data value to set
+     * @notice The following data key/value pair has been changed in the ERC725Y storage: Data key: `dataKey`, data value: `dataValue`.
+     * @dev Emitted when data at a specific `dataKey` was changed to a new value `dataValue`.
+     * @param dataKey The data key for which a bytes value is set.
+     * @param dataValue The value to set for the given data key.
      */
     event DataChanged(bytes32 indexed dataKey, bytes dataValue);
 
     /**
-     * @notice Gets singular data at a given `dataKey`
-     * @param dataKey The key which value to retrieve
-     * @return dataValue The data stored at the key
+     * @notice Reading the ERC725Y storage for data key `dataKey` returned the following value: `dataValue`.
+     * @dev Get in the ERC725Y storage the bytes data stored at a specific data key `dataKey`.
+     * @param dataKey The data key for which to retrieve the value.
+     * @return dataValue The bytes value stored under the specified data key.
      */
     function getData(
         bytes32 dataKey
     ) external view returns (bytes memory dataValue);
 
     /**
-     * @notice Gets array of data for multiple given keys
+     * @notice Reading the ERC725Y storage for data keys `dataKeys` returned the following values: `dataValues`.
+     * @dev Get in the ERC725Y storage the bytes data stored at multiple data keys `dataKeys`.
      * @param dataKeys The array of keys which values to retrieve
      * @return dataValues The array of data stored at multiple keys
      */
@@ -37,32 +39,24 @@ interface IERC725Y is IERC165 {
     ) external view returns (bytes[] memory dataValues);
 
     /**
-     * @notice Sets singular data for a given `dataKey`
-     * @param dataKey The key to retrieve stored value
-     * @param dataValue The value to set
-     * SHOULD only be callable by the owner of the contract set via ERC173
+     * @notice Setting the following data key value pair in the ERC725Y storage. Data key: `dataKey`, data value: `dataValue`.
      *
-     * The function is marked as payable to enable flexibility on child contracts
+     * @dev Sets a single bytes value `dataValue` in the ERC725Y storage for a specific data key `dataKey`.
+     * The function is marked as payable to enable flexibility on child contracts. For instance to implement
+     * a fee mechanism for setting specific data.
      *
-     * If the function is not intended to receive value, an additional check
-     * should be implemented to check that value equal 0.
-     *
-     * Emits a {DataChanged} event.
+     * @param dataKey The data key for which to set a new value.
+     * @param dataValue The new bytes value to set.
      */
     function setData(bytes32 dataKey, bytes memory dataValue) external payable;
 
     /**
-     * @param dataKeys The array of data keys for values to set
-     * @param dataValues The array of values to set
-     * @dev Sets array of data for multiple given `dataKeys`
-     * SHOULD only be callable by the owner of the contract set via ERC173
-     *
-     * The function is marked as payable to enable flexibility on child contracts
+     * @notice Setting the following data key value pairs in the ERC725Y storage. Data keys: `dataKeys`, data values: `dataValues`.
      *
-     * If the function is not intended to receive value, an additional check
-     * should be implemented to check that value equal 0.
+     * @dev Batch data setting function that behaves the same as {setData} but allowing to set multiple data key/value pairs in the ERC725Y storage in the same transaction.
      *
-     * Emits a {DataChanged} event.
+     * @param dataKeys An array of data keys to set bytes values for.
+     * @param dataValues An array of bytes values to set for each `dataKeys`.
      */
     function setDataBatch(
         bytes32[] memory dataKeys,

From adc2d006cc26391dfc5235c66c9763d07f69b0b0 Mon Sep 17 00:00:00 2001
From: Jean Cvllr <31145285+CJ42@users.noreply.github.com>
Date: Wed, 26 Jul 2023 12:23:37 +0100
Subject: [PATCH 3/6] chore: prepare release 5.2.0 (#230)

---
 implementations/CHANGELOG.md      | 4 ++++
 implementations/package-lock.json | 4 ++--
 implementations/package.json      | 2 +-
 3 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/implementations/CHANGELOG.md b/implementations/CHANGELOG.md
index ea9806da..dfe29471 100644
--- a/implementations/CHANGELOG.md
+++ b/implementations/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [5.2.0](https://github.com/ERC725Alliance/ERC725/compare/v5.1.0...v5.2.0) (2023-07-25)
+
+- Improve Natspec comments of smart contracts ([#229](https://github.com/ERC725Alliance/ERC725/pull/229))
+
 ## [5.1.0](https://github.com/ERC725Alliance/ERC725/compare/v5.0.0...v5.1.0) (2023-06-21)
 
 ### Features
diff --git a/implementations/package-lock.json b/implementations/package-lock.json
index f85b4c53..071e002b 100644
--- a/implementations/package-lock.json
+++ b/implementations/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@erc725/smart-contracts",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "@erc725/smart-contracts",
-      "version": "5.1.0",
+      "version": "5.2.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@openzeppelin/contracts": "^4.9.2",
diff --git a/implementations/package.json b/implementations/package.json
index c5b8cc17..4e3de63d 100644
--- a/implementations/package.json
+++ b/implementations/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@erc725/smart-contracts",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "description": "ERC725 contract implementations",
   "homepage": "https://erc725alliance.org",
   "repository": {

From 5a681beb67b11600445d46401b9835e2723ba52d Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 11 Aug 2023 19:14:35 +0000
Subject: [PATCH 4/6] chore(deps): bump @openzeppelin/contracts-upgradeable

Bumps [@openzeppelin/contracts-upgradeable](https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable) from 4.9.2 to 4.9.3.
- [Release notes](https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable/releases)
- [Changelog](https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable/blob/v4.9.3/CHANGELOG.md)
- [Commits](https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable/compare/v4.9.2...v4.9.3)

---
updated-dependencies:
- dependency-name: "@openzeppelin/contracts-upgradeable"
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <support@github.com>
---
 implementations/package-lock.json | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/implementations/package-lock.json b/implementations/package-lock.json
index 071e002b..b1dd35d3 100644
--- a/implementations/package-lock.json
+++ b/implementations/package-lock.json
@@ -2213,9 +2213,9 @@
       "integrity": "sha512-mO+y6JaqXjWeMh9glYVzVu8HYPGknAAnWyxTRhGeckOruyXQMNnlcW6w/Dx9ftLeIQk6N+ZJFuVmTwF7lEIFrg=="
     },
     "node_modules/@openzeppelin/contracts-upgradeable": {
-      "version": "4.9.2",
-      "resolved": "https://registry.npmjs.org/@openzeppelin/contracts-upgradeable/-/contracts-upgradeable-4.9.2.tgz",
-      "integrity": "sha512-siviV3PZV/fHfPaoIC51rf1Jb6iElkYWnNYZ0leO23/ukXuvOyoC/ahy8jqiV7g+++9Nuo3n/rk5ajSN/+d/Sg=="
+      "version": "4.9.3",
+      "resolved": "https://registry.npmjs.org/@openzeppelin/contracts-upgradeable/-/contracts-upgradeable-4.9.3.tgz",
+      "integrity": "sha512-jjaHAVRMrE4UuZNfDwjlLGDxTHWIOwTJS2ldnc278a0gevfXfPr8hxKEVBGFBE96kl2G3VHDZhUimw/+G3TG2A=="
     },
     "node_modules/@scure/base": {
       "version": "1.1.1",
@@ -16478,9 +16478,9 @@
       "integrity": "sha512-mO+y6JaqXjWeMh9glYVzVu8HYPGknAAnWyxTRhGeckOruyXQMNnlcW6w/Dx9ftLeIQk6N+ZJFuVmTwF7lEIFrg=="
     },
     "@openzeppelin/contracts-upgradeable": {
-      "version": "4.9.2",
-      "resolved": "https://registry.npmjs.org/@openzeppelin/contracts-upgradeable/-/contracts-upgradeable-4.9.2.tgz",
-      "integrity": "sha512-siviV3PZV/fHfPaoIC51rf1Jb6iElkYWnNYZ0leO23/ukXuvOyoC/ahy8jqiV7g+++9Nuo3n/rk5ajSN/+d/Sg=="
+      "version": "4.9.3",
+      "resolved": "https://registry.npmjs.org/@openzeppelin/contracts-upgradeable/-/contracts-upgradeable-4.9.3.tgz",
+      "integrity": "sha512-jjaHAVRMrE4UuZNfDwjlLGDxTHWIOwTJS2ldnc278a0gevfXfPr8hxKEVBGFBE96kl2G3VHDZhUimw/+G3TG2A=="
     },
     "@scure/base": {
       "version": "1.1.1",

From 32864a5b44c60108f873033a42cf63cc468c11d9 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 11 Aug 2023 19:33:05 +0000
Subject: [PATCH 5/6] chore(deps): bump @openzeppelin/contracts in
 /implementations

Bumps [@openzeppelin/contracts](https://github.com/OpenZeppelin/openzeppelin-contracts) from 4.9.2 to 4.9.3.
- [Release notes](https://github.com/OpenZeppelin/openzeppelin-contracts/releases)
- [Changelog](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v4.9.3/CHANGELOG.md)
- [Commits](https://github.com/OpenZeppelin/openzeppelin-contracts/compare/v4.9.2...v4.9.3)

---
updated-dependencies:
- dependency-name: "@openzeppelin/contracts"
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <support@github.com>
---
 implementations/package-lock.json | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/implementations/package-lock.json b/implementations/package-lock.json
index 071e002b..ccdfa237 100644
--- a/implementations/package-lock.json
+++ b/implementations/package-lock.json
@@ -2208,9 +2208,9 @@
       }
     },
     "node_modules/@openzeppelin/contracts": {
-      "version": "4.9.2",
-      "resolved": "https://registry.npmjs.org/@openzeppelin/contracts/-/contracts-4.9.2.tgz",
-      "integrity": "sha512-mO+y6JaqXjWeMh9glYVzVu8HYPGknAAnWyxTRhGeckOruyXQMNnlcW6w/Dx9ftLeIQk6N+ZJFuVmTwF7lEIFrg=="
+      "version": "4.9.3",
+      "resolved": "https://registry.npmjs.org/@openzeppelin/contracts/-/contracts-4.9.3.tgz",
+      "integrity": "sha512-He3LieZ1pP2TNt5JbkPA4PNT9WC3gOTOlDcFGJW4Le4QKqwmiNJCRt44APfxMxvq7OugU/cqYuPcSBzOw38DAg=="
     },
     "node_modules/@openzeppelin/contracts-upgradeable": {
       "version": "4.9.2",
@@ -16473,9 +16473,9 @@
       }
     },
     "@openzeppelin/contracts": {
-      "version": "4.9.2",
-      "resolved": "https://registry.npmjs.org/@openzeppelin/contracts/-/contracts-4.9.2.tgz",
-      "integrity": "sha512-mO+y6JaqXjWeMh9glYVzVu8HYPGknAAnWyxTRhGeckOruyXQMNnlcW6w/Dx9ftLeIQk6N+ZJFuVmTwF7lEIFrg=="
+      "version": "4.9.3",
+      "resolved": "https://registry.npmjs.org/@openzeppelin/contracts/-/contracts-4.9.3.tgz",
+      "integrity": "sha512-He3LieZ1pP2TNt5JbkPA4PNT9WC3gOTOlDcFGJW4Le4QKqwmiNJCRt44APfxMxvq7OugU/cqYuPcSBzOw38DAg=="
     },
     "@openzeppelin/contracts-upgradeable": {
       "version": "4.9.2",

From bedd8ab7ec92f0f253c34ccc2c7e4ff5d8ffe258 Mon Sep 17 00:00:00 2001
From: CJ42 <cavallerajean@gmail.com>
Date: Thu, 24 Aug 2023 14:46:33 +0100
Subject: [PATCH 6/6] build: upgrade OpenZeppelin package to `4.9.3`

---
 implementations/CHANGELOG.md      | 1 +
 implementations/package-lock.json | 4 ++--
 implementations/package.json      | 4 ++--
 3 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/implementations/CHANGELOG.md b/implementations/CHANGELOG.md
index dfe29471..d0bc7d22 100644
--- a/implementations/CHANGELOG.md
+++ b/implementations/CHANGELOG.md
@@ -5,6 +5,7 @@ All notable changes to this project will be documented in this file. See [standa
 ### [5.2.0](https://github.com/ERC725Alliance/ERC725/compare/v5.1.0...v5.2.0) (2023-07-25)
 
 - Improve Natspec comments of smart contracts ([#229](https://github.com/ERC725Alliance/ERC725/pull/229))
+- Bump version of `@openzeppelin/contracts` dependency from `4.9.2` to `4.9.3`
 
 ## [5.1.0](https://github.com/ERC725Alliance/ERC725/compare/v5.0.0...v5.1.0) (2023-06-21)
 
diff --git a/implementations/package-lock.json b/implementations/package-lock.json
index 79270fba..a838b4da 100644
--- a/implementations/package-lock.json
+++ b/implementations/package-lock.json
@@ -9,8 +9,8 @@
       "version": "5.2.0",
       "license": "Apache-2.0",
       "dependencies": {
-        "@openzeppelin/contracts": "^4.9.2",
-        "@openzeppelin/contracts-upgradeable": "^4.9.2",
+        "@openzeppelin/contracts": "^4.9.3",
+        "@openzeppelin/contracts-upgradeable": "^4.9.3",
         "solidity-bytes-utils": "0.8.0"
       },
       "devDependencies": {
diff --git a/implementations/package.json b/implementations/package.json
index 4e3de63d..9694fd47 100644
--- a/implementations/package.json
+++ b/implementations/package.json
@@ -34,8 +34,8 @@
   "author": "Fabian Vogelsteller <fabian@lukso.network>",
   "license": "Apache-2.0",
   "dependencies": {
-    "@openzeppelin/contracts": "^4.9.2",
-    "@openzeppelin/contracts-upgradeable": "^4.9.2",
+    "@openzeppelin/contracts": "^4.9.3",
+    "@openzeppelin/contracts-upgradeable": "^4.9.3",
     "solidity-bytes-utils": "0.8.0"
   },
   "devDependencies": {