From b55c97a3dc32595c2c80198e59e94dbe811e8aa3 Mon Sep 17 00:00:00 2001 From: Gino Date: Wed, 3 Jul 2024 11:09:51 +0100 Subject: [PATCH 1/8] refactor(wiki): add docstrings to ISC library functions --- packages/vm/core/evm/iscmagic/ISC.sol | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) 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)); } From 3e72c6781eb5f2d0e331d1af1d9e28eea7451e0b Mon Sep 17 00:00:00 2001 From: Gino Date: Wed, 3 Jul 2024 11:15:58 +0100 Subject: [PATCH 2/8] refactor(wiki): add docstrings to ISCAccounts interface functions --- packages/vm/core/evm/iscmagic/ISCAccounts.sol | 63 ++++++++++++++++--- 1 file changed, 54 insertions(+), 9 deletions(-) diff --git a/packages/vm/core/evm/iscmagic/ISCAccounts.sol b/packages/vm/core/evm/iscmagic/ISCAccounts.sol index c4319e36b7..b8d747e653 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 + /** + * @notice Get the L2 base tokens balance of an 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 + /** + * @notice Get the L2 native tokens balance of an 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 + /** + * @notice Get the L2 NFTs owned by an 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 + /** + * @notice Get the amount of L2 NFTs owned by an 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 + /** + * @notice Get the L2 NFTs of a given collection owned by an 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 + /** + * @notice Get the amount of L2 NFTs of a given collection owned by an 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. + /** + * @notice Create a new foundry + * @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 + /** + * @notice Creates foundry + IRC30 metadata + 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. + /** + * @notice Mint new tokens. Only the owner of the foundry can call this function. + * @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; } From 644acda74c7c1314b510643575a0784d8f56fa8b Mon Sep 17 00:00:00 2001 From: Gino Date: Wed, 3 Jul 2024 11:38:25 +0100 Subject: [PATCH 3/8] refactor(wiki): add docstrings to ISCPriviledged interface functions --- packages/vm/core/evm/iscmagic/ISCAccounts.sol | 9 ++++++ .../vm/core/evm/iscmagic/ISCPrivileged.sol | 29 +++++++++++++++++++ 2 files changed, 38 insertions(+) diff --git a/packages/vm/core/evm/iscmagic/ISCAccounts.sol b/packages/vm/core/evm/iscmagic/ISCAccounts.sol index b8d747e653..d7cc76c9e6 100644 --- a/packages/vm/core/evm/iscmagic/ISCAccounts.sol +++ b/packages/vm/core/evm/iscmagic/ISCAccounts.sol @@ -12,6 +12,7 @@ import "./ISCTypes.sol"; interface ISCAccounts { /** * @notice 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 */ @@ -19,6 +20,7 @@ interface ISCAccounts { /** * @notice 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 @@ -27,6 +29,7 @@ interface ISCAccounts { /** * @notice Get the 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 NFTs are to be retrieved * @return An array of NFTIDs representing the NFTs owned by the specified account */ @@ -34,6 +37,7 @@ interface ISCAccounts { /** * @notice Get the amount of L2 NFTs owned by an account + * @dev This function retrieves the 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 */ @@ -41,6 +45,7 @@ interface ISCAccounts { /** * @notice 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 @@ -49,6 +54,7 @@ interface ISCAccounts { /** * @notice 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 @@ -57,6 +63,7 @@ interface ISCAccounts { /** * @notice 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 @@ -65,6 +72,7 @@ interface ISCAccounts { /** * @notice 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 @@ -76,6 +84,7 @@ interface ISCAccounts { /** * @notice 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 diff --git a/packages/vm/core/evm/iscmagic/ISCPrivileged.sol b/packages/vm/core/evm/iscmagic/ISCPrivileged.sol index 6924f5f278..81a67685a6 100644 --- a/packages/vm/core/evm/iscmagic/ISCPrivileged.sol +++ b/packages/vm/core/evm/iscmagic/ISCPrivileged.sol @@ -11,18 +11,40 @@ import "./ISCTypes.sol"; * These methods can only be called from privileged contracts. */ interface ISCPrivileged { + /** + * @notice Move assets between accounts + * @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; + /** + * @notice Set allowance of base tokens + * @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; + /** + * @notice Set allowance of native tokens + * @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 +52,13 @@ interface ISCPrivileged { uint256 numTokens ) external; + /** + * @notice Move allowed funds between accounts + * @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, From 497dd4ad44416c458514bdf2e58d8577ebcfe7f8 Mon Sep 17 00:00:00 2001 From: Gino Date: Mon, 22 Jul 2024 11:20:49 +0100 Subject: [PATCH 4/8] feat: resolve conflict --- packages/vm/core/evm/iscmagic/ISCSandbox.sol | 193 +++++++++++++++---- 1 file changed, 160 insertions(+), 33 deletions(-) diff --git a/packages/vm/core/evm/iscmagic/ISCSandbox.sol b/packages/vm/core/evm/iscmagic/ISCSandbox.sol index d9c7f6f10a..c5156c8603 100644 --- a/packages/vm/core/evm/iscmagic/ISCSandbox.sol +++ b/packages/vm/core/evm/iscmagic/ISCSandbox.sol @@ -10,50 +10,94 @@ import "./ISCTypes.sol"; * @dev This is the main interface of the ISC Magic Contract. */ interface ISCSandbox { - // Get the ISC request ID + /** + * @notice 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 + /** + * @notice 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 + /** + * @notice 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 + /** + * @notice 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 + /** + * @notice 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. + /** + * @notice Take some funds from the given address, which must have authorized first with `allow`. + * @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 + /** + * @notice 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 + /** + * @notice 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 + /** + * @notice 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`. + /** + * @notice Send an on-ledger request (or a regular transaction to any L1 address). + * @dev Sends the specified assets from the caller's L2 account to the EVM core contract's account and includes the specified metadata and options. + * @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 +106,15 @@ interface ISCSandbox { ISCSendOptions memory sendOptions ) external payable; - // Call the entry point of an ISC contract on the same chain. + /** + * @notice 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 hash name 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 +122,99 @@ 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. + /** + * @notice Call a view entry point of an ISC contract on the same chain. + * @dev Calls the specified view entry point of the ISC contract with the given parameters. + * @param contractHname The hash name 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 + /** + * @notice 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 + /** + * @notice 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) + /** + * @notice 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 + /** + * @notice 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 + /** + * @notice 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 + /** + * @notice 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 + /** + * @notice 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 + /** + * @notice Get information about an on-chain IRC27 NFT + * @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 + // })) function getIRC27NFTData(NFTID id) external view returns (IRC27NFT memory); - // Get information about an on-chain IRC27 NFT + /** + * @notice Get the URI of an on-chain IRC27 NFT + * @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 +223,45 @@ interface ISCSandbox { // })) function getIRC27TokenURI(NFTID id) external view returns (string memory); - // Get the address of an ERC20NativeTokens contract for the given foundry serial number + /** + * @notice 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 + /** + * @notice 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 + /** + * @notice 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. + /** + * @notice 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, From 9370eee77a5a453db5f4256860d55e6020d3607e Mon Sep 17 00:00:00 2001 From: Gino Date: Wed, 3 Jul 2024 14:01:33 +0100 Subject: [PATCH 5/8] refactor(wiki): add docstrings to ISCTypes and ISCUtil interface functions --- packages/vm/core/evm/iscmagic/ISCTypes.sol | 42 ++++++++++++++++++++++ packages/vm/core/evm/iscmagic/ISCUtil.sol | 13 +++++-- 2 files changed, 53 insertions(+), 2 deletions(-) diff --git a/packages/vm/core/evm/iscmagic/ISCTypes.sol b/packages/vm/core/evm/iscmagic/ISCTypes.sol index 6792d0bfc0..c9e8aebc91 100644 --- a/packages/vm/core/evm/iscmagic/ISCTypes.sol +++ b/packages/vm/core/evm/iscmagic/ISCTypes.sol @@ -141,12 +141,23 @@ struct ISCTokenProperties { } library ISCTypes { + /** + * @dev Get the type of an L1 address. + * @param addr The L1 address. + * @return The type of the L1 address. + */ 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 +180,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 +203,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 +224,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 +238,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; } From adf2b1d9bb5510f3318336f25d2028aa747d783f Mon Sep 17 00:00:00 2001 From: Gino Date: Thu, 4 Jul 2024 21:42:29 +0100 Subject: [PATCH 6/8] remove the notice tag --- packages/vm/core/evm/iscmagic/ISCAccounts.sol | 9 ------- .../vm/core/evm/iscmagic/ISCPrivileged.sol | 4 --- packages/vm/core/evm/iscmagic/ISCSandbox.sol | 25 ------------------- 3 files changed, 38 deletions(-) diff --git a/packages/vm/core/evm/iscmagic/ISCAccounts.sol b/packages/vm/core/evm/iscmagic/ISCAccounts.sol index d7cc76c9e6..e6bd578306 100644 --- a/packages/vm/core/evm/iscmagic/ISCAccounts.sol +++ b/packages/vm/core/evm/iscmagic/ISCAccounts.sol @@ -11,7 +11,6 @@ import "./ISCTypes.sol"; */ interface ISCAccounts { /** - * @notice 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 @@ -19,7 +18,6 @@ interface ISCAccounts { function getL2BalanceBaseTokens(ISCAgentID memory agentID) external view returns (uint64); /** - * @notice 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 @@ -28,7 +26,6 @@ interface ISCAccounts { function getL2BalanceNativeTokens(NativeTokenID memory id, ISCAgentID memory agentID) external view returns (uint256); /** - * @notice Get the 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 NFTs are to be retrieved * @return An array of NFTIDs representing the NFTs owned by the specified account @@ -36,7 +33,6 @@ interface ISCAccounts { function getL2NFTs(ISCAgentID memory agentID) external view returns (NFTID[] memory); /** - * @notice Get the amount of L2 NFTs owned by an account * @dev This function retrieves the 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 @@ -44,7 +40,6 @@ interface ISCAccounts { function getL2NFTAmount(ISCAgentID memory agentID) external view returns (uint256); /** - * @notice 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 @@ -53,7 +48,6 @@ interface ISCAccounts { function getL2NFTsInCollection(ISCAgentID memory agentID, NFTID collectionId) external view returns (NFTID[] memory); /** - * @notice 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 @@ -62,7 +56,6 @@ interface ISCAccounts { function getL2NFTAmountInCollection(ISCAgentID memory agentID, NFTID collectionId) external view returns (uint256); /** - * @notice 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 @@ -71,7 +64,6 @@ interface ISCAccounts { function foundryCreateNew(NativeTokenScheme memory tokenScheme, ISCAssets memory allowance) external returns(uint32); /** - * @notice 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 @@ -83,7 +75,6 @@ interface ISCAccounts { function createNativeTokenFoundry(string memory tokenName, string memory tokenSymbol, uint8 tokenDecimals, NativeTokenScheme memory tokenScheme, ISCAssets memory allowance) external returns(uint32); /** - * @notice 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 diff --git a/packages/vm/core/evm/iscmagic/ISCPrivileged.sol b/packages/vm/core/evm/iscmagic/ISCPrivileged.sol index 81a67685a6..fa2dbfe25a 100644 --- a/packages/vm/core/evm/iscmagic/ISCPrivileged.sol +++ b/packages/vm/core/evm/iscmagic/ISCPrivileged.sol @@ -12,7 +12,6 @@ import "./ISCTypes.sol"; */ interface ISCPrivileged { /** - * @notice Move assets between accounts * @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 @@ -25,7 +24,6 @@ interface ISCPrivileged { ) external; /** - * @notice Set allowance of base tokens * @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 @@ -38,7 +36,6 @@ interface ISCPrivileged { ) external; /** - * @notice Set allowance of native tokens * @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 @@ -53,7 +50,6 @@ interface ISCPrivileged { ) external; /** - * @notice Move allowed funds between accounts * @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 diff --git a/packages/vm/core/evm/iscmagic/ISCSandbox.sol b/packages/vm/core/evm/iscmagic/ISCSandbox.sol index c5156c8603..e78b919d51 100644 --- a/packages/vm/core/evm/iscmagic/ISCSandbox.sol +++ b/packages/vm/core/evm/iscmagic/ISCSandbox.sol @@ -11,35 +11,30 @@ import "./ISCTypes.sol"; */ interface ISCSandbox { /** - * @notice 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); /** - * @notice 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); /** - * @notice 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; /** - * @notice 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); /** - * @notice 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. @@ -47,7 +42,6 @@ interface ISCSandbox { function allow(address target, ISCAssets memory allowance) external; /** - * @notice Take some funds from the given address, which must have authorized first with `allow`. * @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. @@ -58,7 +52,6 @@ interface ISCSandbox { ) external; /** - * @notice 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. @@ -68,7 +61,6 @@ interface ISCSandbox { ) external view returns (ISCAssets memory); /** - * @notice 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. @@ -78,7 +70,6 @@ interface ISCSandbox { ) external view returns (ISCAssets memory); /** - * @notice 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. @@ -90,7 +81,6 @@ interface ISCSandbox { ) external view returns (ISCAssets memory); /** - * @notice Send an on-ledger request (or a regular transaction to any L1 address). * @dev Sends the specified assets from the caller's L2 account to the EVM core contract's account and includes the specified metadata and options. * @param targetAddress The L1 address to send the assets to. * @param assets The assets to be sent. @@ -107,7 +97,6 @@ interface ISCSandbox { ) external payable; /** - * @notice 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 hash name of the contract. * @param entryPoint The entry point to be called. @@ -123,7 +112,6 @@ interface ISCSandbox { ) external returns (ISCDict memory); /** - * @notice Call a view entry point of an ISC contract on the same chain. * @dev Calls the specified view entry point of the ISC contract with the given parameters. * @param contractHname The hash name of the contract. * @param entryPoint The view entry point to be called. @@ -137,28 +125,24 @@ interface ISCSandbox { ) external view returns (ISCDict memory); /** - * @notice 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); /** - * @notice 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); /** - * @notice 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); /** - * @notice 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. */ @@ -168,7 +152,6 @@ interface ISCSandbox { returns (ISCTokenProperties memory); /** - * @notice 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. @@ -178,7 +161,6 @@ interface ISCSandbox { ) external view returns (NativeTokenID memory); /** - * @notice 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. @@ -188,7 +170,6 @@ interface ISCSandbox { ) external view returns (NativeTokenScheme memory); /** - * @notice 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. @@ -196,7 +177,6 @@ interface ISCSandbox { function getNFTData(NFTID id) external view returns (ISCNFT memory); /** - * @notice Get information about an on-chain IRC27 NFT * @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. @@ -210,7 +190,6 @@ interface ISCSandbox { function getIRC27NFTData(NFTID id) external view returns (IRC27NFT memory); /** - * @notice Get the URI of an on-chain IRC27 NFT * @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. @@ -224,7 +203,6 @@ interface ISCSandbox { function getIRC27TokenURI(NFTID id) external view returns (string memory); /** - * @notice 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. @@ -234,7 +212,6 @@ interface ISCSandbox { ) external view returns (address); /** - * @notice 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. @@ -244,7 +221,6 @@ interface ISCSandbox { ) external view returns (address); /** - * @notice 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. @@ -254,7 +230,6 @@ interface ISCSandbox { ) external view returns (uint32); /** - * @notice 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. From 6c424e176e5728df0c43528188de1f256b63422b Mon Sep 17 00:00:00 2001 From: Gino Date: Wed, 17 Jul 2024 20:12:53 +0100 Subject: [PATCH 7/8] fix: resolve conflict --- packages/vm/core/evm/iscmagic/ISCSandbox.sol | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/packages/vm/core/evm/iscmagic/ISCSandbox.sol b/packages/vm/core/evm/iscmagic/ISCSandbox.sol index e78b919d51..94ddcd8e6b 100644 --- a/packages/vm/core/evm/iscmagic/ISCSandbox.sol +++ b/packages/vm/core/evm/iscmagic/ISCSandbox.sol @@ -180,13 +180,18 @@ interface ISCSandbox { * @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. */ - // Note: the metadata.uri field is encoded as a data URL with: - // base64(jsonEncode({ - // "name": NFT.name, - // "description": NFT.description, - // "image": NFT.URI - // })) + function getIRC27NFTData(NFTID id) external view returns (IRC27NFT memory); + function getIRC27NFTData(NFTID id) external view returns (IRC27NFT memory); /** From 9307c855ba42a631bf4441870cdf14761a025eb9 Mon Sep 17 00:00:00 2001 From: Gino Date: Wed, 24 Jul 2024 03:28:06 +0100 Subject: [PATCH 8/8] fix(docs): implement review suggestions --- packages/vm/core/evm/iscmagic/ISCAccounts.sol | 4 ++-- packages/vm/core/evm/iscmagic/ISCSandbox.sol | 6 +++--- packages/vm/core/evm/iscmagic/ISCTypes.sol | 3 +++ 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/packages/vm/core/evm/iscmagic/ISCAccounts.sol b/packages/vm/core/evm/iscmagic/ISCAccounts.sol index e6bd578306..6514ec1981 100644 --- a/packages/vm/core/evm/iscmagic/ISCAccounts.sol +++ b/packages/vm/core/evm/iscmagic/ISCAccounts.sol @@ -26,14 +26,14 @@ interface ISCAccounts { function getL2BalanceNativeTokens(NativeTokenID memory id, ISCAgentID memory agentID) external view returns (uint256); /** - * @dev This function retrieves the number of NFTs owned by a given 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); /** - * @dev This function retrieves the NFTs owned by a given 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 */ diff --git a/packages/vm/core/evm/iscmagic/ISCSandbox.sol b/packages/vm/core/evm/iscmagic/ISCSandbox.sol index 94ddcd8e6b..1377effdd9 100644 --- a/packages/vm/core/evm/iscmagic/ISCSandbox.sol +++ b/packages/vm/core/evm/iscmagic/ISCSandbox.sol @@ -81,7 +81,7 @@ interface ISCSandbox { ) external view returns (ISCAssets memory); /** - * @dev Sends the specified assets from the caller's L2 account to the EVM core contract's account and includes the specified metadata and options. + * @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. @@ -98,7 +98,7 @@ interface ISCSandbox { /** * @dev Calls the specified entry point of the ISC contract with the given parameters and allowance. - * @param contractHname The hash name of the contract. + * @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. @@ -113,7 +113,7 @@ interface ISCSandbox { /** * @dev Calls the specified view entry point of the ISC contract with the given parameters. - * @param contractHname The hash name of the contract. + * @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. diff --git a/packages/vm/core/evm/iscmagic/ISCTypes.sol b/packages/vm/core/evm/iscmagic/ISCTypes.sol index c9e8aebc91..b44c8cdadf 100644 --- a/packages/vm/core/evm/iscmagic/ISCTypes.sol +++ b/packages/vm/core/evm/iscmagic/ISCTypes.sol @@ -145,6 +145,9 @@ 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