diff --git a/contracts/access-control/MultiOwnable.sol b/contracts/access-control/MultiOwnable.sol index 7a212222..121ef2ea 100644 --- a/contracts/access-control/MultiOwnable.sol +++ b/contracts/access-control/MultiOwnable.sol @@ -40,22 +40,45 @@ abstract contract MultiOwnable is IMultiOwnable, Initializable { _addOwners(msg.sender.asSingletonArray()); } + /** + * @notice The function to add equally rightful owners to the contract + * @param newOwners_ the owners to be added + */ function addOwners(address[] memory newOwners_) public override onlyOwner { _addOwners(newOwners_); } + /** + * @notice The function to remove owners from the contract + * @param oldOwners_ the owners to be removed. Note that one can remove themself + */ function removeOwners(address[] memory oldOwners_) public override onlyOwner { _removeOwners(oldOwners_); } + /** + * @notice The function to remove yourself from the owners list + * + * Note: renouncing ownership may leave the contract without an owner, + * thereby disabling any functionality that is only available to the owner. + */ function renounceOwnership() public override onlyOwner { _removeOwners(msg.sender.asSingletonArray()); } + /** + * @notice The function to get the list of current owners. Be careful, O(n) complexity + * @return the list of current owners + */ function getOwners() public view override returns (address[] memory) { return _owners.values(); } + /** + * @notice The function to check the ownership of a user + * @param address_ the user to check + * @return true if address_ is owner, false otherwise + */ function isOwner(address address_) public view override returns (bool) { return _owners.contains(address_); } diff --git a/contracts/access-control/RBAC.sol b/contracts/access-control/RBAC.sol index 8a6e8475..cab0ef6b 100644 --- a/contracts/access-control/RBAC.sol +++ b/contracts/access-control/RBAC.sol @@ -63,7 +63,7 @@ abstract contract RBAC is IRBAC, Initializable { } /** - * @notice The init function + * @notice The initialization function */ function __RBAC_init() internal onlyInitializing { _addPermissionsToRole(MASTER_ROLE, ALL_RESOURCE, ALL_PERMISSION.asSingletonArray(), true); diff --git a/contracts/access-control/extensions/RBACGroupable.sol b/contracts/access-control/extensions/RBACGroupable.sol index 4b472694..3ca711b6 100644 --- a/contracts/access-control/extensions/RBACGroupable.sol +++ b/contracts/access-control/extensions/RBACGroupable.sol @@ -32,7 +32,7 @@ abstract contract RBACGroupable is IRBACGroupable, RBAC { mapping(string => StringSet.Set) private _groupRoles; /** - * @notice The init function + * @notice The initialization function */ function __RBACGroupable_init() internal onlyInitializing { __RBAC_init(); diff --git a/contracts/compound-rate-keeper/AbstractCompoundRateKeeper.sol b/contracts/compound-rate-keeper/AbstractCompoundRateKeeper.sol index b06dd53c..0536e745 100644 --- a/contracts/compound-rate-keeper/AbstractCompoundRateKeeper.sol +++ b/contracts/compound-rate-keeper/AbstractCompoundRateKeeper.sol @@ -38,7 +38,7 @@ abstract contract AbstractCompoundRateKeeper is ICompoundRateKeeper, Initializab uint256 private _currentRate; /** - * @notice The proxy initializer function + * @notice The initialization function */ function __CompoundRateKeeper_init( uint256 capitalizationRate_, diff --git a/contracts/compound-rate-keeper/presets/OwnableCompoundRateKeeper.sol b/contracts/compound-rate-keeper/presets/OwnableCompoundRateKeeper.sol index e36f84fa..75655395 100644 --- a/contracts/compound-rate-keeper/presets/OwnableCompoundRateKeeper.sol +++ b/contracts/compound-rate-keeper/presets/OwnableCompoundRateKeeper.sol @@ -9,6 +9,11 @@ import {AbstractCompoundRateKeeper} from "../AbstractCompoundRateKeeper.sol"; * @notice The Ownable preset of CompoundRateKeeper */ contract OwnableCompoundRateKeeper is AbstractCompoundRateKeeper, OwnableUpgradeable { + /** + * @notice The initialization function + * @param capitalizationRate_ the compound interest rate with 10\**25 precision + * @param capitalizationPeriod_ the compounding period in seconds + */ function __OwnableCompoundRateKeeper_init( uint256 capitalizationRate_, uint64 capitalizationPeriod_ @@ -17,10 +22,18 @@ contract OwnableCompoundRateKeeper is AbstractCompoundRateKeeper, OwnableUpgrade __CompoundRateKeeper_init(capitalizationRate_, capitalizationPeriod_); } + /** + * The function to set the compound interest rate + * @param capitalizationRate_ new compound interest rate + */ function setCapitalizationRate(uint256 capitalizationRate_) external onlyOwner { _setCapitalizationRate(capitalizationRate_); } + /** + * @notice The function to set the compounding period + * @param capitalizationPeriod_ new compounding period in seconds + */ function setCapitalizationPeriod(uint64 capitalizationPeriod_) external onlyOwner { _setCapitalizationPeriod(capitalizationPeriod_); } diff --git a/contracts/contracts-registry/AbstractContractsRegistry.sol b/contracts/contracts-registry/AbstractContractsRegistry.sol index aafe0fa9..659e30d1 100644 --- a/contracts/contracts-registry/AbstractContractsRegistry.sol +++ b/contracts/contracts-registry/AbstractContractsRegistry.sol @@ -49,7 +49,7 @@ abstract contract AbstractContractsRegistry is Initializable { event ContractRemoved(string name); /** - * @notice The proxy initializer function + * @notice The initialization function */ function __ContractsRegistry_init() internal onlyInitializing { _proxyUpgrader = new TransparentProxyUpgrader(); diff --git a/contracts/contracts-registry/pools/presets/MultiOwnablePoolContractsRegistry.sol b/contracts/contracts-registry/pools/presets/MultiOwnablePoolContractsRegistry.sol index 4d2303a1..b1e4e424 100644 --- a/contracts/contracts-registry/pools/presets/MultiOwnablePoolContractsRegistry.sol +++ b/contracts/contracts-registry/pools/presets/MultiOwnablePoolContractsRegistry.sol @@ -11,11 +11,19 @@ abstract contract MultiOwnablePoolContractsRegistry is AbstractPoolContractsRegistry, MultiOwnable { + /** + * @notice The initialization function + */ function __MultiOwnablePoolContractsRegistry_init() public initializer { __MultiOwnable_init(); __PoolContractsRegistry_init(); } + /** + * @notice The function to set new implementation for the registered pools + * @param names_ the names of registered ProxyBeacons to upgrade + * @param newImplementations_ the addresses of new implementations to be used + */ function setNewImplementations( string[] calldata names_, address[] calldata newImplementations_ @@ -23,6 +31,12 @@ abstract contract MultiOwnablePoolContractsRegistry is _setNewImplementations(names_, newImplementations_); } + /** + * @notice The function to inject dependencies to registered pools (via EIP-6224) + * @param name_ the name of ProxyBeacon to identify the pools + * @param offset_ the start index of the pools array + * @param limit_ the number of pools to inject dependencies to + */ function injectDependenciesToExistingPools( string calldata name_, uint256 offset_, @@ -31,6 +45,13 @@ abstract contract MultiOwnablePoolContractsRegistry is _injectDependenciesToExistingPools(name_, offset_, limit_); } + /** + * @notice The function to inject dependencies to registered pools with data (via EIP-6224) + * @param data_ the data to be passed to `setDependencies()` function + * @param name_ the name of ProxyBeacon to identify the pools + * @param offset_ the start index of the pools array + * @param limit_ the number of pools to inject dependencies to + */ function injectDependenciesToExistingPoolsWithData( string calldata name_, bytes calldata data_, diff --git a/contracts/contracts-registry/pools/presets/OwnablePoolContractsRegistry.sol b/contracts/contracts-registry/pools/presets/OwnablePoolContractsRegistry.sol index a4b09bd8..7d0ee0f0 100644 --- a/contracts/contracts-registry/pools/presets/OwnablePoolContractsRegistry.sol +++ b/contracts/contracts-registry/pools/presets/OwnablePoolContractsRegistry.sol @@ -12,11 +12,19 @@ abstract contract OwnablePoolContractsRegistry is AbstractPoolContractsRegistry, OwnableUpgradeable { + /** + * @notice The initialization function + */ function __OwnablePoolContractsRegistry_init() public initializer { __Ownable_init(); __PoolContractsRegistry_init(); } + /** + * @notice The function to set new implementation for the registered pools + * @param names_ the names of registered ProxyBeacons to upgrade + * @param newImplementations_ the addresses of new implementations to be used + */ function setNewImplementations( string[] calldata names_, address[] calldata newImplementations_ @@ -24,6 +32,12 @@ abstract contract OwnablePoolContractsRegistry is _setNewImplementations(names_, newImplementations_); } + /** + * @notice The function to inject dependencies to registered pools (via EIP-6224) + * @param name_ the name of ProxyBeacon to identify the pools + * @param offset_ the start index of the pools array + * @param limit_ the number of pools to inject dependencies to + */ function injectDependenciesToExistingPools( string calldata name_, uint256 offset_, @@ -32,6 +46,13 @@ abstract contract OwnablePoolContractsRegistry is _injectDependenciesToExistingPools(name_, offset_, limit_); } + /** + * @notice The function to inject dependencies to registered pools with data (via EIP-6224) + * @param data_ the data to be passed to `setDependencies()` function + * @param name_ the name of ProxyBeacon to identify the pools + * @param offset_ the start index of the pools array + * @param limit_ the number of pools to inject dependencies to + */ function injectDependenciesToExistingPoolsWithData( string calldata name_, bytes calldata data_, diff --git a/contracts/contracts-registry/presets/MultiOwnableContractsRegistry.sol b/contracts/contracts-registry/presets/MultiOwnableContractsRegistry.sol index 53034f24..924e5be1 100644 --- a/contracts/contracts-registry/presets/MultiOwnableContractsRegistry.sol +++ b/contracts/contracts-registry/presets/MultiOwnableContractsRegistry.sol @@ -8,15 +8,27 @@ import {MultiOwnable} from "../../access-control/MultiOwnable.sol"; * @notice The MultiOwnable preset of ContractsRegistry */ contract MultiOwnableContractsRegistry is AbstractContractsRegistry, MultiOwnable { + /** + * @notice The initialization function + */ function __MultiOwnableContractsRegistry_init() public initializer { __MultiOwnable_init(); __ContractsRegistry_init(); } + /** + * @notice The function to inject dependencies to the specified contract + * @param name_ the name of the contract to inject dependencies to + */ function injectDependencies(string calldata name_) external onlyOwner { _injectDependencies(name_); } + /** + * @notice The function to inject dependencies with data to the specified contract + * @param name_ the name of the contract to inject dependencies to + * @param data_ the data to be passed to `setDependencies()` function + */ function injectDependenciesWithData( string calldata name_, bytes calldata data_ @@ -24,6 +36,11 @@ contract MultiOwnableContractsRegistry is AbstractContractsRegistry, MultiOwnabl _injectDependenciesWithData(name_, data_); } + /** + * @notice The function to upgrade the specified proxy contract + * @param name_ the name of the proxy contract to upgrade + * @param newImplementation_ the new implementation + */ function upgradeContract( string calldata name_, address newImplementation_ @@ -31,6 +48,12 @@ contract MultiOwnableContractsRegistry is AbstractContractsRegistry, MultiOwnabl _upgradeContract(name_, newImplementation_); } + /** + * @notice The function to upgrade the specified proxy contract with data + * @param name_ the name of the proxy contract to upgrade + * @param newImplementation_ the new implementation + * @param data_ the data the proxy contract will be called after the upgrade + */ function upgradeContractAndCall( string calldata name_, address newImplementation_, @@ -39,14 +62,30 @@ contract MultiOwnableContractsRegistry is AbstractContractsRegistry, MultiOwnabl _upgradeContractAndCall(name_, newImplementation_, data_); } + /** + * @notice The function to add the regular contract to the registry + * @param name_ the associative name of the contract + * @param contractAddress_ the address of the contract to add + */ function addContract(string calldata name_, address contractAddress_) external onlyOwner { _addContract(name_, contractAddress_); } + /** + * @notice The function to add the proxy contract to the registry (deploys TransparentProxy on top) + * @param name_ the associative name of the contract + * @param contractAddress_ the address of the implementation contract to add + */ function addProxyContract(string calldata name_, address contractAddress_) external onlyOwner { _addProxyContract(name_, contractAddress_); } + /** + * @notice The function to add the proxy contract to the registry with immediate call (deploys TransparentProxy on top) + * @param name_ the associative name of the contract + * @param contractAddress_ the address of the implementation contract to add + * @param data_ the data the proxy contract will be called after the addition + */ function addProxyContractAndCall( string calldata name_, address contractAddress_, @@ -55,6 +94,11 @@ contract MultiOwnableContractsRegistry is AbstractContractsRegistry, MultiOwnabl _addProxyContractAndCall(name_, contractAddress_, data_); } + /** + * @notice The function to add proxy contract to the registry as is + * @param name_ the associative name of the contract + * @param contractAddress_ the address of the proxy contract to add + */ function justAddProxyContract( string calldata name_, address contractAddress_ @@ -62,6 +106,10 @@ contract MultiOwnableContractsRegistry is AbstractContractsRegistry, MultiOwnabl _justAddProxyContract(name_, contractAddress_); } + /** + * @notice The function to remove the contract from the registry + * @param name_ the the associative name of the contract to remove + */ function removeContract(string calldata name_) external onlyOwner { _removeContract(name_); } diff --git a/contracts/contracts-registry/presets/OwnableContractsRegistry.sol b/contracts/contracts-registry/presets/OwnableContractsRegistry.sol index 6aa15b3f..5ce4d4d0 100644 --- a/contracts/contracts-registry/presets/OwnableContractsRegistry.sol +++ b/contracts/contracts-registry/presets/OwnableContractsRegistry.sol @@ -9,15 +9,27 @@ import {AbstractContractsRegistry} from "../AbstractContractsRegistry.sol"; * @notice The Ownable preset of ContractsRegistry */ contract OwnableContractsRegistry is AbstractContractsRegistry, OwnableUpgradeable { + /** + * @notice The initialization function + */ function __OwnableContractsRegistry_init() public initializer { __Ownable_init(); __ContractsRegistry_init(); } + /** + * @notice The function to inject dependencies to the specified contract + * @param name_ the name of the contract to inject dependencies to + */ function injectDependencies(string calldata name_) external onlyOwner { _injectDependencies(name_); } + /** + * @notice The function to inject dependencies with data to the specified contract + * @param name_ the name of the contract to inject dependencies to + * @param data_ the data to be passed to `setDependencies()` function + */ function injectDependenciesWithData( string calldata name_, bytes calldata data_ @@ -25,6 +37,11 @@ contract OwnableContractsRegistry is AbstractContractsRegistry, OwnableUpgradeab _injectDependenciesWithData(name_, data_); } + /** + * @notice The function to upgrade the specified proxy contract + * @param name_ the name of the proxy contract to upgrade + * @param newImplementation_ the new implementation + */ function upgradeContract( string calldata name_, address newImplementation_ @@ -32,6 +49,12 @@ contract OwnableContractsRegistry is AbstractContractsRegistry, OwnableUpgradeab _upgradeContract(name_, newImplementation_); } + /** + * @notice The function to upgrade the specified proxy contract with data + * @param name_ the name of the proxy contract to upgrade + * @param newImplementation_ the new implementation + * @param data_ the data the proxy contract will be called after the upgrade + */ function upgradeContractAndCall( string calldata name_, address newImplementation_, @@ -40,14 +63,30 @@ contract OwnableContractsRegistry is AbstractContractsRegistry, OwnableUpgradeab _upgradeContractAndCall(name_, newImplementation_, data_); } + /** + * @notice The function to add the regular contract to the registry + * @param name_ the associative name of the contract + * @param contractAddress_ the address of the contract to add + */ function addContract(string calldata name_, address contractAddress_) external onlyOwner { _addContract(name_, contractAddress_); } + /** + * @notice The function to add the proxy contract to the registry (deploys TransparentProxy on top) + * @param name_ the associative name of the contract + * @param contractAddress_ the address of the implementation contract to add + */ function addProxyContract(string calldata name_, address contractAddress_) external onlyOwner { _addProxyContract(name_, contractAddress_); } + /** + * @notice The function to add the proxy contract to the registry with immediate call (deploys TransparentProxy on top) + * @param name_ the associative name of the contract + * @param contractAddress_ the address of the implementation contract to add + * @param data_ the data the proxy contract will be called after the addition + */ function addProxyContractAndCall( string calldata name_, address contractAddress_, @@ -56,6 +95,11 @@ contract OwnableContractsRegistry is AbstractContractsRegistry, OwnableUpgradeab _addProxyContractAndCall(name_, contractAddress_, data_); } + /** + * @notice The function to add proxy contract to the registry as is + * @param name_ the associative name of the contract + * @param contractAddress_ the address of the proxy contract to add + */ function justAddProxyContract( string calldata name_, address contractAddress_ @@ -63,6 +107,10 @@ contract OwnableContractsRegistry is AbstractContractsRegistry, OwnableUpgradeab _justAddProxyContract(name_, contractAddress_); } + /** + * @notice The function to remove the contract from the registry + * @param name_ the the associative name of the contract to remove + */ function removeContract(string calldata name_) external onlyOwner { _removeContract(name_); } diff --git a/contracts/diamond/introspection/DiamondERC165.sol b/contracts/diamond/introspection/DiamondERC165.sol index 26baf4f5..6504d74a 100644 --- a/contracts/diamond/introspection/DiamondERC165.sol +++ b/contracts/diamond/introspection/DiamondERC165.sol @@ -9,13 +9,18 @@ import {ERC165} from "@openzeppelin/contracts/utils/introspection/ERC165.sol"; * DiamondERC165 - Contract implementing ERC165 interface for Diamonds */ contract DiamondERC165 is ERC165 { - function supportsInterface(bytes4 interfaceId) public view virtual override returns (bool) { + /** + * @notice The function to check whether the Diamond supports the interface + * @param interfaceId_ the interface to check + * @return true if the interface is supported, false otherwise + */ + function supportsInterface(bytes4 interfaceId_) public view virtual override returns (bool) { // This section of code provides support for the Diamond Loupe and Diamond Cut interfaces. // Diamond Loupe interface is defined as: 0x48e2b093 // Diamond Cut interface is defined as: 0x1f931c1c return - interfaceId == 0x1f931c1c || - interfaceId == 0x48e2b093 || - super.supportsInterface(interfaceId); + interfaceId_ == 0x1f931c1c || + interfaceId_ == 0x48e2b093 || + super.supportsInterface(interfaceId_); } } diff --git a/contracts/diamond/presets/OwnableDiamond/OwnableDiamond.sol b/contracts/diamond/presets/OwnableDiamond/OwnableDiamond.sol index 97b66f8c..1032e068 100644 --- a/contracts/diamond/presets/OwnableDiamond/OwnableDiamond.sol +++ b/contracts/diamond/presets/OwnableDiamond/OwnableDiamond.sol @@ -14,16 +14,30 @@ contract OwnableDiamond is Diamond, OwnableDiamondStorage { transferOwnership(msg.sender); } + /** + * @notice The function to transfer the Diamond ownerhip + * @param newOwner_ the new owner of the Diamond + */ function transferOwnership(address newOwner_) public onlyOwner { require(newOwner_ != address(0), "OwnableDiamond: zero address owner"); _getOwnableDiamondStorage().owner = newOwner_; } + /** + * @notice The function to manipulate the Diamond contract, as defined in [EIP-2535](https://eips.ethereum.org/EIPS/eip-2535) + * @param facets_ the array of actions to be executed against the Diamond + */ function diamondCut(Facet[] memory facets_) public onlyOwner { diamondCut(facets_, address(0), ""); } + /** + * @notice The function to manipulate the Diamond contract, as defined in [EIP-2535](https://eips.ethereum.org/EIPS/eip-2535) + * @param facets_ the array of actions to be executed against the Diamond + * @param init_ the address of the init contract to be called via delegatecall + * @param initData_ the data the init address will be called with + */ function diamondCut( Facet[] memory facets_, address init_, diff --git a/contracts/interfaces/access-control/IMultiOwnable.sol b/contracts/interfaces/access-control/IMultiOwnable.sol index bf47775e..c59bb5b0 100644 --- a/contracts/interfaces/access-control/IMultiOwnable.sol +++ b/contracts/interfaces/access-control/IMultiOwnable.sol @@ -9,36 +9,35 @@ interface IMultiOwnable { event OwnersRemoved(address[] removedOwners); /** - * @notice Owner can add new owners to the contract's owners list. - * @param newOwners_ the array of addresses to add to _owners. + * @notice The function to add equally rightful owners to the contract + * @param newOwners_ the owners to be added */ function addOwners(address[] calldata newOwners_) external; /** - * @notice Owner can remove the array of owners from the contract's owners list. - * @param oldOwners_ the array of addresses to remove from _owners + * @notice The function to remove owners from the contract + * @param oldOwners_ the owners to be removed. Note that one can remove themself */ function removeOwners(address[] calldata oldOwners_) external; /** - * @notice Allows to remove yourself from list of owners. - + * @notice The function to remove yourself from the owners list + * * Note: renouncing ownership may leave the contract without an owner, * thereby disabling any functionality that is only available to the owner. */ function renounceOwnership() external; /** - * @notice Returns the addresses of the current owners. - * @dev Returns a copy of the whole Set of owners. - * @return the array of addresses. + * @notice The function to get the list of current owners. Be careful, O(n) complexity + * @return the list of current owners */ function getOwners() external view returns (address[] memory); /** - * @notice Returns true if address is in the contract's owners list. - * @param address_ the address to check. - * @return whether the _address in _owners. + * @notice The function to check the ownership of a user + * @param address_ the user to check + * @return true if address_ is owner, false otherwise */ function isOwner(address address_) external view returns (bool); } diff --git a/contracts/interfaces/access-control/IRBAC.sol b/contracts/interfaces/access-control/IRBAC.sol index 32c8bed2..ecfbd8e7 100644 --- a/contracts/interfaces/access-control/IRBAC.sol +++ b/contracts/interfaces/access-control/IRBAC.sol @@ -23,24 +23,57 @@ interface IRBAC { bool allowed ); + /** + * @notice The function to grant roles to a user + * @param to_ the user to grant roles to + * @param rolesToGrant_ roles to grant + */ function grantRoles(address to_, string[] calldata rolesToGrant_) external; + /** + * @notice The function to revoke roles + * @param from_ the user to revoke roles from + * @param rolesToRevoke_ the roles to revoke + */ function revokeRoles(address from_, string[] calldata rolesToRevoke_) external; + /** + * @notice The function to add resource permission to role + * @param role_ the role to add permissions to + * @param permissionsToAdd_ the array of resources and permissions to add to the role + * @param allowed_ indicates whether to add permissions to an allowlist or disallowlist + */ function addPermissionsToRole( string calldata role_, ResourceWithPermissions[] calldata permissionsToAdd_, bool allowed_ ) external; + /** + * @notice The function to remove permissions from role + * @param role_ the role to remove permissions from + * @param permissionsToRemove_ the array of resources and permissions to remove from the role + * @param allowed_ indicates whether to remove permissions from the allowlist or disallowlist + */ function removePermissionsFromRole( string calldata role_, ResourceWithPermissions[] calldata permissionsToRemove_, bool allowed_ ) external; + /** + * @notice The function to get the list of user roles + * @param who_ the user + * @return roles_ the roles of the user + */ function getUserRoles(address who_) external view returns (string[] calldata roles_); + /** + * @notice The function to get the permissions of the role + * @param role_ the role + * @return allowed_ the list of allowed permissions of the role + * @return disallowed_ the list of disallowed permissions of the role + */ function getRolePermissions( string calldata role_ ) @@ -51,6 +84,17 @@ interface IRBAC { ResourceWithPermissions[] calldata disallowed_ ); + /** + * @notice The function to check the user's possession of the role + * + * @dev DO NOT call `super.hasPermission(...)` in derived contracts, because this method + * handles not 2 but 3 states: NO PERMISSION, ALLOWED, DISALLOWED + * + * @param who_ the user + * @param resource_ the resource the user has to have the permission of + * @param permission_ the permission the user has to have + * @return isAllowed_ true if the user has the permission, false otherwise + */ function hasPermission( address who_, string calldata resource_, diff --git a/contracts/interfaces/access-control/extensions/IRBACGroupable.sol b/contracts/interfaces/access-control/extensions/IRBACGroupable.sol index 2cff8e28..5a7cced7 100644 --- a/contracts/interfaces/access-control/extensions/IRBACGroupable.sol +++ b/contracts/interfaces/access-control/extensions/IRBACGroupable.sol @@ -13,24 +13,62 @@ interface IRBACGroupable { event ToggledDefaultGroup(bool defaultGroupEnabled); + /** + * @notice The function to assign the user to groups + * @param who_ the user to be assigned + * @param groupsToAddTo_ the list of groups to assign the user to + */ function addUserToGroups(address who_, string[] calldata groupsToAddTo_) external; + /** + * @notice The function to remove the user from groups + * @param who_ the user to be removed from groups + * @param groupsToRemoveFrom_ the list of groups to remove the user from + */ function removeUserFromGroups(address who_, string[] calldata groupsToRemoveFrom_) external; + /** + * @notice The function to grant roles to the group + * @param groupTo_ the group to grant roles to + * @param rolesToGrant_ the list of roles to grant + */ function grantGroupRoles(string calldata groupTo_, string[] calldata rolesToGrant_) external; + /** + * @notice The function to revoke roles from the group + * @param groupFrom_ the group to revoke roles from + * @param rolesToRevoke_ the list of roles to revoke + */ function revokeGroupRoles( string calldata groupFrom_, string[] calldata rolesToRevoke_ ) external; + /** + * @notice The function to toggle the default group state. When `defaultGroupEnabled` is set + * to true, the default group is enabled, otherwise it is disabled + */ function toggleDefaultGroup() external; + /** + * @notice The function to get the list of user groups + * @param who_ the user + * @return groups_ the list of user groups + */ function getUserGroups(address who_) external view returns (string[] calldata groups_); + /** + * @notice The function to get the list of groups roles + * @param group_ the group + * @return roles_ the list of group roles + */ function getGroupRoles( string calldata group_ ) external view returns (string[] calldata roles_); + /** + * @notice The function to get the current state of the default group + * @return defaultGroupEnabled_ the boolean indicating whether the default group is enabled + */ function getDefaultGroupEnabled() external view returns (bool); } diff --git a/contracts/interfaces/compound-rate-keeper/ICompoundRateKeeper.sol b/contracts/interfaces/compound-rate-keeper/ICompoundRateKeeper.sol index 544bbb55..0a4926ad 100644 --- a/contracts/interfaces/compound-rate-keeper/ICompoundRateKeeper.sol +++ b/contracts/interfaces/compound-rate-keeper/ICompoundRateKeeper.sol @@ -8,19 +8,51 @@ interface ICompoundRateKeeper { event CapitalizationPeriodChanged(uint256 newCapitalizationPeriod); event CapitalizationRateChanged(uint256 newCapitalizationRate); + /** + * @notice The function to force-update the compound rate if the getter reverts, sets isMaxRateReached to true + */ function emergencyUpdateCompoundRate() external; + /** + * @notice The function to get current compound rate + * @return current compound rate + */ function getCompoundRate() external view returns (uint256); + /** + * @notice The function to get future compound rate (the timestamp_ may be equal to the lastUpdate) + * @param timestamp_ the timestamp to calculate the rate for + * @return the compound rate for the provided timestamp + */ function getFutureCompoundRate(uint64 timestamp_) external view returns (uint256); + /** + * @notice The function to get the current capitalization rate + * @return capitalizationRate_ the current capitalization rate + */ function getCapitalizationRate() external view returns (uint256); + /** + * @notice The function to get the current capitalization period + * @return capitalizationPeriod_ the current capitalization period + */ function getCapitalizationPeriod() external view returns (uint64); + /** + * @notice The function to get the timestamp of the last update + * @return lastUpdate_ the timestamp of the last update + */ function getLastUpdate() external view returns (uint64); + /** + * @notice The function to get the status of whether the max rate is reached + * @return isMaxRateReached_ the boolean indicating if the max rate is reached + */ function getIsMaxRateReached() external view returns (bool); + /** + * @notice The function to get the current rate + * @return currentRate_ the current rate + */ function getCurrentRate() external view returns (uint256); } diff --git a/contracts/interfaces/tokens/ISBT.sol b/contracts/interfaces/tokens/ISBT.sol index 251addab..897a0215 100644 --- a/contracts/interfaces/tokens/ISBT.sol +++ b/contracts/interfaces/tokens/ISBT.sol @@ -7,21 +7,69 @@ pragma solidity ^0.8.4; interface ISBT { event Transfer(address indexed from, address indexed to, uint256 indexed tokenId); + /** + * @notice The function to return the name of the contract + * @return the name of the contract + */ function name() external view returns (string memory); + /** + * @notice The function to return the symbol of the contract + * @return the symbol of the contract + */ function symbol() external view returns (string memory); + /** + * @notice The function to check the existence of the token + * @param tokenId_ the token to check + * @return true if `tokenId_` exists, false otherwise + */ function tokenExists(uint256 tokenId_) external view returns (bool); + /** + * @notice The function to get the balance of the user + * @param owner_ the user to get the balance of + * @return the user's balance + */ function balanceOf(address owner_) external view returns (uint256); + /** + * @notice The function to get a user's token by its ordinal id + * @param owner_ the user to get the token of + * @param index_ the id of the token in the user's array + * @return the token the user owns + */ function tokenOf(address owner_, uint256 index_) external view returns (uint256); + /** + * @notice The function to get ALL the tokens of a user. Be careful, O(n) complexity + * @param owner_ the user to get the tokens of + * @return the array of tokens the user owns + */ function tokensOf(address owner_) external view returns (uint256[] memory); + /** + * @notice The function to get the owner of a token + * @param tokenId_ the token to get the owner of + * @return address of an owner or `address(0)` if token does not exist + */ function ownerOf(uint256 tokenId_) external view returns (address); + /** + * @notice The function to get the base URI of all the tokens + * @return the base URI + */ function baseURI() external view returns (string memory); + /** + * @notice The function to get the token URI. + * + * - If individual token URI is set, it gets returned. + * - Otherwise if base URI is set, the concatenation of base URI and token URI gets returned. + * - Otherwise `""` gets returned + * + * @param tokenId_ the token to get the URI of + * @return the URI of the token + */ function tokenURI(uint256 tokenId_) external view returns (string memory); } diff --git a/contracts/libs/arrays/ArrayHelper.sol b/contracts/libs/arrays/ArrayHelper.sol index 1c8286f9..58fc4284 100644 --- a/contracts/libs/arrays/ArrayHelper.sol +++ b/contracts/libs/arrays/ArrayHelper.sol @@ -101,7 +101,7 @@ library ArrayHelper { } /** - * @notice The function to reverse an array + * @notice The function to reverse a uint256 array * @param arr_ the array to reverse * @return reversed_ the reversed array */ @@ -115,6 +115,9 @@ library ArrayHelper { } } + /** + * @notice The function to reverse an address array + */ function reverse(address[] memory arr_) internal pure returns (address[] memory reversed_) { reversed_ = new address[](arr_.length); uint256 i = arr_.length; @@ -125,6 +128,9 @@ library ArrayHelper { } } + /** + * @notice The function to reverse a string array + */ function reverse(string[] memory arr_) internal pure returns (string[] memory reversed_) { reversed_ = new string[](arr_.length); uint256 i = arr_.length; @@ -135,6 +141,9 @@ library ArrayHelper { } } + /** + * @notice The function to reverse a bytes32 array + */ function reverse(bytes32[] memory arr_) internal pure returns (bytes32[] memory reversed_) { reversed_ = new bytes32[](arr_.length); uint256 i = arr_.length; @@ -146,7 +155,7 @@ library ArrayHelper { } /** - * @notice The function to insert an array into the other array + * @notice The function to insert a uint256 array into the other array * @param to_ the array to insert into * @param index_ the insertion starting index * @param what_ the array to be inserted @@ -164,6 +173,9 @@ library ArrayHelper { return index_ + what_.length; } + /** + * @notice The function to insert an address array into the other array + */ function insert( address[] memory to_, uint256 index_, @@ -176,6 +188,9 @@ library ArrayHelper { return index_ + what_.length; } + /** + * @notice The function to insert a string array into the other array + */ function insert( string[] memory to_, uint256 index_, @@ -188,6 +203,9 @@ library ArrayHelper { return index_ + what_.length; } + /** + * @notice The function to insert a bytes32 array into the other array + */ function insert( bytes32[] memory to_, uint256 index_, @@ -201,7 +219,7 @@ library ArrayHelper { } /** - * @notice The function to crop the array + * @notice The function to crop a uint256 array * @param array_ the array to crop * @param newLength_ the new length of the array (has to be less or equal) * @return ref to cropped array @@ -219,6 +237,9 @@ library ArrayHelper { return array_; } + /** + * @notice The function to crop an address array + */ function crop( address[] memory array_, uint256 newLength_ @@ -232,6 +253,9 @@ library ArrayHelper { return array_; } + /** + * @notice The function to crop a bool array + */ function crop(bool[] memory array_, uint256 newLength_) internal pure returns (bool[] memory) { if (newLength_ < array_.length) { assembly { @@ -242,6 +266,9 @@ library ArrayHelper { return array_; } + /** + * @notice The function to crop a string array + */ function crop( string[] memory array_, uint256 newLength_ @@ -255,6 +282,9 @@ library ArrayHelper { return array_; } + /** + * @notice The function to crop a bytes32 array + */ function crop( bytes32[] memory array_, uint256 newLength_ diff --git a/contracts/libs/arrays/Paginator.sol b/contracts/libs/arrays/Paginator.sol index aa9cb6de..1f22a10d 100644 --- a/contracts/libs/arrays/Paginator.sol +++ b/contracts/libs/arrays/Paginator.sol @@ -16,17 +16,16 @@ library Paginator { using StringSet for StringSet.Set; /** - * @notice Returns part of an array. - * @dev All functions below have the same description. + * @notice Returns part of a uint256 array * * Examples: * - part([4, 5, 6, 7], 0, 4) will return [4, 5, 6, 7] * - part([4, 5, 6, 7], 2, 4) will return [6, 7] * - part([4, 5, 6, 7], 2, 1) will return [6] * - * @param arr Storage array. - * @param offset_ Offset, index in an array. - * @param limit_ Number of elements after the `offset`. + * @param arr the storage array + * @param offset_ the starting index in the array + * @param limit_ the number of elements after the `offset_` */ function part( uint256[] storage arr, @@ -42,6 +41,9 @@ library Paginator { } } + /** + * @notice Returns part of an address array + */ function part( address[] storage arr, uint256 offset_, @@ -56,6 +58,9 @@ library Paginator { } } + /** + * @notice Returns part of a bytes32 array + */ function part( bytes32[] storage arr, uint256 offset_, @@ -70,6 +75,12 @@ library Paginator { } } + /** + * @notice Returns part of a uint256 set + * @param set the storage set + * @param offset_ the starting index in the set + * @param limit_ the number of elements after the `offset` + */ function part( EnumerableSet.UintSet storage set, uint256 offset_, @@ -84,6 +95,9 @@ library Paginator { } } + /** + * @notice Returns part of an address set + */ function part( EnumerableSet.AddressSet storage set, uint256 offset_, @@ -98,6 +112,9 @@ library Paginator { } } + /** + * @notice Returns part of a bytes32 set + */ function part( EnumerableSet.Bytes32Set storage set, uint256 offset_, @@ -112,6 +129,9 @@ library Paginator { } } + /** + * @notice Returns part of a string set + */ function part( StringSet.Set storage set, uint256 offset_, @@ -126,6 +146,12 @@ library Paginator { } } + /** + * @notice Returns the exclusive index of the element to iterate to + * @param length_ the length of the array + * @param offset_ the starting index + * @param limit_ the number of elements + */ function getTo( uint256 length_, uint256 offset_, diff --git a/contracts/libs/arrays/SetHelper.sol b/contracts/libs/arrays/SetHelper.sol index 516fd7e6..47257690 100644 --- a/contracts/libs/arrays/SetHelper.sol +++ b/contracts/libs/arrays/SetHelper.sol @@ -14,7 +14,7 @@ library SetHelper { using StringSet for StringSet.Set; /** - * @notice The function to insert an array of elements into the set + * @notice The function to insert an array of elements into the address set * @param set the set to insert the elements into * @param array_ the elements to be inserted */ @@ -24,12 +24,18 @@ library SetHelper { } } + /** + * @notice The function to insert an array of elements into the uint256 set + */ function add(EnumerableSet.UintSet storage set, uint256[] memory array_) internal { for (uint256 i = 0; i < array_.length; i++) { set.add(array_[i]); } } + /** + * @notice The function to insert an array of elements into the string set + */ function add(StringSet.Set storage set, string[] memory array_) internal { for (uint256 i = 0; i < array_.length; i++) { set.add(array_[i]); @@ -37,7 +43,7 @@ library SetHelper { } /** - * @notice The function to remove an array of elements from the set + * @notice The function to remove an array of elements from the address set * @param set the set to remove the elements from * @param array_ the elements to be removed */ @@ -47,12 +53,18 @@ library SetHelper { } } + /** + * @notice The function to remove an array of elements from the uint256 set + */ function remove(EnumerableSet.UintSet storage set, uint256[] memory array_) internal { for (uint256 i = 0; i < array_.length; i++) { set.remove(array_[i]); } } + /** + * @notice The function to remove an array of elements from the string set + */ function remove(StringSet.Set storage set, string[] memory array_) internal { for (uint256 i = 0; i < array_.length; i++) { set.remove(array_[i]); diff --git a/contracts/libs/data-structures/IncrementalMerkleTree.sol b/contracts/libs/data-structures/IncrementalMerkleTree.sol index 0f776a48..c622a5b5 100644 --- a/contracts/libs/data-structures/IncrementalMerkleTree.sol +++ b/contracts/libs/data-structures/IncrementalMerkleTree.sol @@ -58,7 +58,7 @@ library IncrementalMerkleTree { } /** - * @notice The function to add a new element to the tree. + * @notice The function to add a new element to the uint256 tree. * Complexity is O(log(n)), where n is the number of elements in the tree. * * @param tree self. @@ -69,7 +69,7 @@ library IncrementalMerkleTree { } /** - * @notice The function to return the root hash of the tree. + * @notice The function to return the root hash of the uint256 tree. * Complexity is O(log(n) + h), where n is the number of elements in the tree and * h is the height of the tree. * @@ -81,7 +81,7 @@ library IncrementalMerkleTree { } /** - * @notice The function to return the height of the tree. Complexity is O(1). + * @notice The function to return the height of the uint256 tree. Complexity is O(1). * @param tree self. * @return The height of the Merkle tree. */ @@ -90,7 +90,7 @@ library IncrementalMerkleTree { } /** - * @notice The function to return the number of elements in the tree. Complexity is O(1). + * @notice The function to return the number of elements in the uint256 tree. Complexity is O(1). * @param tree self. * @return The number of elements in the Merkle tree. */ @@ -108,18 +108,33 @@ library IncrementalMerkleTree { IMT _tree; } + /** + * @notice The function to add a new element to the bytes32 tree. + * Complexity is O(log(n)), where n is the number of elements in the tree. + */ function add(Bytes32IMT storage tree, bytes32 element_) internal { _add(tree._tree, element_); } + /** + * @notice The function to return the root hash of the bytes32 tree. + * Complexity is O(log(n) + h), where n is the number of elements in the tree and + * h is the height of the tree. + */ function root(Bytes32IMT storage tree) internal view returns (bytes32) { return _root(tree._tree); } + /** + * @notice The function to return the height of the bytes32 tree. Complexity is O(1). + */ function height(Bytes32IMT storage tree) internal view returns (uint256) { return _height(tree._tree); } + /** + * @notice The function to return the number of elements in the bytes32 tree. Complexity is O(1). + */ function length(Bytes32IMT storage tree) internal view returns (uint256) { return _length(tree._tree); } @@ -134,18 +149,33 @@ library IncrementalMerkleTree { IMT _tree; } + /** + * @notice The function to add a new element to the address tree. + * Complexity is O(log(n)), where n is the number of elements in the tree. + */ function add(AddressIMT storage tree, address element_) internal { _add(tree._tree, bytes32(uint256(uint160(element_)))); } + /** + * @notice The function to return the root hash of the address tree. + * Complexity is O(log(n) + h), where n is the number of elements in the tree and + * h is the height of the tree. + */ function root(AddressIMT storage tree) internal view returns (bytes32) { return _root(tree._tree); } + /** + * @notice The function to return the height of the address tree. Complexity is O(1). + */ function height(AddressIMT storage tree) internal view returns (uint256) { return _height(tree._tree); } + /** + * @notice The function to return the number of elements in the address tree. Complexity is O(1). + */ function length(AddressIMT storage tree) internal view returns (uint256) { return _length(tree._tree); } diff --git a/contracts/libs/data-structures/PriorityQueue.sol b/contracts/libs/data-structures/PriorityQueue.sol index d9300b13..2eeb8636 100644 --- a/contracts/libs/data-structures/PriorityQueue.sol +++ b/contracts/libs/data-structures/PriorityQueue.sol @@ -41,7 +41,7 @@ library PriorityQueue { } /** - * @notice The function to add an element to the queue. O(log(n)) complex + * @notice The function to add an element to the uint256 queue. O(log(n)) complex * @param queue self * @param value_ the element value * @param priority_ the element priority @@ -120,30 +120,53 @@ library PriorityQueue { Queue _queue; } + /** + * @notice The function to add an element to the bytes32 queue. O(log(n)) complex + */ function add(Bytes32Queue storage queue, bytes32 value_, uint256 priority_) internal { _add(queue._queue, value_, priority_); } + /** + * @notice The function to remove the element with the highest priority. O(log(n)) complex + */ function removeTop(Bytes32Queue storage queue) internal { _removeTop(queue._queue); } + /** + * @notice The function to read the value of the element with the highest priority. O(1) complex + */ function topValue(Bytes32Queue storage queue) internal view returns (bytes32) { return _topValue(queue._queue); } + /** + * @notice The function to read the element with the highest priority. O(1) complex + */ function top(Bytes32Queue storage queue) internal view returns (bytes32, uint256) { return _top(queue._queue); } + /** + * @notice The function to read the size of the queue. O(1) complex + */ function length(Bytes32Queue storage queue) internal view returns (uint256) { return _length(queue._queue); } + /** + * @notice The function to get the values stored in the queue. O(n) complex + * It is very expensive to call this function as it reads all the queue elements. Use cautiously + */ function values(Bytes32Queue storage queue) internal view returns (bytes32[] memory values_) { values_ = _values(queue._queue); } + /** + * @notice The function to get the values and priorities stored in the queue. O(n) complex + * It is very expensive to call this function as it reads all the queue elements. Use cautiously + */ function elements( Bytes32Queue storage queue ) internal view returns (bytes32[] memory values_, uint256[] memory priorities_) { @@ -161,32 +184,55 @@ library PriorityQueue { Queue _queue; } + /** + * @notice The function to add an element to the address queue. O(log(n)) complex + */ function add(AddressQueue storage queue, address value_, uint256 priority_) internal { _add(queue._queue, bytes32(uint256(uint160(value_))), priority_); } + /** + * @notice The function to remove the element with the highest priority. O(log(n)) complex + */ function removeTop(AddressQueue storage queue) internal { _removeTop(queue._queue); } + /** + * @notice The function to read the value of the element with the highest priority. O(1) complex + */ function topValue(AddressQueue storage queue) internal view returns (address) { return address(uint160(uint256(_topValue(queue._queue)))); } + /** + * @notice The function to read the element with the highest priority. O(1) complex + */ function top(AddressQueue storage queue) internal view returns (address, uint256) { (bytes32 value_, uint256 priority_) = _top(queue._queue); return (address(uint160(uint256(value_))), priority_); } + /** + * @notice The function to read the size of the queue. O(1) complex + */ function length(AddressQueue storage queue) internal view returns (uint256) { return _length(queue._queue); } + /** + * @notice The function to get the values stored in the queue. O(n) complex + * It is very expensive to call this function as it reads all the queue elements. Use cautiously + */ function values(AddressQueue storage queue) internal view returns (address[] memory values_) { return _values(queue._queue).asAddressArray(); } + /** + * @notice The function to get the values and priorities stored in the queue. O(n) complex + * It is very expensive to call this function as it reads all the queue elements. Use cautiously + */ function elements( AddressQueue storage queue ) internal view returns (address[] memory values_, uint256[] memory priorities_) { diff --git a/contracts/libs/data-structures/memory/Vector.sol b/contracts/libs/data-structures/memory/Vector.sol index 73aeee88..0bfdcd6f 100644 --- a/contracts/libs/data-structures/memory/Vector.sol +++ b/contracts/libs/data-structures/memory/Vector.sol @@ -70,7 +70,7 @@ library Vector { } /** - * @notice The function to push new elements (as an array) to the vector, amortized O(n) + * @notice The function to push new elements (as an array) to the uint256 vector, amortized O(n) * @param vector self * @param values_ the new elements to add */ @@ -79,7 +79,7 @@ library Vector { } /** - * @notice The function to push a new element to the vector, amortized O(1) + * @notice The function to push a new element to the uint256 vector, amortized O(1) * @param vector self * @param value_ the new element to add */ @@ -88,7 +88,7 @@ library Vector { } /** - * @notice The function to pop the last element from the vector, O(1) + * @notice The function to pop the last element from the uint256 vector, O(1) * @param vector self */ function pop(UintVector memory vector) internal pure { @@ -96,7 +96,7 @@ library Vector { } /** - * @notice The function to assign the value to a vector element + * @notice The function to assign the value to a uint256 vector element * @param vector self * @param index_ the index of the element to be assigned * @param value_ the value to assign @@ -106,7 +106,7 @@ library Vector { } /** - * @notice The function to read the element of the vector + * @notice The function to read the element of the uint256 vector * @param vector self * @param index_ the index of the element to read * @return the vector element @@ -116,7 +116,7 @@ library Vector { } /** - * @notice The function to get the number of vector elements + * @notice The function to get the number of uint256 vector elements * @param vector self * @return the number of vector elements */ @@ -125,7 +125,7 @@ library Vector { } /** - * @notice The function to cast the vector to an array + * @notice The function to cast the uint256 vector to an array * @dev The function returns the *reference* to the underlying array. Modifying the reference * will also modify the vector itself. However, this might not always be the case as the vector * resizes @@ -146,44 +146,74 @@ library Vector { Vector _vector; } + /** + * @notice The Bytes32Vector constructor, creates an empty vector instance, O(1) complex + */ function newBytes32() internal pure returns (Bytes32Vector memory vector) { vector._vector = _new(); } + /** + * @notice The Bytes32Vector constructor, creates a vector instance with defined length, O(n) complex + */ function newBytes32(uint256 length_) internal pure returns (Bytes32Vector memory vector) { vector._vector = _new(length_); } + /** + * @notice The Bytes32Vector constructor, creates a vector instance from the array, O(1) complex + */ function newBytes32( bytes32[] memory array_ ) internal pure returns (Bytes32Vector memory vector) { vector._vector = _new(array_); } + /** + * @notice The function to push new elements (as an array) to the bytes32 vector, amortized O(n) + */ function push(Bytes32Vector memory vector, bytes32[] memory values_) internal pure { _push(vector._vector, values_); } + /** + * @notice The function to push a new element to the bytes32 vector, amortized O(1) + */ function push(Bytes32Vector memory vector, bytes32 value_) internal pure { _push(vector._vector, value_); } + /** + * @notice The function to pop the last element from the bytes32 vector, O(1) + */ function pop(Bytes32Vector memory vector) internal pure { _pop(vector._vector); } + /** + * @notice The function to assign the value to a bytes32 vector element + */ function set(Bytes32Vector memory vector, uint256 index_, bytes32 value_) internal pure { _set(vector._vector, index_, value_); } + /** + * @notice The function to read the element of the bytes32 vector + */ function at(Bytes32Vector memory vector, uint256 index_) internal pure returns (bytes32) { return _at(vector._vector, index_); } + /** + * @notice The function to get the number of bytes32 vector elements + */ function length(Bytes32Vector memory vector) internal pure returns (uint256) { return _length(vector._vector); } + /** + * @notice The function to cast the bytes32 vector to an array + */ function toArray(Bytes32Vector memory vector) internal pure returns (bytes32[] memory) { return _toArray(vector._vector); } @@ -198,44 +228,74 @@ library Vector { Vector _vector; } + /** + * @notice The AddressVector constructor, creates an empty vector instance, O(1) complex + */ function newAddress() internal pure returns (AddressVector memory vector) { vector._vector = _new(); } + /** + * @notice The AddressVector constructor, creates a vector instance with defined length, O(n) complex + */ function newAddress(uint256 length_) internal pure returns (AddressVector memory vector) { vector._vector = _new(length_); } + /** + * @notice The AddressVector constructor, creates a vector instance from the array, O(1) complex + */ function newAddress( address[] memory array_ ) internal pure returns (AddressVector memory vector) { vector._vector = _new(array_.asBytes32Array()); } + /** + * @notice The function to push new elements (as an array) to the address vector, amortized O(n) + */ function push(AddressVector memory vector, address[] memory values_) internal pure { _push(vector._vector, values_.asBytes32Array()); } + /** + * @notice The function to push a new element to the address vector, amortized O(1) + */ function push(AddressVector memory vector, address value_) internal pure { _push(vector._vector, bytes32(uint256(uint160(value_)))); } + /** + * @notice The function to pop the last element from the address vector, O(1) + */ function pop(AddressVector memory vector) internal pure { _pop(vector._vector); } + /** + * @notice The function to assign the value to an address vector element + */ function set(AddressVector memory vector, uint256 index_, address value_) internal pure { _set(vector._vector, index_, bytes32(uint256(uint160(value_)))); } + /** + * @notice The function to read the element of the address vector + */ function at(AddressVector memory vector, uint256 index_) internal pure returns (address) { return address(uint160(uint256(_at(vector._vector, index_)))); } + /** + * @notice The function to get the number of address vector elements + */ function length(AddressVector memory vector) internal pure returns (uint256) { return _length(vector._vector); } + /** + * @notice The function to cast the address vector to an array + */ function toArray(AddressVector memory vector) internal pure returns (address[] memory) { return _toArray(vector._vector).asAddressArray(); } diff --git a/contracts/libs/utils/TypeCaster.sol b/contracts/libs/utils/TypeCaster.sol index d80aef1e..56320f2e 100644 --- a/contracts/libs/utils/TypeCaster.sol +++ b/contracts/libs/utils/TypeCaster.sol @@ -8,9 +8,9 @@ pragma solidity ^0.8.4; */ library TypeCaster { /** - * @notice The function that casts the list of `X`-type elements to the list of uint256 - * @param from_ the list of `X`-type elements - * @return array_ the list of uint256 + * @notice The function that casts the bytes32 array to the uint256 array + * @param from_ the bytes32 array + * @return array_ the uint256 array */ function asUint256Array( bytes32[] memory from_ @@ -20,6 +20,9 @@ library TypeCaster { } } + /** + * @notice The function that casts the address array to the uint256 array + */ function asUint256Array( address[] memory from_ ) internal pure returns (uint256[] memory array_) { @@ -29,8 +32,8 @@ library TypeCaster { } /** - * @notice The function that casts the list of `X`-type elements to the list of addresses - * @param from_ the list of `X`-type elements + * @notice The function that casts the bytes32 array to the address array + * @param from_ the bytes32 array * @return array_ the list of addresses */ function asAddressArray( @@ -41,6 +44,9 @@ library TypeCaster { } } + /** + * @notice The function that casts the uint256 array to the address array + */ function asAddressArray( uint256[] memory from_ ) internal pure returns (address[] memory array_) { @@ -50,9 +56,9 @@ library TypeCaster { } /** - * @notice The function that casts the list of `X`-type elements to the list of bytes32 - * @param from_ the list of `X`-type elements - * @return array_ the list of bytes32 + * @notice The function that casts the uint256 array to the bytes32 array + * @param from_ the bytes32 array + * @return array_ the list of addresses */ function asBytes32Array( uint256[] memory from_ @@ -62,6 +68,9 @@ library TypeCaster { } } + /** + * @notice The function that casts the address array to the bytes32 array + */ function asBytes32Array( address[] memory from_ ) internal pure returns (bytes32[] memory array_) { @@ -71,7 +80,7 @@ library TypeCaster { } /** - * @notice The function to transform an element into an array + * @notice The function to transform a uint256 element into an array * @param from_ the element * @return array_ the element as an array */ @@ -80,28 +89,40 @@ library TypeCaster { array_[0] = from_; } + /** + * @notice The function to transform an address element into an array + */ function asSingletonArray(address from_) internal pure returns (address[] memory array_) { array_ = new address[](1); array_[0] = from_; } + /** + * @notice The function to transform a bool element into an array + */ function asSingletonArray(bool from_) internal pure returns (bool[] memory array_) { array_ = new bool[](1); array_[0] = from_; } + /** + * @notice The function to transform a string element into an array + */ function asSingletonArray(string memory from_) internal pure returns (string[] memory array_) { array_ = new string[](1); array_[0] = from_; } + /** + * @notice The function to transform a bytes32 element into an array + */ function asSingletonArray(bytes32 from_) internal pure returns (bytes32[] memory array_) { array_ = new bytes32[](1); array_[0] = from_; } /** - * @notice The function to convert static array to dynamic + * @notice The function to convert static uint256[1] array to dynamic * @param static_ the static array to convert * @return dynamic_ the converted dynamic array */ @@ -111,6 +132,9 @@ library TypeCaster { return asSingletonArray(static_[0]); } + /** + * @notice The function to convert static uint256[2] array to dynamic + */ function asDynamic( uint256[2] memory static_ ) internal pure returns (uint256[] memory dynamic_) { @@ -127,6 +151,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 2); } + /** + * @notice The function to convert static uint256[3] array to dynamic + */ function asDynamic( uint256[3] memory static_ ) internal pure returns (uint256[] memory dynamic_) { @@ -143,6 +170,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 3); } + /** + * @notice The function to convert static uint256[4] array to dynamic + */ function asDynamic( uint256[4] memory static_ ) internal pure returns (uint256[] memory dynamic_) { @@ -159,6 +189,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 4); } + /** + * @notice The function to convert static uint256[5] array to dynamic + */ function asDynamic( uint256[5] memory static_ ) internal pure returns (uint256[] memory dynamic_) { @@ -175,12 +208,18 @@ library TypeCaster { _copy(pointerS_, pointerD_, 5); } + /** + * @notice The function to convert static address[1] array to dynamic + */ function asDynamic( address[1] memory static_ ) internal pure returns (address[] memory dynamic_) { return asSingletonArray(static_[0]); } + /** + * @notice The function to convert static address[2] array to dynamic + */ function asDynamic( address[2] memory static_ ) internal pure returns (address[] memory dynamic_) { @@ -197,6 +236,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 2); } + /** + * @notice The function to convert static address[3] array to dynamic + */ function asDynamic( address[3] memory static_ ) internal pure returns (address[] memory dynamic_) { @@ -213,6 +255,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 3); } + /** + * @notice The function to convert static address[4] array to dynamic + */ function asDynamic( address[4] memory static_ ) internal pure returns (address[] memory dynamic_) { @@ -229,6 +274,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 4); } + /** + * @notice The function to convert static address[5] array to dynamic + */ function asDynamic( address[5] memory static_ ) internal pure returns (address[] memory dynamic_) { @@ -245,10 +293,16 @@ library TypeCaster { _copy(pointerS_, pointerD_, 5); } + /** + * @notice The function to convert static bool[1] array to dynamic + */ function asDynamic(bool[1] memory static_) internal pure returns (bool[] memory dynamic_) { return asSingletonArray(static_[0]); } + /** + * @notice The function to convert static bool[2] array to dynamic + */ function asDynamic(bool[2] memory static_) internal pure returns (bool[] memory dynamic_) { dynamic_ = new bool[](2); @@ -263,6 +317,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 2); } + /** + * @notice The function to convert static bool[3] array to dynamic + */ function asDynamic(bool[3] memory static_) internal pure returns (bool[] memory dynamic_) { dynamic_ = new bool[](3); @@ -277,6 +334,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 3); } + /** + * @notice The function to convert static bool[4] array to dynamic + */ function asDynamic(bool[4] memory static_) internal pure returns (bool[] memory dynamic_) { dynamic_ = new bool[](4); @@ -291,6 +351,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 4); } + /** + * @notice The function to convert static bool[5] array to dynamic + */ function asDynamic(bool[5] memory static_) internal pure returns (bool[] memory dynamic_) { dynamic_ = new bool[](5); @@ -305,10 +368,16 @@ library TypeCaster { _copy(pointerS_, pointerD_, 5); } + /** + * @notice The function to convert static string[1] array to dynamic + */ function asDynamic(string[1] memory static_) internal pure returns (string[] memory dynamic_) { return asSingletonArray(static_[0]); } + /** + * @notice The function to convert static string[2] array to dynamic + */ function asDynamic(string[2] memory static_) internal pure returns (string[] memory dynamic_) { dynamic_ = new string[](2); @@ -323,6 +392,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 2); } + /** + * @notice The function to convert static string[3] array to dynamic + */ function asDynamic(string[3] memory static_) internal pure returns (string[] memory dynamic_) { dynamic_ = new string[](3); @@ -337,6 +409,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 3); } + /** + * @notice The function to convert static string[4] array to dynamic + */ function asDynamic(string[4] memory static_) internal pure returns (string[] memory dynamic_) { dynamic_ = new string[](4); @@ -351,6 +426,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 4); } + /** + * @notice The function to convert static string[5] array to dynamic + */ function asDynamic(string[5] memory static_) internal pure returns (string[] memory dynamic_) { dynamic_ = new string[](5); @@ -365,12 +443,18 @@ library TypeCaster { _copy(pointerS_, pointerD_, 5); } + /** + * @notice The function to convert static bytes32[1] array to dynamic + */ function asDynamic( bytes32[1] memory static_ ) internal pure returns (bytes32[] memory dynamic_) { return asSingletonArray(static_[0]); } + /** + * @notice The function to convert static bytes32[2] array to dynamic + */ function asDynamic( bytes32[2] memory static_ ) internal pure returns (bytes32[] memory dynamic_) { @@ -387,6 +471,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 2); } + /** + * @notice The function to convert static bytes32[3] array to dynamic + */ function asDynamic( bytes32[3] memory static_ ) internal pure returns (bytes32[] memory dynamic_) { @@ -403,6 +490,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 3); } + /** + * @notice The function to convert static bytes32[4] array to dynamic + */ function asDynamic( bytes32[4] memory static_ ) internal pure returns (bytes32[] memory dynamic_) { @@ -419,6 +509,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 4); } + /** + * @notice The function to convert static bytes32[5] array to dynamic + */ function asDynamic( bytes32[5] memory static_ ) internal pure returns (bytes32[] memory dynamic_) { @@ -435,6 +528,9 @@ library TypeCaster { _copy(pointerS_, pointerD_, 5); } + /** + * @notice private function to copy memory + */ function _copy(uint256 locationS_, uint256 locationD_, uint256 length_) private pure { assembly { for { diff --git a/contracts/libs/zkp/snarkjs/VerifierHelper.sol b/contracts/libs/zkp/snarkjs/VerifierHelper.sol index 5b1675aa..422b8f03 100644 --- a/contracts/libs/zkp/snarkjs/VerifierHelper.sol +++ b/contracts/libs/zkp/snarkjs/VerifierHelper.sol @@ -141,7 +141,7 @@ library VerifierHelper { ) ); - // We have to use abi.encodePacked to encode a dynamic array as a static array (without offset and length) + /// @dev We have to use abi.encodePacked to encode a dynamic array as a static array (without offset and length) (bool success_, bytes memory returnData_) = verifier_.staticcall( abi.encodePacked(abi.encodeWithSignature(funcSign_, a_, b_, c_), pubSignals_) );