Merge pull request #628 from lukso-network/update-lsp1-natspec

docs: update LSP1 Natspec

contracts/LSP0ERC725Account/LSP0ERC725AccountCore.sol

@@ -428,7 +428,7 @@ abstract contract LSP0ERC725AccountCore is
     }
 
     /**
-     * @notice Achieves the goal of [LSP1-UniversalReceiver] by allowing the account to be notified about incoming/outgoing
+     * @notice Achieves the goal of [LSP-1-UniversalReceiver] by allowing the account to be notified about incoming/outgoing
      * transactions and enabling reactions to these actions.
      *
      * The reaction is achieved by having two external contracts (UniversalReceiverDelegates) that react on the whole transaction

contracts/LSP1UniversalReceiver/ILSP1UniversalReceiver.sol

@@ -3,16 +3,19 @@ pragma solidity ^0.8.4;
 
 /**
  * @title Interface of the LSP1 - Universal Receiver standard, an entry function for a contract to receive arbitrary information.
- * @dev LSP1UniversalReceiver allows to receive arbitrary messages and to be informed when assets are sent or received
+ * @dev LSP1UniversalReceiver allows to receive arbitrary messages and to be informed when assets are sent or received.
  */
 interface ILSP1UniversalReceiver {
     /**
-     * @notice Emitted when the universalReceiver function is succesfully executed
-     * @param from The address calling the universalReceiver function
-     * @param value The amount sent to the universalReceiver function
-     * @param typeId The hash of a specific standard or a hook
-     * @param receivedData The arbitrary data passed to universalReceiver function
-     * @param returnedValue The value returned by the universalReceiver function
+     * @dev Emitted when the {universalReceiver} function was called with a specific `typeId` and some `receivedData`
+s
+     * @notice Address `from` called the `universalReceiver(...)` function while sending `value` LYX. Notification type (typeId): `typeId` - Data received: `receivedData`.
+     *
+     * @param from The address of the EOA or smart contract that called the {universalReceiver(...)} function.
+     * @param value The amount sent to the {universalReceiver(...)} function.
+     * @param typeId A `bytes32` unique identifier (= _"hook"_)that describe the type of notification, information or transaction received by the contract. Can be related to a specific standard or a hook.
+     * @param receivedData Any arbitrary data that was sent to the {universalReceiver(...)} function.
+     * @param returnedValue The value returned by the {universalReceiver(...)} function.
      */
     event UniversalReceiver(
         address indexed from,
@@ -23,11 +26,13 @@ interface ILSP1UniversalReceiver {
     );
 
     /**
-     * @param typeId The hash of a specific standard or a hook
-     * @param data The arbitrary data received with the call
-     * @dev Emits an event when it's succesfully executed
+     * @dev Generic function that can be used to notify the contract about specific incoming transactions or events like asset transfers, vault transfers, etc. Allows for custom on-chain and off-chain reactions based on the `typeId` and `data`.
+     * @notice Reacted on received notification with `typeId` & `data`.
+     *
+     * @param typeId The hash of a specific standard or a hook.
+     * @param data The arbitrary data received with the call.
      *
-     * Emits a {UniversalReceiver} event
+     * @custom:events {UniversalReceiver} event.
      */
     function universalReceiver(
         bytes32 typeId,

contracts/LSP1UniversalReceiver/LSP1Errors.sol

@@ -2,20 +2,15 @@
 pragma solidity ^0.8.4;
 
 /**
- * @dev reverts when EOA calls the `universalReceiver(..)` function with an asset/vault typeId
+ * @dev Reverts when EOA calls the {universalReceiver(..)} function with an asset/vault typeId.
+ * @notice EOA: `caller` cannot be registered as an asset.
+ *
  * @param caller The address of the EOA
  */
 error CannotRegisterEOAsAsAssets(address caller);
 
 /**
- * @dev reverts when the account calling the UniversalReceiverDelegate is not the same account
- * linked as target in the KeyManager -- Security Check
- * @param account The address of the account implementing the `universalReceiver(..)` function
- * @param target The address of the target linked to the KeyManager
- */
-error CallerNotLSP6LinkedTarget(address account, address target);
-
-/**
- * @dev reverts when `universalReceiver(...)` is called with a value different than 0
+ * @dev Reverts when the {universalReceiver} function in the LSP1 Universal Receiver Delegate contract is called while sending some native tokens along the call (`msg.value` different than `0`)
+ * @notice Cannot send native tokens to {universalReceiver(...)} function of the delegated contract.
  */
 error NativeTokensNotAccepted();

contracts/LSP1UniversalReceiver/LSP1UniversalReceiverDelegateUP/LSP1UniversalReceiverDelegateUP.sol

@@ -32,48 +32,35 @@ import "../../LSP14Ownable2Step/LSP14Constants.sol";
 import "../LSP1Errors.sol";
 
 /**
- * @title Implementation of a UniversalReceiverDelegate for LSP0ERC725Account
+ * @title Implementation of a UniversalReceiverDelegate for the [LSP-0-ERC725Account]
  * @author Fabian Vogelsteller, Yamen Merhi, Jean Cavallera
- * @dev This UniversalReceiverDelegate follows the {LSP1-UniversalReceiver} standards and is designed
- * for LSP0ERC725Account contracts.
+ * @dev The {LSP1UniversalReceiverDelegateUP} follows the [LSP-1-UniversalReceiver] standard and is designed
+ * for [LSP-0-ERC725Account] contracts.
  *
- * @dev Handles two cases:
- * - Registers the address of received assets (exclusively LSP7 and LSP8) and vaults (exclusively LSP9) according
- *   to {LSP5-ReceivedAssets} and {LSP10-ReceivedVaults} respectively
+ * The {LSP1UniversalReceiverDelegateUP} is a contract called by the {universalReceiver(...)} function of the [LSP-0-ERC725Account] contract that:
  *
- *   https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-5-ReceivedAssets.md
- *   https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-10-ReceivedVaults.md
+ * - Writes the data keys representing assets received from type [LSP-7-DigitalAsset] and [LSP-8-IdentifiableDigitalAsset] into the account storage, and removes them when the balance is zero according to the [LSP-5-ReceivedAssets] Standard.
+ * - Writes the data keys representing the owned vaults from type [LSP-9-Vault] into your account storage, and removes them when transferring ownership to other accounts according to the [LSP-10-ReceivedVaults] Standard.
  *
- * - Removes the address of registered assets and vaults when the full balance is sent from the LSP0ERC725Account contract
- *
- * Requirements:
- * - The contract should be able to setData the LSP5 and LSP10 data Keys according to the logic of the owner
- *    of the LSP0ERC725Account.
- *
- * For example, for contracts that are owned by an LSP6KeyManager, this contract should be granted
- * the SUPER/SETDATA and REENTRANCY Permission.
- *
- * Assets and Vaults that are compliant with this version of the UniversalReceiverDelegate are:
- *
- * - LSP7-DigitalAsset: https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-7-DigitalAsset.md
- * - LSP8-IdentifiableDigitalAsset: https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-8-IdentifiableDigitalAsset.md
- * - LSP9-Vault: https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-9-Vault.md
  */
 contract LSP1UniversalReceiverDelegateUP is ERC165, ILSP1UniversalReceiver {
     using ERC165Checker for address;
 
     /**
-     * @dev Handles two cases:
-     * - Registers the address of received assets (exclusively LSP7 and LSP8) and vaults (exclusively LSP9) according
-     *   to {LSP5-ReceivedAssets} and {LSP10-ReceivedVaults} respectively
+     * @dev
+     * 1. Writes the data keys of the received [LSP-7-DigitalAsset], [LSP-8-IdentifiableDigitalAsset] and [LSP-9-Vault] contract addresses into the account storage according to the [LSP-5-ReceivedAssets] and [LSP-10-ReceivedVaults] Standard.
+     * 2. The data keys representing an asset/vault are cleared when the asset/vault is no longer owned by the account.
      *
-     * - Removes the address of registered assets and vaults when the full balance is sent from the LSP0ERC725Account contract
+     * @notice Reacted on received notification with `typeId`.
      *
-     * Requirements:
-     * - The contract should be able to setData the LSP5 and LSP10 data Keys according to the logic of the owner
-     *    of the LSP0ERC725Account.
+     * @custom:warning When the data stored in the ERC725Y storage of the LSP0 contract is corrupted (_e.g: ([LSP-5-ReceivedAssets]'s Array length not 16 bytes long, the token received is already registered in `LSP5ReceivetAssets[]`, the token being sent is not sent as full balance, etc...), the function call will still pass and return (**not revert!**) and not modify any data key on the storage of the [LSP-0-ERC725Account].
      *
+     * @custom:requirements
+     * - This contract should be allowed to use the {setDataBatch(...)} function in order to update the LSP5 and LSP10 Data Keys.
      * - Cannot accept native tokens
+     *
+     * @param typeId Unique identifier for a specific notification.
+     * @return result The result of the reaction for `typeId`.
      */
     function universalReceiver(
         bytes32 typeId,

contracts/LSP1UniversalReceiver/LSP1UniversalReceiverDelegateVault/LSP1UniversalReceiverDelegateVault.sol

@@ -24,17 +24,28 @@ import "../../LSP9Vault/LSP9Constants.sol";
 import "../LSP1Errors.sol";
 
 /**
- * @title Core Implementation of contract writing the received LSP7 and LSP8 assets into your Vault using
- *        the LSP5-ReceivedAsset standard and removing the sent assets.
- *
+ * @title Implementation of a UniversalReceiverDelegate for the [LSP9Vault]
  * @author Fabian Vogelsteller, Yamen Merhi, Jean Cavallera
- * @dev Delegate contract of the initial universal receiver
+ * @dev The {LSP1UniversalReceiverDelegateVault} follows the [LSP-1-UniversalReceiver] standard and is designed
+ * for [LSP9Vault] contracts.
+ *
+ * The {LSP1UniversalReceiverDelegateVault} is a contract called by the {universalReceiver(...)} function of the [LSP-9-Vault] contract that:
+ *
+ * - Writes the data keys representing assets received from type [LSP-7-DigitalAsset] and [LSP-8-IdentifiableDigitalAsset] into the account storage, and removes them when the balance is zero according to the [LSP-5-ReceivedAssets] Standard.
  */
 contract LSP1UniversalReceiverDelegateVault is ERC165, ILSP1UniversalReceiver {
     /**
      * @inheritdoc ILSP1UniversalReceiver
-     * @dev allows to register arrayKeys and Map of incoming assets and remove after being sent
-     * @return result The return value
+     * @dev Handles two cases:
+     *
+     * Writes the received [LSP-7-DigitalAsset] or [LSP-8-IdentifiableDigitalAsset] assets into the vault storage according to the [LSP-5-ReceivedAssets] standard.
+     *
+     * @notice Reacted on received notification with `typeId`.
+     *
+     * @custom:requirements Cannot accept native tokens.
+     *
+     * @param typeId Unique identifier for a specific notification.
+     * @return result The result of the reaction for `typeId`.
      */
     function universalReceiver(
         bytes32 typeId,