From 03754e04bddfde76ba3ba08a422615e7378ff3b4 Mon Sep 17 00:00:00 2001 From: b00ste Date: Mon, 17 Jul 2023 11:30:20 +0300 Subject: [PATCH] docs: update LSP9 Natspec --- contracts/LSP9Vault/ILSP9Vault.sol | 15 ++-- contracts/LSP9Vault/LSP9Errors.sol | 5 +- contracts/LSP9Vault/LSP9Vault.sol | 9 +-- contracts/LSP9Vault/LSP9VaultCore.sol | 100 +++++++++++--------------- 4 files changed, 60 insertions(+), 69 deletions(-) diff --git a/contracts/LSP9Vault/ILSP9Vault.sol b/contracts/LSP9Vault/ILSP9Vault.sol index 2f0f75d52..7f0880caa 100644 --- 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 index ee1654b35..64ebc58d3 100644 --- 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 index 1fdfdc2ef..951d0804c 100644 --- 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 index f07653bc1..59eaf3bc8 100644 --- 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_ + - * 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();