Merge 7bd2d58 into ddc59be

lukso-network · Aug 14, 2023 · 5e3a9f9 · 5e3a9f9
2 parents ddc59be + 7bd2d58
commit 5e3a9f9
Show file tree

Hide file tree

Showing 18 changed files with 7,207 additions and 82 deletions.
diff --git a/contracts/LSP7DigitalAsset/extensions/ILSP7CompatibleERC20.sol b/contracts/LSP7DigitalAsset/extensions/ILSP7CompatibleERC20.sol
@@ -10,17 +10,19 @@ import {ILSP7DigitalAsset} from "../ILSP7DigitalAsset.sol";
  */
 interface ILSP7CompatibleERC20 is ILSP7DigitalAsset {
     /**
-     * @notice To provide compatibility with indexing ERC20 events.
-     * @dev Emitted when `amount` tokens is transferred from `from` to `to`.
+     * @dev ERC20 `Transfer` event emitted when `amount` tokens is transferred from `from` to `to`.
+     * To provide compatibility with indexing ERC20 events.
+     *
      * @param from The sending address
      * @param to The receiving address
      * @param value The amount of tokens transfered.
      */
     event Transfer(address indexed from, address indexed to, uint256 value);
 
     /**
-     * @notice To provide compatibility with indexing ERC20 events.
-     * @dev Emitted when `owner` enables `spender` for `value` tokens.
+     * @dev ERC20 `Approval` event emitted when `owner` enables `spender` for `value` tokens.
+     * To provide compatibility with indexing ERC20 events.
+     *
      * @param owner The account giving approval
      * @param spender The account receiving approval
      * @param value The amount of tokens `spender` has access to from `owner`
@@ -32,17 +34,22 @@ interface ILSP7CompatibleERC20 is ILSP7DigitalAsset {
     );
 
     /*
-     * @dev Compatible with ERC20 transfer
-     * @param to The receiving address
-     * @param amount The amount of tokens to transfer
+     * @dev Transfer function from the ERC20 standard interface.
+
+     * @param to The address receiving tokens.
+     * @param amount The amount of tokens to transfer.
+     * @return `true` on successful transfer.
      */
     function transfer(address to, uint256 amount) external returns (bool);
 
     /*
-     * @dev Compatible with ERC20 transferFrom
-     * @param from The sending address
-     * @param to The receiving address
-     * @param amount The amount of tokens to transfer
+     * @dev Transfer functions for operators from the ERC20 standard interface.
+
+     * @param from The address sending tokens.
+     * @param to The address receiving tokens.
+     * @param amount The amount of tokens to transfer.
+     * 
+     * @return `true` on successful transfer.
      */
     function transferFrom(
         address from,
@@ -51,16 +58,21 @@ interface ILSP7CompatibleERC20 is ILSP7DigitalAsset {
     ) external returns (bool);
 
     /*
-     * @dev Compatible with ERC20 approve
+     * @dev Approval function from th ERC20 standard interface.
+
      * @param operator The address to approve for `amount`
-     * @param amount The amount to approve
+     * @param amount The amount to approve.
+     * 
+     * @return `true` on successful approval.
      */
     function approve(address operator, uint256 amount) external returns (bool);
 
     /*
-     * @dev Compatible with ERC20 allowance
+     * @dev Function to get operator allowance allowed to spend on behalf of `tokenOwner` from the ERC20 standard interface.
+
      * @param tokenOwner The address of the token owner
      * @param operator The address approved by the `tokenOwner`
+     * 
      * @return The amount `operator` is approved by `tokenOwner`
      */
     function allowance(

diff --git a/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol b/contracts/LSP7DigitalAsset/extensions/LSP7Burnable.sol
@@ -5,14 +5,12 @@ pragma solidity ^0.8.4;
 import {LSP7DigitalAsset} from "../LSP7DigitalAsset.sol";
 
 /**
- * @dev LSP7 extension that allows token holders to destroy both
+ * @title LSP7 token extension that allows token holders to destroy both
  * their own tokens and those that they have an allowance for as an operator.
  */
 abstract contract LSP7Burnable is LSP7DigitalAsset {
     /**
-     * @dev Destroys `amount` tokens from the `from` address.
-     *
-     * See internal _burn function for more details
+     * @dev See internal {_burn} function for details.
      */
     function burn(
         address from,

diff --git a/contracts/LSP7DigitalAsset/extensions/LSP7BurnableInitAbstract.sol b/contracts/LSP7DigitalAsset/extensions/LSP7BurnableInitAbstract.sol
@@ -7,14 +7,12 @@ import {
 } from "../LSP7DigitalAssetInitAbstract.sol";
 
 /**
- * @dev LSP7 extension that allows token holders to destroy both
+ * @title LSP7 token extension that allows token holders to destroy both
  * their own tokens and those that they have an allowance for as an operator.
  */
 abstract contract LSP7BurnableInitAbstract is LSP7DigitalAssetInitAbstract {
     /**
-     * @dev Destroys `amount` tokens from the `from` address.
-     *
-     * See internal _burn function for more details
+     * @dev See internal {_burn} function for details.
      */
     function burn(
         address from,

diff --git a/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol b/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupply.sol
@@ -6,19 +6,35 @@ pragma solidity ^0.8.4;
 import {LSP7DigitalAsset} from "../LSP7DigitalAsset.sol";
 
 /**
- * @dev LSP7 extension, adds token supply cap.
+ * @dev LSP7 token extension to add a max token supply cap.
  */
 abstract contract LSP7CappedSupply is LSP7DigitalAsset {
     // --- Errors
+
+    /**
+     * @notice The `tokenSupplyCap` must be set and cannot be `0`.
+     * @dev Reverts when setting `0` for the {tokenSupplyCap}. The max token supply MUST be set to a number greater than 0.
+     */
     error LSP7CappedSupplyRequired();
+
+    /**
+     * @notice Cannot mint anymore as total supply reached the maximum cap.
+     * @dev Reverts when trying to mint tokens but the {totalSupply} has reached the maximum {tokenSupplyCap}.
+     */
     error LSP7CappedSupplyCannotMintOverCap();
 
     // --- Storage
     uint256 private immutable _tokenSupplyCap;
 
     /**
-     * @notice Sets the token max supply
-     * @param tokenSupplyCap_ The Token max supply
+     * @notice Deploying a `LSP7CappedSupply` token contract with max token supply cap set to `tokenSupplyCap_`.
+     * @dev Deploy a `LSP7CappedSupply` token contract and set the maximum token supply token cap up to which
+     * it is not possible to mint more tokens.
+     *
+     * @param tokenSupplyCap_ The maximum token supply.
+     *
+     * @custom:requirements
+     * - `tokenSupplyCap_` MUST NOT be 0.
      */
     constructor(uint256 tokenSupplyCap_) {
         if (tokenSupplyCap_ == 0) {
@@ -31,8 +47,11 @@ abstract contract LSP7CappedSupply is LSP7DigitalAsset {
     // --- Token queries
 
     /**
-     * @dev Returns the number of tokens that can be minted
-     * @return The number of tokens that can be minted
+     * @notice The maximum supply amount of tokens allowed to exist is `_tokenSupplyCap`.
+     * @dev Get the maximum number of tokens that can exist to circulate. Once {totalSupply} reaches
+     * reaches {totalSuuplyCap}, it is not possible to mint more tokens.
+     *
+     * @return The maximum number of tokens that can exist in the contract.
      */
     function tokenSupplyCap() public view virtual returns (uint256) {
         return _tokenSupplyCap;
@@ -41,14 +60,12 @@ abstract contract LSP7CappedSupply is LSP7DigitalAsset {
     // --- Transfer functionality
 
     /**
-     * @dev Mints `amount` and transfers it to `to`.
+     * @dev Same as {_mint} but allows to mint only if the {totalSupply} does not exceed the {tokenSupplyCap}
+     * after `amount` of tokens have been minted.
      *
-     * Requirements:
-     *
-     * - `tokenSupplyCap() - totalSupply()` must be greater than zero.
+     * @custom:requirements
+     * - {tokenSupplyCap} - {totalSupply} must be greater than zero.
      * - `to` cannot be the zero address.
-     *
-     * Emits a {Transfer} event.
      */
     function _mint(
         address to,

diff --git a/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupplyInitAbstract.sol b/contracts/LSP7DigitalAsset/extensions/LSP7CappedSupplyInitAbstract.sol
@@ -8,16 +8,36 @@ import {
 } from "../LSP7DigitalAssetInitAbstract.sol";
 
 /**
- * @dev LSP7 extension, adds token supply cap.
+ * @dev LSP7 token extension to add a max token supply cap (proxy version).
  */
 abstract contract LSP7CappedSupplyInitAbstract is LSP7DigitalAssetInitAbstract {
     // --- Errors
+
+    /**
+     * @notice The `tokenSupplyCap` must be set and cannot be `0`.
+     * @dev Reverts when setting `0` for the {tokenSupplyCap}. The max token supply MUST be set to a number greater than 0.
+     */
     error LSP7CappedSupplyRequired();
+
+    /**
+     * @notice Cannot mint anymore as total supply reached the maximum cap.
+     * @dev Reverts when trying to mint tokens but the {totalSupply} has reached the maximum {tokenSupplyCap}.
+     */
     error LSP7CappedSupplyCannotMintOverCap();
 
     // --- Storage
     uint256 private _tokenSupplyCap;
 
+    /**
+     * @notice Deploying a `LSP7CappedSupply` token contract with max token supply cap set to `tokenSupplyCap_`.
+     * @dev Deploy a `LSP7CappedSupply` token contract and set the maximum token supply token cap up to which
+     * it is not possible to mint more tokens.
+     *
+     * @param tokenSupplyCap_ The maximum token supply.
+     *
+     * @custom:requirements
+     * - `tokenSupplyCap_` MUST NOT be 0.
+     */
     function _initialize(
         uint256 tokenSupplyCap_
     ) internal virtual onlyInitializing {
@@ -31,8 +51,11 @@ abstract contract LSP7CappedSupplyInitAbstract is LSP7DigitalAssetInitAbstract {
     // --- Token queries
 
     /**
-     * @dev Returns the number of tokens that can be minted
-     * @return The number of tokens that can be minted
+     * @notice The maximum supply amount of tokens allowed to exist is `_tokenSupplyCap`.
+     * @dev Get the maximum number of tokens that can exist to circulate. Once {totalSupply} reaches
+     * reaches {totalSuuplyCap}, it is not possible to mint more tokens.
+     *
+     * @return The maximum number of tokens that can exist in the contract.
      */
     function tokenSupplyCap() public view virtual returns (uint256) {
         return _tokenSupplyCap;
@@ -41,14 +64,12 @@ abstract contract LSP7CappedSupplyInitAbstract is LSP7DigitalAssetInitAbstract {
     // --- Transfer functionality
 
     /**
-     * @dev Mints `amount` and transfers it to `to`.
-     *
-     * Requirements:
+     * @dev Same as {_mint} but allows to mint only if the {totalSupply} does not exceed the {tokenSupplyCap}
+     * after `amount` of tokens have been minted.
      *
-     * - `tokenSupplyCap() - totalSupply()` must be greater than zero.
+     * @custom:requirements
+     * - {tokenSupplyCap} - {totalSupply} must be greater than zero.
      * - `to` cannot be the zero address.
-     *
-     * Emits a {Transfer} event.
      */
     function _mint(
         address to,

diff --git a/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol b/contracts/LSP7DigitalAsset/extensions/LSP7CompatibleERC20.sol
@@ -11,6 +11,7 @@ import {
 } from "../../LSP4DigitalAssetMetadata/LSP4Compatibility.sol";
 import {
     LSP7DigitalAsset,
+    LSP7DigitalAssetCore,
     LSP4DigitalAssetMetadata,
     ERC725YCore
 } from "../LSP7DigitalAsset.sol";
@@ -24,10 +25,12 @@ abstract contract LSP7CompatibleERC20 is
     LSP7DigitalAsset
 {
     /**
-     * @notice Sets the name, the symbol and the owner of the token
-     * @param name_ The name of the token
-     * @param symbol_ The symbol of the token
-     * @param newOwner_ The owner of the token
+     * @notice Deploying a `LSP7CompatibleERC20` token contract with: token name = `name_`, token symbol = `symbol_`, and
+     * address `newOwner_` as the token contract owner.
+     *
+     * @param name_ The name of the token.
+     * @param symbol_ The symbol of the token.
+     * @param newOwner_ The owner of the token contract.
      */
     constructor(
         string memory name_,
@@ -36,7 +39,7 @@ abstract contract LSP7CompatibleERC20 is
     ) LSP7DigitalAsset(name_, symbol_, newOwner_, false) {}
 
     /**
-     * @dev See {IERC165-supportsInterface}.
+     * @inheritdoc LSP7DigitalAsset
      */
     function supportsInterface(
         bytes4 interfaceId
@@ -73,8 +76,8 @@ abstract contract LSP7CompatibleERC20 is
 
     /**
      * @inheritdoc ILSP7CompatibleERC20
-     * @dev Compatible with ERC20 transferFrom.
-     * Using allowNonLSP1Recipient=true so that EOA and any contract may receive the tokens.
+     *
+     * @custom:info This function uses the `allowNonLSP1Recipient` parameter as `true` so that EOA and any contract can receive tokens.
      */
     function transferFrom(
         address from,
@@ -89,8 +92,8 @@ abstract contract LSP7CompatibleERC20 is
 
     /**
      * @inheritdoc ILSP7CompatibleERC20
-     * @dev Compatible with ERC20 transfer.
-     * Using allowNonLSP1Recipient=true so that EOA and any contract may receive the tokens.
+     *
+     * @custom:info This function uses the `allowNonLSP1Recipient` parameter as `true` so that EOA and any contract can receive tokens.
      */
     function transfer(
         address to,
@@ -101,8 +104,7 @@ abstract contract LSP7CompatibleERC20 is
     }
 
     /**
-     * @dev same behaviour as LSP7DigitalAssetCore
-     * with the addition of emitting ERC20 Approval event.
+     * @inheritdoc LSP7DigitalAssetCore
      */
     function _updateOperator(
         address tokenOwner,
@@ -113,6 +115,13 @@ abstract contract LSP7CompatibleERC20 is
         emit Approval(tokenOwner, operator, amount);
     }
 
+    /**
+     * @inheritdoc LSP7DigitalAssetCore
+     *
+     * @custom:events
+     * - LSP7 {Transfer} event.
+     * - ERC20 {Transfer} event.
+     */
     function _transfer(
         address from,
         address to,
@@ -124,6 +133,13 @@ abstract contract LSP7CompatibleERC20 is
         super._transfer(from, to, amount, allowNonLSP1Recipient, data);
     }
 
+    /**
+     * @inheritdoc LSP7DigitalAssetCore
+     *
+     * @custom:events
+     * - LSP7 {Transfer} event with `address(0)` as `from`.
+     * - ERC20 {Transfer} event with `address(0)` as `from`.
+     */
     function _mint(
         address to,
         uint256 amount,
@@ -134,6 +150,13 @@ abstract contract LSP7CompatibleERC20 is
         super._mint(to, amount, allowNonLSP1Recipient, data);
     }
 
+    /**
+     * @inheritdoc LSP7DigitalAssetCore
+     *
+     * @custom:events
+     * - LSP7 {Transfer} event with `address(0)` as the `to` address.
+     * - ERC20 {Transfer} event with `address(0)` as the `to` address.
+     */
     function _burn(
         address from,
         uint256 amount,
@@ -143,6 +166,9 @@ abstract contract LSP7CompatibleERC20 is
         super._burn(from, amount, data);
     }
 
+    /**
+     * @inheritdoc LSP4DigitalAssetMetadata
+     */
     function _setData(
         bytes32 key,
         bytes memory value