Merge pull request #3457 from iotaledger/devx/update-docStrings-in-ma…

…gic-contracts fix(magic-contracts): Add missing docstrings in magic contracts
iotaledger · Jul 25, 2024 · cecf521 · cecf521
2 parents d2f4efb + 9307c85
commit cecf521
Show file tree

Hide file tree

Showing 6 changed files with 285 additions and 46 deletions.
diff --git a/packages/vm/core/evm/iscmagic/ISC.sol b/packages/vm/core/evm/iscmagic/ISC.sol
@@ -26,14 +26,22 @@ library ISC {
 
     ERC20BaseTokens constant baseTokens = __erc20BaseTokens;
 
-    // Get the ERC20NativeTokens contract for the given foundry serial number
+    /**
+     * @notice Get the ERC20NativeTokens contract for the given foundry serial number
+     * @param foundrySN The serial number of the foundry
+     * @return The ERC20NativeTokens contract corresponding to the given foundry serial number
+     */
     function nativeTokens(uint32 foundrySN) internal view returns (ERC20NativeTokens) {
         return ERC20NativeTokens(sandbox.erc20NativeTokensAddress(foundrySN));
     }
 
     ERC721NFTs constant nfts = __erc721NFTs;
 
-    // Get the ERC721NFTCollection contract for the given collection
+    /**
+     * @notice Get the ERC721NFTCollection contract for the given collection
+     * @param collectionID The ID of the NFT collection
+     * @return The ERC721NFTCollection contract corresponding to the given collection ID
+     */
     function erc721NFTCollection(NFTID collectionID) internal view returns (ERC721NFTCollection) {
         return ERC721NFTCollection(sandbox.erc721NFTCollectionAddress(collectionID));
     }

diff --git a/packages/vm/core/evm/iscmagic/ISCAccounts.sol b/packages/vm/core/evm/iscmagic/ISCAccounts.sol
@@ -10,31 +10,76 @@ import "./ISCTypes.sol";
  * @dev Functions of the ISC Magic Contract to access the core accounts functionality
  */
 interface ISCAccounts {
-    // Get the L2 base tokens balance of an account
+    /**
+     * @dev This function retrieves the balance of L2 base tokens for a given account.
+     * @param agentID The ID of the agent (account) whose balance is to be retrieved
+     * @return The L2 base tokens balance of the specified account
+     */
     function getL2BalanceBaseTokens(ISCAgentID memory agentID) external view returns (uint64);
 
-    // Get the L2 native tokens balance of an account
+    /**
+     * @dev This function retrieves the balance of L2 native tokens for a given account.
+     * @param id The ID of the native token
+     * @param agentID The ID of the agent (account) whose balance is to be retrieved
+     * @return The L2 native tokens balance of the specified account
+     */
     function getL2BalanceNativeTokens(NativeTokenID memory id, ISCAgentID memory agentID) external view returns (uint256);
 
-    // Get the L2 NFTs owned by an account
+    /**
+     * @dev This function retrieves the IDs of NFTs owned by a given account.
+     * @param agentID The ID of the agent (account) whose NFTs are to be retrieved
+     * @return An array of NFTIDs representing the NFTs owned by the specified account
+     */
     function getL2NFTs(ISCAgentID memory agentID) external view returns (NFTID[] memory);
 
-    // Get the amount of L2 NFTs owned by an account
+    /**
+     * @dev This function retrieves the number of NFTs owned by a given account.
+     * @param agentID The ID of the agent (account) whose NFT amount is to be retrieved
+     * @return The amount of L2 NFTs owned by the specified account
+     */
     function getL2NFTAmount(ISCAgentID memory agentID) external view returns (uint256);
 
-    // Get the L2 NFTs of a given collection owned by an account
+    /**
+     * @dev This function retrieves the NFTs of a specific collection owned by a given account.
+     * @param agentID The ID of the agent (account) whose NFTs are to be retrieved
+     * @param collectionId The ID of the NFT collection
+     * @return An array of NFTIDs representing the NFTs in the specified collection owned by the account
+     */
     function getL2NFTsInCollection(ISCAgentID memory agentID, NFTID collectionId) external view returns (NFTID[] memory);
 
-    // Get the amount of L2 NFTs of a given collection owned by an account
+    /**
+     * @dev This function retrieves the number of NFTs in a specific collection owned by a given account.
+     * @param agentID The ID of the agent (account) whose NFT amount is to be retrieved
+     * @param collectionId The ID of the NFT collection
+     * @return The amount of L2 NFTs in the specified collection owned by the account
+     */
     function getL2NFTAmountInCollection(ISCAgentID memory agentID, NFTID collectionId) external view returns (uint256);
 
-    // Create a new foundry.
+    /**
+     * @dev This function allows the creation of a new foundry with a specified token scheme and asset allowance.
+     * @param tokenScheme The token scheme for the new foundry
+     * @param allowance The assets to be allowed for the foundry creation
+     * @return The serial number of the newly created foundry
+     */
     function foundryCreateNew(NativeTokenScheme memory tokenScheme, ISCAssets memory allowance) external returns(uint32);
 
-    // Creates foundry + IRC30 metadata + ERC20 token registration
+    /**
+     * @dev This function allows the creation of a new native token foundry along with its IRC30 metadata and ERC20 token registration.
+     * @param tokenName The name of the new token
+     * @param tokenSymbol The symbol of the new token
+     * @param tokenDecimals The number of decimals for the new token
+     * @param tokenScheme The token scheme for the new foundry
+     * @param allowance The assets to be allowed for the foundry creation
+     * @return The serial number of the newly created foundry
+     */
     function createNativeTokenFoundry(string memory tokenName, string memory tokenSymbol, uint8 tokenDecimals, NativeTokenScheme memory tokenScheme, ISCAssets memory allowance) external returns(uint32);
 
-    // Mint new tokens. Only the owner of the foundry can call this function.
+    /**
+     * @dev This function allows the owner of a foundry to mint new native tokens.
+     * @param foundrySN The serial number of the foundry
+     * @param amount The amount of tokens to mint
+     * @param allowance The assets to be allowed for the minting process
+     */
     function mintNativeTokens(uint32 foundrySN, uint256 amount, ISCAssets memory allowance) external;
 }
 

diff --git a/packages/vm/core/evm/iscmagic/ISCPrivileged.sol b/packages/vm/core/evm/iscmagic/ISCPrivileged.sol
@@ -11,25 +11,50 @@ import "./ISCTypes.sol";
  * These methods can only be called from privileged contracts.
  */
 interface ISCPrivileged {
+    /**
+     * @dev This function allows privileged contracts to move assets between accounts.
+     * @param sender The address of the sender account
+     * @param receiver The address of the receiver account
+     * @param allowance The assets to be moved from the sender to the receiver
+     */
     function moveBetweenAccounts(
         address sender,
         address receiver,
         ISCAssets memory allowance
     ) external;
 
+    /**
+     * @dev This function allows privileged contracts to set the allowance of base tokens from one account to another.
+     * @param from The address of the account from which tokens are allowed
+     * @param to The address of the account to which tokens are allowed
+     * @param numTokens The number of base tokens to be allowed
+     */
     function setAllowanceBaseTokens(
         address from,
         address to,
         uint256 numTokens
     ) external;
 
+    /**
+     * @dev This function allows privileged contracts to set the allowance of native tokens from one account to another.
+     * @param from The address of the account from which tokens are allowed
+     * @param to The address of the account to which tokens are allowed
+     * @param nativeTokenID The ID of the native token
+     * @param numTokens The number of native tokens to be allowed
+     */
     function setAllowanceNativeTokens(
         address from,
         address to,
         NativeTokenID memory nativeTokenID,
         uint256 numTokens
     ) external;
 
+    /**
+     * @dev This function allows privileged contracts to move allowed funds from one account to another.
+     * @param from The address of the account from which funds are allowed
+     * @param to The address of the account to which funds are allowed
+     * @param allowance The assets to be moved from the sender to the receiver
+     */
     function moveAllowedFunds(
         address from,
         address to,