Merge pull request #234 from ERC725Alliance/develop

chore: release 5.2.0

implementations/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 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))
+- 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)
 
 ### Features
@@ -16,7 +21,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)
 

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);
     }
 
     /**

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);
     }
 }

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
      */

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);
     }
 }

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

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);
     }
 }

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);
     }
 }