From 989d63bddacb1b20a4a969f3ae37883c4ad7ba13 Mon Sep 17 00:00:00 2001 From: b00ste Date: Mon, 17 Jul 2023 11:45:11 +0300 Subject: [PATCH 1/4] docs: update LSP0 Natspec --- .../LSP0ERC725Account/ILSP0ERC725Account.sol | 44 +--- .../LSP0ERC725Account/LSP0ERC725Account.sol | 37 +--- .../LSP0ERC725AccountCore.sol | 198 ++++++------------ .../LSP0ERC725AccountInit.sol | 28 +-- .../LSP0ERC725AccountInitAbstract.sol | 28 +-- 5 files changed, 83 insertions(+), 252 deletions(-) diff --git a/contracts/LSP0ERC725Account/ILSP0ERC725Account.sol b/contracts/LSP0ERC725Account/ILSP0ERC725Account.sol index c8c4f0b2b..8db3a5cfe 100644 --- a/contracts/LSP0ERC725Account/ILSP0ERC725Account.sol +++ b/contracts/LSP0ERC725Account/ILSP0ERC725Account.sol @@ -16,53 +16,23 @@ import { import {ILSP14Ownable2Step} from "../LSP14Ownable2Step/ILSP14Ownable2Step.sol"; /** - * @title Interface of the LSP0 - ERC725Account standard, an account based smart contract that represents an identity on-chain. - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-0-ERC725Account.md + * @title Interface of the [LSP-0-ERC725Account] standard, an account based smart contract that represents an identity on-chain. * * @author Fabian Vogelsteller , Jean Cavallera (CJ42) - * @dev A smart contract account including basic functionalities such as: - * - * - Detecting supported standards using ERC165 - * https://eips.ethereum.org/EIPS/eip-165 - * - * - Executing several operation on other addresses including creating contracts using ERC725X - * https://github.com/ERC725Alliance/ERC725/blob/develop/docs/ERC-725.md - * - * - Storing data in a generic way using ERC725Y - * https://github.com/ERC725Alliance/ERC725/blob/develop/docs/ERC-725.md - * - * - Validating signatures using ERC1271 - * https://eips.ethereum.org/EIPS/eip-1271 - * - * - Receiving notification and react on them using LSP1 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-1-UniversalReceiver.md - * - * - Secure ownership management using LSP14 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-14-Ownable2Step.md - * - * - Extending the account with new functions and interfaceIds of future standards using LSP17 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-17-ContractExtension.md - * - * - Verifying calls on the owner to allow unified and standard interaction with the account using LSP20 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-20-CallVerification.md - * - * This interface implicitly inherits: IERC165, IERC725X, IERC725Y, IERC1271, ILSP1UniversalReceiver, ILSP14Ownable2Step */ interface ILSP0ERC725Account { /** - * @notice Emitted when receiving native tokens - * @param sender The address of the sender - * @param value The amount of native tokens received + * @dev Emitted when receiving native tokens. + * @notice `value` native tokens received from `sender`. + * @param sender The address that sent some native tokens to this contract. + * @param value The amount of native tokens received. */ event ValueReceived(address indexed sender, uint256 indexed value); /** - * @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. - * + * @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. * @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. + * @return results An array of abi-encode data returned by the functions executed. */ function batchCalls( bytes[] calldata data diff --git a/contracts/LSP0ERC725Account/LSP0ERC725Account.sol b/contracts/LSP0ERC725Account/LSP0ERC725Account.sol index a03745cde..2ac6bf912 100644 --- a/contracts/LSP0ERC725Account/LSP0ERC725Account.sol +++ b/contracts/LSP0ERC725Account/LSP0ERC725Account.sol @@ -8,44 +8,19 @@ import { } from "@erc725/smart-contracts/contracts/custom/OwnableUnset.sol"; /** - * @title Deployable Implementation of LSP0-ERC725Account Standard - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-0-ERC725Account.md + * @title Deployable Implementation of [LSP-0-ERC725Account] Standard. * * @author Fabian Vogelsteller , Jean Cavallera (CJ42) - * @dev A smart contract account including basic functionalities such as: - * - * - Detecting supported standards using ERC165 - * https://eips.ethereum.org/EIPS/eip-165 - * - * - Executing several operation on other addresses including creating contracts using ERC725X - * https://github.com/ERC725Alliance/ERC725/blob/develop/docs/ERC-725.md - * - * - Storing data in a generic way using ERC725Y - * https://github.com/ERC725Alliance/ERC725/blob/develop/docs/ERC-725.md - * - * - Validating signatures using ERC1271 - * https://eips.ethereum.org/EIPS/eip-1271 - * - * - Receiving notification and react on them using LSP1 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-1-UniversalReceiver.md - * - * - Secure ownership management using LSP14 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-14-Ownable2Step.md - * - * - Extending the account with new functions and interfaceIds of future standards using LSP17 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-17-ContractExtension.md - * - * - Verifying calls on the owner to allow unified and standard interaction with the account using LSP20 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-20-CallVerification.md */ contract LSP0ERC725Account is LSP0ERC725AccountCore { /** - * @notice Deploying the contract with owner set to: `initialOwner` - * @dev Set `initialOwner` as the contract owner. - * The `constructor` also allows funding the contract on deployment. + * @notice Deploying a LSP0ERC725Account contract with owner set to address `initialOwner`. + * @dev Set `initialOwner` as the contract owner. The `constructor` also allows funding the contract on deployment. * @param initialOwner The owner of the contract. * - * @custom:events {ValueReceived} event when funding the contract on deployment. + * @custom:events + * - {ValueReceived} event when funding the contract on deployment. + * - {OwnershipTransferred} event when `initialOwner` is set as the contract {owner}. */ constructor(address initialOwner) payable { if (msg.value != 0) { diff --git a/contracts/LSP0ERC725Account/LSP0ERC725AccountCore.sol b/contracts/LSP0ERC725Account/LSP0ERC725AccountCore.sol index 519424901..5a98bcedd 100644 --- a/contracts/LSP0ERC725Account/LSP0ERC725AccountCore.sol +++ b/contracts/LSP0ERC725Account/LSP0ERC725AccountCore.sol @@ -19,8 +19,14 @@ import {LSP1Utils} from "../LSP1UniversalReceiver/LSP1Utils.sol"; import {LSP2Utils} from "../LSP2ERC725YJSONSchema/LSP2Utils.sol"; // modules -import {ERC725YCore} from "@erc725/smart-contracts/contracts/ERC725YCore.sol"; -import {ERC725XCore} from "@erc725/smart-contracts/contracts/ERC725XCore.sol"; +import { + ERC725YCore, + IERC725Y +} from "@erc725/smart-contracts/contracts/ERC725YCore.sol"; +import { + ERC725XCore, + IERC725X +} from "@erc725/smart-contracts/contracts/ERC725XCore.sol"; import { OwnableUnset } from "@erc725/smart-contracts/contracts/custom/OwnableUnset.sol"; @@ -68,34 +74,18 @@ import { } from "../LSP14Ownable2Step/LSP14Errors.sol"; /** - * @title The Core Implementation of LSP0-ERC725Account Standard - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-0-ERC725Account.md + * @title The Core Implementation of [LSP-0-ERC725Account] Standard. * * @author Fabian Vogelsteller , Jean Cavallera (CJ42) * @dev A smart contract account including basic functionalities such as: - * - Detecting supported standards using ERC165 - * https://eips.ethereum.org/EIPS/eip-165 - * - * - Executing several operation on other addresses including creating contracts using ERC725X - * https://github.com/ERC725Alliance/ERC725/blob/develop/docs/ERC-725.md - * - * - Storing data in a generic way using ERC725Y - * https://github.com/ERC725Alliance/ERC725/blob/develop/docs/ERC-725.md - * - * - Validating signatures using ERC1271 - * https://eips.ethereum.org/EIPS/eip-1271 - * - * - Receiving notification and react on them using LSP1 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-1-UniversalReceiver.md - * - * - Secure ownership management using LSP14 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-14-Ownable2Step.md - * - * - Extending the account with new functions and interfaceIds of future standards using LSP17 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-17-ContractExtension.md - * - * - Verifying calls on the owner to allow unified and standard interaction with the account using LSP20 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-20-CallVerification.md + * - Detecting supported standards using [ERC-165] + * - Executing several operation on other addresses including creating contracts using [ERC-725X] + * - Storing data in a generic way using [ERC-725Y] + * - Validating signatures using [ERC-1271] + * - Receiving notification and react on them using [LSP-1-UniversalReceiver] + * - Secure ownership management using [LSP-14-Ownable2Step] + * - Extending the account with new functions and interfaceIds of future standards using [LSP-17-ContractExtension] + * - Verifying calls on the owner to allow unified and standard interaction with the account using [LSP-20-CallVerification] */ abstract contract LSP0ERC725AccountCore is ERC725XCore, @@ -113,8 +103,8 @@ abstract contract LSP0ERC725AccountCore is /** * @dev Executed: - * - when receiving some native tokens without any additional data. - * - on empty calls to the contract. + * - When receiving some native tokens without any additional data. + * - On empty calls to the contract. * * @custom:events {ValueReceived} event when receiving native tokens. */ @@ -127,28 +117,20 @@ abstract contract LSP0ERC725AccountCore is // solhint-disable no-complex-fallback /** - * @notice Achieves the goal of [LSP17-ContractExtension] standard by extending the contract to - * handle calls of functions that do not exist natively, forwarding the function call to the - * extension address mapped to the function being called. + * @notice Achieves the goal of [LSP-17-ContractExtension] standard by extending the contract to handle calls of functions that do not exist natively, forwarding the function call to the extension address mapped to the function being called. * * @dev This function is executed when: - * - sending data of length less than 4 bytes to the contract. - * - the first 4 bytes of the calldata do not match any publicly callable functions from the contract ABI. - * - receiving native tokens with some calldata. - * - * 1. If the data is equal or longer than 4 bytes, the ERC725Y storage is queried with the following data key: - * `[_LSP17_EXTENSION_PREFIX] + ` (Check [LSP2-ERC725YJSONSchema] for encoding the data key) + * - Sending data of length less than 4 bytes to the contract. + * - The first 4 bytes of the calldata do not match any publicly callable functions from the contract ABI. + * - Receiving native tokens with some calldata. * - * - If there is no address stored under the following data key, revert with {NoExtensionFoundForFunctionSelector(bytes4)} - * The data key relative to `bytes4(0)` is an exception, where no reverts occurs if there is no extension address stored under + * 1. If the data is equal or longer than 4 bytes, the [ERC-725Y] storage is queried with the following data key: [_LSP17_EXTENSION_PREFIX] + `bytes4(msg.sig)` (Check [LSP-2-ERC725YJSONSchema] for encoding the data key) * - * This exception is made to allow users to send random data (graffiti) to the account and to be able to react on it. + * - If there is no address stored under the following data key, revert with {NoExtensionFoundForFunctionSelector(bytes4)}. The data key relative to `bytes4(0)` is an exception, where no reverts occurs if there is no extension address stored under. This exception is made to allow users to send random data (graffiti) to the account and to be able to react on it. * - * - If there is an address, forward the `msg.data` to the extension using the CALL opcode, - * appending 52 bytes (20 bytes of `msg.sender` and 32 bytes of `msg.value`). - * Return what the calls returns, or revert if the call failed + * - If there is an address, forward the `msg.data` to the extension using the CALL opcode, appending 52 bytes (20 bytes of `msg.sender` and 32 bytes of `msg.value`). Return what the calls returns, or revert if the call failed. * - * @custom:return if the data sent to this function is of length less than 4 bytes (not a function selector) + * 2. If the data sent to this function is of length less than 4 bytes (not a function selector), return. * * @custom:events {ValueReceived} event when receiving native tokens. */ @@ -167,12 +149,9 @@ abstract contract LSP0ERC725AccountCore is } /** - * @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. + * @inheritdoc ILSP0ERC725Account * - * @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. + * @custom:info It's not possible to send value along the functions call due to the use of `delegatecall`. */ function batchCalls( bytes[] calldata data @@ -207,22 +186,17 @@ abstract contract LSP0ERC725AccountCore is } /** - * @dev Executes any call on other addresses. - * - * @param operationType The operation to execute: `CALL = 0`, `CREATE = 1` `CREATE2 = 2`, `STATICCALL = 3`, `DELEGATECALL = 4`. - * @param target The address (smart contract/EOA) to interact with, `target` will be unused if a contract is created (`CREATE` & `CREATE2`). - * @param value The amount of native tokens to transfer (in Wei). - * @param data The call data to execute on `target`, or the bytecode of the contract to deploy. + * @inheritdoc IERC725X * * @custom:requirements - * - if a `value` is provided, the contract MUST have at least this amount in its balance to execute successfully. - * - if the operation type is `STATICCALL` or `DELEGATECALL`, `value` SHOULD be 0. - * - `target` SHOULD be `address(0)` when deploying a contract. - * - MUST pass when called by the owner or by an authorised address that pass the verification check performed on the owner accordinng to [LSP20-CallVerification] specification + * - Can be only called by the {owner} or by an authorised address that pass the verification check performed on the owner. + * - If a `value` is provided, the contract must have at least this amount in its balance to execute successfully. + * - If the operation type is `CREATE` (1) or `CREATE2` (2), `target` must be `address(0)`. + * - If the operation type is `STATICCALL` (3) or `DELEGATECALL` (4), `value` transfer is disallowed and must be 0. * * @custom:events - * - {Executed} event, when a call is executed under `operationType` 0, 3 and 4 - * - {ContractCreated} event, when a contract is created under `operationType` 1 and 2 + * - {Executed} event for each call that uses under `operationType`: `CALL` (0), `STATICCALL` (3) and `DELEGATECALL` (4). (each iteration) + * - {ContractCreated} event, when a contract is created under `operationType`: `CREATE` (1) and `CREATE2` (2) (each iteration) * - {ValueReceived} event when receiving native tokens. */ function execute( @@ -263,24 +237,18 @@ abstract contract LSP0ERC725AccountCore is } /** - * @dev Generic batch executor function that executes any call on other addresses - * - * @param operationsType The list of operations type used: `CALL = 0`, `CREATE = 1`, `CREATE2 = 2`, `STATICCALL = 3`, `DELEGATECALL = 4`. - * @param targets The list of addresses to call. `targets` will be unused if a contract is created (`CREATE` & `CREATE2`). - * @param values The list of native token amounts to transfer (in Wei). - * @param datas The list of call data to execute on `targets`, or the creation bytecode of the contracts to deploy. + * @inheritdoc IERC725X * * @custom:requirements - * - The length of the parameters provided MUST be equal - * - if a `value` is provided, the contract MUST have at least this amount in its balance to execute successfully. - * - if the operation type is `STATICCALL` or `DELEGATECALL`, `value` SHOULD be 0. - * - `target` SHOULD be `address(0)` when deploying a contract. - * - MUST pass when called by the owner or by an authorised address that pass the verification check performed - * on the owner accordinng to [LSP20-CallVerification] specification + * - The length of the parameters provided must be equal. + * - Can be only called by the {owner} or by an authorised address that pass the verification check performed on the owner. + * - If a `value` is provided, the contract must have at least this amount in its balance to execute successfully. + * - If the operation type is `CREATE` (1) or `CREATE2` (2), `target` must be `address(0)`. + * - If the operation type is `STATICCALL` (3) or `DELEGATECALL` (4), `value` transfer is disallowed and must be 0. * * @custom:events - * - {Executed} event, when a call is executed under `operationType` 0, 3 and 4 (each iteration) - * - {ContractCreated} event, when a contract is created under `operationType` 1 and 2 (each iteration) + * - {Executed} event for each call that uses under `operationType`: `CALL` (0), `STATICCALL` (3) and `DELEGATECALL` (4). (each iteration) + * - {ContractCreated} event, when a contract is created under `operationType`: `CREATE` (1) and `CREATE2` (2) (each iteration) * - {ValueReceived} event when receiving native tokens. */ function executeBatch( @@ -330,13 +298,9 @@ abstract contract LSP0ERC725AccountCore is } /** - * @dev Sets singular data for a given `dataKey` - * - * @param dataKey The key to retrieve stored value - * @param dataValue The value to set + * @inheritdoc IERC725Y * - * @custom:requirements - * - MUST pass when called by the owner or by an authorised address that pass the verification check performed on the owner accordinng to [LSP20-CallVerification] specification + * @custom:requirements Can be only called by the {owner} or by an authorised address that pass the verification check performed on the owner. * * @custom:events * - {ValueReceived} event when receiving native tokens. @@ -371,13 +335,9 @@ abstract contract LSP0ERC725AccountCore is } /** - * @dev Sets array of data for multiple given `dataKeys` + * @inheritdoc IERC725Y * - * @param dataKeys The array of data keys for values to set - * @param dataValues The array of values to set - * - * @custom:requirements - * - MUST pass when called by the owner or by an authorised address that pass the verification check performed on the owner accordinng to [LSP20-CallVerification] specification + * @custom:requirements Can be only called by the {owner} or by an authorised address that pass the verification check performed on the owner. * * @custom:events * - {ValueReceived} event when receiving native tokens. @@ -430,25 +390,22 @@ abstract contract LSP0ERC725AccountCore is } /** - * @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. + * @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 - * and on the specific typeId, respectively. + * The reaction is achieved by having two external contracts ([LSP1UniversalReceiverDelegate]) that react on the whole transaction and on the specific typeId, respectively. * - * The notification is achieved by emitting a {UniversalReceiver} event on the call with the function parameters, call options, and the - * response of the UniversalReceiverDelegates (URD) contract. + * The notification is achieved by emitting a {UniversalReceiver} event on the call with the function parameters, call options, and the response of the UniversalReceiverDelegates (URD) contract. * * @dev The function performs the following steps: * - * 1. Query the ERC725Y storage with the data key `[_LSP1_UNIVERSAL_RECEIVER_DELEGATE_KEY]`. + * 1. Query the [ERC-725Y] storage with the data key [_LSP1_UNIVERSAL_RECEIVER_DELEGATE_KEY]. * - If there is an address stored under the data key, check if this address supports the LSP1 interfaceId. * * - If yes, call this address with the typeId and data (params), along with additional calldata consisting of 20 bytes of `msg.sender` and 32 bytes of `msg.value`. If not, continue the execution of the function. * * - * 2. Query the ERC725Y storage with the data key `[_LSP1_UNIVERSAL_RECEIVER_DELEGATE_KEY] + `. - * (Check [LSP2-ERC725YJSONSchema] for encoding the data key) + * 2. Query the [ERC-725Y] storage with the data key [_LSP1_UNIVERSAL_RECEIVER_DELEGATE_PREFIX] + `bytes32(typeId)`. + * (Check [LSP-2-ERC725YJSONSchema] for encoding the data key) * * - If there is an address stored under the data key, check if this address supports the LSP1 interfaceId. * @@ -545,19 +502,11 @@ abstract contract LSP0ERC725AccountCore is } /** - * @notice Achieves the goal of LSP14Ownable2Step by implementing a 2-step ownership transfer process. - * - * @dev Sets the address of the `pendingNewOwner` as a pending owner that should call {`acceptOwnership()`} in order to complete - * the ownership transfer to become the new {`owner()`} of the account. - * - * Notifies the pending owner via LSP1Standard by calling {universalReceiver()} on the pending owner if it's - * an address that supports LSP1. - * - * @param pendingNewOwner The address of the new pending owner. + * @inheritdoc LSP14Ownable2Step * * @custom:requirements - * - MUST pass when called by the owner or by an authorized address that passes the verification check performed on the owner according to [LSP20-CallVerification] specification. - * - When notifying the new owner via LSP1, the `typeId` used MUST be `keccak256('LSP0OwnershipTransferStarted')`. + * - Can be only called by the {owner} or by an authorised address that pass the verification check performed on the owner. + * - When notifying the new owner via LSP1, the `typeId` used must be the `keccak256(...)` hash of [LSP0OwnershipTransferStarted]. * - Pending owner cannot accept ownership in the same tx via the LSP1 hook. */ function transferOwnership( @@ -612,18 +561,12 @@ abstract contract LSP0ERC725AccountCore is } /** - * @notice Achieves the goal of LSP14Ownable2Step by implementing a 2-step ownership transfer process. - * - * @dev Transfer ownership of the contract from the current {`owner()`} to the {`pendingOwner()`}. - * - * Once this function is called: - * - the current {`owner()`} will loose access to the functions restricted to the {`owner()`} only. - * - the {`pendingOwner()`} will gain access to the functions restricted to the {`owner()`} only. + * @inheritdoc LSP14Ownable2Step * * @custom:requirements - * - MUST be called by the pendingOwner. - * - When notifying the previous owner via LSP1, the typeId used MUST be `keccak256('LSP0OwnershipTransferred_SenderNotification')`. - * - When notifying the new owner via LSP1, the typeId used MUST be `keccak256('LSP0OwnershipTransferred_RecipientNotification')`. + * - Only the {pendingOwner} can call this function. + * - When notifying the previous owner via LSP1, the typeId used must be the `keccak256(...)` hash of [LSP0OwnershipTransferred_SenderNotification]. + * - When notifying the new owner via LSP1, the typeId used must be the `keccak256(...)` hash of [LSP0OwnershipTransferred_RecipientNotification]. */ function acceptOwnership() public virtual override NotInTransferOwnership { address previousOwner = owner(); @@ -644,14 +587,9 @@ abstract contract LSP0ERC725AccountCore is } /** - * @notice Achieves the goal of LSP14Ownable2Step by implementing a 2-step ownership renouncing process. - * - * @dev Renounce ownership of the contract in a 2-step process. - * - * 1. the first call will initiate the process of renouncing ownership. - * 2. the second is used as a confirmation and will leave the contract without an owner. + * @inheritdoc LSP14Ownable2Step * - * MUST pass when called by the owner or by an authorised address that pass the verification check performed on the owner accordinng to [LSP20-CallVerification] specification + * @custom:requirements Can be only called by the {owner} or by an authorised address that pass the verification check performed on the owner. * * @custom:danger Leaves the contract without an owner. Once ownership of the contract has been renounced, any functions that are restricted to be called by the owner will be permanently inaccessible, making these functions not callable anymore and unusable. * @@ -690,14 +628,14 @@ abstract contract LSP0ERC725AccountCore is } /** - * @notice Achieves the goal of ERC165 to detect supported interfaces and LSP17 by + * @notice Achieves the goal of [ERC-165] to detect supported interfaces and [LSP-17-ContractExtension] by * checking if the interfaceId being queried is supported on another linked extension. * * @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 + * `supportsInterface` extension according to [LSP-17-ContractExtension], and checks if the extension * implements the interface defined by `interfaceId`. */ function supportsInterface( @@ -727,7 +665,7 @@ abstract contract LSP0ERC725AccountCore is * * 1. If the owner is an EOA, recovers an address from the hash and the signature provided: * - * - Returns the magicValue if the address recovered is the same as the owner, indicating that it was a valid signature. + * - Returns the `magicValue` if the address recovered is the same as the owner, indicating that it was a valid signature. * * - If the address is different, it returns the fail value indicating that the signature is not valid. * @@ -735,12 +673,12 @@ abstract contract LSP0ERC725AccountCore is * * - If the contract fails or returns the fail value, the {isValidSignature()} on the account returns the fail value, indicating that the signature is not valid. * - * - If the {isValidSignature()} on the owner returned the magicValue, the {isValidSignature()} on the account returns the magicValue, indicating that it's a valid signature. + * - If the {isValidSignature()} on the owner returned the `magicValue`, the {isValidSignature()} on the account returns the `magicValue`, indicating that it's a valid signature. * * @param dataHash The hash of the data to be validated. * @param signature A signature that can validate the previous parameter (Hash). * - * @return magicValue A bytes4 value that indicates if the signature is valid or not. + * @return magicValue A `bytes4` value that indicates if the signature is valid or not. */ function isValidSignature( bytes32 dataHash, diff --git a/contracts/LSP0ERC725Account/LSP0ERC725AccountInit.sol b/contracts/LSP0ERC725Account/LSP0ERC725AccountInit.sol index 0f26f975a..303c1a614 100644 --- a/contracts/LSP0ERC725Account/LSP0ERC725AccountInit.sol +++ b/contracts/LSP0ERC725Account/LSP0ERC725AccountInit.sol @@ -7,35 +7,9 @@ import { } from "./LSP0ERC725AccountInitAbstract.sol"; /** - * @title Deployable Proxy Implementation of LSP0-ERC725Account Standard - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-0-ERC725Account.md + * @title Deployable Proxy Implementation of [LSP-0-ERC725Account] Standard. * * @author Fabian Vogelsteller , Jean Cavallera (CJ42) - * @dev A smart contract account including basic functionalities such as: - * - * - Detecting supported standards using ERC165 - * https://eips.ethereum.org/EIPS/eip-165 - * - * - Executing several operation on other addresses including creating contracts using ERC725X - * https://github.com/ERC725Alliance/ERC725/blob/develop/docs/ERC-725.md - * - * - Storing data in a generic way using ERC725Y - * https://github.com/ERC725Alliance/ERC725/blob/develop/docs/ERC-725.md - * - * - Validating signatures using ERC1271 - * https://eips.ethereum.org/EIPS/eip-1271 - * - * - Receiving notification and react on them using LSP1 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-1-UniversalReceiver.md - * - * - Secure ownership management using LSP14 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-14-Ownable2Step.md - * - * - Extending the account with new functions and interfaceIds of future standards using LSP17 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-17-ContractExtension.md - * - * - Verifying calls on the owner to allow unified and standard interaction with the account using LSP20 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-20-CallVerification.md */ contract LSP0ERC725AccountInit is LSP0ERC725AccountInitAbstract { /** diff --git a/contracts/LSP0ERC725Account/LSP0ERC725AccountInitAbstract.sol b/contracts/LSP0ERC725Account/LSP0ERC725AccountInitAbstract.sol index 492859f36..24dc21f6f 100644 --- a/contracts/LSP0ERC725Account/LSP0ERC725AccountInitAbstract.sol +++ b/contracts/LSP0ERC725Account/LSP0ERC725AccountInitAbstract.sol @@ -11,35 +11,9 @@ import { } from "@erc725/smart-contracts/contracts/custom/OwnableUnset.sol"; /** - * @title Inheritable Proxy Implementation of LSP0-ERC725Account Standard - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-0-ERC725Account.md + * @title Inheritable Proxy Implementation of [LSP-0-ERC725Account] Standard. * * @author Fabian Vogelsteller , Jean Cavallera (CJ42) - * @dev A smart contract account including basic functionalities such as: - * - * - Detecting supported standards using ERC165 - * https://eips.ethereum.org/EIPS/eip-165 - * - * - Executing several operation on other addresses including creating contracts using ERC725X - * https://github.com/ERC725Alliance/ERC725/blob/develop/docs/ERC-725.md - * - * - Storing data in a generic way using ERC725Y - * https://github.com/ERC725Alliance/ERC725/blob/develop/docs/ERC-725.md - * - * - Validating signatures using ERC1271 - * https://eips.ethereum.org/EIPS/eip-1271 - * - * - Receiving notification and react on them using LSP1 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-1-UniversalReceiver.md - * - * - Secure ownership management using LSP14 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-14-Ownable2Step.md - * - * - Extending the account with new functions and interfaceIds of future standards using LSP17 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-17-ContractExtension.md - * - * - Verifying calls on the owner to allow unified and standard interaction with the account using LSP20 - * https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-20-CallVerification.md */ abstract contract LSP0ERC725AccountInitAbstract is Initializable, From 2527726172aeb97e7dfa573633b26fd96570f89a Mon Sep 17 00:00:00 2001 From: b00ste Date: Tue, 15 Aug 2023 14:04:17 +0300 Subject: [PATCH 2/4] docs: update `ERC725.md` auto-generated doc file --- docs/contracts/ERC725/ERC725.md | 314 ++++++++++++++++++++++---------- 1 file changed, 216 insertions(+), 98 deletions(-) diff --git a/docs/contracts/ERC725/ERC725.md b/docs/contracts/ERC725/ERC725.md index c07702b51..659c54b4f 100644 --- a/docs/contracts/ERC725/ERC725.md +++ b/docs/contracts/ERC725/ERC725.md @@ -14,13 +14,9 @@ ::: -> ERC725 bundle +> ERC725 bundle. -Bundles ERC725X and ERC725Y together into one smart contract. This implementation does not have by default a: - -- `receive() external payable {}` - -- or `fallback() external payable {}` +Bundle ERC725X and ERC725Y together into one smart contract. This implementation does not have by default a `receive() external payable {}` or `fallback() external payable {}` function. ## Public Methods @@ -37,16 +33,26 @@ When marked as 'public', a method can be called both externally and internally, ::: ```solidity -constructor(address newOwner); +constructor(address initialOwner); ``` -_Sets the owner of the contract_ +_Deploying an ERC725 smart contract and setting address `initialOwner` as the contract owner._ + +Deploy a new ERC725 contract with the provided `initialOwner` as the contract [`owner`](#owner). + +
+ +**Requirements:** + +- `initialOwner` CANNOT be the zero address. + +
#### Parameters -| Name | Type | Description | -| ---------- | :-------: | ------------------------- | -| `newOwner` | `address` | the owner of the contract | +| Name | Type | Description | +| -------------- | :-------: | -------------------------- | +| `initialOwner` | `address` | the owner of the contract. |
@@ -70,21 +76,35 @@ function execute( ) external payable returns (bytes); ``` +_Calling address `target` using `operationType`, transferring `value` wei and data: `data`. _ + Generic executor function to: - send native tokens to any address. - interact with any contract by passing an abi-encoded function call in the `data` parameter. -- deploy a contract by providing its creation bytecode in the `data` parameter. Requirements: +- deploy a contract by providing its creation bytecode in the `data` parameter. -- SHOULD only be callable by the owner of the contract set via ERC173. +
-- if a `value` is provided, the contract MUST have at least this amount in its balance to execute successfully. +**Requirements:** -- if the operation type is STATICCALL or DELEGATECALL, `value` SHOULD be 0. +- SHOULD only be callable by the [`owner`](#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`). -- `target` SHOULD be address(0) when deploying a contract. Emits an [`Executed`](#executed) event, when a call is made with `operationType` 0 (CALL), 3 (STATICCALL) or 4 (DELEGATECALL) Emits a [`ContractCreated`](#contractcreated) event, when deploying a contract with `operationType` 1 (CREATE) or 2 (CREATE2) +
+ +
+ +**Emitted events:** + +- [`Executed`](#executed) event when a call is made with `operationType` 0 (CALL), 3 (STATICCALL) or 4 (DELEGATECALL). +- [`ContractCreated`](#contractcreated) event when deploying a new contract with `operationType` 1 (CREATE) or 2 (CREATE2). + +
#### Parameters @@ -93,7 +113,7 @@ Generic executor function to: | `operationType` | `uint256` | The operation type used: CALL = 0; CREATE = 1; CREATE2 = 2; STATICCALL = 3; DELEGATECALL = 4 | | `target` | `address` | The address of the EOA or smart contract. (unused if a contract is created via operation type 1 or 2) | | `value` | `uint256` | The amount of native tokens to transfer (in Wei) | -| `data` | `bytes` | The call data, or the creation bytecode of the contract to deploy | +| `data` | `bytes` | The call data, or the creation bytecode of the contract to deploy if `operationType` is `1` or `2`. | #### Returns @@ -123,32 +143,37 @@ function executeBatch( ) external payable returns (bytes[]); ``` -Generic batch executor function to: +_Calling multiple addresses `targets` using `operationsType`, transferring `values` wei and data: `datas`. _ -- send native tokens to any address. +Batch executor function that behaves the same as [`execute`](#execute) but allowing multiple operations in the same transaction. + +
-- interact with any contract by passing an abi-encoded function call in the `datas` parameter. +**Requirements:** -- deploy a contract by providing its creation bytecode in the `datas` parameter. Requirements: +- All the array parameters provided MUST be equal and have the same length. +- SHOULD only be callable by the [`owner`](#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. -- The length of the parameters provided MUST be equal +
-- SHOULD only be callable by the owner of the contract set via ERC173. +
-- if a `values` is provided, the contract MUST have at least this amount in its balance to execute successfully. +**Emitted events:** -- if the operation type is STATICCALL or DELEGATECALL, `values` SHOULD be 0. +- [`Executed`](#executed) event, when a call is made with `operationType` 0 (CALL), 3 (STATICCALL) or 4 (DELEGATECALL) +- [`ContractCreated`](#contractcreated) event, when deploying a contract with `operationType` 1 (CREATE) or 2 (CREATE2) -- `targets` SHOULD be address(0) when deploying a contract. Emits an [`Executed`](#executed) event, when a call is made with `operationType` 0 (CALL), 3 (STATICCALL) or 4 (DELEGATECALL) Emits a [`ContractCreated`](#contractcreated) event, when deploying a contract with `operationType` 1 (CREATE) or 2 (CREATE2) +
#### Parameters -| Name | Type | Description | -| ---------------- | :---------: | ----------------------------------------------------------------------------------------------------------- | -| `operationsType` | `uint256[]` | The list of operations type used: CALL = 0; CREATE = 1; CREATE2 = 2; STATICCALL = 3; DELEGATECALL = 4 | -| `targets` | `address[]` | The list of addresses to call. `targets` will be unused if a contract is created (operation types 1 and 2). | -| `values` | `uint256[]` | The list of native token amounts to transfer (in Wei) | -| `datas` | `bytes[]` | The list of call data, or the creation bytecode of the contract to deploy | +| Name | Type | Description | +| ---------------- | :---------: | --------------------------------------------------------------------------------------------------------------- | +| `operationsType` | `uint256[]` | The list of operations type used: `CALL = 0`; `CREATE = 1`; `CREATE2 = 2`; `STATICCALL = 3`; `DELEGATECALL = 4` | +| `targets` | `address[]` | The list of addresses to call. `targets` will be unused if a contract is created (operation types 1 and 2). | +| `values` | `uint256[]` | The list of native token amounts to transfer (in Wei). | +| `datas` | `bytes[]` | The list of calldata, or the creation bytecode of the contract to deploy if `operationType` is `1` or `2`. | #### Returns @@ -173,19 +198,21 @@ Generic batch executor function to: function getData(bytes32 dataKey) external view returns (bytes dataValue); ``` -_Gets singular data at a given `dataKey`_ +_Reading the ERC725Y storage for data key `dataKey` returned the following value: `dataValue`._ + +Get in the ERC725Y storage the bytes data stored at a specific data key `dataKey`. #### Parameters -| Name | Type | Description | -| --------- | :-------: | ------------------------------- | -| `dataKey` | `bytes32` | The key which value to retrieve | +| Name | Type | Description | +| --------- | :-------: | --------------------------------------------- | +| `dataKey` | `bytes32` | The data key for which to retrieve the value. | #### Returns -| Name | Type | Description | -| ----------- | :-----: | -------------------------- | -| `dataValue` | `bytes` | The data stored at the key | +| Name | Type | Description | +| ----------- | :-----: | ---------------------------------------------------- | +| `dataValue` | `bytes` | The bytes value stored under the specified data key. |
@@ -206,7 +233,9 @@ function getDataBatch( ) external view returns (bytes[] dataValues); ``` -_Gets array of data for multiple given keys_ +_Reading the ERC725Y storage for data keys `dataKeys` returned the following values: `dataValues`._ + +Get in the ERC725Y storage the bytes data stored at multiple data keys `dataKeys`. #### Parameters @@ -277,18 +306,42 @@ Leaves the contract without owner. It will not be possible to call `onlyOwner` f ::: +:::caution Warning + +**Note for developers:** despite the fact that this function is set as `payable`, if the function is not intended to receive value (= native tokens), **an additional check should be implemented to ensure that `msg.value` sent was equal to 0**. + +::: + ```solidity function setData(bytes32 dataKey, bytes dataValue) external payable; ``` -_Sets singular data for a given `dataKey`_ +_Setting the following data key value pair in the ERC725Y storage. Data key: `dataKey`, data value: `dataValue`. _ + +Sets a single bytes value `dataValue` in the ERC725Y storage for a specific data key `dataKey`. The function is marked as payable to enable flexibility on child contracts. For instance to implement a fee mechanism for setting specific data. + +
+ +**Requirements:** + +- SHOULD only be callable by the [`owner`](#owner). + +
+ +
+ +**Emitted events:** + +- [`DataChanged`](#datachanged) event. + +
#### Parameters -| Name | Type | Description | -| ----------- | :-------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `dataKey` | `bytes32` | The key to retrieve stored value | -| `dataValue` | `bytes` | The value to set SHOULD only be callable by the owner of the contract set via ERC173 The function is marked as payable to enable flexibility on child contracts If the function is not intended to receive value, an additional check should be implemented to check that value equal 0. Emits a {DataChanged} event. | +| Name | Type | Description | +| ----------- | :-------: | ------------------------------------------ | +| `dataKey` | `bytes32` | The data key for which to set a new value. | +| `dataValue` | `bytes` | The new bytes value to set. |
@@ -303,20 +356,42 @@ _Sets singular data for a given `dataKey`_ ::: +:::caution Warning + +**Note for developers:** despite the fact that this function is set as `payable`, if the function is not intended to receive value (= native tokens), **an additional check should be implemented to ensure that `msg.value` sent was equal to 0**. + +::: + ```solidity function setDataBatch(bytes32[] dataKeys, bytes[] dataValues) external payable; ``` -Sets array of data for multiple given `dataKeys` SHOULD only be callable by the owner of the contract set via ERC173 The function is marked as payable to enable flexibility on child contracts If the function is not intended to receive value, an additional check should be implemented to check that value equal +_Setting the following data key value pairs in the ERC725Y storage. Data keys: `dataKeys`, data values: `dataValues`. _ + +Batch data setting function that behaves the same as [`setData`](#setdata) but allowing to set multiple data key/value pairs in the ERC725Y storage in the same transaction. + +
+ +**Requirements:** + +- SHOULD only be callable by the [`owner`](#owner) of the contract. + +
+ +
+ +**Emitted events:** -0. Emits a [`DataChanged`](#datachanged) event. +- [`DataChanged`](#datachanged) event **for each data key/value pair set**. + +
#### Parameters -| Name | Type | Description | -| ------------ | :---------: | ---------------------------------------- | -| `dataKeys` | `bytes32[]` | The array of data keys for values to set | -| `dataValues` | `bytes[]` | The array of values to set | +| Name | Type | Description | +| ------------ | :---------: | ---------------------------------------------------- | +| `dataKeys` | `bytes32[]` | An array of data keys to set bytes values for. | +| `dataValues` | `bytes[]` | An array of bytes values to set for each `dataKeys`. |
@@ -414,8 +489,7 @@ function _execute( ) internal nonpayable returns (bytes); ``` -check the `operationType` provided and perform the associated low-level opcode. -see `IERC725X.execute(uint256,address,uint256,bytes)`. +check the `operationType` provided and perform the associated low-level opcode after checking for requirements (see [`execute`](#execute)).
@@ -430,8 +504,7 @@ function _executeBatch( ) internal nonpayable returns (bytes[]); ``` -same as `_execute` but for batch execution -see `IERC725X,execute(uint256[],address[],uint256[],bytes[])` +check each `operationType` provided in the batch and perform the associated low-level opcode after checking for requirements (see [`executeBatch`](#executebatch)).
@@ -445,7 +518,7 @@ function _executeCall( ) internal nonpayable returns (bytes result); ``` -perform low-level call (operation type = 0) +Perform low-level call (operation type = 0) #### Parameters @@ -472,7 +545,7 @@ function _executeStaticCall( ) internal nonpayable returns (bytes result); ``` -perform low-level staticcall (operation type = 3) +Perform low-level staticcall (operation type = 3) #### Parameters @@ -498,7 +571,7 @@ function _executeDelegateCall( ) internal nonpayable returns (bytes result); ``` -perform low-level delegatecall (operation type = 4) +Perform low-level delegatecall (operation type = 4) #### Parameters @@ -524,7 +597,7 @@ function _deployCreate( ) internal nonpayable returns (bytes newContract); ``` -deploy a contract using the CREATE opcode (operation type = 1) +Deploy a contract using the `CREATE` opcode (operation type = 1) #### Parameters @@ -550,7 +623,7 @@ function _deployCreate2( ) internal nonpayable returns (bytes newContract); ``` -deploy a contract using the CREATE2 opcode (operation type = 2) +Deploy a contract using the `CREATE2` opcode (operation type = 2) #### Parameters @@ -573,6 +646,25 @@ deploy a contract using the CREATE2 opcode (operation type = 2) function _getData(bytes32 dataKey) internal view returns (bytes dataValue); ``` +Read the value stored under a specific `dataKey` inside the underlying ERC725Y storage, +represented as a mapping of `bytes32` data keys mapped to their `bytes` data values. + +```solidity +mapping(bytes32 => bytes) _store +``` + +#### Parameters + +| Name | Type | Description | +| --------- | :-------: | ----------------------------------------------------------------------- | +| `dataKey` | `bytes32` | A bytes32 data key to read the associated `bytes` value from the store. | + +#### Returns + +| Name | Type | Description | +| ----------- | :-----: | ----------------------------------------------------------------------------- | +| `dataValue` | `bytes` | The `bytes` value associated with the given `dataKey` in the ERC725Y storage. | +
### \_setData @@ -581,6 +673,28 @@ function _getData(bytes32 dataKey) internal view returns (bytes dataValue); function _setData(bytes32 dataKey, bytes dataValue) internal nonpayable; ``` +Write a `dataValue` to the underlying ERC725Y storage, represented as a mapping of +`bytes32` data keys mapped to their `bytes` data values. + +```solidity +mapping(bytes32 => bytes) _store +``` + +
+ +**Emitted events:** + +- [`DataChanged`](#datachanged) event emitted after a successful `setData` call. + +
+ +#### Parameters + +| Name | Type | Description | +| ----------- | :-------: | ------------------------------------------------------------------------------- | +| `dataKey` | `bytes32` | A bytes32 data key to write the associated `bytes` value to the store. | +| `dataValue` | `bytes` | The `bytes` value to associate with the given `dataKey` in the ERC725Y storage. | +
## Events @@ -600,18 +714,18 @@ function _setData(bytes32 dataKey, bytes dataValue) internal nonpayable; event ContractCreated(uint256 indexed operationType, address indexed contractAddress, uint256 indexed value, bytes32 salt); ``` -_Emitted when deploying a contract_ +_Deployed new contract at address `contractAddress` and funded with `value` wei (deployed using opcode: `operationType`)._ Emitted whenever a contract is created #### Parameters -| Name | Type | Description | -| ------------------------------- | :-------: | ------------------------------------------------------------------------------ | -| `operationType` **`indexed`** | `uint256` | The opcode used to deploy the contract (CREATE or CREATE2) | -| `contractAddress` **`indexed`** | `address` | The created contract address | -| `value` **`indexed`** | `uint256` | The amount of native tokens (in Wei) sent to fund the created contract address | -| `salt` | `bytes32` | - | +| Name | Type | Description | +| ------------------------------- | :-------: | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `operationType` **`indexed`** | `uint256` | The opcode used to deploy the contract (`CREATE` or `CREATE2`). | +| `contractAddress` **`indexed`** | `address` | The created contract address. | +| `value` **`indexed`** | `uint256` | The amount of native tokens (in Wei) sent to fund the created contract on deployment. | +| `salt` | `bytes32` | The salt used to deterministically deploy the contract (`CREATE2` only). If `CREATE` opcode is used, the salt value will be `bytes32(0)`. |
@@ -630,14 +744,16 @@ Emitted whenever a contract is created event DataChanged(bytes32 indexed dataKey, bytes dataValue); ``` -_Emitted when data at a key is changed_ +_The following data key/value pair has been changed in the ERC725Y storage: Data key: `dataKey`, data value: `dataValue`._ + +Emitted when data at a specific `dataKey` was changed to a new value `dataValue`. #### Parameters -| Name | Type | Description | -| ----------------------- | :-------: | ------------------------------------ | -| `dataKey` **`indexed`** | `bytes32` | The data key which data value is set | -| `dataValue` | `bytes` | The data value to set | +| Name | Type | Description | +| ----------------------- | :-------: | -------------------------------------------- | +| `dataKey` **`indexed`** | `bytes32` | The data key for which a bytes value is set. | +| `dataValue` | `bytes` | The value to set for the given data key. |
@@ -656,16 +772,18 @@ _Emitted when data at a key is changed_ event Executed(uint256 indexed operationType, address indexed target, uint256 indexed value, bytes4 selector); ``` -_Emitted when calling an address (EOA or contract)_ +_Called address `target` using `operationType` with `value` wei and `data`._ + +Emitted when calling an address `target` (EOA or contract) with `value`. #### Parameters -| Name | Type | Description | -| ----------------------------- | :-------: | ------------------------------------------------------------------------------------------------ | -| `operationType` **`indexed`** | `uint256` | The low-level call opcode used to call the `to` address (CALL, STATICALL or DELEGATECALL) | -| `target` **`indexed`** | `address` | The address to call. `target` will be unused if a contract is created (operation types 1 and 2). | -| `value` **`indexed`** | `uint256` | The amount of native tokens transferred with the call (in Wei) | -| `selector` | `bytes4` | The first 4 bytes (= function selector) of the data sent with the call | +| Name | Type | Description | +| ----------------------------- | :-------: | ---------------------------------------------------------------------------------------------------- | +| `operationType` **`indexed`** | `uint256` | The low-level call opcode used to call the `target` address (`CALL`, `STATICALL` or `DELEGATECALL`). | +| `target` **`indexed`** | `address` | The address to call. `target` will be unused if a contract is created (operation types 1 and 2). | +| `value` **`indexed`** | `uint256` | The amount of native tokens transferred along the call (in Wei). | +| `selector` | `bytes4` | The first 4 bytes (= function selector) of the data sent with the call. |
@@ -710,7 +828,7 @@ event OwnershipTransferred(address indexed previousOwner, address indexed newOwn error ERC725X_ContractDeploymentFailed(); ``` -reverts when contract deployment via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)` failed. whether using operation type 1 (CREATE) or 2 (CREATE2). +Reverts when contract deployment failed via [`execute`](#execute) or [`executeBatch`](#executebatch) functions, This error can occur using either operation type 1 (`CREATE`) or 2 (`CREATE2`).
@@ -729,7 +847,7 @@ reverts when contract deployment via `ERC725X.execute(...)`/`ERC725X.executeBatc error ERC725X_CreateOperationsRequireEmptyRecipientAddress(); ``` -reverts when passing a `to` address while deploying a contract va `ERC725X.execute(...)`/`ERC725X.executeBatch(...)` whether using operation type 1 (CREATE) or 2 (CREATE2). +Reverts when passing a `to` address that is not `address(0)` (= address zero) while deploying a contract via [`execute`](#execute) or [`executeBatch`](#executebatch) functions. This error can occur using either operation type 1 (`CREATE`) or 2 (`CREATE2`).
@@ -748,7 +866,7 @@ reverts when passing a `to` address while deploying a contract va `ERC725X.execu error ERC725X_ExecuteParametersEmptyArray(); ``` -reverts when one of the array parameter provided to `executeBatch(uint256[],address[],uint256[],bytes[]) is an empty array +Reverts when one of the array parameter provided to the [`executeBatch`](#executebatch) function is an empty array.
@@ -767,7 +885,7 @@ reverts when one of the array parameter provided to `executeBatch(uint256[],addr error ERC725X_ExecuteParametersLengthMismatch(); ``` -reverts when there is not the same number of operation, to addresses, value, and data. +Reverts when there is not the same number of elements in the `operationTypes`, `targets` addresses, `values`, and `datas` array parameters provided when calling the [`executeBatch`](#executebatch) function.
@@ -786,14 +904,14 @@ reverts when there is not the same number of operation, to addresses, value, and error ERC725X_InsufficientBalance(uint256 balance, uint256 value); ``` -reverts when trying to send more native tokens `value` than available in current `balance`. +Reverts when trying to send more native tokens `value` than available in current `balance`. #### Parameters -| Name | Type | Description | -| --------- | :-------: | ---------------------------------------------------------------------------------------- | -| `balance` | `uint256` | the balance of the ERC725X contract. | -| `value` | `uint256` | the amount of native tokens sent via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)`. | +| Name | Type | Description | +| --------- | :-------: | -------------------------------------------------------------------------------------------------------------------------------------- | +| `balance` | `uint256` | The balance of native tokens of the ERC725X smart contract. | +| `value` | `uint256` | The amount of native tokens sent via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)` that is greater than the contract's `balance`. |
@@ -812,7 +930,7 @@ reverts when trying to send more native tokens `value` than available in current error ERC725X_MsgValueDisallowedInDelegateCall(); ``` -the `value` parameter (= sending native tokens) is not allowed when making a delegatecall via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)` because msg.value is persisting. +Reverts when trying to send native tokens (`value` / `values[]` parameter of [`execute`](#execute) or [`executeBatch`](#executebatch) functions) while making a `delegatecall` (`operationType == 4`). Sending native tokens via `staticcall` is not allowed because `msg.value` is persisting.
@@ -831,7 +949,7 @@ the `value` parameter (= sending native tokens) is not allowed when making a del error ERC725X_MsgValueDisallowedInStaticCall(); ``` -the `value` parameter (= sending native tokens) is not allowed when making a staticcall via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)` because sending native tokens is a state changing operation. +Reverts when trying to send native tokens (`value` / `values[]` parameter of [`execute`](#execute) or [`executeBatch`](#executebatch) functions) while making a `staticcall` (`operationType == 3`). Sending native tokens via `staticcall` is not allowed because it is a state changing operation.
@@ -850,7 +968,7 @@ the `value` parameter (= sending native tokens) is not allowed when making a sta error ERC725X_NoContractBytecodeProvided(); ``` -reverts when no contract bytecode was provided as parameter when trying to deploy a contract via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)`, whether using operation type 1 (CREATE) or 2 (CREATE2). +Reverts when no contract bytecode was provided as parameter when trying to deploy a contract via [`execute`](#execute) or [`executeBatch`](#executebatch). This error can occur using either operation type 1 (`CREATE`) or 2 (`CREATE2`).
@@ -869,13 +987,13 @@ reverts when no contract bytecode was provided as parameter when trying to deplo error ERC725X_UnknownOperationType(uint256 operationTypeProvided); ``` -reverts when the `operationTypeProvided` is none of the default operation types available. (CALL = 0; CREATE = 1; CREATE2 = 2; STATICCALL = 3; DELEGATECALL = 4) +Reverts when the `operationTypeProvided` is none of the default operation types available. (CALL = 0; CREATE = 1; CREATE2 = 2; STATICCALL = 3; DELEGATECALL = 4) #### Parameters -| Name | Type | Description | -| ----------------------- | :-------: | ----------- | -| `operationTypeProvided` | `uint256` | - | +| Name | Type | Description | +| ----------------------- | :-------: | ------------------------------------------------------------------------------------------------------ | +| `operationTypeProvided` | `uint256` | The unrecognised operation type number provided to `ERC725X.execute(...)`/`ERC725X.executeBatch(...)`. |
@@ -894,7 +1012,7 @@ reverts when the `operationTypeProvided` is none of the default operation types error ERC725Y_DataKeysValuesEmptyArray(); ``` -reverts when one of the array parameter provided to `setDataBatch` is an empty array +Reverts when one of the array parameter provided to [`setDataBatch`](#setdatabatch) function is an empty array.
@@ -913,7 +1031,7 @@ reverts when one of the array parameter provided to `setDataBatch` is an empty a error ERC725Y_DataKeysValuesLengthMismatch(); ``` -reverts when there is not the same number of elements in the lists of data keys and data values when calling setDataBatch. +Reverts when there is not the same number of elements in the `datakeys` and `dataValues` array parameters provided when calling the [`setDataBatch`](#setdatabatch) function.
@@ -932,6 +1050,6 @@ reverts when there is not the same number of elements in the lists of data keys error ERC725Y_MsgValueDisallowed(); ``` -reverts when sending value to the `setData(..)` functions +Reverts when sending value to the [`setData`](#setdata) or [`setDataBatch`](#setdatabatch) function.
From 17d7950799af4449ded7b9c03d0507a95fbf66f4 Mon Sep 17 00:00:00 2001 From: b00ste Date: Tue, 15 Aug 2023 14:04:41 +0300 Subject: [PATCH 3/4] docs: add `.md` auto-generated docs for LSP0 --- .../LSP0ERC725Account/LSP0ERC725Account.md | 1809 +++++++++++++++++ 1 file changed, 1809 insertions(+) create mode 100644 docs/contracts/LSP0ERC725Account/LSP0ERC725Account.md diff --git a/docs/contracts/LSP0ERC725Account/LSP0ERC725Account.md b/docs/contracts/LSP0ERC725Account/LSP0ERC725Account.md new file mode 100644 index 000000000..59b09bdce --- /dev/null +++ b/docs/contracts/LSP0ERC725Account/LSP0ERC725Account.md @@ -0,0 +1,1809 @@ + + + +# LSP0ERC725Account + +:::info Standard Specifications + +[`LSP-0-ERC725Account`](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md) + +::: +:::info Solidity implementation + +[`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) + +::: + +> Deployable Implementation of LSP0-ERC725Account Standard https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-0-ERC725Account.md + +A smart contract account including basic functionalities such as: + +- Detecting supported standards using [ERC-165] + +- Executing several operation on other addresses including creating contracts using [ERC-725X] + +- Storing data in a generic way using [ERC-725Y] + +- Validating signatures using [ERC-1271] + +- Receiving notification and react on them using [LSP-1-UniversalReceiver] + +- Secure ownership management using [LSP-14-Ownable2Step] + +- Extending the account with new functions and interfaceIds of future standards using [LSP-17-ContractExtension] + +- Verifying calls on the owner to allow unified and standard interaction with the account using [LSP-20-CallVerification] + +## Public Methods + +Public methods are accessible externally from users, allowing interaction with this function from dApps or other smart contracts. +When marked as 'public', a method can be called both externally and internally, on the other hand, when marked as 'external', a method can only be called externally. + +### constructor + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#constructor) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) + +::: + +```solidity +constructor(address initialOwner); +``` + +_Deploying an LSP0ERC725Account with owner set to: `initialOwner`_ + +Set `initialOwner` as the contract owner. The `constructor` also allows funding the contract on deployment. + +
+ +**Emitted events:** + +- [`ValueReceived`](#valuereceived) event when funding the contract on deployment. +- [`OwnershipTransferred`](#ownershiptransferred) event when `initialOwner` is set. + +
+ +#### Parameters + +| Name | Type | Description | +| -------------- | :-------: | -------------------------- | +| `initialOwner` | `address` | The owner of the contract. | + +
+ +### fallback + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#fallback) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) + +::: + +```solidity +fallback(bytes calldata callData) external payable returns (bytes memory); +``` + +_Achieves the goal of [LSP-17-ContractExtension] standard by extending the contract to handle calls of functions that do not exist natively, forwarding the function call to the extension address mapped to the function being called._ + +This function is executed when: + +- Sending data of length less than 4 bytes to the contract. + +- The first 4 bytes of the calldata do not match any publicly callable functions from the contract ABI. + +- Receiving native tokens with some calldata. + +1. If the data is equal or longer than 4 bytes, the [ERC-725Y] storage is queried with the following data key: [_LSP17_EXTENSION_PREFIX] + `bytes4(msg.sig)` (Check [LSP-2-ERC725YJSONSchema] for encoding the data key) + +- If there is no address stored under the following data key, revert with [`NoExtensionFoundForFunctionSelector(bytes4)`](#noextensionfoundforfunctionselector). The data key relative to `bytes4(0)` is an exception, where no reverts occurs if there is no extension address stored under. This exception is made to allow users to send random data (graffiti) to the account and to be able to react on it. + +- If there is an address, forward the `msg.data` to the extension using the CALL opcode, appending 52 bytes (20 bytes of `msg.sender` and 32 bytes of `msg.value`). Return what the calls returns, or revert if the call failed. + +2. If the data sent to this function is of length less than 4 bytes (not a function selector), return. + +
+ +**Emitted events:** + +- [`ValueReceived`](#valuereceived) event when receiving native tokens. + +
+ +
+ +### receive + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#receive) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) + +::: + +```solidity +receive() external payable; +``` + +Executed: + +- When receiving some native tokens without any additional data. + +- On empty calls to the contract. + +
+ +**Emitted events:** + +- [`ValueReceived`](#valuereceived) event when receiving native tokens. + +
+ +
+ +### RENOUNCE_OWNERSHIP_CONFIRMATION_DELAY + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#renounce_ownership_confirmation_delay) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `RENOUNCE_OWNERSHIP_CONFIRMATION_DELAY()` +- Function selector: `0xead3fbdf` + +::: + +```solidity +function RENOUNCE_OWNERSHIP_CONFIRMATION_DELAY() + external + view + returns (uint256); +``` + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ----------- | +| `0` | `uint256` | - | + +
+ +### RENOUNCE_OWNERSHIP_CONFIRMATION_PERIOD + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#renounce_ownership_confirmation_period) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `RENOUNCE_OWNERSHIP_CONFIRMATION_PERIOD()` +- Function selector: `0x01bfba61` + +::: + +```solidity +function RENOUNCE_OWNERSHIP_CONFIRMATION_PERIOD() + external + view + returns (uint256); +``` + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ----------- | +| `0` | `uint256` | - | + +
+ +### acceptOwnership + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#acceptownership) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `acceptOwnership()` +- Function selector: `0x79ba5097` + +::: + +```solidity +function acceptOwnership() external nonpayable; +``` + +_`msg.sender` is accepting ownership of contract: `address(this)`._ + +Transfer ownership of the contract from the current [`owner()`](#owner) to the [`pendingOwner()`](#pendingowner). Once this function is called: + +- The current [`owner()`](#owner) will loose access to the functions restricted to the [`owner()`](#owner) only. + +- The [`pendingOwner()`](#pendingowner) will gain access to the functions restricted to the [`owner()`](#owner) only. + +
+ +**Requirements:** + +- Only the [`pendingOwner`](#pendingowner) can call this function. +- When notifying the previous owner via LSP1, the typeId used must be the `keccak256(...)` hash of [LSP0OwnershipTransferred_SenderNotification]. +- When notifying the new owner via LSP1, the typeId used must be the `keccak256(...)` hash of [LSP0OwnershipTransferred_RecipientNotification]. + +
+ +
+ +### batchCalls + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#batchcalls) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `batchCalls(bytes[])` +- Function selector: `0x6963d438` + +::: + +:::info + +It's not possible to send value along the functions call due to the use of `delegatecall`. + +::: + +```solidity +function batchCalls(bytes[] data) external nonpayable returns (bytes[] results); +``` + +Allows a caller to batch different function calls in one call. Perform a `delegatecall` on self, to call different functions with preserving the context. + +#### Parameters + +| Name | Type | Description | +| ------ | :-------: | -------------------------------------------------------------------- | +| `data` | `bytes[]` | An array of ABI encoded function calls to be called on the contract. | + +#### Returns + +| Name | Type | Description | +| --------- | :-------: | ---------------------------------------------------------------- | +| `results` | `bytes[]` | An array of abi-encoded returned data by the executed functions. | + +
+ +### execute + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#execute) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `execute(uint256,address,uint256,bytes)` +- Function selector: `0x44c028fe` + +::: + +```solidity +function execute( + uint256 operationType, + address target, + uint256 value, + bytes data +) external payable returns (bytes); +``` + +_Calling address `target` using `operationType`, transferring `value` wei and data: `data`. _ + +Generic executor function to: + +- send native tokens to any address. + +- interact with any contract by passing an abi-encoded function call in the `data` parameter. + +- deploy a contract by providing its creation bytecode in the `data` parameter. + +
+ +**Requirements:** + +- Can be only called by the [`owner`](#owner) or by an authorised address that pass the verification check performed on the owner. +- If a `value` is provided, the contract must have at least this amount in its balance to execute successfully. +- If the operation type is `CREATE` (1) or `CREATE2` (2), `target` must be `address(0)`. +- If the operation type is `STATICCALL` (3) or `DELEGATECALL` (4), `value` transfer is disallowed and must be 0. + +
+ +
+ +**Emitted events:** + +- [`Executed`](#executed) event for each call that uses under `operationType`: `CALL` (0), `STATICCALL` (3) and `DELEGATECALL` (4). (each iteration) +- [`ContractCreated`](#contractcreated) event, when a contract is created under `operationType`: `CREATE` (1) and `CREATE2` (2) (each iteration) +- [`ValueReceived`](#valuereceived) event when receiving native tokens. + +
+ +#### Parameters + +| Name | Type | Description | +| --------------- | :-------: | ----------------------------------------------------------------------------------------------------- | +| `operationType` | `uint256` | The operation type used: CALL = 0; CREATE = 1; CREATE2 = 2; STATICCALL = 3; DELEGATECALL = 4 | +| `target` | `address` | The address of the EOA or smart contract. (unused if a contract is created via operation type 1 or 2) | +| `value` | `uint256` | The amount of native tokens to transfer (in Wei) | +| `data` | `bytes` | The call data, or the creation bytecode of the contract to deploy if `operationType` is `1` or `2`. | + +#### Returns + +| Name | Type | Description | +| ---- | :-----: | ----------- | +| `0` | `bytes` | - | + +
+ +### executeBatch + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#executebatch) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `executeBatch(uint256[],address[],uint256[],bytes[])` +- Function selector: `0x31858452` + +::: + +```solidity +function executeBatch( + uint256[] operationsType, + address[] targets, + uint256[] values, + bytes[] datas +) external payable returns (bytes[]); +``` + +_Calling multiple addresses `targets` using `operationsType`, transferring `values` wei and data: `datas`. _ + +Batch executor function that behaves the same as [`execute`](#execute) but allowing multiple operations in the same transaction. + +
+ +**Requirements:** + +- The length of the parameters provided must be equal. +- Can be only called by the [`owner`](#owner) or by an authorised address that pass the verification check performed on the owner. +- If a `value` is provided, the contract must have at least this amount in its balance to execute successfully. +- If the operation type is `CREATE` (1) or `CREATE2` (2), `target` must be `address(0)`. +- If the operation type is `STATICCALL` (3) or `DELEGATECALL` (4), `value` transfer is disallowed and must be 0. + +
+ +
+ +**Emitted events:** + +- [`Executed`](#executed) event for each call that uses under `operationType`: `CALL` (0), `STATICCALL` (3) and `DELEGATECALL` (4). (each iteration) +- [`ContractCreated`](#contractcreated) event, when a contract is created under `operationType`: `CREATE` (1) and `CREATE2` (2) (each iteration) +- [`ValueReceived`](#valuereceived) event when receiving native tokens. + +
+ +#### Parameters + +| Name | Type | Description | +| ---------------- | :---------: | --------------------------------------------------------------------------------------------------------------- | +| `operationsType` | `uint256[]` | The list of operations type used: `CALL = 0`; `CREATE = 1`; `CREATE2 = 2`; `STATICCALL = 3`; `DELEGATECALL = 4` | +| `targets` | `address[]` | The list of addresses to call. `targets` will be unused if a contract is created (operation types 1 and 2). | +| `values` | `uint256[]` | The list of native token amounts to transfer (in Wei). | +| `datas` | `bytes[]` | The list of calldata, or the creation bytecode of the contract to deploy if `operationType` is `1` or `2`. | + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ----------- | +| `0` | `bytes[]` | - | + +
+ +### getData + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#getdata) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `getData(bytes32)` +- Function selector: `0x54f6127f` + +::: + +```solidity +function getData(bytes32 dataKey) external view returns (bytes dataValue); +``` + +_Reading the ERC725Y storage for data key `dataKey` returned the following value: `dataValue`._ + +Get in the ERC725Y storage the bytes data stored at a specific data key `dataKey`. + +#### Parameters + +| Name | Type | Description | +| --------- | :-------: | --------------------------------------------- | +| `dataKey` | `bytes32` | The data key for which to retrieve the value. | + +#### Returns + +| Name | Type | Description | +| ----------- | :-----: | ---------------------------------------------------- | +| `dataValue` | `bytes` | The bytes value stored under the specified data key. | + +
+ +### getDataBatch + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#getdatabatch) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `getDataBatch(bytes32[])` +- Function selector: `0xdedff9c6` + +::: + +```solidity +function getDataBatch( + bytes32[] dataKeys +) external view returns (bytes[] dataValues); +``` + +_Reading the ERC725Y storage for data keys `dataKeys` returned the following values: `dataValues`._ + +Get in the ERC725Y storage the bytes data stored at multiple data keys `dataKeys`. + +#### Parameters + +| Name | Type | Description | +| ---------- | :---------: | ------------------------------------------ | +| `dataKeys` | `bytes32[]` | The array of keys which values to retrieve | + +#### Returns + +| Name | Type | Description | +| ------------ | :-------: | ----------------------------------------- | +| `dataValues` | `bytes[]` | The array of data stored at multiple keys | + +
+ +### isValidSignature + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#isvalidsignature) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `isValidSignature(bytes32,bytes)` +- Function selector: `0x1626ba7e` + +::: + +```solidity +function isValidSignature( + bytes32 dataHash, + bytes signature +) external view returns (bytes4 magicValue); +``` + +_Achieves the goal of [EIP-1271] by validating signatures of smart contracts according to their own logic._ + +Handles two cases: + +1. If the owner is an EOA, recovers an address from the hash and the signature provided: + +- Returns the `magicValue` if the address recovered is the same as the owner, indicating that it was a valid signature. + +- If the address is different, it returns the fail value indicating that the signature is not valid. + +2. If the owner is a smart contract, it forwards the call of [`isValidSignature()`](#isvalidsignature) to the owner contract: + +- If the contract fails or returns the fail value, the [`isValidSignature()`](#isvalidsignature) on the account returns the fail value, indicating that the signature is not valid. + +- If the [`isValidSignature()`](#isvalidsignature) on the owner returned the `magicValue`, the [`isValidSignature()`](#isvalidsignature) on the account returns the `magicValue`, indicating that it's a valid signature. + +#### Parameters + +| Name | Type | Description | +| ----------- | :-------: | ------------------------------------------------------------ | +| `dataHash` | `bytes32` | The hash of the data to be validated. | +| `signature` | `bytes` | A signature that can validate the previous parameter (Hash). | + +#### Returns + +| Name | Type | Description | +| ------------ | :------: | ----------------------------------------------------------------- | +| `magicValue` | `bytes4` | A `bytes4` value that indicates if the signature is valid or not. | + +
+ +### owner + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#owner) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `owner()` +- Function selector: `0x8da5cb5b` + +::: + +```solidity +function owner() external view returns (address); +``` + +Returns the address of the current owner. + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ----------- | +| `0` | `address` | - | + +
+ +### pendingOwner + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#pendingowner) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `pendingOwner()` +- Function selector: `0xe30c3978` + +::: + +:::info + +If no ownership transfer is in progress, the pendingOwner will be `address(0).`. + +::: + +```solidity +function pendingOwner() external view returns (address); +``` + +The address that ownership of the contract is transferred to. This address may use [`acceptOwnership()`](#acceptownership) to gain ownership of the contract. + +#### Returns + +| Name | Type | Description | +| ---- | :-------: | ----------- | +| `0` | `address` | - | + +
+ +### renounceOwnership + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#renounceownership) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `renounceOwnership()` +- Function selector: `0x715018a6` + +::: + +:::danger + +Leaves the contract without an owner. Once ownership of the contract has been renounced, any functions that are restricted to be called by the owner will be permanently inaccessible, making these functions not callable anymore and unusable. + +::: + +```solidity +function renounceOwnership() external nonpayable; +``` + +_`msg.sender` is renouncing ownership of contract `address(this)`._ + +Renounce ownership of the contract in a 2-step process. + +1. The first call will initiate the process of renouncing ownership. + +2. The second call is used as a confirmation and will leave the contract without an owner. + +
+ +**Requirements:** + +- Can be only called by the [`owner`](#owner) or by an authorised address that pass the verification check performed on the owner. + +
+ +
+ +### setData + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#setdata) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `setData(bytes32,bytes)` +- Function selector: `0x7f23690c` + +::: + +```solidity +function setData(bytes32 dataKey, bytes dataValue) external payable; +``` + +_Setting the following data key value pair in the ERC725Y storage. Data key: `dataKey`, data value: `dataValue`. _ + +Sets a single bytes value `dataValue` in the ERC725Y storage for a specific data key `dataKey`. The function is marked as payable to enable flexibility on child contracts. For instance to implement a fee mechanism for setting specific data. + +
+ +**Requirements:** + +- Can be only called by the [`owner`](#owner) or by an authorised address that pass the verification check performed on the owner. + +
+ +
+ +**Emitted events:** + +- [`ValueReceived`](#valuereceived) event when receiving native tokens. +- [`DataChanged`](#datachanged) event. + +
+ +#### Parameters + +| Name | Type | Description | +| ----------- | :-------: | ------------------------------------------ | +| `dataKey` | `bytes32` | The data key for which to set a new value. | +| `dataValue` | `bytes` | The new bytes value to set. | + +
+ +### setDataBatch + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#setdatabatch) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `setDataBatch(bytes32[],bytes[])` +- Function selector: `0x97902421` + +::: + +```solidity +function setDataBatch(bytes32[] dataKeys, bytes[] dataValues) external payable; +``` + +_Setting the following data key value pairs in the ERC725Y storage. Data keys: `dataKeys`, data values: `dataValues`. _ + +Batch data setting function that behaves the same as [`setData`](#setdata) but allowing to set multiple data key/value pairs in the ERC725Y storage in the same transaction. + +
+ +**Requirements:** + +- Can be only called by the [`owner`](#owner) or by an authorised address that pass the verification check performed on the owner. + +
+ +
+ +**Emitted events:** + +- [`ValueReceived`](#valuereceived) event when receiving native tokens. +- [`DataChanged`](#datachanged) event. (on each iteration of setting data) + +
+ +#### Parameters + +| Name | Type | Description | +| ------------ | :---------: | ---------------------------------------------------- | +| `dataKeys` | `bytes32[]` | An array of data keys to set bytes values for. | +| `dataValues` | `bytes[]` | An array of bytes values to set for each `dataKeys`. | + +
+ +### supportsInterface + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#supportsinterface) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `supportsInterface(bytes4)` +- Function selector: `0x01ffc9a7` + +::: + +```solidity +function supportsInterface(bytes4 interfaceId) external view returns (bool); +``` + +_Achieves the goal of [ERC-165] to detect supported interfaces and [LSP-17-ContractExtension] by checking if the interfaceId being queried is supported on another linked extension._ + +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 [LSP-17-ContractExtension], and checks if the extension implements the interface defined by `interfaceId`. + +#### Parameters + +| Name | Type | Description | +| ------------- | :------: | ----------- | +| `interfaceId` | `bytes4` | - | + +#### Returns + +| Name | Type | Description | +| ---- | :----: | ----------- | +| `0` | `bool` | - | + +
+ +### transferOwnership + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#transferownership) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `transferOwnership(address)` +- Function selector: `0xf2fde38b` + +::: + +```solidity +function transferOwnership(address pendingNewOwner) external nonpayable; +``` + +_Transfer ownership initiated by `newOwner`._ + +Initiate the process of transferring ownership of the contract by setting the new owner as the pending owner. If the new owner is a contract that supports + implements LSP1, this will also attempt to notify the new owner that ownership has been transferred to them by calling the [`universalReceiver()`](#universalreceiver) function on the `newOwner` contract. + +
+ +**Requirements:** + +- Can be only called by the [`owner`](#owner) or by an authorised address that pass the verification check performed on the owner. +- When notifying the new owner via LSP1, the `typeId` used must be the `keccak256(...)` hash of [LSP0OwnershipTransferStarted]. +- Pending owner cannot accept ownership in the same tx via the LSP1 hook. + +
+ +#### Parameters + +| Name | Type | Description | +| ----------------- | :-------: | ----------- | +| `pendingNewOwner` | `address` | - | + +
+ +### universalReceiver + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#universalreceiver) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Function signature: `universalReceiver(bytes32,bytes)` +- Function selector: `0x6bb56a14` + +::: + +```solidity +function universalReceiver( + bytes32 typeId, + bytes receivedData +) external payable returns (bytes returnedValues); +``` + +_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 ([LSP1UniversalReceiverDelegate]) that react on the whole transaction and on the specific typeId, respectively. The notification is achieved by emitting a [`UniversalReceiver`](#universalreceiver) event on the call with the function parameters, call options, and the response of the UniversalReceiverDelegates (URD) contract._ + +The function performs the following steps: + +1. Query the [ERC-725Y] storage with the data key [_LSP1_UNIVERSAL_RECEIVER_DELEGATE_KEY]. + +- If there is an address stored under the data key, check if this address supports the LSP1 interfaceId. + +- If yes, call this address with the typeId and data (params), along with additional calldata consisting of 20 bytes of `msg.sender` and 32 bytes of `msg.value`. If not, continue the execution of the function. + +2. Query the [ERC-725Y] storage with the data key [_LSP1_UNIVERSAL_RECEIVER_DELEGATE_PREFIX] + `bytes32(typeId)`. (Check [LSP-2-ERC725YJSONSchema] for encoding the data key) + +- If there is an address stored under the data key, check if this address supports the LSP1 interfaceId. + +- If yes, call this address with the typeId and data (params), along with additional calldata consisting of 20 bytes of `msg.sender` and 32 bytes of `msg.value`. If not, continue the execution of the function. + +
+ +**Emitted events:** + +- [`ValueReceived`](#valuereceived) when receiving native tokens. +- [`UniversalReceiver`](#universalreceiver) event. + +
+ +#### Parameters + +| Name | Type | Description | +| -------------- | :-------: | -------------------------- | +| `typeId` | `bytes32` | The type of call received. | +| `receivedData` | `bytes` | The data received. | + +#### Returns + +| Name | Type | Description | +| ---------------- | :-----: | ------------------------------------------------------------------------------------------------------- | +| `returnedValues` | `bytes` | The ABI encoded return value of the LSP1UniversalReceiverDelegate call and the LSP1TypeIdDelegate call. | + +
+ +## Internal Methods + +Any method labeled as `internal` serves as utility function within the contract. They can be used when writing solidity contracts that inherit from this contract. These methods can be extended or modified by overriding their internal behavior to suit specific needs. + +Internal functions cannot be called externally, whether from other smart contracts, dApp interfaces, or backend services. Their restricted accessibility ensures that they remain exclusively available within the context of the current contract, promoting controlled and encapsulated usage of these internal utilities. + +### \_checkOwner + +```solidity +function _checkOwner() internal view; +``` + +Throws if the sender is not the owner. + +
+ +### \_setOwner + +```solidity +function _setOwner(address newOwner) internal nonpayable; +``` + +Changes the owner if `newOwner` and oldOwner are different +This pattern is useful in inheritance. + +
+ +### \_execute + +```solidity +function _execute( + uint256 operationType, + address target, + uint256 value, + bytes data +) internal nonpayable returns (bytes); +``` + +check the `operationType` provided and perform the associated low-level opcode after checking for requirements (see [`execute`](#execute)). + +
+ +### \_executeBatch + +```solidity +function _executeBatch( + uint256[] operationsType, + address[] targets, + uint256[] values, + bytes[] datas +) internal nonpayable returns (bytes[]); +``` + +check each `operationType` provided in the batch and perform the associated low-level opcode after checking for requirements (see [`executeBatch`](#executebatch)). + +
+ +### \_executeCall + +```solidity +function _executeCall( + address target, + uint256 value, + bytes data +) internal nonpayable returns (bytes result); +``` + +Perform low-level call (operation type = 0) + +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | ------------------------------------- | +| `target` | `address` | The address on which call is executed | +| `value` | `uint256` | The value to be sent with the call | +| `data` | `bytes` | The data to be sent with the call | + +#### Returns + +| Name | Type | Description | +| -------- | :-----: | ---------------------- | +| `result` | `bytes` | The data from the call | + +
+ +### \_executeStaticCall + +```solidity +function _executeStaticCall( + address target, + bytes data +) internal nonpayable returns (bytes result); +``` + +Perform low-level staticcall (operation type = 3) + +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | ------------------------------------------- | +| `target` | `address` | The address on which staticcall is executed | +| `data` | `bytes` | The data to be sent with the staticcall | + +#### Returns + +| Name | Type | Description | +| -------- | :-----: | ------------------------------------- | +| `result` | `bytes` | The data returned from the staticcall | + +
+ +### \_executeDelegateCall + +```solidity +function _executeDelegateCall( + address target, + bytes data +) internal nonpayable returns (bytes result); +``` + +Perform low-level delegatecall (operation type = 4) + +#### Parameters + +| Name | Type | Description | +| -------- | :-------: | --------------------------------------------- | +| `target` | `address` | The address on which delegatecall is executed | +| `data` | `bytes` | The data to be sent with the delegatecall | + +#### Returns + +| Name | Type | Description | +| -------- | :-----: | --------------------------------------- | +| `result` | `bytes` | The data returned from the delegatecall | + +
+ +### \_deployCreate + +```solidity +function _deployCreate( + uint256 value, + bytes creationCode +) internal nonpayable returns (bytes newContract); +``` + +Deploy a contract using the `CREATE` opcode (operation type = 1) + +#### Parameters + +| Name | Type | Description | +| -------------- | :-------: | ---------------------------------------------------------------------------------- | +| `value` | `uint256` | The value to be sent to the contract created | +| `creationCode` | `bytes` | The contract creation bytecode to deploy appended with the constructor argument(s) | + +#### Returns + +| Name | Type | Description | +| ------------- | :-----: | -------------------------------------------- | +| `newContract` | `bytes` | The address of the contract created as bytes | + +
+ +### \_deployCreate2 + +```solidity +function _deployCreate2( + uint256 value, + bytes creationCode +) internal nonpayable returns (bytes newContract); +``` + +Deploy a contract using the `CREATE2` opcode (operation type = 2) + +#### Parameters + +| Name | Type | Description | +| -------------- | :-------: | ----------------------------------------------------------------------------------------------------- | +| `value` | `uint256` | The value to be sent to the contract created | +| `creationCode` | `bytes` | The contract creation bytecode to deploy appended with the constructor argument(s) and a bytes32 salt | + +#### Returns + +| Name | Type | Description | +| ------------- | :-----: | -------------------------------------------- | +| `newContract` | `bytes` | The address of the contract created as bytes | + +
+ +### \_getData + +```solidity +function _getData(bytes32 dataKey) internal view returns (bytes dataValue); +``` + +Read the value stored under a specific `dataKey` inside the underlying ERC725Y storage, +represented as a mapping of `bytes32` data keys mapped to their `bytes` data values. + +```solidity +mapping(bytes32 => bytes) _store +``` + +#### Parameters + +| Name | Type | Description | +| --------- | :-------: | ----------------------------------------------------------------------- | +| `dataKey` | `bytes32` | A bytes32 data key to read the associated `bytes` value from the store. | + +#### Returns + +| Name | Type | Description | +| ----------- | :-----: | ----------------------------------------------------------------------------- | +| `dataValue` | `bytes` | The `bytes` value associated with the given `dataKey` in the ERC725Y storage. | + +
+ +### \_setData + +```solidity +function _setData(bytes32 dataKey, bytes dataValue) internal nonpayable; +``` + +This function overrides the [`ERC725YCore`](#erc725ycore) internal [`_setData`](#_setdata) function to optimize gas usage by + +
+ +**Emitted events:** + +- [`DataChanged`](#datachanged) event with only the first 256 bytes of [`dataValue`](#datavalue). + +
+ +#### Parameters + +| Name | Type | Description | +| ----------- | :-------: | -------------------------------------- | +| `dataKey` | `bytes32` | The key to store the data value under. | +| `dataValue` | `bytes` | The data value to be stored. | + +
+ +### \_transferOwnership + +```solidity +function _transferOwnership(address newOwner) internal nonpayable; +``` + +Set the pending owner of the contract and cancel any renounce ownership process that was previously started. + +
+ +**Requirements:** + +- `newOwner` cannot be the address of the contract itself. + +
+ +#### Parameters + +| Name | Type | Description | +| ---------- | :-------: | ------------------------------------- | +| `newOwner` | `address` | The address of the new pending owner. | + +
+ +### \_acceptOwnership + +```solidity +function _acceptOwnership() internal nonpayable; +``` + +Set the pending owner of the contract as the new owner. + +
+ +### \_renounceOwnership + +```solidity +function _renounceOwnership() internal nonpayable; +``` + +Initiate or confirm the process of renouncing ownership after a specific delay of blocks have passed. + +
+ +### \_supportsInterfaceInERC165Extension + +```solidity +function _supportsInterfaceInERC165Extension( + bytes4 interfaceId +) internal view returns (bool); +``` + +Returns whether the interfaceId being checked is supported in the extension of the +[`supportsInterface`](#supportsinterface) selector. +To be used by extendable contracts wishing to extend the ERC165 interfaceIds originally +supported by reading whether the interfaceId queried is supported in the `supportsInterface` +extension if the extension is set, if not it returns false. + +
+ +### \_getExtension + +```solidity +function _getExtension(bytes4 functionSelector) internal view returns (address); +``` + +Returns the extension address stored under the following data key: +{\_LSP17_EXTENSION_PREFIX + } (Check [LSP2-ERC725YJSONSchema] for encoding the data key) +If no extension is stored, returns the address(0) + +
+ +### \_fallbackLSP17Extendable + +```solidity +function _fallbackLSP17Extendable( + bytes callData +) internal nonpayable returns (bytes); +``` + +Forwards the call to an extension mapped to a function selector. +Calls [`_getExtension`](#_getextension) to get the address of the extension mapped to the function selector being +called on the account. If there is no extension, the `address(0)` will be returned. +Reverts if there is no extension for the function being called, except for the bytes4(0) function +selector, which passes even if there is no extension for it. +If there is an extension for the function selector being called, it calls the extension with the +CALL opcode, passing the `msg.data` appended with the 20 bytes of the `msg.sender` and +32 bytes of the `msg.value` + +
+ +### \_verifyCall + +```solidity +function _verifyCall( + address logicVerifier +) internal nonpayable returns (bool verifyAfter); +``` + +Calls [`lsp20VerifyCall`](#lsp20verifycall) function on the logicVerifier. +Reverts in case the value returned does not match the magic value (lsp20VerifyCall selector) +Returns whether a verification after the execution should happen based on the last byte of the magicValue + +
+ +### \_verifyCallResult + +```solidity +function _verifyCallResult( + address logicVerifier, + bytes callResult +) internal nonpayable; +``` + +Calls [`lsp20VerifyCallResult`](#lsp20verifycallresult) function on the logicVerifier. +Reverts in case the value returned does not match the magic value (lsp20VerifyCallResult selector) + +
+ +### \_validateCall + +```solidity +function _validateCall( + bool postCall, + bool success, + bytes returnedData +) internal pure; +``` + +
+ +### \_revertWithLSP20DefaultError + +```solidity +function _revertWithLSP20DefaultError( + bool postCall, + bytes returnedData +) internal pure; +``` + +
+ +## Events + +### ContractCreated + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#contractcreated) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Event signature: `ContractCreated(uint256,address,uint256,bytes32)` +- Event topic hash: `0xa1fb700aaee2ae4a2ff6f91ce7eba292f89c2f5488b8ec4c5c5c8150692595c3` + +::: + +```solidity +event ContractCreated(uint256 indexed operationType, address indexed contractAddress, uint256 indexed value, bytes32 salt); +``` + +_Deployed new contract at address `contractAddress` and funded with `value` wei (deployed using opcode: `operationType`)._ + +Emitted when a new contract was created and deployed. + +#### Parameters + +| Name | Type | Description | +| ------------------------------- | :-------: | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `operationType` **`indexed`** | `uint256` | The opcode used to deploy the contract (`CREATE` or `CREATE2`). | +| `contractAddress` **`indexed`** | `address` | The created contract address. | +| `value` **`indexed`** | `uint256` | The amount of native tokens (in Wei) sent to fund the created contract on deployment. | +| `salt` | `bytes32` | The salt used to deterministically deploy the contract (`CREATE2` only). If `CREATE` opcode is used, the salt value will be `bytes32(0)`. | + +
+ +### DataChanged + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#datachanged) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Event signature: `DataChanged(bytes32,bytes)` +- Event topic hash: `0xece574603820d07bc9b91f2a932baadf4628aabcb8afba49776529c14a6104b2` + +::: + +```solidity +event DataChanged(bytes32 indexed dataKey, bytes dataValue); +``` + +_The following data key/value pair has been changed in the ERC725Y storage: Data key: `dataKey`, data value: `dataValue`._ + +Emitted when data at a specific `dataKey` was changed to a new value `dataValue`. + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | -------------------------------------------- | +| `dataKey` **`indexed`** | `bytes32` | The data key for which a bytes value is set. | +| `dataValue` | `bytes` | The value to set for the given data key. | + +
+ +### Executed + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#executed) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Event signature: `Executed(uint256,address,uint256,bytes4)` +- Event topic hash: `0x4810874456b8e6487bd861375cf6abd8e1c8bb5858c8ce36a86a04dabfac199e` + +::: + +```solidity +event Executed(uint256 indexed operationType, address indexed target, uint256 indexed value, bytes4 selector); +``` + +_Called address `target` using `operationType` with `value` wei and `data`._ + +Emitted when calling an address `target` (EOA or contract) with `value`. + +#### Parameters + +| Name | Type | Description | +| ----------------------------- | :-------: | ---------------------------------------------------------------------------------------------------- | +| `operationType` **`indexed`** | `uint256` | The low-level call opcode used to call the `target` address (`CALL`, `STATICALL` or `DELEGATECALL`). | +| `target` **`indexed`** | `address` | The address to call. `target` will be unused if a contract is created (operation types 1 and 2). | +| `value` **`indexed`** | `uint256` | The amount of native tokens transferred along the call (in Wei). | +| `selector` | `bytes4` | The first 4 bytes (= function selector) of the data sent with the call. | + +
+ +### OwnershipRenounced + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#ownershiprenounced) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Event signature: `OwnershipRenounced()` +- Event topic hash: `0xd1f66c3d2bc1993a86be5e3d33709d98f0442381befcedd29f578b9b2506b1ce` + +::: + +```solidity +event OwnershipRenounced(); +``` + +_Successfully renounced ownership of the contract. This contract is now owned by anyone, it's owner is `address(0)`._ + +Emitted when the ownership of the contract has been renounced. + +
+ +### OwnershipTransferStarted + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#ownershiptransferstarted) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Event signature: `OwnershipTransferStarted(address,address)` +- Event topic hash: `0x38d16b8cac22d99fc7c124b9cd0de2d3fa1faef420bfe791d8c362d765e22700` + +::: + +```solidity +event OwnershipTransferStarted(address indexed previousOwner, address indexed newOwner); +``` + +_The transfer of ownership of the contract was initiated. Pending new owner set to: `newOwner`._ + +Emitted when [`transferOwnership(..)`](#transferownership) was called and the first step of transferring ownership completed successfully which leads to [`pendingOwner`](#pendingowner) being updated. + +#### Parameters + +| Name | Type | Description | +| ----------------------------- | :-------: | ---------------------------------- | +| `previousOwner` **`indexed`** | `address` | The address of the previous owner. | +| `newOwner` **`indexed`** | `address` | The address of the new owner. | + +
+ +### OwnershipTransferred + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#ownershiptransferred) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Event signature: `OwnershipTransferred(address,address)` +- Event topic hash: `0x8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0` + +::: + +```solidity +event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); +``` + +#### Parameters + +| Name | Type | Description | +| ----------------------------- | :-------: | ----------- | +| `previousOwner` **`indexed`** | `address` | - | +| `newOwner` **`indexed`** | `address` | - | + +
+ +### RenounceOwnershipStarted + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#renounceownershipstarted) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Event signature: `RenounceOwnershipStarted()` +- Event topic hash: `0x81b7f830f1f0084db6497c486cbe6974c86488dcc4e3738eab94ab6d6b1653e7` + +::: + +```solidity +event RenounceOwnershipStarted(); +``` + +_Ownership renouncement initiated._ + +Emitted when starting the [`renounceOwnership(..)`](#renounceownership) 2-step process. + +
+ +### UniversalReceiver + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#universalreceiver) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Event signature: `UniversalReceiver(address,uint256,bytes32,bytes,bytes)` +- Event topic hash: `0x9c3ba68eb5742b8e3961aea0afc7371a71bf433c8a67a831803b64c064a178c2` + +::: + +```solidity +event UniversalReceiver(address indexed from, uint256 indexed value, bytes32 indexed typeId, bytes receivedData, bytes returnedValue); +``` + +\*Address `from` called the `universalReceiver(...)` function while sending `value` LYX. Notification type (typeId): `typeId` + +- Data received: `receivedData`.\* + +Emitted when the [`universalReceiver`](#universalreceiver) function was called with a specific `typeId` and some `receivedData` s + +#### Parameters + +| Name | Type | Description | +| ---------------------- | :-------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `from` **`indexed`** | `address` | The address of the EOA or smart contract that called the {universalReceiver(...)} function. | +| `value` **`indexed`** | `uint256` | The amount sent to the {universalReceiver(...)} function. | +| `typeId` **`indexed`** | `bytes32` | 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. | +| `receivedData` | `bytes` | Any arbitrary data that was sent to the {universalReceiver(...)} function. | +| `returnedValue` | `bytes` | The value returned by the {universalReceiver(...)} function. | + +
+ +### ValueReceived + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#valuereceived) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Event signature: `ValueReceived(address,uint256)` +- Event topic hash: `0x7e71433ddf847725166244795048ecf3e3f9f35628254ecbf736056664233493` + +::: + +```solidity +event ValueReceived(address indexed sender, uint256 indexed value); +``` + +_`value` tokens received from `sender`._ + +#### Parameters + +| Name | Type | Description | +| ---------------------- | :-------: | ------------------------------------ | +| `sender` **`indexed`** | `address` | The address of the sender | +| `value` **`indexed`** | `uint256` | The amount of native tokens received | + +
+ +## Errors + +### CannotTransferOwnershipToSelf + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#cannottransferownershiptoself) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `CannotTransferOwnershipToSelf()` +- Error hash: `0x43b248cd` + +::: + +```solidity +error CannotTransferOwnershipToSelf(); +``` + +_Cannot transfer ownership to the address of the contract itself._ + +Reverts when trying to transfer ownership to the `address(this)`. + +
+ +### ERC725X_ContractDeploymentFailed + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#erc725x_contractdeploymentfailed) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `ERC725X_ContractDeploymentFailed()` +- Error hash: `0x0b07489b` + +::: + +```solidity +error ERC725X_ContractDeploymentFailed(); +``` + +Reverts when contract deployment failed via [`execute`](#execute) or [`executeBatch`](#executebatch) functions, This error can occur using either operation type 1 (`CREATE`) or 2 (`CREATE2`). + +
+ +### ERC725X_CreateOperationsRequireEmptyRecipientAddress + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#erc725x_createoperationsrequireemptyrecipientaddress) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `ERC725X_CreateOperationsRequireEmptyRecipientAddress()` +- Error hash: `0x3041824a` + +::: + +```solidity +error ERC725X_CreateOperationsRequireEmptyRecipientAddress(); +``` + +Reverts when passing a `to` address that is not `address(0)` (= address zero) while deploying a contract via [`execute`](#execute) or [`executeBatch`](#executebatch) functions. This error can occur using either operation type 1 (`CREATE`) or 2 (`CREATE2`). + +
+ +### ERC725X_ExecuteParametersEmptyArray + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#erc725x_executeparametersemptyarray) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `ERC725X_ExecuteParametersEmptyArray()` +- Error hash: `0xe9ad2b5f` + +::: + +```solidity +error ERC725X_ExecuteParametersEmptyArray(); +``` + +Reverts when one of the array parameter provided to the [`executeBatch`](#executebatch) function is an empty array. + +
+ +### ERC725X_ExecuteParametersLengthMismatch + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#erc725x_executeparameterslengthmismatch) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `ERC725X_ExecuteParametersLengthMismatch()` +- Error hash: `0x3ff55f4d` + +::: + +```solidity +error ERC725X_ExecuteParametersLengthMismatch(); +``` + +Reverts when there is not the same number of elements in the `operationTypes`, `targets` addresses, `values`, and `datas` array parameters provided when calling the [`executeBatch`](#executebatch) function. + +
+ +### ERC725X_InsufficientBalance + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#erc725x_insufficientbalance) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `ERC725X_InsufficientBalance(uint256,uint256)` +- Error hash: `0x0df9a8f8` + +::: + +```solidity +error ERC725X_InsufficientBalance(uint256 balance, uint256 value); +``` + +Reverts when trying to send more native tokens `value` than available in current `balance`. + +#### Parameters + +| Name | Type | Description | +| --------- | :-------: | -------------------------------------------------------------------------------------------------------------------------------------- | +| `balance` | `uint256` | The balance of native tokens of the ERC725X smart contract. | +| `value` | `uint256` | The amount of native tokens sent via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)` that is greater than the contract's `balance`. | + +
+ +### ERC725X_MsgValueDisallowedInDelegateCall + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#erc725x_msgvaluedisallowedindelegatecall) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `ERC725X_MsgValueDisallowedInDelegateCall()` +- Error hash: `0x5ac83135` + +::: + +```solidity +error ERC725X_MsgValueDisallowedInDelegateCall(); +``` + +Reverts when trying to send native tokens (`value` / `values[]` parameter of [`execute`](#execute) or [`executeBatch`](#executebatch) functions) while making a `delegatecall` (`operationType == 4`). Sending native tokens via `staticcall` is not allowed because `msg.value` is persisting. + +
+ +### ERC725X_MsgValueDisallowedInStaticCall + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#erc725x_msgvaluedisallowedinstaticcall) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `ERC725X_MsgValueDisallowedInStaticCall()` +- Error hash: `0x72f2bc6a` + +::: + +```solidity +error ERC725X_MsgValueDisallowedInStaticCall(); +``` + +Reverts when trying to send native tokens (`value` / `values[]` parameter of [`execute`](#execute) or [`executeBatch`](#executebatch) functions) while making a `staticcall` (`operationType == 3`). Sending native tokens via `staticcall` is not allowed because it is a state changing operation. + +
+ +### ERC725X_NoContractBytecodeProvided + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#erc725x_nocontractbytecodeprovided) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `ERC725X_NoContractBytecodeProvided()` +- Error hash: `0xb81cd8d9` + +::: + +```solidity +error ERC725X_NoContractBytecodeProvided(); +``` + +Reverts when no contract bytecode was provided as parameter when trying to deploy a contract via [`execute`](#execute) or [`executeBatch`](#executebatch). This error can occur using either operation type 1 (`CREATE`) or 2 (`CREATE2`). + +
+ +### ERC725X_UnknownOperationType + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#erc725x_unknownoperationtype) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `ERC725X_UnknownOperationType(uint256)` +- Error hash: `0x7583b3bc` + +::: + +```solidity +error ERC725X_UnknownOperationType(uint256 operationTypeProvided); +``` + +Reverts when the `operationTypeProvided` is none of the default operation types available. (CALL = 0; CREATE = 1; CREATE2 = 2; STATICCALL = 3; DELEGATECALL = 4) + +#### Parameters + +| Name | Type | Description | +| ----------------------- | :-------: | ------------------------------------------------------------------------------------------------------ | +| `operationTypeProvided` | `uint256` | The unrecognised operation type number provided to `ERC725X.execute(...)`/`ERC725X.executeBatch(...)`. | + +
+ +### ERC725Y_DataKeysValuesLengthMismatch + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#erc725y_datakeysvalueslengthmismatch) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `ERC725Y_DataKeysValuesLengthMismatch()` +- Error hash: `0x3bcc8979` + +::: + +```solidity +error ERC725Y_DataKeysValuesLengthMismatch(); +``` + +Reverts when there is not the same number of elements in the `datakeys` and `dataValues` array parameters provided when calling the [`setDataBatch`](#setdatabatch) function. + +
+ +### LSP14MustAcceptOwnershipInSeparateTransaction + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#lsp14mustacceptownershipinseparatetransaction) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `LSP14MustAcceptOwnershipInSeparateTransaction()` +- Error hash: `0x5758dd07` + +::: + +```solidity +error LSP14MustAcceptOwnershipInSeparateTransaction(); +``` + +_Cannot accept ownership in the same transaction with [`transferOwnership(...)`](#transferownership)._ + +Reverts when pending owner accept ownership in the same transaction of transferring ownership. + +
+ +### LSP20CallingVerifierFailed + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#lsp20callingverifierfailed) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `LSP20CallingVerifierFailed(bool)` +- Error hash: `0x8c6a8ae3` + +::: + +```solidity +error LSP20CallingVerifierFailed(bool postCall); +``` + +reverts when the call to the owner fail with no revert reason + +#### Parameters + +| Name | Type | Description | +| ---------- | :----: | ---------------------------------------------------- | +| `postCall` | `bool` | True if the execution call was done, False otherwise | + +
+ +### LSP20InvalidMagicValue + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#lsp20invalidmagicvalue) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `LSP20InvalidMagicValue(bool,bytes)` +- Error hash: `0xd088ec40` + +::: + +```solidity +error LSP20InvalidMagicValue(bool postCall, bytes returnedData); +``` + +reverts when the call to the owner does not return the magic value + +#### Parameters + +| Name | Type | Description | +| -------------- | :-----: | ---------------------------------------------------- | +| `postCall` | `bool` | True if the execution call was done, False otherwise | +| `returnedData` | `bytes` | The data returned by the call to the logic verifier | + +
+ +### NoExtensionFoundForFunctionSelector + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#noextensionfoundforfunctionselector) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `NoExtensionFoundForFunctionSelector(bytes4)` +- Error hash: `0xbb370b2b` + +::: + +```solidity +error NoExtensionFoundForFunctionSelector(bytes4 functionSelector); +``` + +reverts when there is no extension for the function selector being called with + +#### Parameters + +| Name | Type | Description | +| ------------------ | :------: | ----------- | +| `functionSelector` | `bytes4` | - | + +
+ +### NotInRenounceOwnershipInterval + +:::note References + +- Specification details: [**LSP-0-ERC725Account**](https://github.com/lukso-network/lips/tree/main/LSPs/LSP-0-ERC725Account.md#notinrenounceownershipinterval) +- Solidity implementation: [`LSP0ERC725Account.sol`](https://github.com/lukso-network/lsp-smart-contracts/blob/develop/contracts/LSP0ERC725Account/LSP0ERC725Account.sol) +- Error signature: `NotInRenounceOwnershipInterval(uint256,uint256)` +- Error hash: `0x8b9bf507` + +::: + +```solidity +error NotInRenounceOwnershipInterval( + uint256 renounceOwnershipStart, + uint256 renounceOwnershipEnd +); +``` + +_Cannot confirm ownership renouncement yet. The ownership renouncement is allowed from: `renounceOwnershipStart` until: `renounceOwnershipEnd`._ + +Reverts when trying to renounce ownership before the initial confirmation delay. + +#### Parameters + +| Name | Type | Description | +| ------------------------ | :-------: | ----------------------------------------------------------------------- | +| `renounceOwnershipStart` | `uint256` | The start timestamp when one can confirm the renouncement of ownership. | +| `renounceOwnershipEnd` | `uint256` | The end timestamp when one can confirm the renouncement of ownership. | + +
From 7993a4089262fc4f1f3e749abf003f2d81c7dfcd Mon Sep 17 00:00:00 2001 From: CJ42 Date: Tue, 22 Aug 2023 10:23:44 +0100 Subject: [PATCH 4/4] docs: add `@notice` tags + move `@dev` tag to child contract --- .../LSP0ERC725Account/ILSP0ERC725Account.sol | 4 +- .../LSP0ERC725Account/LSP0ERC725Account.sol | 10 + .../LSP0ERC725AccountCore.sol | 39 ++- .../LSP0ERC725AccountInit.sol | 10 + .../LSP0ERC725Account/LSP0ERC725Account.md | 247 +++++++++--------- 5 files changed, 162 insertions(+), 148 deletions(-) diff --git a/contracts/LSP0ERC725Account/ILSP0ERC725Account.sol b/contracts/LSP0ERC725Account/ILSP0ERC725Account.sol index 8db3a5cfe..8cdc2adf1 100644 --- a/contracts/LSP0ERC725Account/ILSP0ERC725Account.sol +++ b/contracts/LSP0ERC725Account/ILSP0ERC725Account.sol @@ -30,9 +30,11 @@ interface ILSP0ERC725Account { event ValueReceived(address indexed sender, uint256 indexed value); /** + * @notice Executing the following batch of abi-encoded function calls on the contract: `data`. + * * @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. * @param data An array of ABI encoded function calls to be called on the contract. - * @return results An array of abi-encode data returned by the functions executed. + * @return results An array of abi-encoded data returned by the functions executed. */ function batchCalls( bytes[] calldata data diff --git a/contracts/LSP0ERC725Account/LSP0ERC725Account.sol b/contracts/LSP0ERC725Account/LSP0ERC725Account.sol index 2ac6bf912..e30ee26da 100644 --- a/contracts/LSP0ERC725Account/LSP0ERC725Account.sol +++ b/contracts/LSP0ERC725Account/LSP0ERC725Account.sol @@ -11,6 +11,16 @@ import { * @title Deployable Implementation of [LSP-0-ERC725Account] Standard. * * @author Fabian Vogelsteller , Jean Cavallera (CJ42) + * + * @dev A smart contract account including basic functionalities such as: + * - Detecting supported standards using [ERC-165] + * - Executing several operation on other addresses including creating contracts using [ERC-725X] + * - A generic data key-value store using [ERC-725Y] + * - Validating signatures using [ERC-1271] + * - Receiving notification and react on them using [LSP-1-UniversalReceiver] + * - Safer ownership management through 2-steps transfer using [LSP-14-Ownable2Step] + * - Extending the account with new functions and interfaceIds of future standards using [LSP-17-ContractExtension] + * - Verifying calls on the owner to make it easier to interact with the account directly using [LSP-20-CallVerification] */ contract LSP0ERC725Account is LSP0ERC725AccountCore { /** diff --git a/contracts/LSP0ERC725Account/LSP0ERC725AccountCore.sol b/contracts/LSP0ERC725Account/LSP0ERC725AccountCore.sol index 5a98bcedd..1b42cdf53 100644 --- a/contracts/LSP0ERC725Account/LSP0ERC725AccountCore.sol +++ b/contracts/LSP0ERC725Account/LSP0ERC725AccountCore.sol @@ -77,15 +77,6 @@ import { * @title The Core Implementation of [LSP-0-ERC725Account] Standard. * * @author Fabian Vogelsteller , Jean Cavallera (CJ42) - * @dev A smart contract account including basic functionalities such as: - * - Detecting supported standards using [ERC-165] - * - Executing several operation on other addresses including creating contracts using [ERC-725X] - * - Storing data in a generic way using [ERC-725Y] - * - Validating signatures using [ERC-1271] - * - Receiving notification and react on them using [LSP-1-UniversalReceiver] - * - Secure ownership management using [LSP-14-Ownable2Step] - * - Extending the account with new functions and interfaceIds of future standards using [LSP-17-ContractExtension] - * - Verifying calls on the owner to allow unified and standard interaction with the account using [LSP-20-CallVerification] */ abstract contract LSP0ERC725AccountCore is ERC725XCore, @@ -117,9 +108,12 @@ abstract contract LSP0ERC725AccountCore is // solhint-disable no-complex-fallback /** - * @notice Achieves the goal of [LSP-17-ContractExtension] standard by extending the contract to handle calls of functions that do not exist natively, forwarding the function call to the extension address mapped to the function being called. + * @notice The `fallback` function was called with the following amount of native tokens: `msg.value`; and the following calldata: `callData`. * - * @dev This function is executed when: + * @dev Achieves the goal of [LSP-17-ContractExtension] standard by extending the contract to handle calls of functions that do not exist natively, + * forwarding the function call to the extension address mapped to the function being called. + * + * This function is executed when: * - Sending data of length less than 4 bytes to the contract. * - The first 4 bytes of the calldata do not match any publicly callable functions from the contract ABI. * - Receiving native tokens with some calldata. @@ -390,13 +384,12 @@ abstract contract LSP0ERC725AccountCore is } /** - * @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. + * @notice Notifying the contract by calling its `universalReceiver` function with the following informations: typeId: `typeId`; data: `data`. * + * @dev 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 ([LSP1UniversalReceiverDelegate]) that react on the whole transaction and on the specific typeId, respectively. * - * The notification is achieved by emitting a {UniversalReceiver} event on the call with the function parameters, call options, and the response of the UniversalReceiverDelegates (URD) contract. - * - * @dev The function performs the following steps: + * The function performs the following steps: * * 1. Query the [ERC-725Y] storage with the data key [_LSP1_UNIVERSAL_RECEIVER_DELEGATE_KEY]. * - If there is an address stored under the data key, check if this address supports the LSP1 interfaceId. @@ -418,7 +411,7 @@ abstract contract LSP0ERC725AccountCore is * * @custom:events * - {ValueReceived} when receiving native tokens. - * - {UniversalReceiver} event. + * - {UniversalReceiver} event with the function parameters, call options, and the response of the UniversalReceiverDelegates (URD) contract that was called. */ function universalReceiver( bytes32 typeId, @@ -628,15 +621,18 @@ abstract contract LSP0ERC725AccountCore is } /** - * @notice Achieves the goal of [ERC-165] to detect supported interfaces and [LSP-17-ContractExtension] by - * checking if the interfaceId being queried is supported on another linked extension. + * @notice Checking if this contract supports the interface defined by the bytes4 interface ID `interfaceId`. * - * @dev Returns true if this contract implements the interface defined by - * `interfaceId`. + * @dev Achieves the goal of [ERC-165] to detect supported interfaces and [LSP-17-ContractExtension] by + * checking if the interfaceId being queried is supported on another linked extension. * * If the contract doesn't support the `interfaceId`, it forwards the call to the * `supportsInterface` extension according to [LSP-17-ContractExtension], and checks if the extension * implements the interface defined by `interfaceId`. + * + * @param interfaceId The interface ID to check if the contract supports it. + * + * @return `true` if this contract implements the interface defined by `interfaceId`, `false` otherwise. */ function supportsInterface( bytes4 interfaceId @@ -792,7 +788,8 @@ abstract contract LSP0ERC725AccountCore is /** * @custom:events {DataChanged} event with only the first 256 bytes of {dataValue}. * - * @dev This function overrides the {ERC725YCore} internal {_setData} function to optimize gas usage by + * @dev This function overrides the {ERC725YCore} internal {_setData} function to optimize gas usage by emitting only the first 256 bytes of the `dataValue`. + * * @param dataKey The key to store the data value under. * @param dataValue The data value to be stored. */ diff --git a/contracts/LSP0ERC725Account/LSP0ERC725AccountInit.sol b/contracts/LSP0ERC725Account/LSP0ERC725AccountInit.sol index 303c1a614..41e0301f0 100644 --- a/contracts/LSP0ERC725Account/LSP0ERC725AccountInit.sol +++ b/contracts/LSP0ERC725Account/LSP0ERC725AccountInit.sol @@ -10,6 +10,16 @@ import { * @title Deployable Proxy Implementation of [LSP-0-ERC725Account] Standard. * * @author Fabian Vogelsteller , Jean Cavallera (CJ42) + * + * @dev A smart contract account including basic functionalities such as: + * - Detecting supported standards using [ERC-165] + * - Executing several operation on other addresses including creating contracts using [ERC-725X] + * - A generic data key-value store using [ERC-725Y] + * - Validating signatures using [ERC-1271] + * - Receiving notification and react on them using [LSP-1-UniversalReceiver] + * - Safer ownership management through 2-steps transfer using [LSP-14-Ownable2Step] + * - Extending the account with new functions and interfaceIds of future standards using [LSP-17-ContractExtension] + * - Verifying calls on the owner to make it easier to interact with the account directly using [LSP-20-CallVerification] */ contract LSP0ERC725AccountInit is LSP0ERC725AccountInitAbstract { /** diff --git a/docs/contracts/LSP0ERC725Account/LSP0ERC725Account.md b/docs/contracts/LSP0ERC725Account/LSP0ERC725Account.md index 59b09bdce..243c842a1 100644 --- a/docs/contracts/LSP0ERC725Account/LSP0ERC725Account.md +++ b/docs/contracts/LSP0ERC725Account/LSP0ERC725Account.md @@ -14,7 +14,7 @@ ::: -> Deployable Implementation of LSP0-ERC725Account Standard https://github.com/lukso-network/LIPs/blob/main/LSPs/LSP-0-ERC725Account.md +> Deployable Implementation of [LSP-0-ERC725Account] Standard. A smart contract account including basic functionalities such as: @@ -22,17 +22,17 @@ A smart contract account including basic functionalities such as: - Executing several operation on other addresses including creating contracts using [ERC-725X] -- Storing data in a generic way using [ERC-725Y] +- A generic data key-value store using [ERC-725Y] - Validating signatures using [ERC-1271] - Receiving notification and react on them using [LSP-1-UniversalReceiver] -- Secure ownership management using [LSP-14-Ownable2Step] +- Safer ownership management through 2-steps transfer using [LSP-14-Ownable2Step] - Extending the account with new functions and interfaceIds of future standards using [LSP-17-ContractExtension] -- Verifying calls on the owner to allow unified and standard interaction with the account using [LSP-20-CallVerification] +- Verifying calls on the owner to make it easier to interact with the account directly using [LSP-20-CallVerification] ## Public Methods @@ -52,7 +52,7 @@ When marked as 'public', a method can be called both externally and internally, constructor(address initialOwner); ``` -_Deploying an LSP0ERC725Account with owner set to: `initialOwner`_ +_Deploying a LSP0ERC725Account contract with owner set to address `initialOwner`._ Set `initialOwner` as the contract owner. The `constructor` also allows funding the contract on deployment. @@ -61,7 +61,7 @@ Set `initialOwner` as the contract owner. The `constructor` also allows funding **Emitted events:** - [`ValueReceived`](#valuereceived) event when funding the contract on deployment. -- [`OwnershipTransferred`](#ownershiptransferred) event when `initialOwner` is set. +- [`OwnershipTransferred`](#ownershiptransferred) event when `initialOwner` is set as the contract [`owner`](#owner). @@ -86,8 +86,10 @@ Set `initialOwner` as the contract owner. The `constructor` also allows funding fallback(bytes calldata callData) external payable returns (bytes memory); ``` -_Achieves the goal of [LSP-17-ContractExtension] standard by extending the contract to handle calls of functions that do not exist natively, forwarding the function call to the extension address mapped to the function being called._ +_The `fallback` function was called with the following amount of native tokens: `msg.value`; and the following calldata: `callData`._ +Achieves the goal of [LSP-17-ContractExtension] standard by extending the contract to handle calls of functions that do not exist natively, +forwarding the function call to the extension address mapped to the function being called. This function is executed when: - Sending data of length less than 4 bytes to the contract. @@ -251,6 +253,8 @@ It's not possible to send value along the functions call due to the use of ` function batchCalls(bytes[] data) external nonpayable returns (bytes[] results); ``` +_Executing the following batch of abi-encoded function calls on the contract: `data`._ + Allows a caller to batch different function calls in one call. Perform a `delegatecall` on self, to call different functions with preserving the context. #### Parameters @@ -263,7 +267,7 @@ Allows a caller to batch different function calls in one call. Perform a `delega | Name | Type | Description | | --------- | :-------: | ---------------------------------------------------------------- | -| `results` | `bytes[]` | An array of abi-encoded returned data by the executed functions. | +| `results` | `bytes[]` | An array of abi-encoded data returned by the functions executed. |
@@ -287,15 +291,21 @@ function execute( ) external payable returns (bytes); ``` -_Calling address `target` using `operationType`, transferring `value` wei and data: `data`. _ - Generic executor function to: - send native tokens to any address. - interact with any contract by passing an abi-encoded function call in the `data` parameter. -- deploy a contract by providing its creation bytecode in the `data` parameter. +- deploy a contract by providing its creation bytecode in the `data` parameter. Requirements: + +- SHOULD only be callable by the owner of the contract set via ERC173. + +- if a `value` is provided, the contract MUST have at least this amount in its balance to execute successfully. + +- if the operation type is STATICCALL or DELEGATECALL, `value` SHOULD be 0. + +- `target` SHOULD be address(0) when deploying a contract. Emits an [`Executed`](#executed) event, when a call is made with `operationType` 0 (CALL), 3 (STATICCALL) or 4 (DELEGATECALL) Emits a [`ContractCreated`](#contractcreated) event, when deploying a contract with `operationType` 1 (CREATE) or 2 (CREATE2)
@@ -325,7 +335,7 @@ Generic executor function to: | `operationType` | `uint256` | The operation type used: CALL = 0; CREATE = 1; CREATE2 = 2; STATICCALL = 3; DELEGATECALL = 4 | | `target` | `address` | The address of the EOA or smart contract. (unused if a contract is created via operation type 1 or 2) | | `value` | `uint256` | The amount of native tokens to transfer (in Wei) | -| `data` | `bytes` | The call data, or the creation bytecode of the contract to deploy if `operationType` is `1` or `2`. | +| `data` | `bytes` | The call data, or the creation bytecode of the contract to deploy | #### Returns @@ -355,9 +365,23 @@ function executeBatch( ) external payable returns (bytes[]); ``` -_Calling multiple addresses `targets` using `operationsType`, transferring `values` wei and data: `datas`. _ +Generic batch executor function to: + +- send native tokens to any address. -Batch executor function that behaves the same as [`execute`](#execute) but allowing multiple operations in the same transaction. +- interact with any contract by passing an abi-encoded function call in the `datas` parameter. + +- deploy a contract by providing its creation bytecode in the `datas` parameter. Requirements: + +- The length of the parameters provided MUST be equal + +- SHOULD only be callable by the owner of the contract set via ERC173. + +- if a `values` is provided, the contract MUST have at least this amount in its balance to execute successfully. + +- if the operation type is STATICCALL or DELEGATECALL, `values` SHOULD be 0. + +- `targets` SHOULD be address(0) when deploying a contract. Emits an [`Executed`](#executed) event, when a call is made with `operationType` 0 (CALL), 3 (STATICCALL) or 4 (DELEGATECALL) Emits a [`ContractCreated`](#contractcreated) event, when deploying a contract with `operationType` 1 (CREATE) or 2 (CREATE2)
@@ -383,12 +407,12 @@ Batch executor function that behaves the same as [`execute`](#execute) but allow #### Parameters -| Name | Type | Description | -| ---------------- | :---------: | --------------------------------------------------------------------------------------------------------------- | -| `operationsType` | `uint256[]` | The list of operations type used: `CALL = 0`; `CREATE = 1`; `CREATE2 = 2`; `STATICCALL = 3`; `DELEGATECALL = 4` | -| `targets` | `address[]` | The list of addresses to call. `targets` will be unused if a contract is created (operation types 1 and 2). | -| `values` | `uint256[]` | The list of native token amounts to transfer (in Wei). | -| `datas` | `bytes[]` | The list of calldata, or the creation bytecode of the contract to deploy if `operationType` is `1` or `2`. | +| Name | Type | Description | +| ---------------- | :---------: | ----------------------------------------------------------------------------------------------------------- | +| `operationsType` | `uint256[]` | The list of operations type used: CALL = 0; CREATE = 1; CREATE2 = 2; STATICCALL = 3; DELEGATECALL = 4 | +| `targets` | `address[]` | The list of addresses to call. `targets` will be unused if a contract is created (operation types 1 and 2). | +| `values` | `uint256[]` | The list of native token amounts to transfer (in Wei) | +| `datas` | `bytes[]` | The list of call data, or the creation bytecode of the contract to deploy | #### Returns @@ -413,21 +437,19 @@ Batch executor function that behaves the same as [`execute`](#execute) but allow function getData(bytes32 dataKey) external view returns (bytes dataValue); ``` -_Reading the ERC725Y storage for data key `dataKey` returned the following value: `dataValue`._ - -Get in the ERC725Y storage the bytes data stored at a specific data key `dataKey`. +_Gets singular data at a given `dataKey`_ #### Parameters -| Name | Type | Description | -| --------- | :-------: | --------------------------------------------- | -| `dataKey` | `bytes32` | The data key for which to retrieve the value. | +| Name | Type | Description | +| --------- | :-------: | ------------------------------- | +| `dataKey` | `bytes32` | The key which value to retrieve | #### Returns -| Name | Type | Description | -| ----------- | :-----: | ---------------------------------------------------- | -| `dataValue` | `bytes` | The bytes value stored under the specified data key. | +| Name | Type | Description | +| ----------- | :-----: | -------------------------- | +| `dataValue` | `bytes` | The data stored at the key |
@@ -448,9 +470,7 @@ function getDataBatch( ) external view returns (bytes[] dataValues); ``` -_Reading the ERC725Y storage for data keys `dataKeys` returned the following values: `dataValues`._ - -Get in the ERC725Y storage the bytes data stored at multiple data keys `dataKeys`. +_Gets array of data for multiple given keys_ #### Parameters @@ -625,9 +645,7 @@ Renounce ownership of the contract in a 2-step process. function setData(bytes32 dataKey, bytes dataValue) external payable; ``` -_Setting the following data key value pair in the ERC725Y storage. Data key: `dataKey`, data value: `dataValue`. _ - -Sets a single bytes value `dataValue` in the ERC725Y storage for a specific data key `dataKey`. The function is marked as payable to enable flexibility on child contracts. For instance to implement a fee mechanism for setting specific data. +_Sets singular data for a given `dataKey`_
@@ -648,10 +666,10 @@ Sets a single bytes value `dataValue` in the ERC725Y storage for a specific data #### Parameters -| Name | Type | Description | -| ----------- | :-------: | ------------------------------------------ | -| `dataKey` | `bytes32` | The data key for which to set a new value. | -| `dataValue` | `bytes` | The new bytes value to set. | +| Name | Type | Description | +| ----------- | :-------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `dataKey` | `bytes32` | The key to retrieve stored value | +| `dataValue` | `bytes` | The value to set SHOULD only be callable by the owner of the contract set via ERC173 The function is marked as payable to enable flexibility on child contracts If the function is not intended to receive value, an additional check should be implemented to check that value equal 0. Emits a {DataChanged} event. |
@@ -670,9 +688,9 @@ Sets a single bytes value `dataValue` in the ERC725Y storage for a specific data function setDataBatch(bytes32[] dataKeys, bytes[] dataValues) external payable; ``` -_Setting the following data key value pairs in the ERC725Y storage. Data keys: `dataKeys`, data values: `dataValues`. _ +Sets array of data for multiple given `dataKeys` SHOULD only be callable by the owner of the contract set via ERC173 The function is marked as payable to enable flexibility on child contracts If the function is not intended to receive value, an additional check should be implemented to check that value equal -Batch data setting function that behaves the same as [`setData`](#setdata) but allowing to set multiple data key/value pairs in the ERC725Y storage in the same transaction. +0. Emits a [`DataChanged`](#datachanged) event.
@@ -693,10 +711,10 @@ Batch data setting function that behaves the same as [`setData`](#setdata) but a #### Parameters -| Name | Type | Description | -| ------------ | :---------: | ---------------------------------------------------- | -| `dataKeys` | `bytes32[]` | An array of data keys to set bytes values for. | -| `dataValues` | `bytes[]` | An array of bytes values to set for each `dataKeys`. | +| Name | Type | Description | +| ------------ | :---------: | ---------------------------------------- | +| `dataKeys` | `bytes32[]` | The array of data keys for values to set | +| `dataValues` | `bytes[]` | The array of values to set |
@@ -715,21 +733,21 @@ Batch data setting function that behaves the same as [`setData`](#setdata) but a function supportsInterface(bytes4 interfaceId) external view returns (bool); ``` -_Achieves the goal of [ERC-165] to detect supported interfaces and [LSP-17-ContractExtension] by checking if the interfaceId being queried is supported on another linked extension._ +_Checking if this contract supports the interface defined by the bytes4 interface ID `interfaceId`._ -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 [LSP-17-ContractExtension], and checks if the extension implements the interface defined by `interfaceId`. +Achieves the goal of [ERC-165] to detect supported interfaces and [LSP-17-ContractExtension] by checking if the interfaceId being queried is supported on another linked extension. If the contract doesn't support the `interfaceId`, it forwards the call to the `supportsInterface` extension according to [LSP-17-ContractExtension], and checks if the extension implements the interface defined by `interfaceId`. #### Parameters -| Name | Type | Description | -| ------------- | :------: | ----------- | -| `interfaceId` | `bytes4` | - | +| Name | Type | Description | +| ------------- | :------: | ------------------------------------------------------ | +| `interfaceId` | `bytes4` | The interface ID to check if the contract supports it. | #### Returns -| Name | Type | Description | -| ---- | :----: | ----------- | -| `0` | `bool` | - | +| Name | Type | Description | +| ---- | :----: | --------------------------------------------------------------------------------------------- | +| `0` | `bool` | `true` if this contract implements the interface defined by `interfaceId`, `false` otherwise. |
@@ -788,9 +806,9 @@ function universalReceiver( ) external payable returns (bytes returnedValues); ``` -_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 ([LSP1UniversalReceiverDelegate]) that react on the whole transaction and on the specific typeId, respectively. The notification is achieved by emitting a [`UniversalReceiver`](#universalreceiver) event on the call with the function parameters, call options, and the response of the UniversalReceiverDelegates (URD) contract._ +_Notifying the contract by calling its `universalReceiver` function with the following informations: typeId: `typeId`; data: `data`._ -The function performs the following steps: +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 ([LSP1UniversalReceiverDelegate]) that react on the whole transaction and on the specific typeId, respectively. The function performs the following steps: 1. Query the [ERC-725Y] storage with the data key [_LSP1_UNIVERSAL_RECEIVER_DELEGATE_KEY]. @@ -809,7 +827,7 @@ The function performs the following steps: **Emitted events:** - [`ValueReceived`](#valuereceived) when receiving native tokens. -- [`UniversalReceiver`](#universalreceiver) event. +- [`UniversalReceiver`](#universalreceiver) event with the function parameters, call options, and the response of the UniversalReceiverDelegates (URD) contract that was called.
@@ -866,7 +884,8 @@ function _execute( ) internal nonpayable returns (bytes); ``` -check the `operationType` provided and perform the associated low-level opcode after checking for requirements (see [`execute`](#execute)). +check the `operationType` provided and perform the associated low-level opcode. +see `IERC725X.execute(uint256,address,uint256,bytes)`.
@@ -881,7 +900,8 @@ function _executeBatch( ) internal nonpayable returns (bytes[]); ``` -check each `operationType` provided in the batch and perform the associated low-level opcode after checking for requirements (see [`executeBatch`](#executebatch)). +same as `_execute` but for batch execution +see `IERC725X,execute(uint256[],address[],uint256[],bytes[])`
@@ -895,7 +915,7 @@ function _executeCall( ) internal nonpayable returns (bytes result); ``` -Perform low-level call (operation type = 0) +perform low-level call (operation type = 0) #### Parameters @@ -922,7 +942,7 @@ function _executeStaticCall( ) internal nonpayable returns (bytes result); ``` -Perform low-level staticcall (operation type = 3) +perform low-level staticcall (operation type = 3) #### Parameters @@ -948,7 +968,7 @@ function _executeDelegateCall( ) internal nonpayable returns (bytes result); ``` -Perform low-level delegatecall (operation type = 4) +perform low-level delegatecall (operation type = 4) #### Parameters @@ -974,7 +994,7 @@ function _deployCreate( ) internal nonpayable returns (bytes newContract); ``` -Deploy a contract using the `CREATE` opcode (operation type = 1) +deploy a contract using the CREATE opcode (operation type = 1) #### Parameters @@ -1000,7 +1020,7 @@ function _deployCreate2( ) internal nonpayable returns (bytes newContract); ``` -Deploy a contract using the `CREATE2` opcode (operation type = 2) +deploy a contract using the CREATE2 opcode (operation type = 2) #### Parameters @@ -1023,25 +1043,6 @@ Deploy a contract using the `CREATE2` opcode (operation type = 2) function _getData(bytes32 dataKey) internal view returns (bytes dataValue); ``` -Read the value stored under a specific `dataKey` inside the underlying ERC725Y storage, -represented as a mapping of `bytes32` data keys mapped to their `bytes` data values. - -```solidity -mapping(bytes32 => bytes) _store -``` - -#### Parameters - -| Name | Type | Description | -| --------- | :-------: | ----------------------------------------------------------------------- | -| `dataKey` | `bytes32` | A bytes32 data key to read the associated `bytes` value from the store. | - -#### Returns - -| Name | Type | Description | -| ----------- | :-----: | ----------------------------------------------------------------------------- | -| `dataValue` | `bytes` | The `bytes` value associated with the given `dataKey` in the ERC725Y storage. | -
### \_setData @@ -1050,7 +1051,7 @@ mapping(bytes32 => bytes) _store function _setData(bytes32 dataKey, bytes dataValue) internal nonpayable; ``` -This function overrides the [`ERC725YCore`](#erc725ycore) internal [`_setData`](#_setdata) function to optimize gas usage by +This function overrides the [`ERC725YCore`](#erc725ycore) internal [`_setData`](#_setdata) function to optimize gas usage by emitting only the first 256 bytes of the `dataValue`.
@@ -1228,18 +1229,16 @@ function _revertWithLSP20DefaultError( event ContractCreated(uint256 indexed operationType, address indexed contractAddress, uint256 indexed value, bytes32 salt); ``` -_Deployed new contract at address `contractAddress` and funded with `value` wei (deployed using opcode: `operationType`)._ - -Emitted when a new contract was created and deployed. +_Emitted when deploying a contract_ #### Parameters -| Name | Type | Description | -| ------------------------------- | :-------: | ----------------------------------------------------------------------------------------------------------------------------------------- | -| `operationType` **`indexed`** | `uint256` | The opcode used to deploy the contract (`CREATE` or `CREATE2`). | -| `contractAddress` **`indexed`** | `address` | The created contract address. | -| `value` **`indexed`** | `uint256` | The amount of native tokens (in Wei) sent to fund the created contract on deployment. | -| `salt` | `bytes32` | The salt used to deterministically deploy the contract (`CREATE2` only). If `CREATE` opcode is used, the salt value will be `bytes32(0)`. | +| Name | Type | Description | +| ------------------------------- | :-------: | ------------------------------------------------------------------------------ | +| `operationType` **`indexed`** | `uint256` | The opcode used to deploy the contract (CREATE or CREATE2) | +| `contractAddress` **`indexed`** | `address` | The created contract address | +| `value` **`indexed`** | `uint256` | The amount of native tokens (in Wei) sent to fund the created contract address | +| `salt` | `bytes32` | - |
@@ -1258,16 +1257,14 @@ Emitted when a new contract was created and deployed. event DataChanged(bytes32 indexed dataKey, bytes dataValue); ``` -_The following data key/value pair has been changed in the ERC725Y storage: Data key: `dataKey`, data value: `dataValue`._ - -Emitted when data at a specific `dataKey` was changed to a new value `dataValue`. +_Emitted when data at a key is changed_ #### Parameters -| Name | Type | Description | -| ----------------------- | :-------: | -------------------------------------------- | -| `dataKey` **`indexed`** | `bytes32` | The data key for which a bytes value is set. | -| `dataValue` | `bytes` | The value to set for the given data key. | +| Name | Type | Description | +| ----------------------- | :-------: | ------------------------------------ | +| `dataKey` **`indexed`** | `bytes32` | The data key which data value is set | +| `dataValue` | `bytes` | The data value to set |
@@ -1286,18 +1283,16 @@ Emitted when data at a specific `dataKey` was changed to a new value `dataValue` event Executed(uint256 indexed operationType, address indexed target, uint256 indexed value, bytes4 selector); ``` -_Called address `target` using `operationType` with `value` wei and `data`._ - -Emitted when calling an address `target` (EOA or contract) with `value`. +_Emitted when calling an address (EOA or contract)_ #### Parameters -| Name | Type | Description | -| ----------------------------- | :-------: | ---------------------------------------------------------------------------------------------------- | -| `operationType` **`indexed`** | `uint256` | The low-level call opcode used to call the `target` address (`CALL`, `STATICALL` or `DELEGATECALL`). | -| `target` **`indexed`** | `address` | The address to call. `target` will be unused if a contract is created (operation types 1 and 2). | -| `value` **`indexed`** | `uint256` | The amount of native tokens transferred along the call (in Wei). | -| `selector` | `bytes4` | The first 4 bytes (= function selector) of the data sent with the call. | +| Name | Type | Description | +| ----------------------------- | :-------: | ------------------------------------------------------------------------------------------------ | +| `operationType` **`indexed`** | `uint256` | The low-level call opcode used to call the `to` address (CALL, STATICALL or DELEGATECALL) | +| `target` **`indexed`** | `address` | The address to call. `target` will be unused if a contract is created (operation types 1 and 2). | +| `value` **`indexed`** | `uint256` | The amount of native tokens transferred with the call (in Wei) | +| `selector` | `bytes4` | The first 4 bytes (= function selector) of the data sent with the call |
@@ -1443,7 +1438,7 @@ Emitted when the [`universalReceiver`](#universalreceiver) function was called w event ValueReceived(address indexed sender, uint256 indexed value); ``` -_`value` tokens received from `sender`._ +_`value` native tokens received from `sender`._ #### Parameters @@ -1492,7 +1487,7 @@ Reverts when trying to transfer ownership to the `address(this)`. error ERC725X_ContractDeploymentFailed(); ``` -Reverts when contract deployment failed via [`execute`](#execute) or [`executeBatch`](#executebatch) functions, This error can occur using either operation type 1 (`CREATE`) or 2 (`CREATE2`). +reverts when contract deployment via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)` failed. whether using operation type 1 (CREATE) or 2 (CREATE2).
@@ -1511,7 +1506,7 @@ Reverts when contract deployment failed via [`execute`](#execute) or [`executeBa error ERC725X_CreateOperationsRequireEmptyRecipientAddress(); ``` -Reverts when passing a `to` address that is not `address(0)` (= address zero) while deploying a contract via [`execute`](#execute) or [`executeBatch`](#executebatch) functions. This error can occur using either operation type 1 (`CREATE`) or 2 (`CREATE2`). +reverts when passing a `to` address while deploying a contract va `ERC725X.execute(...)`/`ERC725X.executeBatch(...)` whether using operation type 1 (CREATE) or 2 (CREATE2).
@@ -1530,7 +1525,7 @@ Reverts when passing a `to` address that is not `address(0)` (= address zero) wh error ERC725X_ExecuteParametersEmptyArray(); ``` -Reverts when one of the array parameter provided to the [`executeBatch`](#executebatch) function is an empty array. +reverts when one of the array parameter provided to `executeBatch(uint256[],address[],uint256[],bytes[]) is an empty array
@@ -1549,7 +1544,7 @@ Reverts when one of the array parameter provided to the [`executeBatch`](#execut error ERC725X_ExecuteParametersLengthMismatch(); ``` -Reverts when there is not the same number of elements in the `operationTypes`, `targets` addresses, `values`, and `datas` array parameters provided when calling the [`executeBatch`](#executebatch) function. +reverts when there is not the same number of operation, to addresses, value, and data.
@@ -1568,14 +1563,14 @@ Reverts when there is not the same number of elements in the `operationTypes`, ` error ERC725X_InsufficientBalance(uint256 balance, uint256 value); ``` -Reverts when trying to send more native tokens `value` than available in current `balance`. +reverts when trying to send more native tokens `value` than available in current `balance`. #### Parameters -| Name | Type | Description | -| --------- | :-------: | -------------------------------------------------------------------------------------------------------------------------------------- | -| `balance` | `uint256` | The balance of native tokens of the ERC725X smart contract. | -| `value` | `uint256` | The amount of native tokens sent via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)` that is greater than the contract's `balance`. | +| Name | Type | Description | +| --------- | :-------: | ---------------------------------------------------------------------------------------- | +| `balance` | `uint256` | the balance of the ERC725X contract. | +| `value` | `uint256` | the amount of native tokens sent via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)`. |
@@ -1594,7 +1589,7 @@ Reverts when trying to send more native tokens `value` than available in current error ERC725X_MsgValueDisallowedInDelegateCall(); ``` -Reverts when trying to send native tokens (`value` / `values[]` parameter of [`execute`](#execute) or [`executeBatch`](#executebatch) functions) while making a `delegatecall` (`operationType == 4`). Sending native tokens via `staticcall` is not allowed because `msg.value` is persisting. +the `value` parameter (= sending native tokens) is not allowed when making a delegatecall via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)` because msg.value is persisting.
@@ -1613,7 +1608,7 @@ Reverts when trying to send native tokens (`value` / `values[]` parameter of [`e error ERC725X_MsgValueDisallowedInStaticCall(); ``` -Reverts when trying to send native tokens (`value` / `values[]` parameter of [`execute`](#execute) or [`executeBatch`](#executebatch) functions) while making a `staticcall` (`operationType == 3`). Sending native tokens via `staticcall` is not allowed because it is a state changing operation. +the `value` parameter (= sending native tokens) is not allowed when making a staticcall via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)` because sending native tokens is a state changing operation.
@@ -1632,7 +1627,7 @@ Reverts when trying to send native tokens (`value` / `values[]` parameter of [`e error ERC725X_NoContractBytecodeProvided(); ``` -Reverts when no contract bytecode was provided as parameter when trying to deploy a contract via [`execute`](#execute) or [`executeBatch`](#executebatch). This error can occur using either operation type 1 (`CREATE`) or 2 (`CREATE2`). +reverts when no contract bytecode was provided as parameter when trying to deploy a contract via `ERC725X.execute(...)`/`ERC725X.executeBatch(...)`, whether using operation type 1 (CREATE) or 2 (CREATE2).
@@ -1651,13 +1646,13 @@ Reverts when no contract bytecode was provided as parameter when trying to deplo error ERC725X_UnknownOperationType(uint256 operationTypeProvided); ``` -Reverts when the `operationTypeProvided` is none of the default operation types available. (CALL = 0; CREATE = 1; CREATE2 = 2; STATICCALL = 3; DELEGATECALL = 4) +reverts when the `operationTypeProvided` is none of the default operation types available. (CALL = 0; CREATE = 1; CREATE2 = 2; STATICCALL = 3; DELEGATECALL = 4) #### Parameters -| Name | Type | Description | -| ----------------------- | :-------: | ------------------------------------------------------------------------------------------------------ | -| `operationTypeProvided` | `uint256` | The unrecognised operation type number provided to `ERC725X.execute(...)`/`ERC725X.executeBatch(...)`. | +| Name | Type | Description | +| ----------------------- | :-------: | ----------- | +| `operationTypeProvided` | `uint256` | - |
@@ -1676,7 +1671,7 @@ Reverts when the `operationTypeProvided` is none of the default operation types error ERC725Y_DataKeysValuesLengthMismatch(); ``` -Reverts when there is not the same number of elements in the `datakeys` and `dataValues` array parameters provided when calling the [`setDataBatch`](#setdatabatch) function. +reverts when there is not the same number of elements in the lists of data keys and data values when calling setDataBatch.