diff --git a/packages/vm/core/evm/iscmagic/ISC.sol b/packages/vm/core/evm/iscmagic/ISC.sol index dcc5404485..f6d0a4f85a 100644 --- 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 index c4319e36b7..6514ec1981 100644 --- 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 index 6924f5f278..fa2dbfe25a 100644 --- a/packages/vm/core/evm/iscmagic/ISCPrivileged.sol +++ b/packages/vm/core/evm/iscmagic/ISCPrivileged.sol @@ -11,18 +11,37 @@ 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, @@ -30,6 +49,12 @@ interface ISCPrivileged { 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, diff --git a/packages/vm/core/evm/iscmagic/ISCSandbox.sol b/packages/vm/core/evm/iscmagic/ISCSandbox.sol index d9c7f6f10a..1377effdd9 100644 --- a/packages/vm/core/evm/iscmagic/ISCSandbox.sol +++ b/packages/vm/core/evm/iscmagic/ISCSandbox.sol @@ -10,50 +10,84 @@ import "./ISCTypes.sol"; * @dev This is the main interface of the ISC Magic Contract. */ interface ISCSandbox { - // Get the ISC request ID + /** + * @dev Retrieves the ID of the current ISC request. + * @return The ISCRequestID of the current request. + */ function getRequestID() external view returns (ISCRequestID memory); - // Get the AgentID of the sender of the ISC request + /** + * @dev Retrieves the AgentID of the account that sent the current ISC request. + * @return The ISCAgentID of the sender. + */ function getSenderAccount() external view returns (ISCAgentID memory); - // Trigger an ISC event + /** + * @dev Triggers an event in the ISC system with the given string. + * @param s The string to include in the event. + */ function triggerEvent(string memory s) external; - // Get a random 32-bit value based on the hash of the current ISC state transaction + /** + * @dev Retrieves a random 32-bit value derived from the hash of the current ISC state transaction. + * @return A random bytes32 value. + */ function getEntropy() external view returns (bytes32); - // Allow the `target` EVM contract to take some funds from the caller's L2 account + /** + * @dev Authorizes the specified target address to take the given assets from the caller's account. + * @param target The address of the target EVM contract. + * @param allowance The assets to be allowed. + */ function allow(address target, ISCAssets memory allowance) external; - // Take some funds from the given address, which must have authorized first with `allow`. - // If `allowance` is empty, all allowed funds are taken. + /** + * @dev Takes the specified assets from the given address if they have authorized the caller. If the allowance is empty, all allowed funds are taken. + * @param addr The address to take funds from. + * @param allowance The assets to take. + */ function takeAllowedFunds( address addr, ISCAssets memory allowance ) external; - // Get the amount of funds currently allowed by the given address to the caller + /** + * @dev Retrieves the amount of assets the specified address has allowed the caller to take. + * @param addr The address that has allowed funds. + * @return The allowed ISCAssets. + */ function getAllowanceFrom( address addr ) external view returns (ISCAssets memory); - // Get the amount of funds currently allowed by the caller to the given address + /** + * @dev Retrieves the amount of assets the caller has allowed the specified address to take. + * @param target The address allowed to take funds. + * @return The allowed ISCAssets. + */ function getAllowanceTo( address target ) external view returns (ISCAssets memory); - // Get the amount of funds currently allowed between the given addresses + /** + * @dev Retrieves the amount of assets allowed between the specified addresses. + * @param from The address that has allowed funds. + * @param to The address allowed to take funds. + * @return The allowed ISCAssets. + */ function getAllowance( address from, address to ) external view returns (ISCAssets memory); - // Send an on-ledger request (or a regular transaction to any L1 address). - // The specified `assets` are transferred from the caller's - // L2 account to the `evm` core contract's account. - // The sent request will have the `evm` core contract as sender. It will - // include the transferred `assets`. - // The specified `allowance` must not be greater than `assets`. + /** + * @dev Sends the specified assets from the caller's L2 account to a L1 address and includes the specified metadata and options. This can also be used to create on-ledger requests to the chain itself. + * @param targetAddress The L1 address to send the assets to. + * @param assets The assets to be sent. + * @param adjustMinimumStorageDeposit Whether to adjust the minimum storage deposit. + * @param metadata The metadata to include in the request. + * @param sendOptions The options for the send operation. + */ function send( L1Address memory targetAddress, ISCAssets memory assets, @@ -62,7 +96,14 @@ interface ISCSandbox { ISCSendOptions memory sendOptions ) external payable; - // Call the entry point of an ISC contract on the same chain. + /** + * @dev Calls the specified entry point of the ISC contract with the given parameters and allowance. + * @param contractHname The hname of the contract. + * @param entryPoint The entry point to be called. + * @param params The parameters to pass to the entry point. + * @param allowance The assets to be allowed for the call. + * @return The return data from the ISC contract call. + */ function call( ISCHname contractHname, ISCHname entryPoint, @@ -70,47 +111,94 @@ interface ISCSandbox { ISCAssets memory allowance ) external returns (ISCDict memory); - // Call a view entry point of an ISC contract on the same chain. - // The called entry point will have the `evm` core contract as caller. + /** + * @dev Calls the specified view entry point of the ISC contract with the given parameters. + * @param contractHname The hname of the contract. + * @param entryPoint The view entry point to be called. + * @param params The parameters to pass to the view entry point. + * @return The return data from the ISC contract view call. + */ function callView( ISCHname contractHname, ISCHname entryPoint, ISCDict memory params ) external view returns (ISCDict memory); - // Get the ChainID of the underlying ISC chain + /** + * @dev Retrieves the ChainID of the current ISC chain. + * @return The ISCChainID of the current chain. + */ function getChainID() external view returns (ISCChainID); - // Get the ISC chain's owner + /** + * @dev Retrieves the AgentID of the owner of the current ISC chain. + * @return The ISCAgentID of the chain owner. + */ function getChainOwnerID() external view returns (ISCAgentID memory); - // Get the timestamp of the ISC block (seconds since UNIX epoch) + /** + * @dev Retrieves the timestamp of the current ISC block in seconds since the UNIX epoch. + * @return The timestamp of the current block. + */ function getTimestampUnixSeconds() external view returns (int64); - // Get the properties of the ISC base token + /** + * @dev Retrieves the properties of the base token used in the ISC system. + * @return The ISCTokenProperties of the base token. + */ function getBaseTokenProperties() external view returns (ISCTokenProperties memory); - // Get the ID of a L2-controlled native token, given its foundry serial number + /** + * @dev Retrieves the NativeTokenID of a native token based on its foundry serial number. + * @param foundrySN The serial number of the foundry. + * @return The NativeTokenID of the specified native token. + */ function getNativeTokenID( uint32 foundrySN ) external view returns (NativeTokenID memory); - // Get the token scheme of a L2-controlled native token, given its foundry serial number + /** + * @dev Retrieves the NativeTokenScheme of a native token based on its foundry serial number. + * @param foundrySN The serial number of the foundry. + * @return The NativeTokenScheme of the specified native token. + */ function getNativeTokenScheme( uint32 foundrySN ) external view returns (NativeTokenScheme memory); - // Get information about an on-chain NFT + /** + * @dev Retrieves the details of an NFT based on its ID. + * @param id The ID of the NFT. + * @return The ISCNFT data of the specified NFT. + */ function getNFTData(NFTID id) external view returns (ISCNFT memory); - // Get information about an on-chain IRC27 NFT - // NOTE: metadata does not include attributes, use `getIRC27TokenURI` to get those attributes off-chain in JSON form + /** + * @dev Retrieves the details of an IRC27 NFT based on its ID. + * @param id The ID of the IRC27 NFT. + * @return The IRC27NFT data of the specified NFT. + * + * Note: the metadata.uri field is encoded as a data URL with: + * base64(jsonEncode({ + * "name": NFT.name, + * "description": NFT.description, + * "image": NFT.URI + * })) + * + * Note: metadata does not include attributes, use `getIRC27TokenURI` to get those attributes off-chain in JSON form. + */ function getIRC27NFTData(NFTID id) external view returns (IRC27NFT memory); - // Get information about an on-chain IRC27 NFT + function getIRC27NFTData(NFTID id) external view returns (IRC27NFT memory); + + /** + * @dev Retrieves the URI of an IRC27 NFT based on its ID. + * @param id The ID of the IRC27 NFT. + * @return The URI of the specified IRC27 NFT. + */ // returns a JSON file encoded with the following format: // base64(jsonEncode({ // "name": NFT.name, @@ -119,22 +207,41 @@ interface ISCSandbox { // })) function getIRC27TokenURI(NFTID id) external view returns (string memory); - // Get the address of an ERC20NativeTokens contract for the given foundry serial number + /** + * @dev Retrieves the address of an ERC20NativeTokens contract based on the foundry serial number. + * @param foundrySN The serial number of the foundry. + * @return The address of the specified ERC20NativeTokens contract. + */ function erc20NativeTokensAddress( uint32 foundrySN ) external view returns (address); - // Get the address of an ERC721NFTCollection contract for the given collection ID + /** + * @dev Retrieves the address of an ERC721NFTCollection contract based on the collection ID. + * @param collectionID The ID of the NFT collection. + * @return The address of the specified ERC721NFTCollection contract. + */ function erc721NFTCollectionAddress( NFTID collectionID ) external view returns (address); - // Extract the foundry serial number from an ERC20NativeTokens contract's address + /** + * @dev Retrieves the foundry serial number from the address of an ERC20NativeTokens contract. + * @param addr The address of the ERC20NativeTokens contract. + * @return The foundry serial number. + */ function erc20NativeTokensFoundrySerialNumber( address addr ) external view returns (uint32); - // Creates an ERC20NativeTokens contract instance and register it with the foundry as a native token. Only the foundry owner can call this function. + /** + * @dev Registers a new ERC20NativeTokens contract with the specified foundry and token details. Only callable by the foundry owner. + * @param foundrySN The serial number of the foundry. + * @param name The name of the new token. + * @param symbol The symbol of the new token. + * @param decimals The decimals of the new token. + * @param allowance The assets to be allowed for the registration. + */ function registerERC20NativeToken( uint32 foundrySN, string memory name, diff --git a/packages/vm/core/evm/iscmagic/ISCTypes.sol b/packages/vm/core/evm/iscmagic/ISCTypes.sol index 6792d0bfc0..b44c8cdadf 100644 --- a/packages/vm/core/evm/iscmagic/ISCTypes.sol +++ b/packages/vm/core/evm/iscmagic/ISCTypes.sol @@ -141,12 +141,26 @@ struct ISCTokenProperties { } library ISCTypes { + /** + * @dev Get the type of an L1 address. + * @param addr The L1 address. + * @return The type of the L1 address. + * + * For more details about the types of L1 addresses, please refer to the IOTA Tangle Improvement Proposal (TIP) 18: + * https://wiki.iota.org/tips/tips/TIP-0018/#address-unlock-condition + */ function L1AddressType( L1Address memory addr ) internal pure returns (uint8) { return uint8(addr.data[0]); } + /** + * @dev Create a new Ethereum AgentID. + * @param addr The Ethereum address. + * @param iscChainID The ISC chain ID. + * @return The new ISCAgentID. + */ function newEthereumAgentID( address addr, ISCChainID iscChainID @@ -169,6 +183,11 @@ library ISCTypes { return r; } + /** + * @dev Create a new L1 AgentID. + * @param l1Addr The L1 address. + * @return The new ISCAgentID. + */ function newL1AgentID( bytes memory l1Addr ) internal pure returns (ISCAgentID memory) { @@ -187,10 +206,20 @@ library ISCTypes { return r; } + /** + * @dev Check if an ISCAgentID is of Ethereum type. + * @param a The ISCAgentID to check. + * @return True if the ISCAgentID is of Ethereum type, false otherwise. + */ function isEthereum(ISCAgentID memory a) internal pure returns (bool) { return uint8(a.data[0]) == ISCAgentIDKindEthereumAddress; } + /** + * @dev Get the Ethereum address from an ISCAgentID. + * @param a The ISCAgentID. + * @return The Ethereum address. + */ function ethAddress(ISCAgentID memory a) internal pure returns (address) { bytes memory b = new bytes(20); //offset of 33 (kind byte + chainID) @@ -198,6 +227,11 @@ library ISCTypes { return address(uint160(bytes20(b))); } + /** + * @dev Get the chain ID from an ISCAgentID. + * @param a The ISCAgentID. + * @return The ISCChainID. + */ function chainID(ISCAgentID memory a) internal pure returns (ISCChainID) { bytes32 out; for (uint i = 0; i < 32; i++) { @@ -207,10 +241,21 @@ library ISCTypes { return ISCChainID.wrap(out); } + /** + * @notice Convert a token ID to an NFTID. + * @param tokenID The token ID. + * @return The NFTID. + */ function asNFTID(uint256 tokenID) internal pure returns (NFTID) { return NFTID.wrap(bytes32(tokenID)); } + /** + * @dev Check if an NFT is part of a given collection. + * @param nft The NFT to check. + * @param collectionId The collection ID to check against. + * @return True if the NFT is part of the collection, false otherwise. + */ function isInCollection( ISCNFT memory nft, NFTID collectionId diff --git a/packages/vm/core/evm/iscmagic/ISCUtil.sol b/packages/vm/core/evm/iscmagic/ISCUtil.sol index 56b764fbaf..eb767f97de 100644 --- a/packages/vm/core/evm/iscmagic/ISCUtil.sol +++ b/packages/vm/core/evm/iscmagic/ISCUtil.sol @@ -10,10 +10,19 @@ import "./ISCTypes.sol"; * @dev Functions of the ISC Magic Contract not directly related to the ISC sandbox */ interface ISCUtil { - // Get an ISC contract's hname given its instance name + /** + * @notice Get an ISC contract's hname given its instance name + * @dev Converts a string instance name to its corresponding ISC hname. + * @param s The instance name of the ISC contract. + * @return The ISCHname corresponding to the given instance name. + */ function hn(string memory s) external pure returns (ISCHname); - // Print something to the console (will only work when debugging contracts with Solo) + /** + * @notice Print something to the console (will only work when debugging contracts with Solo) + * @dev Prints the given string to the console for debugging purposes. + * @param s The string to print to the console. + */ function print(string memory s) external pure; }