docs: update LSP9 Natspec

lukso-network · Jul 17, 2023 · 03754e0 · 03754e0
1 parent 32ad32f
commit 03754e0
Show file tree

Hide file tree

Showing 4 changed files with 60 additions and 69 deletions.
diff --git a/contracts/LSP9Vault/ILSP9Vault.sol b/contracts/LSP9Vault/ILSP9Vault.sol
@@ -16,18 +16,23 @@ import {ILSP14Ownable2Step} from "../LSP14Ownable2Step/ILSP14Ownable2Step.sol";
 
 /**
  * @title Interface of LSP9 - Vault standard, a blockchain vault that can hold assets and interact with other smart contracts.
- * @dev this interface implicitly inherits: IERC165, IERC725X, IERC725Y, ILSP1UniversalReceiver, ILSP14Ownable2Step
+ * @dev Could be owned by an EOA or by a contract and is able to receive and send assets. Also allows for registering received assets by levereging the key-value storage.
  */
 interface ILSP9Vault {
     /**
-     * @notice Emitted when receiving native tokens
-     * @param sender The address of the sender
-     * @param value The amount of native tokens received
+     * @notice Emitted when receiving native tokens.
+     * @param sender The address of the sender.
+     * @param value The amount of native tokens received.
      */
     event ValueReceived(address indexed sender, uint256 indexed value);
 
     /**
-     * @dev Receives and executes a batch of function calls on this contract.
+     * @dev Allows a caller to batch different function calls in one call.
+     * Perform a `delegatecall` on self, to call different functions with preserving the context.
+     * It is not possible to send value along the functions call due to the use of `delegatecall`.
+     *
+     * @param data An array of ABI encoded function calls to be called on the contract.
+     * @return results An array of values returned by the executed functions.
      */
     function batchCalls(
         bytes[] calldata data

diff --git a/contracts/LSP9Vault/LSP9Errors.sol b/contracts/LSP9Vault/LSP9Errors.sol
@@ -2,7 +2,8 @@
 pragma solidity ^0.8.4;
 
 /**
- * @dev reverts when the UniversalReceiverDelegates of the Vault sets LSP1/6/17 Data Keys
- * @param dataKey The data key that the UniversalReceiverDelegate is not allowed to set
+ * @dev Reverts when the Vault version of [LSP1UniversalReceiverDelegate] sets LSP1/6/17 Data Keys.
+ * @notice Couldn't set the Data Key: `dataKey`.
+ * @param dataKey The data key that the Vault version of [LSP1UniversalReceiverDelegate] is not allowed to set.
  */
 error LSP1DelegateNotAllowedToSetDataKey(bytes32 dataKey);
diff --git a/contracts/LSP9Vault/LSP9Vault.sol b/contracts/LSP9Vault/LSP9Vault.sol
@@ -18,16 +18,17 @@ import {
 } from "../LSP9Vault/LSP9Constants.sol";
 
 /**
- * @title Implementation of LSP9Vault built on top of ERC725, LSP1UniversalReceiver
+ * @title Implementation of LSP9Vault built on top of [ERC725], [LSP-1-UniversalReceiver]
  * @author Fabian Vogelsteller, Yamen Merhi, Jean Cavallera
- * @dev Could be owned by a UniversalProfile and able to register received asset with UniversalReceiverDelegateVault
+ * @dev Could be owned by an EOA or by a contract and is able to receive and send assets. Also allows for registering received assets by levereging the key-value storage.
  */
 contract LSP9Vault is LSP9VaultCore {
     using LSP1Utils for address;
 
     /**
-     * @notice Sets the owner of the contract and sets the SupportedStandards:LSP9Vault key
-     * @param newOwner the owner of the contract
+     * @dev Sets the owner of the contract and sets the `SupportedStandards:LSP9Vault` Data Key.
+     * @notice New owner set, `newOwner`.
+     * @param newOwner The new owner of the contract.
      */
     constructor(address newOwner) payable {
         if (msg.value != 0) emit ValueReceived(msg.sender, msg.value);

diff --git a/contracts/LSP9Vault/LSP9VaultCore.sol b/contracts/LSP9Vault/LSP9VaultCore.sol
@@ -65,9 +65,9 @@ import "./LSP9Errors.sol";
 import "../LSP17ContractExtension/LSP17Errors.sol";
 
 /**
- * @title Core Implementation of LSP9Vault built on top of ERC725, LSP1UniversalReceiver
+ * @title Core Implementation of LSP9Vault built on top of [ERC725], [LSP1UniversalReceiver]
  * @author Fabian Vogelsteller, Yamen Merhi, Jean Cavallera
- * @dev Could be owned by a UniversalProfile and able to register received asset with UniversalReceiverDelegateVault
+ * @dev Could be owned by an EOA or by a contract and is able to receive and send assets. Also allows for registering received assets by levereging the key-value storage.
  */
 contract LSP9VaultCore is
     ERC725XCore,
@@ -83,11 +83,11 @@ contract LSP9VaultCore is
     address private _reentrantDelegate;
 
     /**
-     * @dev Emits an event when receiving native tokens
+     * @dev  Executed:
+     * - When receiving some native tokens without any additional data.
+     * - On empty calls to the contract.
      *
-     * Executed:
-     *     - when receiving some native tokens without any additional data.
-     *     - on empty calls to the contract.
+     * @custom:events {ValueReceived} when receiving native tokens.
      */
     receive() external payable virtual {
         if (msg.value > 0) emit ValueReceived(msg.sender, msg.value);
@@ -96,21 +96,18 @@ contract LSP9VaultCore is
     // solhint-disable no-complex-fallback
 
     /**
-     * @dev Emits an event when receiving native tokens
-     *
-     * Forwards the call to an extension contract (address). This address can be retrieved from
-     * the ERC725Y data key-value store using the data key below (function selector appended to the prefix):
-     *_LSP17_FALLBACK_EXTENSIONS_HANDLER_ + <function-selector>
-     * If there is no extension stored under the data key, return.
+     * @dev Forwards the call to an extension contract (address). This address can be retrieved from the ERC725Y data key-value store using the data key below (function selector appended to the prefix): `_LSP17_FALLBACK_EXTENSIONS_HANDLER_ + function-selector`. If there is no extension stored under the data key, return.
      *
      * The call to the extension is appended with bytes20 (msg.sender) and bytes32 (msg.value).
      * Returns the return value on success and revert in case of failure.
      *
-     * If the msg.data is shorter than 4 bytes do not check for an extension and return
+     * If the `msg.data` is shorter than 4 bytes do not check for an extension and return.
      *
      * Executed when:
-     * - the first 4 bytes of the calldata do not match any publicly callable functions from the contract ABI.
-     * - receiving native tokens with some calldata.
+     * - The first 4 bytes of the calldata do not match any publicly callable functions from the contract ABI.
+     * - Receiving native tokens with some calldata.
+     *
+     * @custom:events {ValueReceived} when receiving native tokens.
      */
     fallback() external payable virtual {
         if (msg.value != 0) emit ValueReceived(msg.sender, msg.value);
@@ -120,19 +117,16 @@ contract LSP9VaultCore is
     }
 
     /**
-     * @dev Forwards the call to an extension mapped to a function selector. If no extension address
-     * is mapped to the function selector (address(0)), then revert.
+     * @dev Forwards the call to an extension mapped to a function selector. If no extension address is mapped to the function selector (`address(0)`), then revert.
      *
-     * The bytes4(0) msg.sig is an exception, the function won't revert if there is no extension found
-     * mapped to bytes4(0), but will execute the call to the extension in case it existed.
+     * The `msg.sig = bytes4(0)` is an exception, the function won't revert if there is no extension found mapped to `bytes4(0)`, but will execute the call to the extension in case it existed.
      *
-     * The call to the extension is appended with bytes20 (msg.sender) and bytes32 (msg.value).
+     * The call to the extension is appended with `bytes20` (`msg.sender`) and `bytes32` (`msg.value`).
      * Returns the return value on success and revert in case of failure.
      *
-     * Because the function uses assembly {return()/revert()} to terminate the call, it cannot be
-     * called before other codes in fallback().
+     * Because the function uses assembly {`return()`/`revert()`} to terminate the call, it cannot be called before other codes in fallback().
      *
-     * Otherwise, the codes after _fallbackLSP17Extendable() may never be reached.
+     * Otherwise, the code after {_fallbackLSP17Extendable()} may never be reached.
      */
     function _fallbackLSP17Extendable() internal virtual override {
         // If there is a function selector
@@ -204,12 +198,9 @@ contract LSP9VaultCore is
     }
 
     /**
-     * @dev Returns true if this contract implements the interface defined by
-     * `interfaceId`.
+     * @dev Returns true if this contract implements the interface defined by `interfaceId`.
      *
-     * If the contract doesn't support the `interfaceId`, it forwards the call to the
-     * `supportsInterface` extension according to LSP17, and checks if the extension
-     * implements the interface defined by `interfaceId`.
+     * If the contract doesn't support the `interfaceId`, it forwards the call to the `supportsInterface` extension according to LSP17, and checks if the extension implements the interface defined by `interfaceId`.
      */
     function supportsInterface(
         bytes4 interfaceId
@@ -229,7 +220,7 @@ contract LSP9VaultCore is
     }
 
     /**
-     * @dev Receives and executes a batch of function calls on this contract.
+     * @inheritdoc ILSP9Vault
      */
     function batchCalls(
         bytes[] calldata data
@@ -265,13 +256,13 @@ contract LSP9VaultCore is
 
     /**
      * @inheritdoc IERC725X
-     * @param operationType The operation to execute: CALL = 0 CREATE = 1 CREATE2 = 2 STATICCALL = 3
-     * @dev Executes any other smart contract.
-     * SHOULD only be callable by the owner of the contract set via ERC173
      *
-     * Emits a {Executed} event, when a call is executed under `operationType` 0 and 3
-     * Emits a {ContractCreated} event, when a contract is created under `operationType` 1 and 2
-     * Emits a {ValueReceived} event, when receives native token
+     * @custom:events
+     * - {Executed} event, when a call is executed under `operationType` 0 and 3.
+     * - {ContractCreated} event, when a contract is created under `operationType` 1 and 2.
+     * - {ValueReceived} event, when receives native token.
+     *
+     * @custom:info The `operationType` 4 `DELEGATECALL` is disabled by default in the LSP9 Vault.
      */
     function execute(
         uint256 operationType,
@@ -286,7 +277,12 @@ contract LSP9VaultCore is
     /**
      * @inheritdoc ERC725XCore
      *
-     * @dev Emits a {ValueReceived} event when receiving native tokens.
+     * @custom:events
+     * - {Executed} event, when a call is executed under `operationType` 0 and 3.
+     * - {ContractCreated} event, when a contract is created under `operationType` 1 and 2.
+     * - {ValueReceived} event, when receives native token.
+     *
+     * @custom:info The `operationType` 4 `DELEGATECALL` is disabled by default in the LSP9 Vault.
      */
     function executeBatch(
         uint256[] memory operationsType,
@@ -300,11 +296,8 @@ contract LSP9VaultCore is
 
     /**
      * @inheritdoc IERC725Y
-     * @dev Sets data as bytes in the vault storage for a single key.
-     * SHOULD only be callable by the owner of the contract set via ERC173
-     * and the UniversalReceiverDelegate
      *
-     * Emits a {DataChanged} event.
+     * @custom:events {DataChanged} event.
      */
     function setData(
         bytes32 dataKey,
@@ -327,11 +320,8 @@ contract LSP9VaultCore is
 
     /**
      * @inheritdoc IERC725Y
-     * @dev Sets array of data at multiple given `key`
-     * SHOULD only be callable by the owner of the contract set via ERC173
-     * and the UniversalReceiverDelegate
      *
-     * Emits a {DataChanged} event.
+     * @custom:events {DataChanged} event.
      */
     function setDataBatch(
         bytes32[] memory dataKeys,
@@ -377,14 +367,13 @@ contract LSP9VaultCore is
     }
 
     /**
-     * @notice Triggers the UniversalReceiver event when this function gets executed successfully.
-     * Forwards the call to the addresses stored in the ERC725Y storage under the LSP1UniversalReceiverDelegate
-     * Key and the typeId Key (param) respectively. The call will be discarded if no addresses are set.
+     * @notice Forwards the call to the addresses stored in the [ERC725Y] storage under the the Vault version of [LSP1UniversalReceiverDelegate] Data Key and the `typeId` Key (param) respectively. The call will be discarded if no addresses are set.
      *
      * @param typeId The type of call received.
      * @param receivedData The data received.
-     * @return returnedValues The ABI encoded return value of the LSP1UniversalReceiverDelegate call
-     * and the LSP1TypeIdDelegate call.
+     * @return returnedValues The ABI encoded return value of the the Vault version of [LSP1UniversalReceiverDelegate] call and the LSP1TypeIdDelegate call.
+     *
+     * @custom:events {UniversalReceiver} when this function gets executed successfully.
      */
     function universalReceiver(
         bytes32 typeId,
@@ -463,10 +452,7 @@ contract LSP9VaultCore is
     /**
      * @inheritdoc LSP14Ownable2Step
      *
-     * @dev same as ILSP14.transferOwnership with the additional requirement:
-     *
-     * Requirements:
-     *  - when notifying the new owner via LSP1, the typeId used MUST be keccak256('LSP9OwnershipTransferStarted')
+     * @custom:requirements When notifying the new owner via LSP1, the typeId used MUST be `keccak256('LSP9OwnershipTransferStarted')`
      */
     function transferOwnership(
         address newOwner
@@ -490,11 +476,9 @@ contract LSP9VaultCore is
     /**
      * @inheritdoc LSP14Ownable2Step
      *
-     * @dev same as ILSP14.acceptOwnership with the additional requirement:
-     *
-     * Requirements:
-     * - when notifying the previous owner via LSP1, the typeId used MUST be keccak256('LSP9OwnershipTransferred_SenderNotification')
-     * - when notifying the new owner via LSP1, the typeId used MUST be keccak256('LSP9OwnershipTransferred_RecipientNotification')
+     * @custom:requirements
+     * - When notifying the previous owner via LSP1, the typeId used MUST be `keccak256('LSP9OwnershipTransferred_SenderNotification')`
+     * - When notifying the new owner via LSP1, the typeId used MUST be `keccak256('LSP9OwnershipTransferred_RecipientNotification')`
      */
     function acceptOwnership() public virtual override {
         address previousOwner = owner();