diff --git a/.github/workflows/codecov.yaml b/.github/workflows/codecov.yaml index e5a7dd9a..0b1f67fd 100644 --- a/.github/workflows/codecov.yaml +++ b/.github/workflows/codecov.yaml @@ -2,6 +2,10 @@ name: Code Coverage on: pull_request: + push: + branches: + - main + - releases/** concurrency: group: ${{ github.workflow }}-${{ github.ref }} diff --git a/contracts/InterchainTokenFactory.sol b/contracts/InterchainTokenFactory.sol index 19c7a548..f3be98d3 100644 --- a/contracts/InterchainTokenFactory.sol +++ b/contracts/InterchainTokenFactory.sol @@ -10,6 +10,7 @@ import { IInterchainTokenFactory } from './interfaces/IInterchainTokenFactory.so import { ITokenManagerType } from './interfaces/ITokenManagerType.sol'; import { ITokenManager } from './interfaces/ITokenManager.sol'; import { IInterchainToken } from './interfaces/IInterchainToken.sol'; +import { IERC20Named } from './interfaces/IERC20Named.sol'; /** * @title InterchainTokenFactory @@ -66,24 +67,22 @@ contract InterchainTokenFactory is IInterchainTokenFactory, ITokenManagerType, M } /** - * @notice Calculates the salt for an interchain token. - * @param chainNameHash_ The hash of the chain name. + * @notice Computes the deploy salt for an interchain token. * @param deployer The address of the deployer. * @param salt A unique identifier to generate the salt. - * @return tokenSalt The calculated salt for the interchain token. + * @return deploySalt The deploy salt for the interchain token. */ - function interchainTokenSalt(bytes32 chainNameHash_, address deployer, bytes32 salt) public pure returns (bytes32 tokenSalt) { - tokenSalt = keccak256(abi.encode(PREFIX_INTERCHAIN_TOKEN_SALT, chainNameHash_, deployer, salt)); + function interchainTokenDeploySalt(address deployer, bytes32 salt) public view returns (bytes32 deploySalt) { + deploySalt = keccak256(abi.encode(PREFIX_INTERCHAIN_TOKEN_SALT, chainNameHash, deployer, salt)); } /** - * @notice Calculates the salt for a canonical interchain token. - * @param chainNameHash_ The hash of the chain name. + * @notice Computes the deploy salt for a canonical interchain token. * @param tokenAddress The address of the token. - * @return salt The calculated salt for the interchain token. + * @return deploySalt The deploy salt for the interchain token. */ - function canonicalInterchainTokenSalt(bytes32 chainNameHash_, address tokenAddress) public pure returns (bytes32 salt) { - salt = keccak256(abi.encode(PREFIX_CANONICAL_TOKEN_SALT, chainNameHash_, tokenAddress)); + function canonicalInterchainTokenDeploySalt(address tokenAddress) public view returns (bytes32 deploySalt) { + deploySalt = keccak256(abi.encode(PREFIX_CANONICAL_TOKEN_SALT, chainNameHash, tokenAddress)); } /** @@ -93,7 +92,8 @@ contract InterchainTokenFactory is IInterchainTokenFactory, ITokenManagerType, M * @return tokenId The ID of the interchain token. */ function interchainTokenId(address deployer, bytes32 salt) public view returns (bytes32 tokenId) { - tokenId = interchainTokenService.interchainTokenId(TOKEN_FACTORY_DEPLOYER, interchainTokenSalt(chainNameHash, deployer, salt)); + bytes32 deploySalt = interchainTokenDeploySalt(deployer, salt); + tokenId = _interchainTokenId(deploySalt); } /** @@ -102,20 +102,17 @@ contract InterchainTokenFactory is IInterchainTokenFactory, ITokenManagerType, M * @return tokenId The ID of the canonical interchain token. */ function canonicalInterchainTokenId(address tokenAddress) public view returns (bytes32 tokenId) { - tokenId = interchainTokenService.interchainTokenId( - TOKEN_FACTORY_DEPLOYER, - canonicalInterchainTokenSalt(chainNameHash, tokenAddress) - ); + bytes32 deploySalt = canonicalInterchainTokenDeploySalt(tokenAddress); + tokenId = _interchainTokenId(deploySalt); } /** - * @notice Retrieves the address of an interchain token based on the deployer and a salt. - * @param deployer The address that deployed the interchain token. - * @param salt A unique identifier used in the deployment process. - * @return tokenAddress The address of the interchain token. + * @notice Computes the tokenId for an interchain token based on the deploySalt. + * @param deploySalt The salt used for the deployment. + * @return tokenId The tokenId of the interchain token. */ - function interchainTokenAddress(address deployer, bytes32 salt) public view returns (address tokenAddress) { - tokenAddress = interchainTokenService.interchainTokenAddress(interchainTokenId(deployer, salt)); + function _interchainTokenId(bytes32 deploySalt) internal view returns (bytes32 tokenId) { + tokenId = interchainTokenService.interchainTokenId(TOKEN_FACTORY_DEPLOYER, deploySalt); } /** @@ -141,8 +138,10 @@ contract InterchainTokenFactory is IInterchainTokenFactory, ITokenManagerType, M address minter ) external payable returns (bytes32 tokenId) { address sender = msg.sender; - salt = interchainTokenSalt(chainNameHash, sender, salt); + bytes32 deploySalt = interchainTokenDeploySalt(sender, salt); bytes memory minterBytes = new bytes(0); + string memory currentChain = ''; + uint256 gasValue = 0; if (initialSupply > 0) { minterBytes = address(this).toBytes(); @@ -152,11 +151,11 @@ contract InterchainTokenFactory is IInterchainTokenFactory, ITokenManagerType, M minterBytes = minter.toBytes(); } - tokenId = _deployInterchainToken(salt, '', name, symbol, decimals, minterBytes, 0); + tokenId = _deployInterchainToken(deploySalt, currentChain, name, symbol, decimals, minterBytes, gasValue); if (initialSupply > 0) { - IInterchainToken token = IInterchainToken(interchainTokenService.interchainTokenAddress(tokenId)); - ITokenManager tokenManager = ITokenManager(interchainTokenService.tokenManagerAddress(tokenId)); + IInterchainToken token = IInterchainToken(interchainTokenService.registeredTokenAddress(tokenId)); + ITokenManager tokenManager = ITokenManager(interchainTokenService.deployedTokenManager(tokenId)); token.mint(sender, initialSupply); @@ -173,6 +172,11 @@ contract InterchainTokenFactory is IInterchainTokenFactory, ITokenManagerType, M /** * @notice Allow the minter to approve the deployer for a remote interchain token deployment that uses a custom destinationMinter address. * This ensures that a token deployer can't choose the destinationMinter itself, and requires the approval of the minter to reduce trust assumptions on the deployer. + * @param deployer The address of the deployer. + * @param salt The unique salt for deploying the token. + * @param destinationChain The name of the destination chain. + * @param destinationMinter The minter address to set on the deployed token on the destination chain. This can be arbitrary bytes + * since the encoding of the account is dependent on the destination chain. */ function approveDeployRemoteInterchainToken( address deployer, @@ -182,8 +186,8 @@ contract InterchainTokenFactory is IInterchainTokenFactory, ITokenManagerType, M ) external { address minter = msg.sender; bytes32 tokenId = interchainTokenId(deployer, salt); - IInterchainToken token = IInterchainToken(interchainTokenService.interchainTokenAddress(tokenId)); - if (!token.isMinter(minter)) revert InvalidMinter(minter); + + _checkTokenMinter(tokenId, minter); if (bytes(interchainTokenService.trustedAddress(destinationChain)).length == 0) revert InvalidChainName(); @@ -196,6 +200,9 @@ contract InterchainTokenFactory is IInterchainTokenFactory, ITokenManagerType, M /** * @notice Allows the minter to revoke a deployer's approval for a remote interchain token deployment that uses a custom destinationMinter address. + * @param deployer The address of the deployer. + * @param salt The unique salt for deploying the token. + * @param destinationChain The name of the destination chain. */ function revokeDeployRemoteInterchainToken(address deployer, bytes32 salt, string calldata destinationChain) external { address minter = msg.sender; @@ -208,10 +215,16 @@ contract InterchainTokenFactory is IInterchainTokenFactory, ITokenManagerType, M emit RevokedDeployRemoteInterchainTokenApproval(minter, deployer, tokenId, destinationChain); } + /** + * @dev Compute the key for the deploy approval mapping. + */ function _deployApprovalKey(DeployApproval memory approval) internal pure returns (bytes32 key) { key = keccak256(abi.encode(PREFIX_DEPLOY_APPROVAL, approval)); } + /** + * @dev Use the deploy approval to check that the destination minter is valid and then delete the approval. + */ function _useDeployApproval(DeployApproval memory approval, bytes memory destinationMinter) internal { bytes32 approvalKey = _deployApprovalKey(approval); @@ -259,38 +272,28 @@ contract InterchainTokenFactory is IInterchainTokenFactory, ITokenManagerType, M bytes memory destinationMinter, uint256 gasValue ) public payable returns (bytes32 tokenId) { - string memory tokenName; - string memory tokenSymbol; - uint8 tokenDecimals; - bytes memory minter_ = new bytes(0); - - salt = interchainTokenSalt(chainNameHash, msg.sender, salt); - tokenId = interchainTokenService.interchainTokenId(TOKEN_FACTORY_DEPLOYER, salt); - - IInterchainToken token = IInterchainToken(interchainTokenService.interchainTokenAddress(tokenId)); - - tokenName = token.name(); - tokenSymbol = token.symbol(); - tokenDecimals = token.decimals(); + bytes32 deploySalt = interchainTokenDeploySalt(msg.sender, salt); if (minter != address(0)) { - if (!token.isMinter(minter)) revert NotMinter(minter); - // Sanity check to prevent accidental use of the current ITS address as the destination minter - if (minter == address(interchainTokenService)) revert InvalidMinter(minter); + bytes32 deployedTokenId = _interchainTokenId(deploySalt); + _checkTokenMinter(deployedTokenId, minter); if (destinationMinter.length > 0) { - DeployApproval memory approval = DeployApproval({ minter: minter, tokenId: tokenId, destinationChain: destinationChain }); + DeployApproval memory approval = DeployApproval({ + minter: minter, + tokenId: deployedTokenId, + destinationChain: destinationChain + }); _useDeployApproval(approval, destinationMinter); - minter_ = destinationMinter; } else { - minter_ = minter.toBytes(); + destinationMinter = minter.toBytes(); } } else if (destinationMinter.length > 0) { // If a destinationMinter is provided, then minter must not be address(0) revert InvalidMinter(minter); } - tokenId = _deployInterchainToken(salt, destinationChain, tokenName, tokenSymbol, tokenDecimals, minter_, gasValue); + tokenId = _deployRemoteInterchainToken(deploySalt, destinationChain, destinationMinter, gasValue); } /** @@ -318,6 +321,20 @@ contract InterchainTokenFactory is IInterchainTokenFactory, ITokenManagerType, M tokenId = deployRemoteInterchainTokenWithMinter(salt, minter, destinationChain, new bytes(0), gasValue); } + /** + * @notice Checks that the minter is registered for the token on the current chain and not the ITS address. + * @param tokenId The unique identifier for the token. The token must be an interchain token deployed via ITS. + * @param minter The address to be checked as a minter for the interchain token. + */ + function _checkTokenMinter(bytes32 tokenId, address minter) internal view { + // Ensure that the minter is registered for the token on the current chain + IInterchainToken token = IInterchainToken(interchainTokenService.registeredTokenAddress(tokenId)); + if (!token.isMinter(minter)) revert NotMinter(minter); + + // Sanity check to prevent accidental use of the current ITS address as the token minter + if (minter == address(interchainTokenService)) revert InvalidMinter(minter); + } + /** * @notice Deploys a new interchain token with specified parameters. * @param salt The unique salt for deploying the token. @@ -350,6 +367,29 @@ contract InterchainTokenFactory is IInterchainTokenFactory, ITokenManagerType, M ); } + /** + * @notice Deploys a remote interchain token on a specified destination chain. + * @param deploySalt The salt used for the deployment. + * @param destinationChain The name of the destination chain. + * @param minter The address to receive the minter and operator role of the token, in addition to ITS. + * @param gasValue The amount of gas to send for the deployment. + * @return tokenId The tokenId corresponding to the deployed InterchainToken. + */ + function _deployRemoteInterchainToken( + bytes32 deploySalt, + string memory destinationChain, + bytes memory minter, + uint256 gasValue + ) internal returns (bytes32 tokenId) { + bytes32 expectedTokenId = _interchainTokenId(deploySalt); + // Ensure that a local token has been registered for the tokenId + IERC20Named token = IERC20Named(interchainTokenService.registeredTokenAddress(expectedTokenId)); + + // The local token must expose the name, symbol, and decimals metadata + tokenId = _deployInterchainToken(deploySalt, destinationChain, token.name(), token.symbol(), token.decimals(), minter, gasValue); + if (tokenId != expectedTokenId) revert InvalidTokenId(tokenId, expectedTokenId); + } + /** * @notice Registers a canonical token as an interchain token and deploys its token manager. * @dev This function is `payable` because non-payable functions cannot be called in a multicall that calls other `payable` functions. @@ -358,9 +398,11 @@ contract InterchainTokenFactory is IInterchainTokenFactory, ITokenManagerType, M */ function registerCanonicalInterchainToken(address tokenAddress) external payable returns (bytes32 tokenId) { bytes memory params = abi.encode('', tokenAddress); - bytes32 salt = canonicalInterchainTokenSalt(chainNameHash, tokenAddress); + bytes32 deploySalt = canonicalInterchainTokenDeploySalt(tokenAddress); + string memory currentChain = ''; + uint256 gasValue = 0; - tokenId = interchainTokenService.deployTokenManager(salt, '', TokenManagerType.LOCK_UNLOCK, params, 0); + tokenId = interchainTokenService.deployTokenManager(deploySalt, currentChain, TokenManagerType.LOCK_UNLOCK, params, gasValue); } /** @@ -375,21 +417,11 @@ contract InterchainTokenFactory is IInterchainTokenFactory, ITokenManagerType, M string calldata destinationChain, uint256 gasValue ) public payable returns (bytes32 tokenId) { - bytes32 salt; - IInterchainToken token; - - // This ensures that the token manager has been deployed by this address, so it's safe to trust it. - salt = canonicalInterchainTokenSalt(chainNameHash, originalTokenAddress); - tokenId = interchainTokenService.interchainTokenId(TOKEN_FACTORY_DEPLOYER, salt); - token = IInterchainToken(interchainTokenService.registeredTokenAddress(tokenId)); - - // The 3 lines below will revert if the token does not exist. - string memory tokenName = token.name(); - string memory tokenSymbol = token.symbol(); - uint8 tokenDecimals = token.decimals(); - bytes memory minter = ''; // No additional minter is set on a canonical token deployment + // No additional minter is set on a canonical token deployment + bytes memory minter = ''; + bytes32 deploySalt = canonicalInterchainTokenDeploySalt(originalTokenAddress); - tokenId = _deployInterchainToken(salt, destinationChain, tokenName, tokenSymbol, tokenDecimals, minter, gasValue); + tokenId = _deployRemoteInterchainToken(deploySalt, destinationChain, minter, gasValue); } /** diff --git a/contracts/interfaces/IInterchainTokenFactory.sol b/contracts/interfaces/IInterchainTokenFactory.sol index 4ea56324..e425ecbf 100644 --- a/contracts/interfaces/IInterchainTokenFactory.sol +++ b/contracts/interfaces/IInterchainTokenFactory.sol @@ -20,6 +20,7 @@ interface IInterchainTokenFactory is IUpgradable, IMulticall { error NotServiceOwner(address sender); error NotSupported(); error RemoteDeploymentNotApproved(); + error InvalidTokenId(bytes32 tokenId, bytes32 expectedTokenId); /// @notice Emitted when a minter approves a deployer for a remote interchain token deployment that uses a custom destinationMinter address. event DeployRemoteInterchainTokenApproval( @@ -51,13 +52,12 @@ interface IInterchainTokenFactory is IUpgradable, IMulticall { function chainNameHash() external view returns (bytes32); /** - * @notice Calculates the salt for an interchain token. - * @param chainNameHash_ The hash of the chain name. + * @notice Computes the deploy salt for an interchain token. * @param deployer The address of the deployer. * @param salt A unique identifier to generate the salt. - * @return tokenSalt The calculated salt for the interchain token. + * @return deploySalt The deploy salt for the interchain token. */ - function interchainTokenSalt(bytes32 chainNameHash_, address deployer, bytes32 salt) external view returns (bytes32 tokenSalt); + function interchainTokenDeploySalt(address deployer, bytes32 salt) external view returns (bytes32 deploySalt); /** * @notice Computes the ID for an interchain token based on the deployer and a salt. @@ -67,14 +67,6 @@ interface IInterchainTokenFactory is IUpgradable, IMulticall { */ function interchainTokenId(address deployer, bytes32 salt) external view returns (bytes32 tokenId); - /** - * @notice Retrieves the address of an interchain token based on the deployer and a salt. - * @param deployer The address that deployed the interchain token. - * @param salt A unique identifier used in the deployment process. - * @return tokenAddress The address of the interchain token. - */ - function interchainTokenAddress(address deployer, bytes32 salt) external view returns (address tokenAddress); - /** * @notice Deploys a new interchain token with specified parameters. * @param salt The unique salt for deploying the token. @@ -95,8 +87,13 @@ interface IInterchainTokenFactory is IUpgradable, IMulticall { ) external payable returns (bytes32 tokenId); /** - * @notice Allows the minter to approve a deployer for a remote interchain token deployment that uses a custom destinationMinter address. + * @notice Allow the minter to approve the deployer for a remote interchain token deployment that uses a custom destinationMinter address. * This ensures that a token deployer can't choose the destinationMinter itself, and requires the approval of the minter to reduce trust assumptions on the deployer. + * @param deployer The address of the deployer. + * @param salt The unique salt for deploying the token. + * @param destinationChain The name of the destination chain. + * @param destinationMinter The minter address to set on the deployed token on the destination chain. This can be arbitrary bytes + * since the encoding of the account is dependent on the destination chain. */ function approveDeployRemoteInterchainToken( address deployer, @@ -107,6 +104,9 @@ interface IInterchainTokenFactory is IUpgradable, IMulticall { /** * @notice Allows the minter to revoke a deployer's approval for a remote interchain token deployment that uses a custom destinationMinter address. + * @param deployer The address of the deployer. + * @param salt The unique salt for deploying the token. + * @param destinationChain The name of the destination chain. */ function revokeDeployRemoteInterchainToken(address deployer, bytes32 salt, string calldata destinationChain) external; @@ -165,12 +165,11 @@ interface IInterchainTokenFactory is IUpgradable, IMulticall { ) external payable returns (bytes32 tokenId); /** - * @notice Calculates the salt for a canonical interchain token. - * @param chainNameHash_ The hash of the chain name. + * @notice Computes the deploy salt for a canonical interchain token. * @param tokenAddress The address of the token. - * @return tokenSalt The calculated salt for the interchain token. + * @return deploySalt The deploy salt for the interchain token. */ - function canonicalInterchainTokenSalt(bytes32 chainNameHash_, address tokenAddress) external view returns (bytes32 tokenSalt); + function canonicalInterchainTokenDeploySalt(address tokenAddress) external view returns (bytes32 deploySalt); /** * @notice Computes the ID for a canonical interchain token based on its address. @@ -201,13 +200,14 @@ interface IInterchainTokenFactory is IUpgradable, IMulticall { /** * @notice Deploys a canonical interchain token on a remote chain. + * This method is deprecated and will be removed in the future. Please use the above method instead. * @dev originalChain is only allowed to be '', i.e the current chain. * Other source chains are not supported anymore to simplify ITS token deployment behaviour. * @param originalChain The name of the chain where the token originally exists. * @param originalTokenAddress The address of the original token on the original chain. * @param destinationChain The name of the chain where the token will be deployed. * @param gasValue The gas amount to be sent for deployment. - * @return tokenId The tokenId corresponding to the deployed canonical InterchainToken. + * @return tokenId The tokenId corresponding to the deployed InterchainToken. */ function deployRemoteCanonicalInterchainToken( string calldata originalChain, diff --git a/docs/index.md b/docs/index.md index e44214fb..f830591c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,6 +4,33 @@ This contract is responsible for deploying new interchain tokens and managing their token managers. +### INTERCHAIN_TOKEN_FACTORY_SLOT + +```solidity +bytes32 INTERCHAIN_TOKEN_FACTORY_SLOT +``` + +_This slot contains the storage for this contract in an upgrade-compatible manner +keccak256('InterchainTokenFactory.Slot') - 1;_ + +### PREFIX_CANONICAL_TOKEN_SALT + +```solidity +bytes32 PREFIX_CANONICAL_TOKEN_SALT +``` + +### PREFIX_INTERCHAIN_TOKEN_SALT + +```solidity +bytes32 PREFIX_INTERCHAIN_TOKEN_SALT +``` + +### PREFIX_DEPLOY_APPROVAL + +```solidity +bytes32 PREFIX_DEPLOY_APPROVAL +``` + ### interchainTokenService ```solidity @@ -30,22 +57,29 @@ Returns the hash of the chain name. | Name | Type | Description | | ---- | ---- | ----------- | -### gateway +### DeployApproval ```solidity -contract IAxelarGateway gateway +struct DeployApproval { + address minter; + bytes32 tokenId; + string destinationChain; +} ``` -### PREFIX_CANONICAL_TOKEN_SALT +### InterchainTokenFactoryStorage -```solidity -bytes32 PREFIX_CANONICAL_TOKEN_SALT -``` +_Storage for this contract_ -### PREFIX_INTERCHAIN_TOKEN_SALT +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | ```solidity -bytes32 PREFIX_INTERCHAIN_TOKEN_SALT +struct InterchainTokenFactoryStorage { + mapping(bytes32 => bytes32) approvedDestinationMinters; +} ``` ### constructor @@ -58,9 +92,25 @@ Constructs the InterchainTokenFactory contract. #### Parameters -| Name | Type | Description | -| ------------------------ | ------- | -------------------------------------------- | -| interchainTokenService\_ | address | The address of the interchain token service. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| interchainTokenService_ | address | The address of the interchain token service. | + +### _setup + +```solidity +function _setup(bytes data) internal +``` + +Internal function to set up the contract with initial data + +_This function should be implemented in derived contracts._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| data | bytes | Initialization data for the contract | ### contractId @@ -72,52 +122,50 @@ Getter for the contract id. #### Return Values -| Name | Type | Description | -| ---- | ------- | ----------------------------------------- | -| [0] | bytes32 | bytes32 The contract id of this contract. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 The contract id of this contract. | -### interchainTokenSalt +### interchainTokenDeploySalt ```solidity -function interchainTokenSalt(bytes32 chainNameHash_, address deployer, bytes32 salt) public pure returns (bytes32) +function interchainTokenDeploySalt(address deployer, bytes32 salt) public view returns (bytes32 deploySalt) ``` -Calculates the salt for an interchain token. +Computes the deploy salt for an interchain token. #### Parameters -| Name | Type | Description | -| --------------- | ------- | ----------------------------------------- | -| chainNameHash\_ | bytes32 | The hash of the chain name. | -| deployer | address | The address of the deployer. | -| salt | bytes32 | A unique identifier to generate the salt. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| deployer | address | The address of the deployer. | +| salt | bytes32 | A unique identifier to generate the salt. | #### Return Values -| Name | Type | Description | -| ---- | ------- | ----------------------------------------------------- | -| [0] | bytes32 | bytes32 The calculated salt for the interchain token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| deploySalt | bytes32 | The deploy salt for the interchain token. | -### canonicalInterchainTokenSalt +### canonicalInterchainTokenDeploySalt ```solidity -function canonicalInterchainTokenSalt(bytes32 chainNameHash_, address tokenAddress) public pure returns (bytes32 salt) +function canonicalInterchainTokenDeploySalt(address tokenAddress) public view returns (bytes32 deploySalt) ``` -Calculates the salt for a canonical interchain token. +Computes the deploy salt for a canonical interchain token. #### Parameters -| Name | Type | Description | -| --------------- | ------- | --------------------------- | -| chainNameHash\_ | bytes32 | The hash of the chain name. | -| tokenAddress | address | The address of the token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress | address | The address of the token. | #### Return Values -| Name | Type | Description | -| ---- | ------- | --------------------------------------------- | -| salt | bytes32 | The calculated salt for the interchain token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| deploySalt | bytes32 | The deploy salt for the interchain token. | ### interchainTokenId @@ -129,15 +177,15 @@ Computes the ID for an interchain token based on the deployer and a salt. #### Parameters -| Name | Type | Description | -| -------- | ------- | --------------------------------------------------- | -| deployer | address | The address that deployed the interchain token. | -| salt | bytes32 | A unique identifier used in the deployment process. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| deployer | address | The address that deployed the interchain token. | +| salt | bytes32 | A unique identifier used in the deployment process. | #### Return Values -| Name | Type | Description | -| ------- | ------- | ------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | tokenId | bytes32 | The ID of the interchain token. | ### canonicalInterchainTokenId @@ -150,36 +198,35 @@ Computes the ID for a canonical interchain token based on its address. #### Parameters -| Name | Type | Description | -| ------------ | ------- | ---------------------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | tokenAddress | address | The address of the canonical interchain token. | #### Return Values -| Name | Type | Description | -| ------- | ------- | ----------------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | tokenId | bytes32 | The ID of the canonical interchain token. | -### interchainTokenAddress +### _interchainTokenId ```solidity -function interchainTokenAddress(address deployer, bytes32 salt) public view returns (address tokenAddress) +function _interchainTokenId(bytes32 deploySalt) internal view returns (bytes32 tokenId) ``` -Retrieves the address of an interchain token based on the deployer and a salt. +Computes the tokenId for an interchain token based on the deploySalt. #### Parameters -| Name | Type | Description | -| -------- | ------- | --------------------------------------------------- | -| deployer | address | The address that deployed the interchain token. | -| salt | bytes32 | A unique identifier used in the deployment process. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| deploySalt | bytes32 | The salt used for the deployment. | #### Return Values -| Name | Type | Description | -| ------------ | ------- | ------------------------------------ | -| tokenAddress | address | The address of the interchain token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the interchain token. | ### deployInterchainToken @@ -189,3580 +236,4107 @@ function deployInterchainToken(bytes32 salt, string name, string symbol, uint8 d Deploys a new interchain token with specified parameters. -_Creates a new token and optionally mints an initial amount to a specified minter._ +_Creates a new token and optionally mints an initial amount to a specified minter. +This function is `payable` because non-payable functions cannot be called in a multicall that calls other `payable` functions._ #### Parameters -| Name | Type | Description | -| ------------- | ------- | ----------------------------------------------------- | -| salt | bytes32 | The unique salt for deploying the token. | -| name | string | The name of the token. | -| symbol | string | The symbol of the token. | -| decimals | uint8 | The number of decimals for the token. | -| initialSupply | uint256 | The amount of tokens to mint initially (can be zero). | -| minter | address | The address to receive the initially minted tokens. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| salt | bytes32 | The unique salt for deploying the token. | +| name | string | The name of the token. | +| symbol | string | The symbol of the token. | +| decimals | uint8 | The number of decimals for the token. | +| initialSupply | uint256 | The amount of tokens to mint initially (can be zero), allocated to the msg.sender. | +| minter | address | The address to receive the minter and operator role of the token, in addition to ITS. If it is set to `address(0)`, the additional minter isn't set, and can't be added later. This allows creating tokens that are managed only by ITS, reducing trust assumptions. Reverts if the minter is the ITS address since it's already added as a minter. | #### Return Values -| Name | Type | Description | -| ------- | ------- | ---------------------------------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | +### approveDeployRemoteInterchainToken + +```solidity +function approveDeployRemoteInterchainToken(address deployer, bytes32 salt, string destinationChain, bytes destinationMinter) external +``` + +Allow the minter to approve the deployer for a remote interchain token deployment that uses a custom destinationMinter address. +This ensures that a token deployer can't choose the destinationMinter itself, and requires the approval of the minter to reduce trust assumptions on the deployer. + +### revokeDeployRemoteInterchainToken + +```solidity +function revokeDeployRemoteInterchainToken(address deployer, bytes32 salt, string destinationChain) external +``` + +Allows the minter to revoke a deployer's approval for a remote interchain token deployment that uses a custom destinationMinter address. + +### _deployApprovalKey + +```solidity +function _deployApprovalKey(struct InterchainTokenFactory.DeployApproval approval) internal pure returns (bytes32 key) +``` + +### _useDeployApproval + +```solidity +function _useDeployApproval(struct InterchainTokenFactory.DeployApproval approval, bytes destinationMinter) internal +``` + ### deployRemoteInterchainToken ```solidity -function deployRemoteInterchainToken(string originalChainName, bytes32 salt, address minter, string destinationChain, uint256 gasValue) external payable returns (bytes32 tokenId) +function deployRemoteInterchainToken(bytes32 salt, address minter, string destinationChain, uint256 gasValue) external payable returns (bytes32 tokenId) ``` Deploys a remote interchain token on a specified destination chain. #### Parameters -| Name | Type | Description | -| ----------------- | ------- | ------------------------------------------------------------- | -| originalChainName | string | The name of the chain where the token originally exists. | -| salt | bytes32 | The unique salt for deploying the token. | -| minter | address | The address to distribute the token on the destination chain. | -| destinationChain | string | The name of the destination chain. | -| gasValue | uint256 | The amount of gas to send for the deployment. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| salt | bytes32 | The unique salt for deploying the token. | +| minter | address | The address to use as the minter of the deployed token on the destination chain. If the destination chain is not EVM, then use the more generic `deployRemoteInterchainToken` function below that allows setting an arbitrary destination minter that was approved by the current minter. | +| destinationChain | string | The name of the destination chain. | +| gasValue | uint256 | The amount of gas to send for the deployment. | #### Return Values -| Name | Type | Description | -| ------- | ------- | ---------------------------------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | -### \_deployInterchainToken +### deployRemoteInterchainTokenWithMinter ```solidity -function _deployInterchainToken(bytes32 salt, string destinationChain, string tokenName, string tokenSymbol, uint8 tokenDecimals, bytes minter, uint256 gasValue) internal returns (bytes32 tokenId) +function deployRemoteInterchainTokenWithMinter(bytes32 salt, address minter, string destinationChain, bytes destinationMinter, uint256 gasValue) public payable returns (bytes32 tokenId) ``` -Deploys a new interchain token with specified parameters. +Deploys a remote interchain token on a specified destination chain. #### Parameters -| Name | Type | Description | -| ---------------- | ------- | --------------------------------------------------- | -| salt | bytes32 | The unique salt for deploying the token. | -| destinationChain | string | The name of the destination chain. | -| tokenName | string | The name of the token. | -| tokenSymbol | string | The symbol of the token. | -| tokenDecimals | uint8 | The number of decimals for the token. | -| minter | bytes | The address to receive the initially minted tokens. | -| gasValue | uint256 | The amount of gas to send for the transfer. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| salt | bytes32 | The unique salt for deploying the token. | +| minter | address | The address to receive the minter and operator role of the token, in addition to ITS. If the address is `address(0)`, no additional minter is set on the token. Reverts if the minter does not have mint permission for the token. | +| destinationChain | string | The name of the destination chain. | +| destinationMinter | bytes | The minter address to set on the deployed token on the destination chain. This can be arbitrary bytes since the encoding of the account is dependent on the destination chain. If this is empty, then the `minter` of the token on the current chain is used as the destination minter, which makes it convenient when deploying to other EVM chains. | +| gasValue | uint256 | The amount of gas to send for the deployment. | #### Return Values -| Name | Type | Description | -| ------- | ------- | ---------------------------------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | -### registerCanonicalInterchainToken +### deployRemoteInterchainToken ```solidity -function registerCanonicalInterchainToken(address tokenAddress) external payable returns (bytes32 tokenId) +function deployRemoteInterchainToken(string originalChainName, bytes32 salt, address minter, string destinationChain, uint256 gasValue) external payable returns (bytes32 tokenId) ``` -Registers a canonical token as an interchain token and deploys its token manager. +Deploys a remote interchain token on a specified destination chain. +This method is deprecated and will be removed in the future. Please use the above method instead. + +_originalChainName is only allowed to be '', i.e the current chain. +Other source chains are not supported anymore to simplify ITS token deployment behaviour._ #### Parameters -| Name | Type | Description | -| ------------ | ------- | ----------------------------------- | -| tokenAddress | address | The address of the canonical token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| originalChainName | string | The name of the chain where the token originally exists. | +| salt | bytes32 | The unique salt for deploying the token. | +| minter | address | The address to receive the minter and operator role of the token, in addition to ITS. If the address is `address(0)`, no additional minter is set on the token. Reverts if the minter does not have mint permission for the token. | +| destinationChain | string | The name of the destination chain. | +| gasValue | uint256 | The amount of gas to send for the deployment. | #### Return Values -| Name | Type | Description | -| ------- | ------- | ------------------------------------------------------------ | -| tokenId | bytes32 | The tokenId corresponding to the registered canonical token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | -### deployRemoteCanonicalInterchainToken +### _deployInterchainToken ```solidity -function deployRemoteCanonicalInterchainToken(string originalChain, address originalTokenAddress, string destinationChain, uint256 gasValue) external payable returns (bytes32 tokenId) +function _deployInterchainToken(bytes32 salt, string destinationChain, string tokenName, string tokenSymbol, uint8 tokenDecimals, bytes minter, uint256 gasValue) internal returns (bytes32 tokenId) ``` -Deploys a canonical interchain token on a remote chain. +Deploys a new interchain token with specified parameters. #### Parameters -| Name | Type | Description | -| -------------------- | ------- | -------------------------------------------------------- | -| originalChain | string | The name of the chain where the token originally exists. | -| originalTokenAddress | address | The address of the original token on the original chain. | -| destinationChain | string | The name of the chain where the token will be deployed. | -| gasValue | uint256 | The gas amount to be sent for deployment. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| salt | bytes32 | The unique salt for deploying the token. | +| destinationChain | string | The name of the destination chain. | +| tokenName | string | The name of the token. | +| tokenSymbol | string | The symbol of the token. | +| tokenDecimals | uint8 | The number of decimals for the token. | +| minter | bytes | The address to receive the initially minted tokens. | +| gasValue | uint256 | The amount of gas to send for the transfer. | #### Return Values -| Name | Type | Description | -| ------- | ------- | ---------------------------------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | -### \_isGatewayToken +### _deployRemoteInterchainToken ```solidity -function _isGatewayToken(address token) internal view returns (bool) +function _deployRemoteInterchainToken(bytes32 deploySalt, string destinationChain, bytes minter, uint256 gasValue) internal returns (bytes32 tokenId) ``` -Checks if a given token is a gateway token. +Deploys a remote interchain token on a specified destination chain. #### Parameters -| Name | Type | Description | -| ----- | ------- | ---------------------------------- | -| token | address | The address of the token to check. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| deploySalt | bytes32 | The salt used for the deployment. | +| destinationChain | string | The name of the destination chain. | +| minter | bytes | The address to receive the minter and operator role of the token, in addition to ITS. | +| gasValue | uint256 | The amount of gas to send for the deployment. | #### Return Values -| Name | Type | Description | -| ---- | ---- | ----------------------------------------------------------- | -| [0] | bool | bool True if the token is a gateway token, false otherwise. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | -## InterchainTokenService +### registerCanonicalInterchainToken -This contract is responsible for facilitating interchain token transfers. -It (mostly) does not handle tokens, but is responsible for the messaging that needs to occur for interchain transfers to happen. +```solidity +function registerCanonicalInterchainToken(address tokenAddress) external payable returns (bytes32 tokenId) +``` -_The only storage used in this contract is for Express calls. -Furthermore, no ether is intended to or should be sent to this contract except as part of deploy/interchainTransfer payable methods for gas payment._ +Registers a canonical token as an interchain token and deploys its token manager. -### gateway +_This function is `payable` because non-payable functions cannot be called in a multicall that calls other `payable` functions._ -```solidity -contract IAxelarGateway gateway -``` +#### Parameters -### gasService +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress | address | The address of the canonical token. | -```solidity -contract IAxelarGasService gasService -``` +#### Return Values -### interchainTokenFactory +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId corresponding to the registered canonical token. | + +### deployRemoteCanonicalInterchainToken ```solidity -address interchainTokenFactory +function deployRemoteCanonicalInterchainToken(address originalTokenAddress, string destinationChain, uint256 gasValue) public payable returns (bytes32 tokenId) ``` -Returns the address of the interchain token factory. +Deploys a canonical interchain token on a remote chain. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| originalTokenAddress | address | The address of the original token on the original chain. | +| destinationChain | string | The name of the chain where the token will be deployed. | +| gasValue | uint256 | The gas amount to be sent for deployment. | #### Return Values | Name | Type | Description | | ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | -### chainNameHash +### deployRemoteCanonicalInterchainToken ```solidity -bytes32 chainNameHash +function deployRemoteCanonicalInterchainToken(string originalChain, address originalTokenAddress, string destinationChain, uint256 gasValue) external payable returns (bytes32 tokenId) ``` -Returns the hash of the chain name. +Deploys a canonical interchain token on a remote chain. +This method is deprecated and will be removed in the future. Please use the above method instead. + +_originalChain is only allowed to be '', i.e the current chain. +Other source chains are not supported anymore to simplify ITS token deployment behaviour._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| originalChain | string | The name of the chain where the token originally exists. | +| originalTokenAddress | address | The address of the original token on the original chain. | +| destinationChain | string | The name of the chain where the token will be deployed. | +| gasValue | uint256 | The gas amount to be sent for deployment. | #### Return Values | Name | Type | Description | | ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | -### interchainTokenDeployer +## IAddressTracker + +This interface allows setting and removing a trusted address for a specific chain. + +_Extends the IInterchainAddressTracker interface._ + +### setTrustedAddress ```solidity -address interchainTokenDeployer +function setTrustedAddress(string chain, string address_) external ``` -Returns the address of the interchain token deployer contract. +Sets the trusted address for the specified chain. -#### Return Values +#### Parameters | Name | Type | Description | | ---- | ---- | ----------- | +| chain | string | Chain name to be trusted. | +| address_ | string | Trusted address to be added for the chain. | -### tokenManagerDeployer +### removeTrustedAddress ```solidity -address tokenManagerDeployer +function removeTrustedAddress(string chain) external ``` -Returns the address of the token manager deployer contract. +Remove the trusted address of the chain. -#### Return Values +#### Parameters | Name | Type | Description | | ---- | ---- | ----------- | +| chain | string | Chain name to remove the trusted address for. | -### tokenManager +## IBaseTokenManager + +This contract is defines the base token manager interface implemented by all token managers. + +### interchainTokenId ```solidity -address tokenManager +function interchainTokenId() external view returns (bytes32) ``` -_Token manager implementation addresses_ +A function that returns the token id. -### tokenHandler +### tokenAddress ```solidity -address tokenHandler +function tokenAddress() external view returns (address) ``` -Returns the address of TokenHandler implementation. +A function that should return the address of the token. +Must be overridden in the inheriting contract. #### Return Values | Name | Type | Description | | ---- | ---- | ----------- | +| [0] | address | address address of the token. | -### PREFIX_INTERCHAIN_TOKEN_ID +### getTokenAddressFromParams ```solidity -bytes32 PREFIX_INTERCHAIN_TOKEN_ID +function getTokenAddressFromParams(bytes params) external pure returns (address) ``` -### PREFIX_INTERCHAIN_TOKEN_SALT +A function that should return the token address from the init params. -```solidity -bytes32 PREFIX_INTERCHAIN_TOKEN_SALT -``` +## IERC20MintableBurnable -### TOKEN_FACTORY_DEPLOYER +_Interface of the ERC20 standard as defined in the EIP._ + +### mint ```solidity -address TOKEN_FACTORY_DEPLOYER +function mint(address to, uint256 amount) external ``` -_Tokens and token managers deployed via the Token Factory contract use a special deployer address. -This removes the dependency on the address the token factory was deployed too to be able to derive the same tokenId._ +Function to mint new tokens. -### MetadataVersion +_Can only be called by the minter address._ -_Latest version of metadata that's supported._ +#### Parameters -```solidity -enum MetadataVersion { - CONTRACT_CALL, - EXPRESS_CALL -} -``` +| Name | Type | Description | +| ---- | ---- | ----------- | +| to | address | The address that will receive the minted tokens. | +| amount | uint256 | The amount of tokens to mint. | -### LATEST_METADATA_VERSION +### burn ```solidity -uint32 LATEST_METADATA_VERSION +function burn(address from, uint256 amount) external ``` -### constructor +Function to burn tokens. -```solidity -constructor(address tokenManagerDeployer_, address interchainTokenDeployer_, address gateway_, address gasService_, address interchainTokenFactory_, string chainName_, address tokenManagerImplementation_, address tokenHandler_) public -``` +_Can only be called by the minter address._ -Constructor for the Interchain Token Service. +#### Parameters -_All of the variables passed here are stored as immutable variables._ +| Name | Type | Description | +| ---- | ---- | ----------- | +| from | address | The address that will have its tokens burnt. | +| amount | uint256 | The amount of tokens to burn. | -#### Parameters +## IERC20Named -| Name | Type | Description | -| ---------------------------- | ------- | -------------------------------------------------------- | -| tokenManagerDeployer\_ | address | The address of the TokenManagerDeployer. | -| interchainTokenDeployer\_ | address | The address of the InterchainTokenDeployer. | -| gateway\_ | address | The address of the AxelarGateway. | -| gasService\_ | address | The address of the AxelarGasService. | -| interchainTokenFactory\_ | address | The address of the InterchainTokenFactory. | -| chainName\_ | string | The name of the chain that this contract is deployed on. | -| tokenManagerImplementation\_ | address | The tokenManager implementation. | -| tokenHandler\_ | address | The tokenHandler implementation. | +_Interface of the ERC20 standard as defined in the EIP._ -### onlyRemoteService +### name ```solidity -modifier onlyRemoteService(string sourceChain, string sourceAddress) +function name() external view returns (string) ``` -This modifier is used to ensure that only a remote InterchainTokenService can invoke the execute function. +Getter for the name of the token. -#### Parameters +#### Return Values -| Name | Type | Description | -| ------------- | ------ | ------------------------------------------- | -| sourceChain | string | The source chain of the contract call. | -| sourceAddress | string | The source address that the call came from. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | string | string Name of the token. | -### contractId +### symbol ```solidity -function contractId() external pure returns (bytes32) +function symbol() external view returns (string) ``` -Getter for the contract id. +Getter for the symbol of the token. #### Return Values -| Name | Type | Description | -| ---- | ------- | ----------------------------------------- | -| [0] | bytes32 | bytes32 The contract id of this contract. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | string | string The symbol of the token. | -### tokenManagerAddress +### decimals ```solidity -function tokenManagerAddress(bytes32 tokenId) public view returns (address tokenManagerAddress_) +function decimals() external view returns (uint8) ``` -Calculates the address of a TokenManager from a specific tokenId. - -_The TokenManager does not need to exist already._ +Getter for the decimals of the token. -#### Parameters +#### Return Values -| Name | Type | Description | -| ------- | ------- | ------------ | -| tokenId | bytes32 | The tokenId. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint8 | uint8 The decimals of the token. | -#### Return Values +## IFlowLimit -| Name | Type | Description | -| --------------------- | ------- | ------------------------------------------- | -| tokenManagerAddress\_ | address | The deployment address of the TokenManager. | +Interface for flow limit logic for interchain token transfers. -### deployedTokenManager +### FlowLimitExceeded ```solidity -function deployedTokenManager(bytes32 tokenId) public view returns (address tokenManagerAddress_) +error FlowLimitExceeded(uint256 limit, uint256 flowAmount, address tokenManager) ``` -Returns the address of a TokenManager from a specific tokenId. - -_The TokenManager needs to exist already._ +### FlowAdditionOverflow -#### Parameters - -| Name | Type | Description | -| ------- | ------- | ------------ | -| tokenId | bytes32 | The tokenId. | +```solidity +error FlowAdditionOverflow(uint256 flowAmount, uint256 flowToAdd, address tokenManager) +``` -#### Return Values +### FlowLimitOverflow -| Name | Type | Description | -| --------------------- | ------- | ------------------------------------------- | -| tokenManagerAddress\_ | address | The deployment address of the TokenManager. | +```solidity +error FlowLimitOverflow(uint256 flowLimit, uint256 flowToCompare, address tokenManager) +``` -### registeredTokenAddress +### FlowLimitSet ```solidity -function registeredTokenAddress(bytes32 tokenId) public view returns (address tokenAddress) +event FlowLimitSet(bytes32 tokenId, address operator, uint256 flowLimit_) ``` -Returns the address of the token that an existing tokenManager points to. +### flowLimit -#### Parameters +```solidity +function flowLimit() external view returns (uint256 flowLimit_) +``` -| Name | Type | Description | -| ------- | ------- | ------------ | -| tokenId | bytes32 | The tokenId. | +Returns the current flow limit. #### Return Values -| Name | Type | Description | -| ------------ | ------- | ------------------------- | -| tokenAddress | address | The address of the token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowLimit_ | uint256 | The current flow limit value. | -### interchainTokenAddress +### flowOutAmount ```solidity -function interchainTokenAddress(bytes32 tokenId) public view returns (address tokenAddress) +function flowOutAmount() external view returns (uint256 flowOutAmount_) ``` -Returns the address of the interchain token associated with the given tokenId. - -_The token does not need to exist._ - -#### Parameters - -| Name | Type | Description | -| ------- | ------- | ------------------------------------ | -| tokenId | bytes32 | The tokenId of the interchain token. | +Returns the current flow out amount. #### Return Values -| Name | Type | Description | -| ------------ | ------- | ------------------------------------ | -| tokenAddress | address | The address of the interchain token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowOutAmount_ | uint256 | The current flow out amount. | -### interchainTokenId +### flowInAmount ```solidity -function interchainTokenId(address sender, bytes32 salt) public pure returns (bytes32 tokenId) +function flowInAmount() external view returns (uint256 flowInAmount_) ``` -Calculates the tokenId that would correspond to a link for a given deployer with a specified salt. +Returns the current flow in amount. -#### Parameters +#### Return Values -| Name | Type | Description | -| ------ | ------- | --------------------------------------------------- | -| sender | address | The address of the TokenManager deployer. | -| salt | bytes32 | The salt that the deployer uses for the deployment. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowInAmount_ | uint256 | The current flow in amount. | -#### Return Values +## IInterchainToken -| Name | Type | Description | -| ------- | ------- | ------------------------------------------------------------------- | -| tokenId | bytes32 | The tokenId that the custom TokenManager would get (or has gotten). | +_Extends IInterchainTokenStandard and IMinter._ -### tokenManagerImplementation +### InterchainTokenServiceAddressZero ```solidity -function tokenManagerImplementation(uint256) external view returns (address) +error InterchainTokenServiceAddressZero() ``` -Getter function for TokenManager implementation. This will mainly be called by TokenManager proxies -to figure out their implementations. - -#### Return Values +### TokenIdZero -| Name | Type | Description | -| ---- | ------- | ------------------------------------------------------------------- | -| [0] | address | tokenManagerAddress The address of the TokenManager implementation. | +```solidity +error TokenIdZero() +``` -### flowLimit +### TokenNameEmpty ```solidity -function flowLimit(bytes32 tokenId) external view returns (uint256 flowLimit_) +error TokenNameEmpty() ``` -Getter function for the flow limit of an existing TokenManager with a given tokenId. - -#### Parameters +### TokenSymbolEmpty -| Name | Type | Description | -| ------- | ------- | -------------------------------- | -| tokenId | bytes32 | The tokenId of the TokenManager. | +```solidity +error TokenSymbolEmpty() +``` -#### Return Values +### AlreadyInitialized -| Name | Type | Description | -| ----------- | ------- | --------------- | -| flowLimit\_ | uint256 | The flow limit. | +```solidity +error AlreadyInitialized() +``` -### flowOutAmount +### interchainTokenService ```solidity -function flowOutAmount(bytes32 tokenId) external view returns (uint256 flowOutAmount_) +function interchainTokenService() external view returns (address interchainTokenServiceAddress) ``` -Getter function for the flow out amount of an existing TokenManager with a given tokenId. - -#### Parameters +Getter for the interchain token service contract. -| Name | Type | Description | -| ------- | ------- | -------------------------------- | -| tokenId | bytes32 | The tokenId of the TokenManager. | +_Needs to be overwitten._ #### Return Values -| Name | Type | Description | -| --------------- | ------- | -------------------- | -| flowOutAmount\_ | uint256 | The flow out amount. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| interchainTokenServiceAddress | address | The interchain token service address. | -### flowInAmount +### interchainTokenId ```solidity -function flowInAmount(bytes32 tokenId) external view returns (uint256 flowInAmount_) +function interchainTokenId() external view returns (bytes32 tokenId_) ``` -Getter function for the flow in amount of an existing TokenManager with a given tokenId. - -#### Parameters +Getter for the tokenId used for this token. -| Name | Type | Description | -| ------- | ------- | -------------------------------- | -| tokenId | bytes32 | The tokenId of the TokenManager. | +_Needs to be overwitten._ #### Return Values -| Name | Type | Description | -| -------------- | ------- | ------------------- | -| flowInAmount\_ | uint256 | The flow in amount. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId_ | bytes32 | The tokenId for this token. | -### deployTokenManager +### init ```solidity -function deployTokenManager(bytes32 salt, string destinationChain, enum ITokenManagerType.TokenManagerType tokenManagerType, bytes params, uint256 gasValue) external payable returns (bytes32 tokenId) +function init(bytes32 tokenId_, address minter, string tokenName, string tokenSymbol, uint8 tokenDecimals) external ``` -Used to deploy remote custom TokenManagers. - -_At least the `gasValue` amount of native token must be passed to the function call. `gasValue` exists because this function can be -part of a multicall involving multiple functions that could make remote contract calls._ +Setup function to initialize contract parameters. #### Parameters -| Name | Type | Description | -| ---------------- | --------------------------------------- | -------------------------------------------------------------------------------- | -| salt | bytes32 | The salt to be used during deployment. | -| destinationChain | string | The name of the chain to deploy the TokenManager and standardized token to. | -| tokenManagerType | enum ITokenManagerType.TokenManagerType | The type of token manager to be deployed. Cannot be NATIVE_INTERCHAIN_TOKEN. | -| params | bytes | The params that will be used to initialize the TokenManager. | -| gasValue | uint256 | The amount of native tokens to be used to pay for gas for the remote deployment. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId_ | bytes32 | The tokenId of the token. | +| minter | address | The address of the token minter. | +| tokenName | string | The name of the token. | +| tokenSymbol | string | The symbopl of the token. | +| tokenDecimals | uint8 | The decimals of the token. | -#### Return Values +## IInterchainTokenFactory -| Name | Type | Description | -| ------- | ------- | ------------------------------------------------------- | -| tokenId | bytes32 | The tokenId corresponding to the deployed TokenManager. | +This interface defines functions for deploying new interchain tokens and managing their token managers. -### deployInterchainToken +### ZeroAddress ```solidity -function deployInterchainToken(bytes32 salt, string destinationChain, string name, string symbol, uint8 decimals, bytes minter, uint256 gasValue) external payable returns (bytes32 tokenId) +error ZeroAddress() ``` -Used to deploy an interchain token alongside a TokenManager in another chain. +### InvalidChainName -_At least the `gasValue` amount of native token must be passed to the function call. `gasValue` exists because this function can be -part of a multicall involving multiple functions that could make remote contract calls. If the `minter` parameter is empty bytes then -a mint/burn TokenManager is used, otherwise a lock/unlock TokenManager is used._ +```solidity +error InvalidChainName() +``` -#### Parameters +### InvalidMinter -| Name | Type | Description | -| ---------------- | ------- | -------------------------------------------------------------------------------- | -| salt | bytes32 | The salt to be used during deployment. | -| destinationChain | string | The name of the destination chain to deploy to. | -| name | string | The name of the token to be deployed. | -| symbol | string | The symbol of the token to be deployed. | -| decimals | uint8 | The decimals of the token to be deployed. | -| minter | bytes | The address that will be able to mint and burn the deployed token. | -| gasValue | uint256 | The amount of native tokens to be used to pay for gas for the remote deployment. | +```solidity +error InvalidMinter(address minter) +``` -#### Return Values +### NotMinter -| Name | Type | Description | -| ------- | ------- | ---------------------------------------------------------- | -| tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | +```solidity +error NotMinter(address minter) +``` -### contractCallValue +### NotOperator ```solidity -function contractCallValue(string sourceChain, string sourceAddress, bytes payload) public view virtual returns (address, uint256) +error NotOperator(address operator) ``` -Returns the amount of token that this call is worth. +### NotServiceOwner -_If `tokenAddress` is `0`, then value is in terms of the native token, otherwise it's in terms of the token address._ +```solidity +error NotServiceOwner(address sender) +``` -#### Parameters +### NotSupported -| Name | Type | Description | -| ------------- | ------ | --------------------------------------- | -| sourceChain | string | The source chain. | -| sourceAddress | string | The source address on the source chain. | -| payload | bytes | The payload sent with the call. | +```solidity +error NotSupported() +``` -#### Return Values +### RemoteDeploymentNotApproved -| Name | Type | Description | -| ---- | ------- | ------------------------------------ | -| [0] | address | address The token address. | -| [1] | uint256 | uint256 The value the call is worth. | +```solidity +error RemoteDeploymentNotApproved() +``` -### expressExecute +### InvalidTokenId ```solidity -function expressExecute(bytes32 commandId, string sourceChain, string sourceAddress, bytes payload) external payable +error InvalidTokenId(bytes32 tokenId, bytes32 expectedTokenId) ``` -Express executes operations based on the payload and selector. +### DeployRemoteInterchainTokenApproval -#### Parameters +```solidity +event DeployRemoteInterchainTokenApproval(address minter, address deployer, bytes32 tokenId, string destinationChain, bytes destinationMinter) +``` -| Name | Type | Description | -| ------------- | ------- | -------------------------------------------------------------------- | -| commandId | bytes32 | The unique message id. | -| sourceChain | string | The chain where the transaction originates from. | -| sourceAddress | string | The address of the remote ITS where the transaction originates from. | -| payload | bytes | The encoded data payload for the transaction. | +Emitted when a minter approves a deployer for a remote interchain token deployment that uses a custom destinationMinter address. -### \_expressExecute +### RevokedDeployRemoteInterchainTokenApproval ```solidity -function _expressExecute(bytes32 commandId, string sourceChain, bytes payload) internal +event RevokedDeployRemoteInterchainTokenApproval(address minter, address deployer, bytes32 tokenId, string destinationChain) ``` -Uses the caller's tokens to fullfill a sendCall ahead of time. Use this only if you have detected an outgoing -interchainTransfer that matches the parameters passed here. - -#### Parameters - -| Name | Type | Description | -| ----------- | ------- | ------------------------------------------------------------------- | -| commandId | bytes32 | The unique message id of the transfer being expressed. | -| sourceChain | string | the name of the chain where the interchainTransfer originated from. | -| payload | bytes | the payload of the receive token | +Emitted when a minter revokes a deployer's approval for a remote interchain token deployment that uses a custom destinationMinter address. -### interchainTransfer +### interchainTokenService ```solidity -function interchainTransfer(bytes32 tokenId, string destinationChain, bytes destinationAddress, uint256 amount, bytes metadata, uint256 gasValue) external payable +function interchainTokenService() external view returns (contract IInterchainTokenService) ``` -Initiates an interchain transfer of a specified token to a destination chain. - -_The function retrieves the TokenManager associated with the tokenId._ +Returns the address of the interchain token service. -#### Parameters +#### Return Values -| Name | Type | Description | -| ------------------ | ------- | ----------------------------------------------------------------------------------------------- | -| tokenId | bytes32 | The unique identifier of the token to be transferred. | -| destinationChain | string | The destination chain to send the tokens to. | -| destinationAddress | bytes | The address on the destination chain to send the tokens to. | -| amount | uint256 | The amount of tokens to be transferred. | -| metadata | bytes | Optional metadata for the call for additional effects (such as calling a destination contract). | -| gasValue | uint256 | | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | contract IInterchainTokenService | IInterchainTokenService The address of the interchain token service. | -### callContractWithInterchainToken +### chainNameHash ```solidity -function callContractWithInterchainToken(bytes32 tokenId, string destinationChain, bytes destinationAddress, uint256 amount, bytes data, uint256 gasValue) external payable +function chainNameHash() external view returns (bytes32) ``` -Initiates an interchain call contract with interchain token to a destination chain. +Returns the hash of the chain name. -#### Parameters +#### Return Values -| Name | Type | Description | -| ------------------ | ------- | ----------------------------------------------------------- | -| tokenId | bytes32 | The unique identifier of the token to be transferred. | -| destinationChain | string | The destination chain to send the tokens to. | -| destinationAddress | bytes | The address on the destination chain to send the tokens to. | -| amount | uint256 | The amount of tokens to be transferred. | -| data | bytes | Additional data to be passed along with the transfer. | -| gasValue | uint256 | | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 The hash of the chain name. | -### transmitInterchainTransfer +### interchainTokenDeploySalt ```solidity -function transmitInterchainTransfer(bytes32 tokenId, address sourceAddress, string destinationChain, bytes destinationAddress, uint256 amount, bytes metadata) external payable +function interchainTokenDeploySalt(address deployer, bytes32 salt) external view returns (bytes32 deploySalt) ``` -Transmit an interchain transfer for the given tokenId. - -_Only callable by a token registered under a tokenId._ +Computes the deploy salt for an interchain token. #### Parameters -| Name | Type | Description | -| ------------------ | ------- | ----------------------------------------------------------------------------------------------- | -| tokenId | bytes32 | The tokenId of the token (which must be the msg.sender). | -| sourceAddress | address | The address where the token is coming from. | -| destinationChain | string | The name of the chain to send tokens to. | -| destinationAddress | bytes | The destinationAddress for the interchainTransfer. | -| amount | uint256 | The amount of token to give. | -| metadata | bytes | Optional metadata for the call for additional effects (such as calling a destination contract). | +| Name | Type | Description | +| ---- | ---- | ----------- | +| deployer | address | The address of the deployer. | +| salt | bytes32 | A unique identifier to generate the salt. | -### setFlowLimits - -```solidity -function setFlowLimits(bytes32[] tokenIds, uint256[] flowLimits) external -``` - -Used to set a flow limit for a token manager that has the service as its operator. - -#### Parameters +#### Return Values -| Name | Type | Description | -| ---------- | --------- | ------------------------------------------------------------------------ | -| tokenIds | bytes32[] | An array of the tokenIds of the tokenManagers to set the flow limits of. | -| flowLimits | uint256[] | The flowLimits to set. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| deploySalt | bytes32 | The deploy salt for the interchain token. | -### setTrustedAddress +### interchainTokenId ```solidity -function setTrustedAddress(string chain, string address_) external +function interchainTokenId(address deployer, bytes32 salt) external view returns (bytes32 tokenId) ``` -Used to set a trusted address for a chain. +Computes the ID for an interchain token based on the deployer and a salt. #### Parameters -| Name | Type | Description | -| --------- | ------ | ---------------------------------------- | -| chain | string | The chain to set the trusted address of. | -| address\_ | string | The address to set as trusted. | - -### removeTrustedAddress - -```solidity -function removeTrustedAddress(string chain) external -``` - -Used to remove a trusted address for a chain. +| Name | Type | Description | +| ---- | ---- | ----------- | +| deployer | address | The address that deployed the interchain token. | +| salt | bytes32 | A unique identifier used in the deployment process. | -#### Parameters +#### Return Values -| Name | Type | Description | -| ----- | ------ | ---------------------------------------- | -| chain | string | The chain to set the trusted address of. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The ID of the interchain token. | -### setPauseStatus +### deployInterchainToken ```solidity -function setPauseStatus(bool paused) external +function deployInterchainToken(bytes32 salt, string name, string symbol, uint8 decimals, uint256 initialSupply, address minter) external payable returns (bytes32 tokenId) ``` -Allows the owner to pause/unpause the token service. +Deploys a new interchain token with specified parameters. #### Parameters -| Name | Type | Description | -| ------ | ---- | ------------------------------------------------------- | -| paused | bool | Boolean value representing whether to pause or unpause. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| salt | bytes32 | The unique salt for deploying the token. | +| name | string | The name of the token. | +| symbol | string | The symbol of the token. | +| decimals | uint8 | The number of decimals for the token. | +| initialSupply | uint256 | The amount of tokens to mint initially (can be zero), allocated to the msg.sender. | +| minter | address | The address to receive the initially minted tokens. | -### \_setup +#### Return Values -```solidity -function _setup(bytes params) internal -``` +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | -### execute +### approveDeployRemoteInterchainToken ```solidity -function execute(bytes32 commandId, string sourceChain, string sourceAddress, bytes payload) external +function approveDeployRemoteInterchainToken(address deployer, bytes32 salt, string destinationChain, bytes destinationMinter) external ``` -Executes operations based on the payload and selector. - -#### Parameters - -| Name | Type | Description | -| ------------- | ------- | -------------------------------------------------------------------- | -| commandId | bytes32 | The unique message id. | -| sourceChain | string | The chain where the transaction originates from. | -| sourceAddress | string | The address of the remote ITS where the transaction originates from. | -| payload | bytes | The encoded data payload for the transaction. | +Allows the minter to approve a deployer for a remote interchain token deployment that uses a custom destinationMinter address. +This ensures that a token deployer can't choose the destinationMinter itself, and requires the approval of the minter to reduce trust assumptions on the deployer. -### contractCallWithTokenValue +### revokeDeployRemoteInterchainToken ```solidity -function contractCallWithTokenValue(string, string, bytes, string, uint256) public view virtual returns (address, uint256) +function revokeDeployRemoteInterchainToken(address deployer, bytes32 salt, string destinationChain) external ``` -### expressExecuteWithToken +Allows the minter to revoke a deployer's approval for a remote interchain token deployment that uses a custom destinationMinter address. -```solidity -function expressExecuteWithToken(bytes32, string, string, bytes, string, uint256) external payable -``` - -### executeWithToken - -```solidity -function executeWithToken(bytes32, string, string, bytes, string, uint256) external pure -``` - -### \_processInterchainTransferPayload +### deployRemoteInterchainToken ```solidity -function _processInterchainTransferPayload(bytes32 commandId, address expressExecutor, string sourceChain, bytes payload) internal +function deployRemoteInterchainToken(bytes32 salt, address minter, string destinationChain, uint256 gasValue) external payable returns (bytes32 tokenId) ``` -Processes the payload data for a send token call. +Deploys a remote interchain token on a specified destination chain. #### Parameters -| Name | Type | Description | -| --------------- | ------- | -------------------------------------------------------------------------------- | -| commandId | bytes32 | The unique message id. | -| expressExecutor | address | The address of the express executor. Equals `address(0)` if it wasn't expressed. | -| sourceChain | string | The chain where the transaction originates from. | -| payload | bytes | The encoded data payload to be processed. | - -### \_processDeployTokenManagerPayload +| Name | Type | Description | +| ---- | ---- | ----------- | +| salt | bytes32 | The unique salt for deploying the token. | +| minter | address | The address to use as the minter of the deployed token on the destination chain. If the destination chain is not EVM, then use the more generic `deployRemoteInterchainToken` function below that allows setting an arbitrary destination minter that was approved by the current minter. | +| destinationChain | string | The name of the destination chain. | +| gasValue | uint256 | The amount of gas to send for the deployment. | -```solidity -function _processDeployTokenManagerPayload(bytes payload) internal -``` +#### Return Values -Processes a deploy token manager payload. +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | -### \_processDeployInterchainTokenPayload +### deployRemoteInterchainTokenWithMinter ```solidity -function _processDeployInterchainTokenPayload(bytes payload) internal +function deployRemoteInterchainTokenWithMinter(bytes32 salt, address minter, string destinationChain, bytes destinationMinter, uint256 gasValue) external payable returns (bytes32 tokenId) ``` -Processes a deploy interchain token manager payload. +Deploys a remote interchain token on a specified destination chain. #### Parameters -| Name | Type | Description | -| ------- | ----- | ----------------------------------------- | -| payload | bytes | The encoded data payload to be processed. | - -### \_callContract - -```solidity -function _callContract(string destinationChain, bytes payload, enum InterchainTokenService.MetadataVersion metadataVersion, uint256 gasValue) internal -``` - -Calls a contract on a specific destination chain with the given payload +| Name | Type | Description | +| ---- | ---- | ----------- | +| salt | bytes32 | The unique salt for deploying the token. | +| minter | address | The address to distribute the token on the destination chain. | +| destinationChain | string | The name of the destination chain. | +| destinationMinter | bytes | The minter address to set on the deployed token on the destination chain. This can be arbitrary bytes since the encoding of the account is dependent on the destination chain. If this is empty, then the `minter` of the token on the current chain is used as the destination minter, which makes it convenient when deploying to other EVM chains. | +| gasValue | uint256 | The amount of gas to send for the deployment. | -#### Parameters +#### Return Values -| Name | Type | Description | -| ---------------- | ------------------------------------------- | --------------------------------------------------- | -| destinationChain | string | The target chain where the contract will be called. | -| payload | bytes | The data payload for the transaction. | -| metadataVersion | enum InterchainTokenService.MetadataVersion | | -| gasValue | uint256 | The amount of gas to be paid for the transaction. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | -### \_deployRemoteTokenManager +### deployRemoteInterchainToken ```solidity -function _deployRemoteTokenManager(bytes32 tokenId, string destinationChain, uint256 gasValue, enum ITokenManagerType.TokenManagerType tokenManagerType, bytes params) internal +function deployRemoteInterchainToken(string originalChainName, bytes32 salt, address minter, string destinationChain, uint256 gasValue) external payable returns (bytes32 tokenId) ``` -Deploys a token manager on a destination chain. +Deploys a remote interchain token on a specified destination chain. + +_originalChainName is only allowed to be '', i.e the current chain. +Other source chains are not supported anymore to simplify ITS token deployment behaviour._ #### Parameters -| Name | Type | Description | -| ---------------- | --------------------------------------- | ------------------------------------------------------- | -| tokenId | bytes32 | The ID of the token. | -| destinationChain | string | The chain where the token manager will be deployed. | -| gasValue | uint256 | The amount of gas to be paid for the transaction. | -| tokenManagerType | enum ITokenManagerType.TokenManagerType | The type of token manager to be deployed. | -| params | bytes | Additional parameters for the token manager deployment. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| originalChainName | string | The name of the chain where the token originally exists. | +| salt | bytes32 | The unique salt for deploying the token. | +| minter | address | The address to distribute the token on the destination chain. | +| destinationChain | string | The name of the destination chain. | +| gasValue | uint256 | The amount of gas to send for the deployment. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | -### \_deployRemoteInterchainToken +### canonicalInterchainTokenDeploySalt ```solidity -function _deployRemoteInterchainToken(bytes32 tokenId, string name, string symbol, uint8 decimals, bytes minter, string destinationChain, uint256 gasValue) internal +function canonicalInterchainTokenDeploySalt(address tokenAddress) external view returns (bytes32 deploySalt) ``` -Deploys an interchain token on a destination chain. +Computes the deploy salt for a canonical interchain token. #### Parameters -| Name | Type | Description | -| ---------------- | ------- | ------------------------------------------------------- | -| tokenId | bytes32 | The ID of the token. | -| name | string | The name of the token. | -| symbol | string | The symbol of the token. | -| decimals | uint8 | The number of decimals of the token. | -| minter | bytes | The minter address for the token. | -| destinationChain | string | The destination chain where the token will be deployed. | -| gasValue | uint256 | The amount of gas to be paid for the transaction. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress | address | The address of the token. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| deploySalt | bytes32 | The deploy salt for the interchain token. | -### \_deployTokenManager +### canonicalInterchainTokenId ```solidity -function _deployTokenManager(bytes32 tokenId, enum ITokenManagerType.TokenManagerType tokenManagerType, bytes params) internal +function canonicalInterchainTokenId(address tokenAddress) external view returns (bytes32 tokenId) ``` -Deploys a token manager. +Computes the ID for a canonical interchain token based on its address. #### Parameters -| Name | Type | Description | -| ---------------- | --------------------------------------- | ------------------------------------------------------- | -| tokenId | bytes32 | The ID of the token. | -| tokenManagerType | enum ITokenManagerType.TokenManagerType | The type of the token manager to be deployed. | -| params | bytes | Additional parameters for the token manager deployment. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress | address | The address of the canonical interchain token. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The ID of the canonical interchain token. | -### \_getInterchainTokenSalt +### registerCanonicalInterchainToken ```solidity -function _getInterchainTokenSalt(bytes32 tokenId) internal pure returns (bytes32 salt) +function registerCanonicalInterchainToken(address tokenAddress) external payable returns (bytes32 tokenId) ``` -Computes the salt for an interchain token deployment. +Registers a canonical token as an interchain token and deploys its token manager. #### Parameters -| Name | Type | Description | -| ------- | ------- | -------------------- | -| tokenId | bytes32 | The ID of the token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress | address | The address of the canonical token. | #### Return Values -| Name | Type | Description | -| ---- | ------- | ------------------------------------------- | -| salt | bytes32 | The computed salt for the token deployment. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId corresponding to the registered canonical token. | -### \_deployInterchainToken +### deployRemoteCanonicalInterchainToken ```solidity -function _deployInterchainToken(bytes32 tokenId, bytes minterBytes, string name, string symbol, uint8 decimals) internal returns (address tokenAddress) +function deployRemoteCanonicalInterchainToken(address originalTokenAddress, string destinationChain, uint256 gasValue) external payable returns (bytes32 tokenId) ``` -Deploys an interchain token. +Deploys a canonical interchain token on a remote chain. #### Parameters -| Name | Type | Description | -| ----------- | ------- | ------------------------------------ | -| tokenId | bytes32 | The ID of the token. | -| minterBytes | bytes | The minter address for the token. | -| name | string | The name of the token. | -| symbol | string | The symbol of the token. | -| decimals | uint8 | The number of decimals of the token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| originalTokenAddress | address | The address of the original token on the original chain. | +| destinationChain | string | The name of the chain where the token will be deployed. | +| gasValue | uint256 | The gas amount to be sent for deployment. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId corresponding to the deployed canonical InterchainToken. | -### \_decodeMetadata +### deployRemoteCanonicalInterchainToken ```solidity -function _decodeMetadata(bytes metadata) internal pure returns (enum InterchainTokenService.MetadataVersion version, bytes data) +function deployRemoteCanonicalInterchainToken(string originalChain, address originalTokenAddress, string destinationChain, uint256 gasValue) external payable returns (bytes32 tokenId) ``` -Decodes the metadata into a version number and data bytes. +Deploys a canonical interchain token on a remote chain. +This method is deprecated and will be removed in the future. Please use the above method instead. -_The function expects the metadata to have the version in the first 4 bytes, followed by the actual data._ +_originalChain is only allowed to be '', i.e the current chain. +Other source chains are not supported anymore to simplify ITS token deployment behaviour._ #### Parameters -| Name | Type | Description | -| -------- | ----- | -------------------------------------------- | -| metadata | bytes | The bytes containing the metadata to decode. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| originalChain | string | The name of the chain where the token originally exists. | +| originalTokenAddress | address | The address of the original token on the original chain. | +| destinationChain | string | The name of the chain where the token will be deployed. | +| gasValue | uint256 | The gas amount to be sent for deployment. | #### Return Values -| Name | Type | Description | -| ------- | ------------------------------------------- | ----------------------------------------------- | -| version | enum InterchainTokenService.MetadataVersion | The version number extracted from the metadata. | -| data | bytes | The data bytes extracted from the metadata. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | + +## IInterchainTokenService + +Interface for the Interchain Token Service -### \_transmitInterchainTransfer +### InvalidTokenManagerImplementationType ```solidity -function _transmitInterchainTransfer(bytes32 tokenId, address sourceAddress, string destinationChain, bytes destinationAddress, uint256 amount, enum InterchainTokenService.MetadataVersion metadataVersion, bytes data, uint256 gasValue) internal +error InvalidTokenManagerImplementationType(address implementation) ``` -Transmit a callContractWithInterchainToken for the given tokenId. - -#### Parameters +### InvalidChainName -| Name | Type | Description | -| ------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------ | -| tokenId | bytes32 | The tokenId of the TokenManager (which must be the msg.sender). | -| sourceAddress | address | The address where the token is coming from, which will also be used for gas reimbursement. | -| destinationChain | string | The name of the chain to send tokens to. | -| destinationAddress | bytes | The destinationAddress for the interchainTransfer. | -| amount | uint256 | The amount of tokens to send. | -| metadataVersion | enum InterchainTokenService.MetadataVersion | The version of the metadata. | -| data | bytes | The data to be passed with the token transfer. | -| gasValue | uint256 | | +```solidity +error InvalidChainName() +``` -### \_takeToken +### NotRemoteService ```solidity -function _takeToken(bytes32 tokenId, address from, uint256 amount, bool tokenOnly) internal returns (uint256) +error NotRemoteService() ``` -_Takes token from a sender via the token service. `tokenOnly` indicates if the caller should be restricted to the token only._ - -### \_giveToken +### TokenManagerDoesNotExist ```solidity -function _giveToken(bytes32 tokenId, address to, uint256 amount) internal returns (uint256, address) +error TokenManagerDoesNotExist(bytes32 tokenId) ``` -_Gives token to recipient via the token service._ - -## TokenHandler +### ExecuteWithInterchainTokenFailed -This interface is responsible for handling tokens before initiating an interchain token transfer, or after receiving one. +```solidity +error ExecuteWithInterchainTokenFailed(address contractAddress) +``` -### giveToken +### ExpressExecuteWithInterchainTokenFailed ```solidity -function giveToken(uint256 tokenManagerType, address tokenAddress, address tokenManager, address to, uint256 amount) external payable returns (uint256) +error ExpressExecuteWithInterchainTokenFailed(address contractAddress) ``` -This function gives token to a specified address from the token manager. - -#### Parameters +### TokenManagerDeploymentFailed -| Name | Type | Description | -| ---------------- | ------- | --------------------------------- | -| tokenManagerType | uint256 | The token manager type. | -| tokenAddress | address | The address of the token to give. | -| tokenManager | address | The address of the token manager. | -| to | address | The address to give tokens to. | -| amount | uint256 | The amount of tokens to give. | +```solidity +error TokenManagerDeploymentFailed(bytes error) +``` -#### Return Values +### InterchainTokenDeploymentFailed -| Name | Type | Description | -| ---- | ------- | -------------------------------------------------------------------------------------------- | -| [0] | uint256 | uint256 The amount of token actually given, which could be different for certain token type. | +```solidity +error InterchainTokenDeploymentFailed(bytes error) +``` -### takeToken +### InvalidMessageType ```solidity -function takeToken(uint256 tokenManagerType, address tokenAddress, address tokenManager, address from, uint256 amount) external payable returns (uint256) +error InvalidMessageType(uint256 messageType) ``` -This function takes token from a specified address to the token manager. - -#### Parameters +### InvalidMetadataVersion -| Name | Type | Description | -| ---------------- | ------- | --------------------------------- | -| tokenManagerType | uint256 | The token manager type. | -| tokenAddress | address | The address of the token to give. | -| tokenManager | address | The address of the token manager. | -| from | address | The address to take tokens from. | -| amount | uint256 | The amount of token to take. | +```solidity +error InvalidMetadataVersion(uint32 version) +``` -#### Return Values +### InvalidExpressMessageType -| Name | Type | Description | -| ---- | ------- | -------------------------------------------------------------------------------------------- | -| [0] | uint256 | uint256 The amount of token actually taken, which could be different for certain token type. | +```solidity +error InvalidExpressMessageType(uint256 messageType) +``` -### transferTokenFrom +### TakeTokenFailed ```solidity -function transferTokenFrom(uint256 tokenManagerType, address tokenAddress, address from, address to, uint256 amount) external payable returns (uint256) +error TakeTokenFailed(bytes data) ``` -This function transfers token from and to a specified address. - -#### Parameters +### GiveTokenFailed -| Name | Type | Description | -| ---------------- | ------- | ------------------------------------ | -| tokenManagerType | uint256 | The token manager type. | -| tokenAddress | address | the address of the token to give. | -| from | address | The address to transfer tokens from. | -| to | address | The address to transfer tokens to. | -| amount | uint256 | The amount of token to transfer. | +```solidity +error GiveTokenFailed(bytes data) +``` -#### Return Values +### TokenHandlerFailed -| Name | Type | Description | -| ---- | ------- | -------------------------------------------------------------------------------------------------- | -| [0] | uint256 | uint256 The amount of token actually transferred, which could be different for certain token type. | +```solidity +error TokenHandlerFailed(bytes data) +``` -### \_transferTokenFrom +### EmptyData ```solidity -function _transferTokenFrom(address tokenAddress, address from, address to, uint256 amount) internal +error EmptyData() ``` -### \_transferTokenFromWithFee +### PostDeployFailed ```solidity -function _transferTokenFromWithFee(address tokenAddress, address from, address to, uint256 amount) internal returns (uint256) +error PostDeployFailed(bytes data) ``` -### \_giveInterchainToken +### ZeroAmount ```solidity -function _giveInterchainToken(address tokenAddress, address to, uint256 amount) internal +error ZeroAmount() ``` -### \_takeInterchainToken +### CannotDeploy ```solidity -function _takeInterchainToken(address tokenAddress, address from, uint256 amount) internal +error CannotDeploy(enum ITokenManagerType.TokenManagerType) ``` -### \_mintToken +### CannotDeployRemotelyToSelf ```solidity -function _mintToken(address tokenManager, address tokenAddress, address to, uint256 amount) internal +error CannotDeployRemotelyToSelf() ``` -### \_burnToken +### InvalidPayload ```solidity -function _burnToken(address tokenManager, address tokenAddress, address from, uint256 amount) internal +error InvalidPayload() ``` -### \_burnTokenFrom +### GatewayCallFailed ```solidity -function _burnTokenFrom(address tokenAddress, address from, uint256 amount) internal +error GatewayCallFailed(bytes data) ``` -## InterchainTokenExecutable - -Abstract contract that defines an interface for executing arbitrary logic -in the context of interchain token operations. +### EmptyTokenName -_This contract should be inherited by contracts that intend to execute custom -logic in response to interchain token actions such as transfers. This contract -will only be called by the interchain token service._ +```solidity +error EmptyTokenName() +``` -### NotService +### EmptyTokenSymbol ```solidity -error NotService(address caller) +error EmptyTokenSymbol() ``` -### interchainTokenService +### EmptyParams ```solidity -address interchainTokenService +error EmptyParams() ``` -### EXECUTE_SUCCESS +### EmptyDestinationAddress ```solidity -bytes32 EXECUTE_SUCCESS +error EmptyDestinationAddress() ``` -### constructor +### NotSupported ```solidity -constructor(address interchainTokenService_) internal +error NotSupported() ``` -Creates a new InterchainTokenExecutable contract. - -#### Parameters +### InterchainTransfer -| Name | Type | Description | -| ------------------------ | ------- | ------------------------------------------------------------------------- | -| interchainTokenService\_ | address | The address of the interchain token service that will call this contract. | +```solidity +event InterchainTransfer(bytes32 tokenId, address sourceAddress, string destinationChain, bytes destinationAddress, uint256 amount, bytes32 dataHash) +``` -### onlyService +### InterchainTransferReceived ```solidity -modifier onlyService() +event InterchainTransferReceived(bytes32 commandId, bytes32 tokenId, string sourceChain, bytes sourceAddress, address destinationAddress, uint256 amount, bytes32 dataHash) ``` -Modifier to restrict function execution to the interchain token service. +### TokenManagerDeploymentStarted -### executeWithInterchainToken +```solidity +event TokenManagerDeploymentStarted(bytes32 tokenId, string destinationChain, enum ITokenManagerType.TokenManagerType tokenManagerType, bytes params) +``` + +### InterchainTokenDeploymentStarted ```solidity -function executeWithInterchainToken(bytes32 commandId, string sourceChain, bytes sourceAddress, bytes data, bytes32 tokenId, address token, uint256 amount) external virtual returns (bytes32) +event InterchainTokenDeploymentStarted(bytes32 tokenId, string tokenName, string tokenSymbol, uint8 tokenDecimals, bytes minter, string destinationChain) ``` -Executes logic in the context of an interchain token transfer. +### TokenManagerDeployed -_Only callable by the interchain token service._ +```solidity +event TokenManagerDeployed(bytes32 tokenId, address tokenManager, enum ITokenManagerType.TokenManagerType tokenManagerType, bytes params) +``` -#### Parameters +### InterchainTokenDeployed -| Name | Type | Description | -| ------------- | ------- | -------------------------------------------- | -| commandId | bytes32 | The unique message id. | -| sourceChain | string | The source chain of the token transfer. | -| sourceAddress | bytes | The source address of the token transfer. | -| data | bytes | The data associated with the token transfer. | -| tokenId | bytes32 | The token ID. | -| token | address | The token address. | -| amount | uint256 | The amount of tokens being transferred. | +```solidity +event InterchainTokenDeployed(bytes32 tokenId, address tokenAddress, address minter, string name, string symbol, uint8 decimals) +``` -#### Return Values +### InterchainTokenIdClaimed -| Name | Type | Description | -| ---- | ------- | ------------------------------------------------- | -| [0] | bytes32 | bytes32 Hash indicating success of the execution. | +```solidity +event InterchainTokenIdClaimed(bytes32 tokenId, address deployer, bytes32 salt) +``` -### \_executeWithInterchainToken +### tokenManagerDeployer ```solidity -function _executeWithInterchainToken(bytes32 commandId, string sourceChain, bytes sourceAddress, bytes data, bytes32 tokenId, address token, uint256 amount) internal virtual +function tokenManagerDeployer() external view returns (address tokenManagerDeployerAddress) ``` -Internal function containing the logic to be executed with interchain token transfer. +Returns the address of the token manager deployer contract. -_Logic must be implemented by derived contracts._ +#### Return Values -#### Parameters +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenManagerDeployerAddress | address | The address of the token manager deployer contract. | -| Name | Type | Description | -| ------------- | ------- | -------------------------------------------- | -| commandId | bytes32 | The unique message id. | -| sourceChain | string | The source chain of the token transfer. | -| sourceAddress | bytes | The source address of the token transfer. | -| data | bytes | The data associated with the token transfer. | -| tokenId | bytes32 | The token ID. | -| token | address | The token address. | -| amount | uint256 | The amount of tokens being transferred. | +### interchainTokenDeployer -## InterchainTokenExpressExecutable +```solidity +function interchainTokenDeployer() external view returns (address interchainTokenDeployerAddress) +``` -Abstract contract that defines an interface for executing express logic in the context of interchain token operations. +Returns the address of the interchain token deployer contract. -_This contract extends `InterchainTokenExecutable` to provide express execution capabilities. It is intended to be inherited by contracts -that implement express logic for interchain token actions. This contract will only be called by the interchain token service._ +#### Return Values -### EXPRESS_EXECUTE_SUCCESS +| Name | Type | Description | +| ---- | ---- | ----------- | +| interchainTokenDeployerAddress | address | The address of the interchain token deployer contract. | + +### tokenManager ```solidity -bytes32 EXPRESS_EXECUTE_SUCCESS +function tokenManager() external view returns (address tokenManagerAddress_) ``` -### constructor +Returns the address of TokenManager implementation. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenManagerAddress_ | address | The address of the token manager contract. | + +### tokenHandler ```solidity -constructor(address interchainTokenService_) internal +function tokenHandler() external view returns (address tokenHandlerAddress) ``` -Creates a new InterchainTokenExpressExecutable contract. +Returns the address of TokenHandler implementation. -#### Parameters +#### Return Values -| Name | Type | Description | -| ------------------------ | ------- | ------------------------------------------------------------------------- | -| interchainTokenService\_ | address | The address of the interchain token service that will call this contract. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenHandlerAddress | address | The address of the token handler contract. | -### expressExecuteWithInterchainToken +### interchainTokenFactory ```solidity -function expressExecuteWithInterchainToken(bytes32 commandId, string sourceChain, bytes sourceAddress, bytes data, bytes32 tokenId, address token, uint256 amount) external virtual returns (bytes32) +function interchainTokenFactory() external view returns (address) ``` -Executes express logic in the context of an interchain token transfer. +Returns the address of the interchain token factory. -_Only callable by the interchain token service._ +#### Return Values -#### Parameters +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | address | address The address of the interchain token factory. | + +### chainNameHash + +```solidity +function chainNameHash() external view returns (bytes32) +``` -| Name | Type | Description | -| ------------- | ------- | -------------------------------------------- | -| commandId | bytes32 | The unique message id. | -| sourceChain | string | The source chain of the token transfer. | -| sourceAddress | bytes | The source address of the token transfer. | -| data | bytes | The data associated with the token transfer. | -| tokenId | bytes32 | The token ID. | -| token | address | The token address. | -| amount | uint256 | The amount of tokens to be transferred. | +Returns the hash of the chain name. #### Return Values -| Name | Type | Description | -| ---- | ------- | --------------------------------------------------------- | -| [0] | bytes32 | bytes32 Hash indicating success of the express execution. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 The hash of the chain name. | -## ERC20 +### tokenManagerAddress -\_Implementation of the {IERC20} interface. +```solidity +function tokenManagerAddress(bytes32 tokenId) external view returns (address tokenManagerAddress_) +``` -This implementation is agnostic to the way tokens are created. This means -that a supply mechanism has to be added in a derived contract using {\_mint}. -For a generic mechanism see {ERC20PresetMinterPauser}. +Returns the address of the token manager associated with the given tokenId. -TIP: For a detailed writeup see our guide -https://forum.zeppelin.solutions/t/how-to-implement-erc20-supply-mechanisms/226[How -to implement supply mechanisms]. +#### Parameters -We have followed general OpenZeppelin guidelines: functions revert instead -of returning `false` on failure. This behavior is nonetheless conventional -and does not conflict with the expectations of ERC20 applications. +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the token manager. | -Additionally, an {Approval} event is emitted on calls to {transferFrom}. -This allows applications to reconstruct the allowance for all accounts just -by listening to said events. Other implementations of the EIP may not emit -these events, as it isn't required by the specification. +#### Return Values -Finally, the non-standard {decreaseAllowance} and {increaseAllowance} -functions have been added to mitigate the well-known issues around setting -allowances. See {IERC20-approve}.\_ +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenManagerAddress_ | address | The address of the token manager. | -### balanceOf +### deployedTokenManager ```solidity -mapping(address => uint256) balanceOf +function deployedTokenManager(bytes32 tokenId) external view returns (contract ITokenManager tokenManager_) ``` -_Returns the amount of tokens owned by `account`._ +Returns the instance of ITokenManager from a specific tokenId. -### allowance +#### Parameters -```solidity -mapping(address => mapping(address => uint256)) allowance -``` +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the deployed token manager. | -\_Returns the remaining number of tokens that `spender` will be -allowed to spend on behalf of `owner` through {transferFrom}. This is -zero by default. +#### Return Values -This value changes when {approve} or {transferFrom} are called.\_ +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenManager_ | contract ITokenManager | The instance of ITokenManager associated with the specified tokenId. | -### totalSupply +### registeredTokenAddress ```solidity -uint256 totalSupply +function registeredTokenAddress(bytes32 tokenId) external view returns (address tokenAddress) ``` -_Returns the amount of tokens in existence._ +Returns the address of the token that an existing tokenManager points to. -### UINT256_MAX +#### Parameters -```solidity -uint256 UINT256_MAX -``` +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the registered token. | -### transfer +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress | address | The address of the token. | + +### interchainTokenAddress ```solidity -function transfer(address recipient, uint256 amount) external virtual returns (bool) +function interchainTokenAddress(bytes32 tokenId) external view returns (address tokenAddress) ``` -\_See {IERC20-transfer}. +Returns the address of the interchain token associated with the given tokenId. -Requirements: +#### Parameters -- `recipient` cannot be the zero address. -- the caller must have a balance of at least `amount`.\_ +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the interchain token. | -### approve +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress | address | The address of the interchain token. | + +### interchainTokenId ```solidity -function approve(address spender, uint256 amount) external virtual returns (bool) +function interchainTokenId(address operator_, bytes32 salt) external view returns (bytes32 tokenId) ``` -\_See {IERC20-approve}. +Returns the custom tokenId associated with the given operator and salt. -NOTE: If `amount` is the maximum `uint256`, the allowance is not updated on -`transferFrom`. This is semantically equivalent to an infinite approval. +#### Parameters -Requirements: +| Name | Type | Description | +| ---- | ---- | ----------- | +| operator_ | address | The operator address. | +| salt | bytes32 | The salt used for token id calculation. | -- `spender` cannot be the zero address.\_ +#### Return Values -### transferFrom +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The custom tokenId associated with the operator and salt. | + +### deployTokenManager ```solidity -function transferFrom(address sender, address recipient, uint256 amount) external virtual returns (bool) +function deployTokenManager(bytes32 salt, string destinationChain, enum ITokenManagerType.TokenManagerType tokenManagerType, bytes params, uint256 gasValue) external payable returns (bytes32 tokenId) ``` -\_See {IERC20-transferFrom}. +Deploys a custom token manager contract on a remote chain. -Emits an {Approval} event indicating the updated allowance. This is not -required by the EIP. See the note at the beginning of {ERC20}. +#### Parameters -Requirements: +| Name | Type | Description | +| ---- | ---- | ----------- | +| salt | bytes32 | The salt used for token manager deployment. | +| destinationChain | string | The name of the destination chain. | +| tokenManagerType | enum ITokenManagerType.TokenManagerType | The type of token manager. Cannot be NATIVE_INTERCHAIN_TOKEN. | +| params | bytes | The deployment parameters. | +| gasValue | uint256 | The gas value for deployment. | -- `sender` and `recipient` cannot be the zero address. -- `sender` must have a balance of at least `amount`. -- the caller must have allowance for `sender`'s tokens of at least - `amount`.\_ +#### Return Values -### increaseAllowance +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId associated with the token manager. | + +### deployInterchainToken ```solidity -function increaseAllowance(address spender, uint256 addedValue) external virtual returns (bool) +function deployInterchainToken(bytes32 salt, string destinationChain, string name, string symbol, uint8 decimals, bytes minter, uint256 gasValue) external payable returns (bytes32 tokenId) ``` -\_Atomically increases the allowance granted to `spender` by the caller. +Deploys and registers an interchain token on a remote chain. -This is an alternative to {approve} that can be used as a mitigation for -problems described in {IERC20-approve}. +#### Parameters -Emits an {Approval} event indicating the updated allowance. +| Name | Type | Description | +| ---- | ---- | ----------- | +| salt | bytes32 | The salt used for token deployment. | +| destinationChain | string | The name of the destination chain. Use '' for this chain. | +| name | string | The name of the interchain tokens. | +| symbol | string | The symbol of the interchain tokens. | +| decimals | uint8 | The number of decimals for the interchain tokens. | +| minter | bytes | The minter data for mint/burn operations. | +| gasValue | uint256 | The gas value for deployment. | -Requirements: +#### Return Values -- `spender` cannot be the zero address.\_ +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | -### decreaseAllowance +### interchainTransfer ```solidity -function decreaseAllowance(address spender, uint256 subtractedValue) external virtual returns (bool) +function interchainTransfer(bytes32 tokenId, string destinationChain, bytes destinationAddress, uint256 amount, bytes metadata, uint256 gasValue) external payable ``` -\_Atomically decreases the allowance granted to `spender` by the caller. +Initiates an interchain transfer of a specified token to a destination chain. -This is an alternative to {approve} that can be used as a mitigation for -problems described in {IERC20-approve}. +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The unique identifier of the token to be transferred. | +| destinationChain | string | The destination chain to send the tokens to. | +| destinationAddress | bytes | The address on the destination chain to send the tokens to. | +| amount | uint256 | The amount of tokens to be transferred. | +| metadata | bytes | Optional metadata for the call for additional effects (such as calling a destination contract). | +| gasValue | uint256 | | + +### callContractWithInterchainToken + +```solidity +function callContractWithInterchainToken(bytes32 tokenId, string destinationChain, bytes destinationAddress, uint256 amount, bytes data, uint256 gasValue) external payable +``` + +Initiates an interchain call contract with interchain token to a destination chain. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The unique identifier of the token to be transferred. | +| destinationChain | string | The destination chain to send the tokens to. | +| destinationAddress | bytes | The address on the destination chain to send the tokens to. | +| amount | uint256 | The amount of tokens to be transferred. | +| data | bytes | Additional data to be passed along with the transfer. | +| gasValue | uint256 | | + +### setFlowLimits + +```solidity +function setFlowLimits(bytes32[] tokenIds, uint256[] flowLimits) external +``` + +Sets the flow limits for multiple tokens. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenIds | bytes32[] | An array of tokenIds. | +| flowLimits | uint256[] | An array of flow limits corresponding to the tokenIds. | + +### flowLimit + +```solidity +function flowLimit(bytes32 tokenId) external view returns (uint256 flowLimit_) +``` + +Returns the flow limit for a specific token. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the token. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowLimit_ | uint256 | The flow limit for the token. | + +### flowOutAmount + +```solidity +function flowOutAmount(bytes32 tokenId) external view returns (uint256 flowOutAmount_) +``` + +Returns the total amount of outgoing flow for a specific token. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the token. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowOutAmount_ | uint256 | The total amount of outgoing flow for the token. | + +### flowInAmount + +```solidity +function flowInAmount(bytes32 tokenId) external view returns (uint256 flowInAmount_) +``` + +Returns the total amount of incoming flow for a specific token. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the token. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowInAmount_ | uint256 | The total amount of incoming flow for the token. | + +### setPauseStatus + +```solidity +function setPauseStatus(bool paused) external +``` + +Allows the owner to pause/unpause the token service. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| paused | bool | whether to pause or unpause. | + +## IInterchainTokenStandard + +_Interface of the ERC20 standard as defined in the EIP._ + +### interchainTransfer + +```solidity +function interchainTransfer(string destinationChain, bytes recipient, uint256 amount, bytes metadata) external payable +``` + +Implementation of the interchainTransfer method. + +_We chose to either pass `metadata` as raw data on a remote contract call, or if no data is passed, just do a transfer. +A different implementation could use metadata to specify a function to invoke, or for other purposes as well._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| destinationChain | string | The destination chain identifier. | +| recipient | bytes | The bytes representation of the address of the recipient. | +| amount | uint256 | The amount of token to be transferred. | +| metadata | bytes | Optional metadata for the call for additional effects (such as calling a destination contract). | + +### interchainTransferFrom + +```solidity +function interchainTransferFrom(address sender, string destinationChain, bytes recipient, uint256 amount, bytes metadata) external payable +``` + +Implementation of the interchainTransferFrom method + +_We chose to either pass `metadata` as raw data on a remote contract call, or, if no data is passed, just do a transfer. +A different implementation could use metadata to specify a function to invoke, or for other purposes as well._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| sender | address | The sender of the tokens. They need to have approved `msg.sender` before this is called. | +| destinationChain | string | The string representation of the destination chain. | +| recipient | bytes | The bytes representation of the address of the recipient. | +| amount | uint256 | The amount of token to be transferred. | +| metadata | bytes | Optional metadata for the call for additional effects (such as calling a destination contract.) | + +## IMinter + +An interface for a contract module which provides a basic access control mechanism, where +there is an account (a minter) that can be granted exclusive access to specific functions. + +### transferMintership + +```solidity +function transferMintership(address minter_) external +``` + +Change the minter of the contract. + +_Can only be called by the current minter._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| minter_ | address | The address of the new minter. | + +### proposeMintership + +```solidity +function proposeMintership(address minter_) external +``` + +Proposed a change of the minter of the contract. + +_Can only be called by the current minter._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| minter_ | address | The address of the new minter. | + +### acceptMintership + +```solidity +function acceptMintership(address fromMinter) external +``` + +Accept a change of the minter of the contract. + +_Can only be called by the proposed minter._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| fromMinter | address | The previous minter. | + +### isMinter + +```solidity +function isMinter(address addr) external view returns (bool) +``` + +Query if an address is a minter + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| addr | address | the address to query for | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | bool Boolean value representing whether or not the address is a minter. | + +## IOperator + +An interface for a contract module which provides a basic access control mechanism, where +there is an account (a operator) that can be granted exclusive access to specific functions. + +### transferOperatorship + +```solidity +function transferOperatorship(address operator_) external +``` + +Change the operator of the contract. + +_Can only be called by the current operator._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| operator_ | address | The address of the new operator. | + +### proposeOperatorship + +```solidity +function proposeOperatorship(address operator_) external +``` + +Proposed a change of the operator of the contract. + +_Can only be called by the current operator._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| operator_ | address | The address of the new operator. | + +### acceptOperatorship + +```solidity +function acceptOperatorship(address fromOperator) external +``` + +Accept a proposed change of operatorship. + +_Can only be called by the proposed operator._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| fromOperator | address | The previous operator of the contract. | + +### isOperator + +```solidity +function isOperator(address addr) external view returns (bool) +``` + +Query if an address is a operator. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| addr | address | The address to query for. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | bool Boolean value representing whether or not the address is an operator. | + +## ITokenManager + +This contract is responsible for managing tokens, such as setting locking token balances, or setting flow limits, for interchain transfers. + +### TokenLinkerZeroAddress + +```solidity +error TokenLinkerZeroAddress() +``` + +### NotService + +```solidity +error NotService(address caller) +``` + +### TakeTokenFailed + +```solidity +error TakeTokenFailed() +``` + +### GiveTokenFailed + +```solidity +error GiveTokenFailed() +``` + +### NotToken + +```solidity +error NotToken(address caller) +``` + +### ZeroAddress + +```solidity +error ZeroAddress() +``` + +### AlreadyFlowLimiter + +```solidity +error AlreadyFlowLimiter(address flowLimiter) +``` + +### NotFlowLimiter + +```solidity +error NotFlowLimiter(address flowLimiter) +``` + +### NotSupported + +```solidity +error NotSupported() +``` + +### implementationType + +```solidity +function implementationType() external view returns (uint256) +``` + +Returns implementation type of this token manager. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | uint256 The implementation type of this token manager. | + +### addFlowIn + +```solidity +function addFlowIn(uint256 amount) external +``` + +### addFlowOut + +```solidity +function addFlowOut(uint256 amount) external +``` + +### addFlowLimiter + +```solidity +function addFlowLimiter(address flowLimiter) external +``` + +This function adds a flow limiter for this TokenManager. + +_Can only be called by the operator._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowLimiter | address | the address of the new flow limiter. | + +### removeFlowLimiter + +```solidity +function removeFlowLimiter(address flowLimiter) external +``` + +This function removes a flow limiter for this TokenManager. -Emits an {Approval} event indicating the updated allowance. +_Can only be called by the operator._ -Requirements: +#### Parameters -- `spender` cannot be the zero address. -- `spender` must have allowance for the caller of at least - `subtractedValue`.\_ +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowLimiter | address | the address of an existing flow limiter. | -### \_transfer +### isFlowLimiter ```solidity -function _transfer(address sender, address recipient, uint256 amount) internal virtual +function isFlowLimiter(address addr) external view returns (bool) ``` -\_Moves tokens `amount` from `sender` to `recipient`. +Query if an address is a flow limiter. -This is internal function is equivalent to {transfer}, and can be used to -e.g. implement automatic token fees, slashing mechanisms, etc. +#### Parameters -Emits a {Transfer} event. +| Name | Type | Description | +| ---- | ---- | ----------- | +| addr | address | The address to query for. | -Requirements: +#### Return Values -- `sender` cannot be the zero address. -- `recipient` cannot be the zero address. -- `sender` must have a balance of at least `amount`.\_ +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | bool Boolean value representing whether or not the address is a flow limiter. | -### \_mint +### setFlowLimit ```solidity -function _mint(address account, uint256 amount) internal virtual +function setFlowLimit(uint256 flowLimit_) external ``` -\_Creates `amount` tokens and assigns them to `account`, increasing -the total supply. +This function sets the flow limit for this TokenManager. -Emits a {Transfer} event with `from` set to the zero address. +_Can only be called by the flow limiters._ -Requirements: +#### Parameters -- `to` cannot be the zero address.\_ +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowLimit_ | uint256 | The maximum difference between the tokens flowing in and/or out at any given interval of time (6h). | -### \_burn +### approveService ```solidity -function _burn(address account, uint256 amount) internal virtual +function approveService() external ``` -\_Destroys `amount` tokens from `account`, reducing the -total supply. - -Emits a {Transfer} event with `to` set to the zero address. - -Requirements: - -- `account` cannot be the zero address. -- `account` must have at least `amount` tokens.\_ +A function to renew approval to the service if we need to. -### \_approve +### params ```solidity -function _approve(address owner, address spender, uint256 amount) internal virtual +function params(bytes operator_, address tokenAddress_) external pure returns (bytes params_) ``` -\_Sets `amount` as the allowance of `spender` over the `owner` s tokens. - -This internal function is equivalent to `approve`, and can be used to -e.g. set automatic allowances for certain subsystems, etc. +Getter function for the parameters of a lock/unlock TokenManager. -Emits an {Approval} event. +_This function will be mainly used by frontends._ -Requirements: +#### Parameters -- `owner` cannot be the zero address. -- `spender` cannot be the zero address.\_ +| Name | Type | Description | +| ---- | ---- | ----------- | +| operator_ | bytes | The operator of the TokenManager. | +| tokenAddress_ | address | The token to be managed. | -## ERC20Permit +#### Return Values -_Extension of ERC20 to include permit functionality (EIP-2612). -Allows for approval of ERC20 tokens by signature rather than transaction._ +| Name | Type | Description | +| ---- | ---- | ----------- | +| params_ | bytes | The resulting params to be passed to custom TokenManager deployments. | -### PermitExpired +### mintToken ```solidity -error PermitExpired() +function mintToken(address tokenAddress_, address to, uint256 amount) external ``` -### InvalidS +External function to allow the service to mint tokens through the tokenManager -```solidity -error InvalidS() -``` +_This function should revert if called by anyone but the service._ -### InvalidV +#### Parameters -```solidity -error InvalidV() -``` +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress_ | address | The address of the token, since its cheaper to pass it in instead of reading it as the token manager. | +| to | address | The recipient. | +| amount | uint256 | The amount to mint. | -### InvalidSignature +### burnToken ```solidity -error InvalidSignature() +function burnToken(address tokenAddress_, address from, uint256 amount) external ``` -### nameHash +External function to allow the service to burn tokens through the tokenManager -```solidity -bytes32 nameHash -``` +_This function should revert if called by anyone but the service._ -_Represents hash of the EIP-712 Domain Separator._ +#### Parameters -### nonces +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress_ | address | The address of the token, since its cheaper to pass it in instead of reading it as the token manager. | +| from | address | The address to burn the token from. | +| amount | uint256 | The amount to burn. | -```solidity -mapping(address => uint256) nonces -``` +## ITokenManagerImplementation -_Mapping of nonces for each address._ +Interface for returning the token manager implementation type. -### \_setNameHash +### tokenManagerImplementation ```solidity -function _setNameHash(string name) internal +function tokenManagerImplementation(uint256 tokenManagerType) external view returns (address tokenManagerAddress_) ``` -Internal function to set the token name hash +Returns the implementation address for a given token manager type. #### Parameters -| Name | Type | Description | -| ---- | ------ | -------------- | -| name | string | The token name | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenManagerType | uint256 | The type of token manager. | -### DOMAIN_SEPARATOR +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenManagerAddress_ | address | The address of the token manager implementation. | + +## ITokenManagerType + +A simple interface that defines all the token manager types. + +### TokenManagerType ```solidity -function DOMAIN_SEPARATOR() public view returns (bytes32) +enum TokenManagerType { + NATIVE_INTERCHAIN_TOKEN, + MINT_BURN_FROM, + LOCK_UNLOCK, + LOCK_UNLOCK_FEE, + MINT_BURN +} ``` -Calculates the domain separator. +## ITransmitInterchainToken -_This is not cached because chainid can change on chain forks._ +Interface for transmiting interchain tokens via the interchain token service -### permit +### transmitInterchainTransfer ```solidity -function permit(address issuer, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) external +function transmitInterchainTransfer(bytes32 tokenId, address sourceAddress, string destinationChain, bytes destinationAddress, uint256 amount, bytes metadata) external payable ``` -Permit the designated spender to spend the holder's tokens +Transmit an interchain transfer for the given tokenId. -_The permit function is used to allow a holder to designate a spender -to spend tokens on their behalf via a signed message._ +_Only callable by a token registered under a tokenId._ #### Parameters -| Name | Type | Description | -| -------- | ------- | ------------------------------------------------- | -| issuer | address | The address of the token holder | -| spender | address | The address of the designated spender | -| value | uint256 | The number of tokens to be spent | -| deadline | uint256 | The time at which the permission to spend expires | -| v | uint8 | The recovery id of the signature | -| r | bytes32 | Half of the ECDSA signature pair | -| s | bytes32 | Half of the ECDSA signature pair | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the token (which must be the msg.sender). | +| sourceAddress | address | The address where the token is coming from. | +| destinationChain | string | The name of the chain to send tokens to. | +| destinationAddress | bytes | The destinationAddress for the interchainTransfer. | +| amount | uint256 | The amount of token to give. | +| metadata | bytes | Optional metadata for the call for additional effects (such as calling a destination contract). | -## InterchainToken +## InterchainTokenService -This contract implements an interchain token which extends InterchainToken functionality. +This contract is responsible for facilitating interchain token transfers. +It (mostly) does not handle tokens, but is responsible for the messaging that needs to occur for interchain transfers to happen. -_This contract also inherits Minter and Implementation logic._ +_The only storage used in this contract is for Express calls. +Furthermore, no ether is intended to or should be sent to this contract except as part of deploy/interchainTransfer payable methods for gas payment._ -### name +### gateway ```solidity -string name +contract IAxelarGateway gateway ``` -Getter for the name of the token. +_There are two types of Axelar Gateways for cross-chain messaging: +1. Cross-chain messaging (GMP): The Axelar Gateway allows sending cross-chain messages. + This is compatible across both Amplifier and consensus chains. IAxelarGateway interface exposes this functionality. +2. Cross-chain messaging with Gateway Token: The AxelarGateway on legacy consensus EVM connections supports this (via callContractWithToken) + but not Amplifier chains. The gateway is cast to IAxelarGatewayWithToken when gateway tokens need to be handled. + ITS deployments on Amplifier chains will revert when this functionality is used._ -#### Return Values +### gasService -| Name | Type | Description | -| ---- | ---- | ----------- | +```solidity +contract IAxelarGasService gasService +``` -### symbol +### interchainTokenFactory ```solidity -string symbol +address interchainTokenFactory ``` -Getter for the symbol of the token. +Returns the address of the interchain token factory. #### Return Values | Name | Type | Description | | ---- | ---- | ----------- | -### decimals +### chainNameHash ```solidity -uint8 decimals +bytes32 chainNameHash ``` -Getter for the decimals of the token. +Returns the hash of the chain name. #### Return Values | Name | Type | Description | | ---- | ---- | ----------- | -### tokenId - -```solidity -bytes32 tokenId -``` - -### interchainTokenService\_ - -```solidity -address interchainTokenService_ -``` - -### INITIALIZED_SLOT +### interchainTokenDeployer ```solidity -bytes32 INITIALIZED_SLOT +address interchainTokenDeployer ``` -### constructor - -```solidity -constructor(address interchainTokenServiceAddress) public -``` +Returns the address of the interchain token deployer contract. -Constructs the InterchainToken contract. +#### Return Values -_Makes the implementation act as if it has been setup already to disallow calls to init() (even though that would not achieve anything really)._ +| Name | Type | Description | +| ---- | ---- | ----------- | -### \_isInitialized +### tokenManagerDeployer ```solidity -function _isInitialized() internal view returns (bool initialized) +address tokenManagerDeployer ``` -Returns true if the contract has been setup. +Returns the address of the token manager deployer contract. #### Return Values -| Name | Type | Description | -| ----------- | ---- | ----------------------------------------------------- | -| initialized | bool | True if the contract has been setup, false otherwise. | +| Name | Type | Description | +| ---- | ---- | ----------- | -### \_initialize +### tokenManager ```solidity -function _initialize() internal +address tokenManager ``` -Sets initialized to true, to allow only a single init. +_Token manager implementation addresses_ -### interchainTokenService +### tokenHandler ```solidity -function interchainTokenService() public view returns (address) +address tokenHandler ``` -Returns the interchain token service +Returns the address of TokenHandler implementation. #### Return Values -| Name | Type | Description | -| ---- | ------- | --------------------------------------------- | -| [0] | address | address The interchain token service contract | +| Name | Type | Description | +| ---- | ---- | ----------- | -### interchainTokenId +### gatewayCaller ```solidity -function interchainTokenId() public view returns (bytes32) +address gatewayCaller ``` -Returns the tokenId for this token. - -#### Return Values - -| Name | Type | Description | -| ---- | ------- | ----------------------------------- | -| [0] | bytes32 | bytes32 The token manager contract. | - -### init +### PREFIX_INTERCHAIN_TOKEN_ID ```solidity -function init(bytes32 tokenId_, address minter, string tokenName, string tokenSymbol, uint8 tokenDecimals) external +bytes32 PREFIX_INTERCHAIN_TOKEN_ID ``` -Setup function to initialize contract parameters. - -#### Parameters - -| Name | Type | Description | -| ------------- | ------- | -------------------------------- | -| tokenId\_ | bytes32 | The tokenId of the token. | -| minter | address | The address of the token minter. | -| tokenName | string | The name of the token. | -| tokenSymbol | string | The symbopl of the token. | -| tokenDecimals | uint8 | The decimals of the token. | - -### mint +### PREFIX_INTERCHAIN_TOKEN_SALT ```solidity -function mint(address account, uint256 amount) external +bytes32 PREFIX_INTERCHAIN_TOKEN_SALT ``` -Function to mint new tokens. - -_Can only be called by the minter address._ - -#### Parameters - -| Name | Type | Description | -| ------- | ------- | ------------------------------------------------ | -| account | address | The address that will receive the minted tokens. | -| amount | uint256 | The amount of tokens to mint. | - -### burn +### TOKEN_FACTORY_DEPLOYER ```solidity -function burn(address account, uint256 amount) external +address TOKEN_FACTORY_DEPLOYER ``` -Function to burn tokens. - -_Can only be called by the minter address._ - -#### Parameters - -| Name | Type | Description | -| ------- | ------- | -------------------------------------------- | -| account | address | The address that will have its tokens burnt. | -| amount | uint256 | The amount of tokens to burn. | +_Tokens and token managers deployed via the Token Factory contract use a special deployer address. +This removes the dependency on the address the token factory was deployed too to be able to derive the same tokenId._ -### \_spendAllowance +### LATEST_METADATA_VERSION ```solidity -function _spendAllowance(address sender, address spender, uint256 amount) internal +uint32 LATEST_METADATA_VERSION ``` -A method to be overwritten that will decrease the allowance of the `spender` from `sender` by `amount`. +_Latest version of metadata that's supported._ -_Needs to be overwritten. This provides flexibility for the choice of ERC20 implementation used. Must revert if allowance is not sufficient._ +### ITS_HUB_CHAIN_NAME -## InterchainTokenStandard +```solidity +string ITS_HUB_CHAIN_NAME +``` -The is an abstract contract that needs to be extended with an ERC20 implementation. See `InterchainToken` for an example implementation. +_Chain name where ITS Hub exists. This is used for routing ITS calls via ITS hub. +This is set as a constant, since the ITS Hub will exist on Axelar._ -### interchainTokenId +### ITS_HUB_CHAIN_NAME_HASH ```solidity -function interchainTokenId() public view virtual returns (bytes32 tokenId_) +bytes32 ITS_HUB_CHAIN_NAME_HASH ``` -Getter for the tokenId used for this token. +### ITS_HUB_ROUTING_IDENTIFIER -_Needs to be overwritten._ +```solidity +string ITS_HUB_ROUTING_IDENTIFIER +``` -#### Return Values +_Special identifier that the trusted address for a chain should be set to, which indicates if the ITS call +for that chain should be routed via the ITS hub._ -| Name | Type | Description | -| --------- | ------- | ------------------------------------------------- | -| tokenId\_ | bytes32 | The tokenId that this token is registerred under. | +### ITS_HUB_ROUTING_IDENTIFIER_HASH -### interchainTokenService +```solidity +bytes32 ITS_HUB_ROUTING_IDENTIFIER_HASH +``` + +### constructor ```solidity -function interchainTokenService() public view virtual returns (address service) +constructor(address tokenManagerDeployer_, address interchainTokenDeployer_, address gateway_, address gasService_, address interchainTokenFactory_, string chainName_, address tokenManagerImplementation_, address tokenHandler_, address gatewayCaller_) public ``` -Getter for the interchain token service. +Constructor for the Interchain Token Service. -_Needs to be overwritten._ +_All of the variables passed here are stored as immutable variables._ -#### Return Values +#### Parameters -| Name | Type | Description | -| ------- | ------- | -------------------------------------------- | -| service | address | The address of the interchain token service. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenManagerDeployer_ | address | The address of the TokenManagerDeployer. | +| interchainTokenDeployer_ | address | The address of the InterchainTokenDeployer. | +| gateway_ | address | The address of the AxelarGateway. | +| gasService_ | address | The address of the AxelarGasService. | +| interchainTokenFactory_ | address | The address of the InterchainTokenFactory. | +| chainName_ | string | The name of the chain that this contract is deployed on. | +| tokenManagerImplementation_ | address | The tokenManager implementation. | +| tokenHandler_ | address | The tokenHandler implementation. | +| gatewayCaller_ | address | The gatewayCaller implementation. | -### interchainTransfer +### onlyRemoteService ```solidity -function interchainTransfer(string destinationChain, bytes recipient, uint256 amount, bytes metadata) external payable +modifier onlyRemoteService(string sourceChain, string sourceAddress) ``` -Implementation of the interchainTransfer method - -_We chose to either pass `metadata` as raw data on a remote contract call, or if no data is passed, just do a transfer. -A different implementation could use metadata to specify a function to invoke, or for other purposes as well._ +This modifier is used to ensure that only a remote InterchainTokenService can invoke the execute function. #### Parameters -| Name | Type | Description | -| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| destinationChain | string | The destination chain identifier. | -| recipient | bytes | The bytes representation of the address of the recipient. | -| amount | uint256 | The amount of token to be transferred. | -| metadata | bytes | Either empty, just to facilitate an interchain transfer, or the data to be passed for an interchain contract call with transfer as per semantics defined by the token service. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| sourceChain | string | The source chain of the contract call. | +| sourceAddress | string | The source address that the call came from. | -### interchainTransferFrom +### contractId ```solidity -function interchainTransferFrom(address sender, string destinationChain, bytes recipient, uint256 amount, bytes metadata) external payable +function contractId() external pure returns (bytes32) ``` -Implementation of the interchainTransferFrom method - -_We chose to either pass `metadata` as raw data on a remote contract call, or, if no data is passed, just do a transfer. -A different implementation could use metadata to specify a function to invoke, or for other purposes as well._ +Getter for the contract id. -#### Parameters +#### Return Values -| Name | Type | Description | -| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | -| sender | address | The sender of the tokens. They need to have approved `msg.sender` before this is called. | -| destinationChain | string | The string representation of the destination chain. | -| recipient | bytes | The bytes representation of the address of the recipient. | -| amount | uint256 | The amount of token to be transferred. | -| metadata | bytes | Either empty, just to facilitate an interchain transfer, or the data to be passed to an interchain contract call and transfer. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 The contract id of this contract. | -### \_beforeInterchainTransfer +### tokenManagerAddress ```solidity -function _beforeInterchainTransfer(address from, string destinationChain, bytes destinationAddress, uint256 amount, bytes metadata) internal virtual +function tokenManagerAddress(bytes32 tokenId) public view returns (address tokenManagerAddress_) ``` -A method to be overwritten that will be called before an interchain transfer. One can approve the tokenManager here if needed, -to allow users for a 1-call transfer in case of a lock-unlock token manager. +Calculates the address of a TokenManager from a specific tokenId. + +_The TokenManager does not need to exist already._ #### Parameters -| Name | Type | Description | -| ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------ | -| from | address | The sender of the tokens. They need to have approved `msg.sender` before this is called. | -| destinationChain | string | The string representation of the destination chain. | -| destinationAddress | bytes | The bytes representation of the address of the recipient. | -| amount | uint256 | The amount of token to be transferred. | -| metadata | bytes | Either empty, just to facilitate an interchain transfer, or the data to be passed to an interchain contract call and transfer. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenManagerAddress_ | address | The deployment address of the TokenManager. | -### \_spendAllowance +### deployedTokenManager ```solidity -function _spendAllowance(address sender, address spender, uint256 amount) internal virtual +function deployedTokenManager(bytes32 tokenId) public view returns (contract ITokenManager tokenManager_) ``` -A method to be overwritten that will decrease the allowance of the `spender` from `sender` by `amount`. +Returns the instance of ITokenManager from a specific tokenId. -_Needs to be overwritten. This provides flexibility for the choice of ERC20 implementation used. Must revert if allowance is not sufficient._ +_This function checks if a token manager contract exists at the address for the specified tokenId. +If no token manager is deployed for the tokenId, the function will revert with `TokenManagerDoesNotExist`._ -## IAddressTracker +#### Parameters -This interface allows setting and removing a trusted address for a specific chain. +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the deployed token manager. | -_Extends the IInterchainAddressTracker interface._ +#### Return Values -### setTrustedAddress +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenManager_ | contract ITokenManager | The instance of ITokenManager associated with the specified tokenId. | + +### registeredTokenAddress ```solidity -function setTrustedAddress(string chain, string address_) external +function registeredTokenAddress(bytes32 tokenId) public view returns (address tokenAddress) ``` -Sets the trusted address for the specified chain. +Returns the address of the token that an existing tokenManager points to. + +_This function requires that a token manager is already deployed for the specified tokenId. +It will call `deployedTokenManager` to get the token manager and return the address of the associated token._ #### Parameters -| Name | Type | Description | -| --------- | ------ | ------------------------------------------ | -| chain | string | Chain name to be trusted. | -| address\_ | string | Trusted address to be added for the chain. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the registered token. | -### removeTrustedAddress +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress | address | The address of the token. | + +### interchainTokenAddress ```solidity -function removeTrustedAddress(string chain) external +function interchainTokenAddress(bytes32 tokenId) public view returns (address tokenAddress) ``` -Remove the trusted address of the chain. +Returns the address of the interchain token associated with the given tokenId. + +_The token does not need to exist._ #### Parameters -| Name | Type | Description | -| ----- | ------ | --------------------------------------------- | -| chain | string | Chain name to remove the trusted address for. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the interchain token. | -## IBaseTokenManager +#### Return Values -This contract is defines the base token manager interface implemented by all token managers. +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress | address | The address of the interchain token. | ### interchainTokenId ```solidity -function interchainTokenId() external view returns (bytes32) +function interchainTokenId(address sender, bytes32 salt) public pure returns (bytes32 tokenId) ``` -A function that returns the token id. - -### tokenAddress +Calculates the tokenId that would correspond to a link for a given deployer with a specified salt. -```solidity -function tokenAddress() external view returns (address) -``` +#### Parameters -A function that should return the address of the token. -Must be overridden in the inheriting contract. +| Name | Type | Description | +| ---- | ---- | ----------- | +| sender | address | The address of the TokenManager deployer. | +| salt | bytes32 | The salt that the deployer uses for the deployment. | #### Return Values -| Name | Type | Description | -| ---- | ------- | ----------------------------- | -| [0] | address | address address of the token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId that the custom TokenManager would get (or has gotten). | -### getTokenAddressFromParams +### tokenManagerImplementation ```solidity -function getTokenAddressFromParams(bytes params) external pure returns (address) +function tokenManagerImplementation(uint256) external view returns (address) ``` -A function that should return the token address from the init params. +Getter function for TokenManager implementation. This will mainly be called by TokenManager proxies +to figure out their implementations. -## IERC20BurnableFrom +#### Return Values -Interface of the ERC20 standard as defined in the EIP. +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | address | tokenManagerAddress The address of the TokenManager implementation. | -### burnFrom +### flowLimit ```solidity -function burnFrom(address from, uint256 amount) external +function flowLimit(bytes32 tokenId) external view returns (uint256 flowLimit_) ``` -Function to burn tokens. - -_Requires the caller to have allowance for `amount` on `from`. -Can only be called by the minter address._ +Getter function for the flow limit of an existing TokenManager with a given tokenId. #### Parameters -| Name | Type | Description | -| ------ | ------- | -------------------------------------------- | -| from | address | The address that will have its tokens burnt. | -| amount | uint256 | The amount of tokens to burn. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the TokenManager. | -## IERC20MintableBurnable +#### Return Values -_Interface of the ERC20 standard as defined in the EIP._ +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowLimit_ | uint256 | The flow limit. | -### mint +### flowOutAmount ```solidity -function mint(address to, uint256 amount) external +function flowOutAmount(bytes32 tokenId) external view returns (uint256 flowOutAmount_) ``` -Function to mint new tokens. - -_Can only be called by the minter address._ +Getter function for the flow out amount of an existing TokenManager with a given tokenId. #### Parameters -| Name | Type | Description | -| ------ | ------- | ------------------------------------------------ | -| to | address | The address that will receive the minted tokens. | -| amount | uint256 | The amount of tokens to mint. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the TokenManager. | + +#### Return Values -### burn +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowOutAmount_ | uint256 | The flow out amount. | + +### flowInAmount ```solidity -function burn(address from, uint256 amount) external +function flowInAmount(bytes32 tokenId) external view returns (uint256 flowInAmount_) ``` -Function to burn tokens. - -_Can only be called by the minter address._ +Getter function for the flow in amount of an existing TokenManager with a given tokenId. #### Parameters -| Name | Type | Description | -| ------ | ------- | -------------------------------------------- | -| from | address | The address that will have its tokens burnt. | -| amount | uint256 | The amount of tokens to burn. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the TokenManager. | -## IERC20Named +#### Return Values -_Interface of the ERC20 standard as defined in the EIP._ +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowInAmount_ | uint256 | The flow in amount. | -### name +### deployTokenManager ```solidity -function name() external view returns (string) +function deployTokenManager(bytes32 salt, string destinationChain, enum ITokenManagerType.TokenManagerType tokenManagerType, bytes params, uint256 gasValue) external payable returns (bytes32 tokenId) ``` -Getter for the name of the token. - -#### Return Values - -| Name | Type | Description | -| ---- | ------ | ------------------------- | -| [0] | string | string Name of the token. | +Used to deploy remote custom TokenManagers. -### symbol +_At least the `gasValue` amount of native token must be passed to the function call. `gasValue` exists because this function can be +part of a multicall involving multiple functions that could make remote contract calls. +This method is temporarily restricted in the following scenarios: +- Deploying to a remote chain and the destination chain is connected via ITS Hub +- Deploying to the current chain, if connected as an Amplifier chain, i.e existing ITS contracts on consensus chains aren't affected. +Once ITS Hub adds support for deploy token manager msg, the restriction will be lifted. +Note that the factory contract can still call `deployTokenManager` to facilitate canonical token registration._ -```solidity -function symbol() external view returns (string) -``` +#### Parameters -Getter for the symbol of the token. +| Name | Type | Description | +| ---- | ---- | ----------- | +| salt | bytes32 | The salt to be used during deployment. | +| destinationChain | string | The name of the chain to deploy the TokenManager and standardized token to. | +| tokenManagerType | enum ITokenManagerType.TokenManagerType | The type of token manager to be deployed. Cannot be NATIVE_INTERCHAIN_TOKEN. | +| params | bytes | The params that will be used to initialize the TokenManager. | +| gasValue | uint256 | The amount of native tokens to be used to pay for gas for the remote deployment. | #### Return Values -| Name | Type | Description | -| ---- | ------ | ------------------------------- | -| [0] | string | string The symbol of the token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId corresponding to the deployed TokenManager. | -### decimals +### deployInterchainToken ```solidity -function decimals() external view returns (uint8) +function deployInterchainToken(bytes32 salt, string destinationChain, string name, string symbol, uint8 decimals, bytes minter, uint256 gasValue) external payable returns (bytes32 tokenId) ``` -Getter for the decimals of the token. - -#### Return Values +Used to deploy an interchain token alongside a TokenManager in another chain. -| Name | Type | Description | -| ---- | ----- | -------------------------------- | -| [0] | uint8 | uint8 The decimals of the token. | +_At least the `gasValue` amount of native token must be passed to the function call. `gasValue` exists because this function can be +part of a multicall involving multiple functions that could make remote contract calls. +If minter is empty bytes, no additional minter is set on the token, only ITS is allowed to mint. +If the token is being deployed on the current chain, minter should correspond to an EVM address (as bytes). +Otherwise, an encoding appropriate to the destination chain should be used._ -## IFlowLimit +#### Parameters -Interface for flow limit logic for interchain token transfers. +| Name | Type | Description | +| ---- | ---- | ----------- | +| salt | bytes32 | The salt to be used during deployment. | +| destinationChain | string | The name of the destination chain to deploy to. | +| name | string | The name of the token to be deployed. | +| symbol | string | The symbol of the token to be deployed. | +| decimals | uint8 | The decimals of the token to be deployed. | +| minter | bytes | The address that will be able to mint and burn the deployed token. | +| gasValue | uint256 | The amount of native tokens to be used to pay for gas for the remote deployment. | -### FlowLimitExceeded +#### Return Values -```solidity -error FlowLimitExceeded(uint256 limit, uint256 flowAmount, address tokenManager) -``` +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | -### FlowLimitSet +### contractCallValue ```solidity -event FlowLimitSet(bytes32 tokenId, address operator, uint256 flowLimit_) +function contractCallValue(string sourceChain, string sourceAddress, bytes payload) public view virtual returns (address, uint256) ``` -### flowLimit +Returns the amount of token that this call is worth. -```solidity -function flowLimit() external view returns (uint256 flowLimit_) -``` +_If `tokenAddress` is `0`, then value is in terms of the native token, otherwise it's in terms of the token address._ + +#### Parameters -Returns the current flow limit. +| Name | Type | Description | +| ---- | ---- | ----------- | +| sourceChain | string | The source chain. | +| sourceAddress | string | The source address on the source chain. | +| payload | bytes | The payload sent with the call. | #### Return Values -| Name | Type | Description | -| ----------- | ------- | ----------------------------- | -| flowLimit\_ | uint256 | The current flow limit value. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | address | address The token address. | +| [1] | uint256 | uint256 The value the call is worth. | -### flowOutAmount +### expressExecute ```solidity -function flowOutAmount() external view returns (uint256 flowOutAmount_) +function expressExecute(bytes32 commandId, string sourceChain, string sourceAddress, bytes payload) public payable ``` -Returns the current flow out amount. +Express executes operations based on the payload and selector. -#### Return Values +_This function is `payable` because non-payable functions cannot be called in a multicall that calls other `payable` functions._ -| Name | Type | Description | -| --------------- | ------- | ---------------------------- | -| flowOutAmount\_ | uint256 | The current flow out amount. | +#### Parameters -### flowInAmount +| Name | Type | Description | +| ---- | ---- | ----------- | +| commandId | bytes32 | The unique message id. | +| sourceChain | string | The chain where the transaction originates from. | +| sourceAddress | string | The address of the remote ITS where the transaction originates from. | +| payload | bytes | The encoded data payload for the transaction. | + +### getExpressExecutor ```solidity -function flowInAmount() external view returns (uint256 flowInAmount_) +function getExpressExecutor(bytes32 commandId, string sourceChain, string sourceAddress, bytes32 payloadHash) external view returns (address expressExecutor) ``` -Returns the current flow in amount. +Returns the express executor for a given command. -#### Return Values +#### Parameters -| Name | Type | Description | -| -------------- | ------- | --------------------------- | -| flowInAmount\_ | uint256 | The current flow in amount. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| commandId | bytes32 | The commandId for the contractCall. | +| sourceChain | string | The source chain. | +| sourceAddress | string | The source address. | +| payloadHash | bytes32 | The hash of the payload. | -## IInterchainToken +#### Return Values -_Extends IInterchainTokenStandard and IMinter._ +| Name | Type | Description | +| ---- | ---- | ----------- | +| expressExecutor | address | The address of the express executor. | -### InterchainTokenServiceAddressZero +### _expressExecute ```solidity -error InterchainTokenServiceAddressZero() +function _expressExecute(bytes32 commandId, string sourceChain, bytes payload) internal ``` -### TokenIdZero +Uses the caller's tokens to fullfill a sendCall ahead of time. Use this only if you have detected an outgoing +interchainTransfer that matches the parameters passed here. -```solidity -error TokenIdZero() -``` +#### Parameters -### TokenNameEmpty +| Name | Type | Description | +| ---- | ---- | ----------- | +| commandId | bytes32 | The unique message id of the transfer being expressed. | +| sourceChain | string | the name of the chain where the interchainTransfer originated from. | +| payload | bytes | the payload of the receive token | + +### interchainTransfer ```solidity -error TokenNameEmpty() +function interchainTransfer(bytes32 tokenId, string destinationChain, bytes destinationAddress, uint256 amount, bytes metadata, uint256 gasValue) external payable ``` -### TokenSymbolEmpty +Initiates an interchain transfer of a specified token to a destination chain. -```solidity -error TokenSymbolEmpty() -``` +_The function retrieves the TokenManager associated with the tokenId._ -### AlreadyInitialized +#### Parameters -```solidity -error AlreadyInitialized() -``` +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The unique identifier of the token to be transferred. | +| destinationChain | string | The destination chain to send the tokens to. | +| destinationAddress | bytes | The address on the destination chain to send the tokens to. | +| amount | uint256 | The amount of tokens to be transferred. | +| metadata | bytes | Optional metadata for the call for additional effects (such as calling a destination contract). | +| gasValue | uint256 | | -### interchainTokenService +### callContractWithInterchainToken ```solidity -function interchainTokenService() external view returns (address interchainTokenServiceAddress) +function callContractWithInterchainToken(bytes32 tokenId, string destinationChain, bytes destinationAddress, uint256 amount, bytes data, uint256 gasValue) external payable ``` -Getter for the interchain token service contract. - -_Needs to be overwitten._ +Initiates an interchain call contract with interchain token to a destination chain. -#### Return Values +#### Parameters -| Name | Type | Description | -| ----------------------------- | ------- | ------------------------------------- | -| interchainTokenServiceAddress | address | The interchain token service address. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The unique identifier of the token to be transferred. | +| destinationChain | string | The destination chain to send the tokens to. | +| destinationAddress | bytes | The address on the destination chain to send the tokens to. | +| amount | uint256 | The amount of tokens to be transferred. | +| data | bytes | Additional data to be passed along with the transfer. | +| gasValue | uint256 | | -### interchainTokenId +### transmitInterchainTransfer ```solidity -function interchainTokenId() external view returns (bytes32 tokenId_) +function transmitInterchainTransfer(bytes32 tokenId, address sourceAddress, string destinationChain, bytes destinationAddress, uint256 amount, bytes metadata) external payable ``` -Getter for the tokenId used for this token. +Transmit an interchain transfer for the given tokenId. -_Needs to be overwitten._ +_Only callable by a token registered under a tokenId._ -#### Return Values +#### Parameters -| Name | Type | Description | -| --------- | ------- | --------------------------- | -| tokenId\_ | bytes32 | The tokenId for this token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the token (which must be the msg.sender). | +| sourceAddress | address | The address where the token is coming from. | +| destinationChain | string | The name of the chain to send tokens to. | +| destinationAddress | bytes | The destinationAddress for the interchainTransfer. | +| amount | uint256 | The amount of token to give. | +| metadata | bytes | Optional metadata for the call for additional effects (such as calling a destination contract). | -### init +### setFlowLimits ```solidity -function init(bytes32 tokenId_, address minter, string tokenName, string tokenSymbol, uint8 tokenDecimals) external +function setFlowLimits(bytes32[] tokenIds, uint256[] flowLimits) external ``` -Setup function to initialize contract parameters. +Used to set a flow limit for a token manager that has the service as its operator. #### Parameters -| Name | Type | Description | -| ------------- | ------- | -------------------------------- | -| tokenId\_ | bytes32 | The tokenId of the token. | -| minter | address | The address of the token minter. | -| tokenName | string | The name of the token. | -| tokenSymbol | string | The symbopl of the token. | -| tokenDecimals | uint8 | The decimals of the token. | - -## IInterchainTokenDeployer - -This interface is used to deploy new instances of the InterchainTokenProxy contract. +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenIds | bytes32[] | An array of the tokenIds of the tokenManagers to set the flow limits of. | +| flowLimits | uint256[] | The flowLimits to set. | -### AddressZero +### setTrustedAddress ```solidity -error AddressZero() +function setTrustedAddress(string chain, string address_) external ``` -### TokenDeploymentFailed +Used to set a trusted address for a chain. -```solidity -error TokenDeploymentFailed() -``` +#### Parameters -### implementationAddress +| Name | Type | Description | +| ---- | ---- | ----------- | +| chain | string | The chain to set the trusted address of. | +| address_ | string | The address to set as trusted. | + +### removeTrustedAddress ```solidity -function implementationAddress() external view returns (address) +function removeTrustedAddress(string chain) external ``` -Returns the interchain token implementation address. +Used to remove a trusted address for a chain. -#### Return Values +#### Parameters -| Name | Type | Description | -| ---- | ------- | ---------------------------------------------------- | -| [0] | address | address The interchain token implementation address. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| chain | string | The chain to set the trusted address of. | -### deployedAddress +### setPauseStatus ```solidity -function deployedAddress(bytes32 salt) external view returns (address tokenAddress) +function setPauseStatus(bool paused) external ``` -Returns the interchain token deployment address. +Allows the owner to pause/unpause the token service. #### Parameters -| Name | Type | Description | -| ---- | ------- | -------------------- | -| salt | bytes32 | The deployment salt. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| paused | bool | Boolean value representing whether to pause or unpause. | -#### Return Values +### _setup -| Name | Type | Description | -| ------------ | ------- | ------------------ | -| tokenAddress | address | The token address. | +```solidity +function _setup(bytes params) internal +``` -### deployInterchainToken +### execute ```solidity -function deployInterchainToken(bytes32 salt, bytes32 tokenId, address minter, string name, string symbol, uint8 decimals) external returns (address tokenAddress) +function execute(bytes32 commandId, string sourceChain, string sourceAddress, bytes payload) external ``` -Deploys a new instance of the InterchainTokenProxy contract. +Executes operations based on the payload and selector. #### Parameters -| Name | Type | Description | -| -------- | ------- | --------------------------------- | -| salt | bytes32 | The salt used by Create3Deployer. | -| tokenId | bytes32 | tokenId of the token. | -| minter | address | Address of the minter. | -| name | string | Name of the token. | -| symbol | string | Symbol of the token. | -| decimals | uint8 | Decimals of the token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| commandId | bytes32 | The unique message id. | +| sourceChain | string | The chain where the transaction originates from. | +| sourceAddress | string | The address of the remote ITS where the transaction originates from. | +| payload | bytes | The encoded data payload for the transaction. | -#### Return Values +### _processInterchainTransferPayload -| Name | Type | Description | -| ------------ | ------- | ------------------------------ | -| tokenAddress | address | Address of the deployed token. | +```solidity +function _processInterchainTransferPayload(bytes32 commandId, address expressExecutor, string sourceChain, bytes payload) internal +``` -## IInterchainTokenExecutable +Processes the payload data for a send token call. -Contracts should implement this interface to accept calls from the InterchainTokenService. +#### Parameters -### executeWithInterchainToken +| Name | Type | Description | +| ---- | ---- | ----------- | +| commandId | bytes32 | The unique message id. | +| expressExecutor | address | The address of the express executor. Equals `address(0)` if it wasn't expressed. | +| sourceChain | string | The chain where the transaction originates from. | +| payload | bytes | The encoded data payload to be processed. | + +### _processDeployTokenManagerPayload ```solidity -function executeWithInterchainToken(bytes32 commandId, string sourceChain, bytes sourceAddress, bytes data, bytes32 tokenId, address token, uint256 amount) external returns (bytes32) +function _processDeployTokenManagerPayload(bytes payload) internal ``` -This will be called after the tokens are sent to this contract. - -_Execution should revert unless the msg.sender is the InterchainTokenService_ - -#### Parameters +Processes a deploy token manager payload. -| Name | Type | Description | -| ------------- | ------- | ---------------------------------------------------- | -| commandId | bytes32 | The unique message id for the call. | -| sourceChain | string | The name of the source chain. | -| sourceAddress | bytes | The address that sent the contract call. | -| data | bytes | The data to be processed. | -| tokenId | bytes32 | The tokenId of the token manager managing the token. | -| token | address | The address of the token. | -| amount | uint256 | The amount of tokens that were sent. | +### _processDeployInterchainTokenPayload -#### Return Values +```solidity +function _processDeployInterchainTokenPayload(bytes payload) internal +``` -| Name | Type | Description | -| ---- | ------- | ------------------------------------------------- | -| [0] | bytes32 | bytes32 Hash indicating success of the execution. | +Processes a deploy interchain token manager payload. -## IInterchainTokenExpressExecutable +#### Parameters -Contracts should implement this interface to accept express calls from the InterchainTokenService. +| Name | Type | Description | +| ---- | ---- | ----------- | +| payload | bytes | The encoded data payload to be processed. | -### expressExecuteWithInterchainToken +### _callContract ```solidity -function expressExecuteWithInterchainToken(bytes32 commandId, string sourceChain, bytes sourceAddress, bytes data, bytes32 tokenId, address token, uint256 amount) external returns (bytes32) +function _callContract(string destinationChain, bytes payload, enum IGatewayCaller.MetadataVersion metadataVersion, uint256 gasValue) internal ``` -Executes express logic in the context of an interchain token transfer. +Calls a contract on a specific destination chain with the given payload -_Only callable by the interchain token service._ +_This method also determines whether the ITS call should be routed via the ITS Hub. +If the `trustedAddress(destinationChain) == 'hub'`, then the call is wrapped and routed to the ITS Hub destination._ #### Parameters -| Name | Type | Description | -| ------------- | ------- | -------------------------------------------- | -| commandId | bytes32 | The unique message id for the call. | -| sourceChain | string | The source chain of the token transfer. | -| sourceAddress | bytes | The source address of the token transfer. | -| data | bytes | The data associated with the token transfer. | -| tokenId | bytes32 | The token ID. | -| token | address | The token address. | -| amount | uint256 | The amount of tokens to be transferred. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| destinationChain | string | The target chain where the contract will be called. | +| payload | bytes | The data payload for the transaction. | +| metadataVersion | enum IGatewayCaller.MetadataVersion | | +| gasValue | uint256 | The amount of gas to be paid for the transaction. | -#### Return Values +### _getCallParams -| Name | Type | Description | -| ---- | ------- | --------------------------------------------------------- | -| [0] | bytes32 | bytes32 Hash indicating success of the express execution. | +```solidity +function _getCallParams(string destinationChain, bytes payload) internal view returns (string, string, bytes) +``` -## IInterchainTokenFactory +_Get the params for the cross-chain message, taking routing via ITS Hub into account._ -This interface defines functions for deploying new interchain tokens and managing their token managers. +### _execute -### ZeroAddress +```solidity +function _execute(bytes32 commandId, string sourceChain, string sourceAddress, bytes payload, bytes32 payloadHash) internal +``` + +### _getMessageType ```solidity -error ZeroAddress() +function _getMessageType(bytes payload) internal pure returns (uint256 messageType) ``` -### InvalidChainName +### _getExecuteParams ```solidity -error InvalidChainName() +function _getExecuteParams(string sourceChain, bytes payload) internal view returns (uint256, string, bytes) ``` -### NotMinter +_Return the parameters for the execute call, taking routing via ITS Hub into account._ + +### _deployRemoteTokenManager ```solidity -error NotMinter(address minter) +function _deployRemoteTokenManager(bytes32 tokenId, string destinationChain, uint256 gasValue, enum ITokenManagerType.TokenManagerType tokenManagerType, bytes params) internal ``` -### NotOperator +Deploys a token manager on a destination chain. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The ID of the token. | +| destinationChain | string | The chain where the token manager will be deployed. | +| gasValue | uint256 | The amount of gas to be paid for the transaction. | +| tokenManagerType | enum ITokenManagerType.TokenManagerType | The type of token manager to be deployed. | +| params | bytes | Additional parameters for the token manager deployment. | + +### _deployRemoteInterchainToken ```solidity -error NotOperator(address operator) +function _deployRemoteInterchainToken(bytes32 tokenId, string name, string symbol, uint8 decimals, bytes minter, string destinationChain, uint256 gasValue) internal ``` -### GatewayToken +Deploys an interchain token on a destination chain. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The ID of the token. | +| name | string | The name of the token. | +| symbol | string | The symbol of the token. | +| decimals | uint8 | The number of decimals of the token. | +| minter | bytes | The minter address for the token. | +| destinationChain | string | The destination chain where the token will be deployed. | +| gasValue | uint256 | The amount of gas to be paid for the transaction. | + +### _deployTokenManager ```solidity -error GatewayToken(address tokenAddress) +function _deployTokenManager(bytes32 tokenId, enum ITokenManagerType.TokenManagerType tokenManagerType, bytes params) internal ``` -### interchainTokenService +Deploys a token manager. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The ID of the token. | +| tokenManagerType | enum ITokenManagerType.TokenManagerType | The type of the token manager to be deployed. | +| params | bytes | Additional parameters for the token manager deployment. | + +### _getInterchainTokenSalt ```solidity -function interchainTokenService() external view returns (contract IInterchainTokenService) +function _getInterchainTokenSalt(bytes32 tokenId) internal pure returns (bytes32 salt) ``` -Returns the address of the interchain token service. +Computes the salt for an interchain token deployment. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The ID of the token. | #### Return Values -| Name | Type | Description | -| ---- | -------------------------------- | -------------------------------------------------------------------- | -| [0] | contract IInterchainTokenService | IInterchainTokenService The address of the interchain token service. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| salt | bytes32 | The computed salt for the token deployment. | -### chainNameHash +### _deployInterchainToken ```solidity -function chainNameHash() external view returns (bytes32) +function _deployInterchainToken(bytes32 tokenId, bytes minterBytes, string name, string symbol, uint8 decimals) internal returns (address tokenAddress) ``` -Returns the hash of the chain name. +Deploys an interchain token. -#### Return Values +#### Parameters -| Name | Type | Description | -| ---- | ------- | ----------------------------------- | -| [0] | bytes32 | bytes32 The hash of the chain name. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The ID of the token. | +| minterBytes | bytes | The minter address for the token. | +| name | string | The name of the token. | +| symbol | string | The symbol of the token. | +| decimals | uint8 | The number of decimals of the token. | -### interchainTokenSalt +### _decodeMetadata ```solidity -function interchainTokenSalt(bytes32 chainNameHash_, address deployer, bytes32 salt) external view returns (bytes32) +function _decodeMetadata(bytes metadata) internal pure returns (enum IGatewayCaller.MetadataVersion version, bytes data) ``` -Calculates the salt for an interchain token. +Decodes the metadata into a version number and data bytes. + +_The function expects the metadata to have the version in the first 4 bytes, followed by the actual data._ #### Parameters -| Name | Type | Description | -| --------------- | ------- | ----------------------------------------- | -| chainNameHash\_ | bytes32 | The hash of the chain name. | -| deployer | address | The address of the deployer. | -| salt | bytes32 | A unique identifier to generate the salt. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| metadata | bytes | The bytes containing the metadata to decode. | #### Return Values -| Name | Type | Description | -| ---- | ------- | ----------------------------------------------------- | -| [0] | bytes32 | bytes32 The calculated salt for the interchain token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| version | enum IGatewayCaller.MetadataVersion | The version number extracted from the metadata. | +| data | bytes | The data bytes extracted from the metadata. | -### interchainTokenId +### _transmitInterchainTransfer ```solidity -function interchainTokenId(address deployer, bytes32 salt) external view returns (bytes32 tokenId) +function _transmitInterchainTransfer(bytes32 tokenId, address sourceAddress, string destinationChain, bytes destinationAddress, uint256 amount, enum IGatewayCaller.MetadataVersion metadataVersion, bytes data, uint256 gasValue) internal ``` -Computes the ID for an interchain token based on the deployer and a salt. +Transmit a callContractWithInterchainToken for the given tokenId. #### Parameters -| Name | Type | Description | -| -------- | ------- | --------------------------------------------------- | -| deployer | address | The address that deployed the interchain token. | -| salt | bytes32 | A unique identifier used in the deployment process. | - -#### Return Values - -| Name | Type | Description | -| ------- | ------- | ------------------------------- | -| tokenId | bytes32 | The ID of the interchain token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId of the TokenManager (which must be the msg.sender). | +| sourceAddress | address | The address where the token is coming from, which will also be used for gas reimbursement. | +| destinationChain | string | The name of the chain to send tokens to. | +| destinationAddress | bytes | The destinationAddress for the interchainTransfer. | +| amount | uint256 | The amount of tokens to send. | +| metadataVersion | enum IGatewayCaller.MetadataVersion | The version of the metadata. | +| data | bytes | The data to be passed with the token transfer. | +| gasValue | uint256 | The amount of gas to be paid for the transaction. | -### interchainTokenAddress +### _takeToken ```solidity -function interchainTokenAddress(address deployer, bytes32 salt) external view returns (address tokenAddress) +function _takeToken(bytes32 tokenId, address from, uint256 amount, bool tokenOnly) internal returns (uint256) ``` -Retrieves the address of an interchain token based on the deployer and a salt. - -#### Parameters +_Takes token from a sender via the token service. `tokenOnly` indicates if the caller should be restricted to the token only._ -| Name | Type | Description | -| -------- | ------- | --------------------------------------------------- | -| deployer | address | The address that deployed the interchain token. | -| salt | bytes32 | A unique identifier used in the deployment process. | +### _giveToken -#### Return Values +```solidity +function _giveToken(bytes32 tokenId, address to, uint256 amount) internal returns (uint256, address tokenAddress) +``` -| Name | Type | Description | -| ------------ | ------- | ------------------------------------ | -| tokenAddress | address | The address of the interchain token. | +_Gives token to recipient via the token service._ -### deployInterchainToken +### _contractCallValue ```solidity -function deployInterchainToken(bytes32 salt, string name, string symbol, uint8 decimals, uint256 initialSupply, address minter) external payable returns (bytes32 tokenId) +function _contractCallValue(bytes payload) internal view returns (address, uint256) ``` -Deploys a new interchain token with specified parameters. +Returns the amount of token that this call is worth. + +_If `tokenAddress` is `0`, then value is in terms of the native token, otherwise it's in terms of the token address._ #### Parameters -| Name | Type | Description | -| ------------- | ------- | ----------------------------------------------------- | -| salt | bytes32 | The unique salt for deploying the token. | -| name | string | The name of the token. | -| symbol | string | The symbol of the token. | -| decimals | uint8 | The number of decimals for the token. | -| initialSupply | uint256 | The amount of tokens to mint initially (can be zero). | -| minter | address | The address to receive the initially minted tokens. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| payload | bytes | The payload sent with the call. | #### Return Values -| Name | Type | Description | -| ------- | ------- | ---------------------------------------------------------- | -| tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | address | address The token address. | +| [1] | uint256 | uint256 The value the call is worth. | -### deployRemoteInterchainToken +### _getExpressExecutorAndEmitEvent ```solidity -function deployRemoteInterchainToken(string originalChainName, bytes32 salt, address minter, string destinationChain, uint256 gasValue) external payable returns (bytes32 tokenId) +function _getExpressExecutorAndEmitEvent(bytes32 commandId, string sourceChain, string sourceAddress, bytes32 payloadHash) internal returns (address expressExecutor) ``` -Deploys a remote interchain token on a specified destination chain. - -#### Parameters - -| Name | Type | Description | -| ----------------- | ------- | ------------------------------------------------------------- | -| originalChainName | string | The name of the chain where the token originally exists. | -| salt | bytes32 | The unique salt for deploying the token. | -| minter | address | The address to distribute the token on the destination chain. | -| destinationChain | string | The name of the destination chain. | -| gasValue | uint256 | The amount of gas to send for the deployment. | - -#### Return Values +## TokenHandler -| Name | Type | Description | -| ------- | ------- | ---------------------------------------------------------- | -| tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | +This interface is responsible for handling tokens before initiating an interchain token transfer, or after receiving one. -### canonicalInterchainTokenSalt +### giveToken ```solidity -function canonicalInterchainTokenSalt(bytes32 chainNameHash_, address tokenAddress) external view returns (bytes32 salt) +function giveToken(bytes32 tokenId, address to, uint256 amount) external returns (uint256, address) ``` -Calculates the salt for a canonical interchain token. +This function gives token to a specified address from the token manager. #### Parameters -| Name | Type | Description | -| --------------- | ------- | --------------------------- | -| chainNameHash\_ | bytes32 | The hash of the chain name. | -| tokenAddress | address | The address of the token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The token id of the tokenManager. | +| to | address | The address to give tokens to. | +| amount | uint256 | The amount of tokens to give. | #### Return Values -| Name | Type | Description | -| ---- | ------- | --------------------------------------------- | -| salt | bytes32 | The calculated salt for the interchain token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | uint256 The amount of token actually given, which could be different for certain token type. | +| [1] | address | address the address of the token. | -### canonicalInterchainTokenId +### takeToken ```solidity -function canonicalInterchainTokenId(address tokenAddress) external view returns (bytes32 tokenId) +function takeToken(bytes32 tokenId, bool tokenOnly, address from, uint256 amount) external payable returns (uint256) ``` -Computes the ID for a canonical interchain token based on its address. +This function takes token from a specified address to the token manager. #### Parameters -| Name | Type | Description | -| ------------ | ------- | ---------------------------------------------- | -| tokenAddress | address | The address of the canonical interchain token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId for the token. | +| tokenOnly | bool | can only be called from the token. | +| from | address | The address to take tokens from. | +| amount | uint256 | The amount of token to take. | #### Return Values -| Name | Type | Description | -| ------- | ------- | ----------------------------------------- | -| tokenId | bytes32 | The ID of the canonical interchain token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | uint256 The amount of token actually taken, which could be different for certain token type. | -### registerCanonicalInterchainToken +### transferTokenFrom ```solidity -function registerCanonicalInterchainToken(address tokenAddress) external payable returns (bytes32 tokenId) +function transferTokenFrom(bytes32 tokenId, address from, address to, uint256 amount) external returns (uint256, address) ``` -Registers a canonical token as an interchain token and deploys its token manager. +This function transfers token from and to a specified address. #### Parameters -| Name | Type | Description | -| ------------ | ------- | ----------------------------------- | -| tokenAddress | address | The address of the canonical token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The token id of the token manager. | +| from | address | The address to transfer tokens from. | +| to | address | The address to transfer tokens to. | +| amount | uint256 | The amount of token to transfer. | #### Return Values -| Name | Type | Description | -| ------- | ------- | ------------------------------------------------------------ | -| tokenId | bytes32 | The tokenId corresponding to the registered canonical token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | uint256 The amount of token actually transferred, which could be different for certain token type. | +| [1] | address | address The address of the token corresponding to the input tokenId. | -### deployRemoteCanonicalInterchainToken +### postTokenManagerDeploy ```solidity -function deployRemoteCanonicalInterchainToken(string originalChain, address originalTokenAddress, string destinationChain, uint256 gasValue) external payable returns (bytes32 tokenId) +function postTokenManagerDeploy(uint256 tokenManagerType, address tokenManager) external payable ``` -Deploys a canonical interchain token on a remote chain. +This function prepares a token manager after it is deployed #### Parameters -| Name | Type | Description | -| -------------------- | ------- | -------------------------------------------------------- | -| originalChain | string | The name of the chain where the token originally exists. | -| originalTokenAddress | address | The address of the original token on the original chain. | -| destinationChain | string | The name of the chain where the token will be deployed. | -| gasValue | uint256 | The gas amount to be sent for deployment. | - -#### Return Values - -| Name | Type | Description | -| ------- | ------- | -------------------------------------------------------------------- | -| tokenId | bytes32 | The tokenId corresponding to the deployed canonical InterchainToken. | - -## IInterchainTokenService - -Interface for the Interchain Token Service +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenManagerType | uint256 | The token manager type. | +| tokenManager | address | The address of the token manager. | -### InvalidTokenManagerImplementationType +### _transferTokenFrom ```solidity -error InvalidTokenManagerImplementationType(address implementation) +function _transferTokenFrom(address tokenAddress, address from, address to, uint256 amount) internal ``` -### InvalidChainName +### _transferTokenFromWithFee ```solidity -error InvalidChainName() +function _transferTokenFromWithFee(address tokenAddress, address from, address to, uint256 amount) internal returns (uint256) ``` -### NotRemoteService +### _giveInterchainToken ```solidity -error NotRemoteService() +function _giveInterchainToken(address tokenAddress, address to, uint256 amount) internal ``` -### TokenManagerDoesNotExist +### _takeInterchainToken ```solidity -error TokenManagerDoesNotExist(bytes32 tokenId) +function _takeInterchainToken(address tokenAddress, address from, uint256 amount) internal ``` -### NotToken +### _mintToken ```solidity -error NotToken(address caller, address token) +function _mintToken(address tokenManager, address tokenAddress, address to, uint256 amount) internal ``` -### ExecuteWithInterchainTokenFailed +### _burnToken ```solidity -error ExecuteWithInterchainTokenFailed(address contractAddress) +function _burnToken(address tokenManager, address tokenAddress, address from, uint256 amount) internal ``` -### ExpressExecuteWithInterchainTokenFailed +### _burnTokenFrom ```solidity -error ExpressExecuteWithInterchainTokenFailed(address contractAddress) +function _burnTokenFrom(address tokenAddress, address from, uint256 amount) internal ``` -### GatewayToken +## InterchainTokenExecutable -```solidity -error GatewayToken() -``` +Abstract contract that defines an interface for executing arbitrary logic +in the context of interchain token operations. -### TokenManagerDeploymentFailed +_This contract should be inherited by contracts that intend to execute custom +logic in response to interchain token actions such as transfers. This contract +will only be called by the interchain token service._ + +### NotService ```solidity -error TokenManagerDeploymentFailed(bytes error) +error NotService(address caller) ``` -### InterchainTokenDeploymentFailed +### interchainTokenService ```solidity -error InterchainTokenDeploymentFailed(bytes error) +address interchainTokenService ``` -### InvalidMessageType +### EXECUTE_SUCCESS ```solidity -error InvalidMessageType(uint256 messageType) +bytes32 EXECUTE_SUCCESS ``` -### InvalidMetadataVersion +### constructor ```solidity -error InvalidMetadataVersion(uint32 version) +constructor(address interchainTokenService_) internal ``` -### ExecuteWithTokenNotSupported +Creates a new InterchainTokenExecutable contract. -```solidity -error ExecuteWithTokenNotSupported() -``` +#### Parameters -### InvalidExpressMessageType +| Name | Type | Description | +| ---- | ---- | ----------- | +| interchainTokenService_ | address | The address of the interchain token service that will call this contract. | + +### onlyService ```solidity -error InvalidExpressMessageType(uint256 messageType) +modifier onlyService() ``` -### TakeTokenFailed +Modifier to restrict function execution to the interchain token service. + +### executeWithInterchainToken ```solidity -error TakeTokenFailed(bytes data) +function executeWithInterchainToken(bytes32 commandId, string sourceChain, bytes sourceAddress, bytes data, bytes32 tokenId, address token, uint256 amount) external virtual returns (bytes32) ``` -### GiveTokenFailed +Executes logic in the context of an interchain token transfer. -```solidity -error GiveTokenFailed(bytes data) -``` +_Only callable by the interchain token service._ -### TokenHandlerFailed +#### Parameters -```solidity -error TokenHandlerFailed(bytes data) -``` +| Name | Type | Description | +| ---- | ---- | ----------- | +| commandId | bytes32 | The unique message id. | +| sourceChain | string | The source chain of the token transfer. | +| sourceAddress | bytes | The source address of the token transfer. | +| data | bytes | The data associated with the token transfer. | +| tokenId | bytes32 | The token ID. | +| token | address | The token address. | +| amount | uint256 | The amount of tokens being transferred. | -### EmptyData +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 Hash indicating success of the execution. | + +### _executeWithInterchainToken ```solidity -error EmptyData() +function _executeWithInterchainToken(bytes32 commandId, string sourceChain, bytes sourceAddress, bytes data, bytes32 tokenId, address token, uint256 amount) internal virtual ``` -### CannotDeploy +Internal function containing the logic to be executed with interchain token transfer. + +_Logic must be implemented by derived contracts._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| commandId | bytes32 | The unique message id. | +| sourceChain | string | The source chain of the token transfer. | +| sourceAddress | bytes | The source address of the token transfer. | +| data | bytes | The data associated with the token transfer. | +| tokenId | bytes32 | The token ID. | +| token | address | The token address. | +| amount | uint256 | The amount of tokens being transferred. | + +## InterchainTokenExpressExecutable + +Abstract contract that defines an interface for executing express logic in the context of interchain token operations. + +_This contract extends `InterchainTokenExecutable` to provide express execution capabilities. It is intended to be inherited by contracts +that implement express logic for interchain token actions. This contract will only be called by the interchain token service._ + +### EXPRESS_EXECUTE_SUCCESS ```solidity -error CannotDeploy(enum ITokenManagerType.TokenManagerType) +bytes32 EXPRESS_EXECUTE_SUCCESS ``` -### InterchainTransfer +### constructor ```solidity -event InterchainTransfer(bytes32 tokenId, address sourceAddress, string destinationChain, bytes destinationAddress, uint256 amount, bytes32 dataHash) +constructor(address interchainTokenService_) internal ``` -### InterchainTransferReceived +Creates a new InterchainTokenExpressExecutable contract. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| interchainTokenService_ | address | The address of the interchain token service that will call this contract. | + +### expressExecuteWithInterchainToken ```solidity -event InterchainTransferReceived(bytes32 commandId, bytes32 tokenId, string sourceChain, bytes sourceAddress, address destinationAddress, uint256 amount, bytes32 dataHash) +function expressExecuteWithInterchainToken(bytes32 commandId, string sourceChain, bytes sourceAddress, bytes data, bytes32 tokenId, address token, uint256 amount) external virtual returns (bytes32) ``` -### TokenManagerDeploymentStarted +Executes express logic in the context of an interchain token transfer. + +_Only callable by the interchain token service._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| commandId | bytes32 | The unique message id. | +| sourceChain | string | The source chain of the token transfer. | +| sourceAddress | bytes | The source address of the token transfer. | +| data | bytes | The data associated with the token transfer. | +| tokenId | bytes32 | The token ID. | +| token | address | The token address. | +| amount | uint256 | The amount of tokens to be transferred. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 Hash indicating success of the express execution. | + +## ERC20 + +_Implementation of the {IERC20} interface. + +This implementation is agnostic to the way tokens are created. This means +that a supply mechanism has to be added in a derived contract using {_mint}. +For a generic mechanism see {ERC20PresetMinterPauser}. + +TIP: For a detailed writeup see our guide +https://forum.zeppelin.solutions/t/how-to-implement-erc20-supply-mechanisms/226[How +to implement supply mechanisms]. + +We have followed general OpenZeppelin guidelines: functions revert instead +of returning `false` on failure. This behavior is nonetheless conventional +and does not conflict with the expectations of ERC20 applications. + +Additionally, an {Approval} event is emitted on calls to {transferFrom}. +This allows applications to reconstruct the allowance for all accounts just +by listening to said events. Other implementations of the EIP may not emit +these events, as it isn't required by the specification. + +Finally, the non-standard {decreaseAllowance} and {increaseAllowance} +functions have been added to mitigate the well-known issues around setting +allowances. See {IERC20-approve}._ + +### balanceOf ```solidity -event TokenManagerDeploymentStarted(bytes32 tokenId, string destinationChain, enum ITokenManagerType.TokenManagerType tokenManagerType, bytes params) +mapping(address => uint256) balanceOf ``` -### InterchainTokenDeploymentStarted +_Returns the amount of tokens owned by `account`._ + +### allowance ```solidity -event InterchainTokenDeploymentStarted(bytes32 tokenId, string tokenName, string tokenSymbol, uint8 tokenDecimals, bytes minter, string destinationChain) +mapping(address => mapping(address => uint256)) allowance ``` -### TokenManagerDeployed +_Returns the remaining number of tokens that `spender` will be +allowed to spend on behalf of `owner` through {transferFrom}. This is +zero by default. -```solidity -event TokenManagerDeployed(bytes32 tokenId, address tokenManager, enum ITokenManagerType.TokenManagerType tokenManagerType, bytes params) -``` +This value changes when {approve} or {transferFrom} are called._ -### InterchainTokenDeployed +### totalSupply ```solidity -event InterchainTokenDeployed(bytes32 tokenId, address tokenAddress, address minter, string name, string symbol, uint8 decimals) +uint256 totalSupply ``` -### InterchainTokenIdClaimed +_Returns the amount of tokens in existence._ + +### UINT256_MAX ```solidity -event InterchainTokenIdClaimed(bytes32 tokenId, address deployer, bytes32 salt) +uint256 UINT256_MAX ``` -### tokenManagerDeployer +### transfer ```solidity -function tokenManagerDeployer() external view returns (address tokenManagerDeployerAddress) +function transfer(address recipient, uint256 amount) external virtual returns (bool) ``` -Returns the address of the token manager deployer contract. +_See {IERC20-transfer}. -#### Return Values +Requirements: -| Name | Type | Description | -| --------------------------- | ------- | --------------------------------------------------- | -| tokenManagerDeployerAddress | address | The address of the token manager deployer contract. | +- `recipient` cannot be the zero address. +- the caller must have a balance of at least `amount`._ -### interchainTokenDeployer +### approve ```solidity -function interchainTokenDeployer() external view returns (address interchainTokenDeployerAddress) +function approve(address spender, uint256 amount) external virtual returns (bool) ``` -Returns the address of the interchain token deployer contract. +_See {IERC20-approve}. -#### Return Values +NOTE: If `amount` is the maximum `uint256`, the allowance is not updated on +`transferFrom`. This is semantically equivalent to an infinite approval. -| Name | Type | Description | -| ------------------------------ | ------- | ------------------------------------------------------ | -| interchainTokenDeployerAddress | address | The address of the interchain token deployer contract. | +Requirements: -### tokenManager +- `spender` cannot be the zero address._ + +### transferFrom ```solidity -function tokenManager() external view returns (address tokenManagerAddress_) +function transferFrom(address sender, address recipient, uint256 amount) external virtual returns (bool) ``` -Returns the address of TokenManager implementation. +_See {IERC20-transferFrom}. -#### Return Values +Emits an {Approval} event indicating the updated allowance. This is not +required by the EIP. See the note at the beginning of {ERC20}. -| Name | Type | Description | -| --------------------- | ------- | ------------------------------------------ | -| tokenManagerAddress\_ | address | The address of the token manager contract. | +Requirements: -### tokenHandler +- `sender` and `recipient` cannot be the zero address. +- `sender` must have a balance of at least `amount`. +- the caller must have allowance for ``sender``'s tokens of at least +`amount`._ + +### increaseAllowance ```solidity -function tokenHandler() external view returns (address tokenHandlerAddress) +function increaseAllowance(address spender, uint256 addedValue) external virtual returns (bool) ``` -Returns the address of TokenHandler implementation. +_Atomically increases the allowance granted to `spender` by the caller. -#### Return Values +This is an alternative to {approve} that can be used as a mitigation for +problems described in {IERC20-approve}. -| Name | Type | Description | -| ------------------- | ------- | ------------------------------------------ | -| tokenHandlerAddress | address | The address of the token handler contract. | +Emits an {Approval} event indicating the updated allowance. -### interchainTokenFactory +Requirements: + +- `spender` cannot be the zero address._ + +### decreaseAllowance ```solidity -function interchainTokenFactory() external view returns (address) +function decreaseAllowance(address spender, uint256 subtractedValue) external virtual returns (bool) ``` -Returns the address of the interchain token factory. +_Atomically decreases the allowance granted to `spender` by the caller. -#### Return Values +This is an alternative to {approve} that can be used as a mitigation for +problems described in {IERC20-approve}. + +Emits an {Approval} event indicating the updated allowance. + +Requirements: -| Name | Type | Description | -| ---- | ------- | ---------------------------------------------------- | -| [0] | address | address The address of the interchain token factory. | +- `spender` cannot be the zero address. +- `spender` must have allowance for the caller of at least +`subtractedValue`._ -### chainNameHash +### _transfer ```solidity -function chainNameHash() external view returns (bytes32) +function _transfer(address sender, address recipient, uint256 amount) internal virtual ``` -Returns the hash of the chain name. +_Moves tokens `amount` from `sender` to `recipient`. -#### Return Values +This is internal function is equivalent to {transfer}, and can be used to +e.g. implement automatic token fees, slashing mechanisms, etc. -| Name | Type | Description | -| ---- | ------- | ----------------------------------- | -| [0] | bytes32 | bytes32 The hash of the chain name. | +Emits a {Transfer} event. -### tokenManagerAddress +Requirements: + +- `sender` cannot be the zero address. +- `recipient` cannot be the zero address. +- `sender` must have a balance of at least `amount`._ + +### _mint ```solidity -function tokenManagerAddress(bytes32 tokenId) external view returns (address tokenManagerAddress_) +function _mint(address account, uint256 amount) internal virtual ``` -Returns the address of the token manager associated with the given tokenId. - -#### Parameters +_Creates `amount` tokens and assigns them to `account`, increasing +the total supply. -| Name | Type | Description | -| ------- | ------- | --------------------------------- | -| tokenId | bytes32 | The tokenId of the token manager. | +Emits a {Transfer} event with `from` set to the zero address. -#### Return Values +Requirements: -| Name | Type | Description | -| --------------------- | ------- | --------------------------------- | -| tokenManagerAddress\_ | address | The address of the token manager. | +- `to` cannot be the zero address._ -### deployedTokenManager +### _burn ```solidity -function deployedTokenManager(bytes32 tokenId) external view returns (address tokenManagerAddress_) +function _burn(address account, uint256 amount) internal virtual ``` -Returns the address of the valid token manager associated with the given tokenId. - -#### Parameters +_Destroys `amount` tokens from `account`, reducing the +total supply. -| Name | Type | Description | -| ------- | ------- | --------------------------------- | -| tokenId | bytes32 | The tokenId of the token manager. | +Emits a {Transfer} event with `to` set to the zero address. -#### Return Values +Requirements: -| Name | Type | Description | -| --------------------- | ------- | --------------------------------------- | -| tokenManagerAddress\_ | address | The address of the valid token manager. | +- `account` cannot be the zero address. +- `account` must have at least `amount` tokens._ -### registeredTokenAddress +### _approve ```solidity -function registeredTokenAddress(bytes32 tokenId) external view returns (address tokenAddress) +function _approve(address owner, address spender, uint256 amount) internal virtual ``` -Returns the address of the token that an existing tokenManager points to. +_Sets `amount` as the allowance of `spender` over the `owner` s tokens. -#### Parameters +This internal function is equivalent to `approve`, and can be used to +e.g. set automatic allowances for certain subsystems, etc. -| Name | Type | Description | -| ------- | ------- | --------------------------------- | -| tokenId | bytes32 | The tokenId of the token manager. | +Emits an {Approval} event. -#### Return Values +Requirements: -| Name | Type | Description | -| ------------ | ------- | ------------------------- | -| tokenAddress | address | The address of the token. | +- `owner` cannot be the zero address. +- `spender` cannot be the zero address._ -### interchainTokenAddress +## ERC20Permit + +_Extension of ERC20 to include permit functionality (EIP-2612). +Allows for approval of ERC20 tokens by signature rather than transaction._ + +### PermitExpired ```solidity -function interchainTokenAddress(bytes32 tokenId) external view returns (address tokenAddress) +error PermitExpired() ``` -Returns the address of the interchain token associated with the given tokenId. - -#### Parameters +### InvalidS -| Name | Type | Description | -| ------- | ------- | ------------------------------------ | -| tokenId | bytes32 | The tokenId of the interchain token. | +```solidity +error InvalidS() +``` -#### Return Values +### InvalidV -| Name | Type | Description | -| ------------ | ------- | ------------------------------------ | -| tokenAddress | address | The address of the interchain token. | +```solidity +error InvalidV() +``` -### interchainTokenId +### InvalidSignature ```solidity -function interchainTokenId(address operator_, bytes32 salt) external view returns (bytes32 tokenId) +error InvalidSignature() ``` -Returns the custom tokenId associated with the given operator and salt. +### nameHash -#### Parameters +```solidity +bytes32 nameHash +``` + +_Represents hash of the EIP-712 Domain Separator._ -| Name | Type | Description | -| ---------- | ------- | --------------------------------------- | -| operator\_ | address | The operator address. | -| salt | bytes32 | The salt used for token id calculation. | +### nonces -#### Return Values +```solidity +mapping(address => uint256) nonces +``` -| Name | Type | Description | -| ------- | ------- | --------------------------------------------------------- | -| tokenId | bytes32 | The custom tokenId associated with the operator and salt. | +_Mapping of nonces for each address._ -### deployTokenManager +### _setNameHash ```solidity -function deployTokenManager(bytes32 salt, string destinationChain, enum ITokenManagerType.TokenManagerType tokenManagerType, bytes params, uint256 gasValue) external payable returns (bytes32 tokenId) +function _setNameHash(string name) internal ``` -Deploys a custom token manager contract on a remote chain. +Internal function to set the token name hash #### Parameters -| Name | Type | Description | -| ---------------- | --------------------------------------- | ------------------------------------------------------------- | -| salt | bytes32 | The salt used for token manager deployment. | -| destinationChain | string | The name of the destination chain. | -| tokenManagerType | enum ITokenManagerType.TokenManagerType | The type of token manager. Cannot be NATIVE_INTERCHAIN_TOKEN. | -| params | bytes | The deployment parameters. | -| gasValue | uint256 | The gas value for deployment. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| name | string | The token name | -#### Return Values +### DOMAIN_SEPARATOR -| Name | Type | Description | -| ------- | ------- | ---------------------------------------------- | -| tokenId | bytes32 | The tokenId associated with the token manager. | +```solidity +function DOMAIN_SEPARATOR() public view returns (bytes32) +``` -### deployInterchainToken +Calculates the domain separator. + +_This is not cached because chainid can change on chain forks._ + +### permit ```solidity -function deployInterchainToken(bytes32 salt, string destinationChain, string name, string symbol, uint8 decimals, bytes minter, uint256 gasValue) external payable returns (bytes32 tokenId) +function permit(address issuer, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s) external ``` -Deploys and registers an interchain token on a remote chain. +Permit the designated spender to spend the holder's tokens + +_The permit function is used to allow a holder to designate a spender +to spend tokens on their behalf via a signed message._ #### Parameters -| Name | Type | Description | -| ---------------- | ------- | --------------------------------------------------------- | -| salt | bytes32 | The salt used for token deployment. | -| destinationChain | string | The name of the destination chain. Use '' for this chain. | -| name | string | The name of the interchain tokens. | -| symbol | string | The symbol of the interchain tokens. | -| decimals | uint8 | The number of decimals for the interchain tokens. | -| minter | bytes | The minter data for mint/burn operations. | -| gasValue | uint256 | The gas value for deployment. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| issuer | address | The address of the token holder | +| spender | address | The address of the designated spender | +| value | uint256 | The number of tokens to be spent | +| deadline | uint256 | The time at which the permission to spend expires | +| v | uint8 | The recovery id of the signature | +| r | bytes32 | Half of the ECDSA signature pair | +| s | bytes32 | Half of the ECDSA signature pair | -#### Return Values +## InterchainToken -| Name | Type | Description | -| ------- | ------- | ---------------------------------------------------------- | -| tokenId | bytes32 | The tokenId corresponding to the deployed InterchainToken. | +This contract implements an interchain token which extends InterchainToken functionality. -### interchainTransfer +_This contract also inherits Minter and Implementation logic._ + +### name ```solidity -function interchainTransfer(bytes32 tokenId, string destinationChain, bytes destinationAddress, uint256 amount, bytes metadata, uint256 gasValue) external payable +string name ``` -Initiates an interchain transfer of a specified token to a destination chain. +Getter for the name of the token. -#### Parameters +#### Return Values -| Name | Type | Description | -| ------------------ | ------- | ----------------------------------------------------------------------------------------------- | -| tokenId | bytes32 | The unique identifier of the token to be transferred. | -| destinationChain | string | The destination chain to send the tokens to. | -| destinationAddress | bytes | The address on the destination chain to send the tokens to. | -| amount | uint256 | The amount of tokens to be transferred. | -| metadata | bytes | Optional metadata for the call for additional effects (such as calling a destination contract). | -| gasValue | uint256 | | +| Name | Type | Description | +| ---- | ---- | ----------- | -### callContractWithInterchainToken +### symbol ```solidity -function callContractWithInterchainToken(bytes32 tokenId, string destinationChain, bytes destinationAddress, uint256 amount, bytes data, uint256 gasValue) external payable +string symbol ``` -Initiates an interchain call contract with interchain token to a destination chain. +Getter for the symbol of the token. -#### Parameters +#### Return Values -| Name | Type | Description | -| ------------------ | ------- | ----------------------------------------------------------- | -| tokenId | bytes32 | The unique identifier of the token to be transferred. | -| destinationChain | string | The destination chain to send the tokens to. | -| destinationAddress | bytes | The address on the destination chain to send the tokens to. | -| amount | uint256 | The amount of tokens to be transferred. | -| data | bytes | Additional data to be passed along with the transfer. | -| gasValue | uint256 | | +| Name | Type | Description | +| ---- | ---- | ----------- | -### setFlowLimits +### decimals ```solidity -function setFlowLimits(bytes32[] tokenIds, uint256[] flowLimits) external +uint8 decimals ``` -Sets the flow limits for multiple tokens. +Getter for the decimals of the token. -#### Parameters +#### Return Values -| Name | Type | Description | -| ---------- | --------- | ------------------------------------------------------ | -| tokenIds | bytes32[] | An array of tokenIds. | -| flowLimits | uint256[] | An array of flow limits corresponding to the tokenIds. | +| Name | Type | Description | +| ---- | ---- | ----------- | -### flowLimit +### tokenId ```solidity -function flowLimit(bytes32 tokenId) external view returns (uint256 flowLimit_) +bytes32 tokenId ``` -Returns the flow limit for a specific token. - -#### Parameters - -| Name | Type | Description | -| ------- | ------- | ------------------------- | -| tokenId | bytes32 | The tokenId of the token. | - -#### Return Values +### interchainTokenService_ -| Name | Type | Description | -| ----------- | ------- | ----------------------------- | -| flowLimit\_ | uint256 | The flow limit for the token. | +```solidity +address interchainTokenService_ +``` -### flowOutAmount +### INITIALIZED_SLOT ```solidity -function flowOutAmount(bytes32 tokenId) external view returns (uint256 flowOutAmount_) +bytes32 INITIALIZED_SLOT ``` -Returns the total amount of outgoing flow for a specific token. - -#### Parameters +### constructor -| Name | Type | Description | -| ------- | ------- | ------------------------- | -| tokenId | bytes32 | The tokenId of the token. | +```solidity +constructor(address interchainTokenServiceAddress) public +``` -#### Return Values +Constructs the InterchainToken contract. -| Name | Type | Description | -| --------------- | ------- | ------------------------------------------------ | -| flowOutAmount\_ | uint256 | The total amount of outgoing flow for the token. | +_Makes the implementation act as if it has been setup already to disallow calls to init() (even though that would not achieve anything really)._ -### flowInAmount +### _isInitialized ```solidity -function flowInAmount(bytes32 tokenId) external view returns (uint256 flowInAmount_) +function _isInitialized() internal view returns (bool initialized) ``` -Returns the total amount of incoming flow for a specific token. - -#### Parameters - -| Name | Type | Description | -| ------- | ------- | ------------------------- | -| tokenId | bytes32 | The tokenId of the token. | +Returns true if the contract has been setup. #### Return Values -| Name | Type | Description | -| -------------- | ------- | ------------------------------------------------ | -| flowInAmount\_ | uint256 | The total amount of incoming flow for the token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| initialized | bool | True if the contract has been setup, false otherwise. | -### setPauseStatus +### _initialize ```solidity -function setPauseStatus(bool paused) external +function _initialize() internal ``` -Allows the owner to pause/unpause the token service. +Sets initialized to true, to allow only a single init. -#### Parameters +### interchainTokenService -| Name | Type | Description | -| ------ | ---- | ---------------------------- | -| paused | bool | whether to pause or unpause. | +```solidity +function interchainTokenService() public view returns (address) +``` -## IInterchainTokenStandard +Returns the interchain token service -_Interface of the ERC20 standard as defined in the EIP._ +#### Return Values -### interchainTransfer +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | address | address The interchain token service contract | + +### interchainTokenId ```solidity -function interchainTransfer(string destinationChain, bytes recipient, uint256 amount, bytes metadata) external payable +function interchainTokenId() public view returns (bytes32) ``` -Implementation of the interchainTransfer method. - -_We chose to either pass `metadata` as raw data on a remote contract call, or if no data is passed, just do a transfer. -A different implementation could use metadata to specify a function to invoke, or for other purposes as well._ +Returns the tokenId for this token. -#### Parameters +#### Return Values -| Name | Type | Description | -| ---------------- | ------- | ----------------------------------------------------------------------------------------------- | -| destinationChain | string | The destination chain identifier. | -| recipient | bytes | The bytes representation of the address of the recipient. | -| amount | uint256 | The amount of token to be transferred. | -| metadata | bytes | Optional metadata for the call for additional effects (such as calling a destination contract). | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 The token manager contract. | -### interchainTransferFrom +### init ```solidity -function interchainTransferFrom(address sender, string destinationChain, bytes recipient, uint256 amount, bytes metadata) external payable +function init(bytes32 tokenId_, address minter, string tokenName, string tokenSymbol, uint8 tokenDecimals) external ``` -Implementation of the interchainTransferFrom method - -_We chose to either pass `metadata` as raw data on a remote contract call, or, if no data is passed, just do a transfer. -A different implementation could use metadata to specify a function to invoke, or for other purposes as well._ +Setup function to initialize contract parameters. #### Parameters -| Name | Type | Description | -| ---------------- | ------- | ----------------------------------------------------------------------------------------------- | -| sender | address | The sender of the tokens. They need to have approved `msg.sender` before this is called. | -| destinationChain | string | The string representation of the destination chain. | -| recipient | bytes | The bytes representation of the address of the recipient. | -| amount | uint256 | The amount of token to be transferred. | -| metadata | bytes | Optional metadata for the call for additional effects (such as calling a destination contract.) | - -## IMinter - -An interface for a contract module which provides a basic access control mechanism, where -there is an account (a minter) that can be granted exclusive access to specific functions. +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId_ | bytes32 | The tokenId of the token. | +| minter | address | The address of the token minter. | +| tokenName | string | The name of the token. | +| tokenSymbol | string | The symbopl of the token. | +| tokenDecimals | uint8 | The decimals of the token. | -### transferMintership +### mint ```solidity -function transferMintership(address minter_) external +function mint(address account, uint256 amount) external ``` -Change the minter of the contract. +Function to mint new tokens. -_Can only be called by the current minter._ +_Can only be called by the minter address._ #### Parameters -| Name | Type | Description | -| -------- | ------- | ------------------------------ | -| minter\_ | address | The address of the new minter. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| account | address | The address that will receive the minted tokens. | +| amount | uint256 | The amount of tokens to mint. | -### proposeMintership +### burn ```solidity -function proposeMintership(address minter_) external +function burn(address account, uint256 amount) external ``` -Proposed a change of the minter of the contract. +Function to burn tokens. -_Can only be called by the current minter._ +_Can only be called by the minter address._ #### Parameters -| Name | Type | Description | -| -------- | ------- | ------------------------------ | -| minter\_ | address | The address of the new minter. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| account | address | The address that will have its tokens burnt. | +| amount | uint256 | The amount of tokens to burn. | -### acceptMintership +### _spendAllowance ```solidity -function acceptMintership(address fromMinter) external +function _spendAllowance(address sender, address spender, uint256 amount) internal ``` -Accept a change of the minter of the contract. +A method to be overwritten that will decrease the allowance of the `spender` from `sender` by `amount`. -_Can only be called by the proposed minter._ +_Needs to be overwritten. This provides flexibility for the choice of ERC20 implementation used. Must revert if allowance is not sufficient._ -#### Parameters +## InterchainTokenStandard -| Name | Type | Description | -| ---------- | ------- | -------------------- | -| fromMinter | address | The previous minter. | +The is an abstract contract that needs to be extended with an ERC20 implementation. See `InterchainToken` for an example implementation. -### isMinter +### interchainTokenId ```solidity -function isMinter(address addr) external view returns (bool) +function interchainTokenId() public view virtual returns (bytes32 tokenId_) ``` -Query if an address is a minter - -#### Parameters +Getter for the tokenId used for this token. -| Name | Type | Description | -| ---- | ------- | ------------------------ | -| addr | address | the address to query for | +_Needs to be overwritten._ #### Return Values -| Name | Type | Description | -| ---- | ---- | ----------------------------------------------------------------------- | -| [0] | bool | bool Boolean value representing whether or not the address is a minter. | - -## IOperator - -An interface for a contract module which provides a basic access control mechanism, where -there is an account (a operator) that can be granted exclusive access to specific functions. +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId_ | bytes32 | The tokenId that this token is registerred under. | -### transferOperatorship +### interchainTokenService ```solidity -function transferOperatorship(address operator_) external +function interchainTokenService() public view virtual returns (address service) ``` -Change the operator of the contract. +Getter for the interchain token service. -_Can only be called by the current operator._ +_Needs to be overwritten._ -#### Parameters +#### Return Values -| Name | Type | Description | -| ---------- | ------- | -------------------------------- | -| operator\_ | address | The address of the new operator. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| service | address | The address of the interchain token service. | -### proposeOperatorship +### interchainTransfer ```solidity -function proposeOperatorship(address operator_) external +function interchainTransfer(string destinationChain, bytes recipient, uint256 amount, bytes metadata) external payable ``` -Proposed a change of the operator of the contract. +Implementation of the interchainTransfer method -_Can only be called by the current operator._ +_We chose to either pass `metadata` as raw data on a remote contract call, or if no data is passed, just do a transfer. +A different implementation could use metadata to specify a function to invoke, or for other purposes as well._ #### Parameters -| Name | Type | Description | -| ---------- | ------- | -------------------------------- | -| operator\_ | address | The address of the new operator. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| destinationChain | string | The destination chain identifier. | +| recipient | bytes | The bytes representation of the address of the recipient. | +| amount | uint256 | The amount of token to be transferred. | +| metadata | bytes | Either empty, just to facilitate an interchain transfer, or the data to be passed for an interchain contract call with transfer as per semantics defined by the token service. | -### acceptOperatorship +### interchainTransferFrom ```solidity -function acceptOperatorship(address fromOperator) external +function interchainTransferFrom(address sender, string destinationChain, bytes recipient, uint256 amount, bytes metadata) external payable ``` -Accept a proposed change of operatorship. +Implementation of the interchainTransferFrom method -_Can only be called by the proposed operator._ +_We chose to either pass `metadata` as raw data on a remote contract call, or, if no data is passed, just do a transfer. +A different implementation could use metadata to specify a function to invoke, or for other purposes as well._ #### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------------------------- | -| fromOperator | address | The previous operator of the contract. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| sender | address | The sender of the tokens. They need to have approved `msg.sender` before this is called. | +| destinationChain | string | The string representation of the destination chain. | +| recipient | bytes | The bytes representation of the address of the recipient. | +| amount | uint256 | The amount of token to be transferred. | +| metadata | bytes | Either empty, just to facilitate an interchain transfer, or the data to be passed to an interchain contract call and transfer. | -### isOperator +### _beforeInterchainTransfer ```solidity -function isOperator(address addr) external view returns (bool) +function _beforeInterchainTransfer(address from, string destinationChain, bytes destinationAddress, uint256 amount, bytes metadata) internal virtual ``` -Query if an address is a operator. +A method to be overwritten that will be called before an interchain transfer. One can approve the tokenManager here if needed, +to allow users for a 1-call transfer in case of a lock-unlock token manager. #### Parameters -| Name | Type | Description | -| ---- | ------- | ------------------------- | -| addr | address | The address to query for. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| from | address | The sender of the tokens. They need to have approved `msg.sender` before this is called. | +| destinationChain | string | The string representation of the destination chain. | +| destinationAddress | bytes | The bytes representation of the address of the recipient. | +| amount | uint256 | The amount of token to be transferred. | +| metadata | bytes | Either empty, just to facilitate an interchain transfer, or the data to be passed to an interchain contract call and transfer. | -#### Return Values +### _spendAllowance -| Name | Type | Description | -| ---- | ---- | -------------------------------------------------------------------------- | -| [0] | bool | bool Boolean value representing whether or not the address is an operator. | +```solidity +function _spendAllowance(address sender, address spender, uint256 amount) internal virtual +``` -## ITokenHandler +A method to be overwritten that will decrease the allowance of the `spender` from `sender` by `amount`. -This interface is responsible for handling tokens before initiating an interchain token transfer, or after receiving one. +_Needs to be overwritten. This provides flexibility for the choice of ERC20 implementation used. Must revert if allowance is not sufficient._ -### UnsupportedTokenManagerType +## IERC20BurnableFrom -```solidity -error UnsupportedTokenManagerType(uint256 tokenManagerType) -``` +Interface of the ERC20 standard as defined in the EIP. -### giveToken +### burnFrom ```solidity -function giveToken(uint256 tokenManagerType, address tokenAddress, address tokenManager, address to, uint256 amount) external payable returns (uint256) +function burnFrom(address from, uint256 amount) external ``` -This function gives token to a specified address from the token manager. +Function to burn tokens. + +_Requires the caller to have allowance for `amount` on `from`. +Can only be called by the minter address._ #### Parameters -| Name | Type | Description | -| ---------------- | ------- | --------------------------------- | -| tokenManagerType | uint256 | The token manager type. | -| tokenAddress | address | The address of the token to give. | -| tokenManager | address | The address of the token manager. | -| to | address | The address to give tokens to. | -| amount | uint256 | The amount of tokens to give. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| from | address | The address that will have its tokens burnt. | +| amount | uint256 | The amount of tokens to burn. | -#### Return Values +## IGatewayCaller -| Name | Type | Description | -| ---- | ------- | -------------------------------------------------------------------------------------------- | -| [0] | uint256 | uint256 The amount of token actually given, which could be different for certain token type. | +_Interface for the GatewayCaller contract_ -### takeToken +### MetadataVersion + +_Enum representing different metadata versions_ ```solidity -function takeToken(uint256 tokenManagerType, address tokenAddress, address tokenManager, address from, uint256 amount) external payable returns (uint256) +enum MetadataVersion { + CONTRACT_CALL, + EXPRESS_CALL +} ``` -This function takes token from a specified address to the token manager. - -#### Parameters - -| Name | Type | Description | -| ---------------- | ------- | --------------------------------- | -| tokenManagerType | uint256 | The token manager type. | -| tokenAddress | address | The address of the token to give. | -| tokenManager | address | The address of the token manager. | -| from | address | The address to take tokens from. | -| amount | uint256 | The amount of token to take. | +### InvalidMetadataVersion -#### Return Values +```solidity +error InvalidMetadataVersion(uint32 metadataVersion) +``` -| Name | Type | Description | -| ---- | ------- | -------------------------------------------------------------------------------------------- | -| [0] | uint256 | uint256 The amount of token actually taken, which could be different for certain token type. | +_Error thrown when an invalid metadata version is provided_ -### transferTokenFrom +### callContract ```solidity -function transferTokenFrom(uint256 tokenManagerType, address tokenAddress, address from, address to, uint256 amount) external payable returns (uint256) +function callContract(string destinationChain, string destinationAddress, bytes payload, enum IGatewayCaller.MetadataVersion metadataVersion, uint256 gasValue) external payable ``` -This function transfers token from and to a specified address. +Call the Axelar gateway to send a payload to a destination contract on a specific destination chain #### Parameters -| Name | Type | Description | -| ---------------- | ------- | ------------------------------------ | -| tokenManagerType | uint256 | The token manager type. | -| tokenAddress | address | the address of the token to give. | -| from | address | The address to transfer tokens from. | -| to | address | The address to transfer tokens to. | -| amount | uint256 | The amount of token to transfer. | - -#### Return Values - -| Name | Type | Description | -| ---- | ------- | -------------------------------------------------------------------------------------------------- | -| [0] | uint256 | uint256 The amount of token actually transferred, which could be different for certain token type. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| destinationChain | string | The target chain where the contract will be called | +| destinationAddress | string | The address of the contract to be called on the destination chain | +| payload | bytes | The data payload for the transaction | +| metadataVersion | enum IGatewayCaller.MetadataVersion | The version of metadata to be used | +| gasValue | uint256 | The amount of gas to be paid for the cross-chain message. If this is 0, then gas payment is skipped. `msg.value` must be at least gasValue. | -## ITokenManager +## IInterchainTokenDeployer -This contract is responsible for managing tokens, such as setting locking token balances, or setting flow limits, for interchain transfers. +This interface is used to deploy new instances of the InterchainTokenProxy contract. -### TokenLinkerZeroAddress +### AddressZero ```solidity -error TokenLinkerZeroAddress() +error AddressZero() ``` -### NotService +### TokenDeploymentFailed ```solidity -error NotService(address caller) +error TokenDeploymentFailed() ``` -### TakeTokenFailed +### implementationAddress ```solidity -error TakeTokenFailed() +function implementationAddress() external view returns (address) ``` -### GiveTokenFailed - -```solidity -error GiveTokenFailed() -``` +Returns the interchain token implementation address. -### NotToken +#### Return Values -```solidity -error NotToken(address caller) -``` +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | address | address The interchain token implementation address. | -### ZeroAddress +### deployedAddress ```solidity -error ZeroAddress() +function deployedAddress(bytes32 salt) external view returns (address tokenAddress) ``` -### AlreadyFlowLimiter +Returns the interchain token deployment address. -```solidity -error AlreadyFlowLimiter(address flowLimiter) -``` +#### Parameters -### NotFlowLimiter +| Name | Type | Description | +| ---- | ---- | ----------- | +| salt | bytes32 | The deployment salt. | -```solidity -error NotFlowLimiter(address flowLimiter) -``` +#### Return Values -### NotSupported +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress | address | The token address. | + +### deployInterchainToken ```solidity -error NotSupported() +function deployInterchainToken(bytes32 salt, bytes32 tokenId, address minter, string name, string symbol, uint8 decimals) external returns (address tokenAddress) ``` -### implementationType +Deploys a new instance of the InterchainTokenProxy contract. -```solidity -function implementationType() external view returns (uint256) -``` +#### Parameters -Returns implementation type of this token manager. +| Name | Type | Description | +| ---- | ---- | ----------- | +| salt | bytes32 | The salt used by Create3Deployer. | +| tokenId | bytes32 | tokenId of the token. | +| minter | address | Address of the minter. | +| name | string | Name of the token. | +| symbol | string | Symbol of the token. | +| decimals | uint8 | Decimals of the token. | #### Return Values -| Name | Type | Description | -| ---- | ------- | ------------------------------------------------------ | -| [0] | uint256 | uint256 The implementation type of this token manager. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress | address | Address of the deployed token. | -### addFlowIn +## IInterchainTokenExecutable -```solidity -function addFlowIn(uint256 amount) external -``` +Contracts should implement this interface to accept calls from the InterchainTokenService. -### addFlowOut +### executeWithInterchainToken ```solidity -function addFlowOut(uint256 amount) external +function executeWithInterchainToken(bytes32 commandId, string sourceChain, bytes sourceAddress, bytes data, bytes32 tokenId, address token, uint256 amount) external returns (bytes32) ``` -### addFlowLimiter +This will be called after the tokens are sent to this contract. -```solidity -function addFlowLimiter(address flowLimiter) external -``` +_Execution should revert unless the msg.sender is the InterchainTokenService_ -This function adds a flow limiter for this TokenManager. +#### Parameters -_Can only be called by the operator._ +| Name | Type | Description | +| ---- | ---- | ----------- | +| commandId | bytes32 | The unique message id for the call. | +| sourceChain | string | The name of the source chain. | +| sourceAddress | bytes | The address that sent the contract call. | +| data | bytes | The data to be processed. | +| tokenId | bytes32 | The tokenId of the token manager managing the token. | +| token | address | The address of the token. | +| amount | uint256 | The amount of tokens that were sent. | -#### Parameters +#### Return Values -| Name | Type | Description | -| ----------- | ------- | ------------------------------------ | -| flowLimiter | address | the address of the new flow limiter. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 Hash indicating success of the execution. | -### removeFlowLimiter +## IInterchainTokenExpressExecutable + +Contracts should implement this interface to accept express calls from the InterchainTokenService. + +### expressExecuteWithInterchainToken ```solidity -function removeFlowLimiter(address flowLimiter) external +function expressExecuteWithInterchainToken(bytes32 commandId, string sourceChain, bytes sourceAddress, bytes data, bytes32 tokenId, address token, uint256 amount) external returns (bytes32) ``` -This function removes a flow limiter for this TokenManager. +Executes express logic in the context of an interchain token transfer. -_Can only be called by the operator._ +_Only callable by the interchain token service._ #### Parameters -| Name | Type | Description | -| ----------- | ------- | ---------------------------------------- | -| flowLimiter | address | the address of an existing flow limiter. | - -### isFlowLimiter +| Name | Type | Description | +| ---- | ---- | ----------- | +| commandId | bytes32 | The unique message id for the call. | +| sourceChain | string | The source chain of the token transfer. | +| sourceAddress | bytes | The source address of the token transfer. | +| data | bytes | The data associated with the token transfer. | +| tokenId | bytes32 | The token ID. | +| token | address | The token address. | +| amount | uint256 | The amount of tokens to be transferred. | -```solidity -function isFlowLimiter(address addr) external view returns (bool) -``` +#### Return Values -Query if an address is a flow limiter. +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 Hash indicating success of the express execution. | -#### Parameters +## ITokenHandler -| Name | Type | Description | -| ---- | ------- | ------------------------- | -| addr | address | The address to query for. | +This interface is responsible for handling tokens before initiating an interchain token transfer, or after receiving one. -#### Return Values +### UnsupportedTokenManagerType -| Name | Type | Description | -| ---- | ---- | ----------------------------------------------------------------------------- | -| [0] | bool | bool Boolean value representing whether or not the address is a flow limiter. | +```solidity +error UnsupportedTokenManagerType(uint256 tokenManagerType) +``` -### setFlowLimit +### NotToken ```solidity -function setFlowLimit(uint256 flowLimit_) external +error NotToken(address caller, address token) ``` -This function sets the flow limit for this TokenManager. +### giveToken -_Can only be called by the flow limiters._ +```solidity +function giveToken(bytes32 tokenId, address to, uint256 amount) external returns (uint256, address) +``` -#### Parameters +This function gives token to a specified address from the token manager. -| Name | Type | Description | -| ----------- | ------- | --------------------------------------------------------------------------------------------------- | -| flowLimit\_ | uint256 | The maximum difference between the tokens flowing in and/or out at any given interval of time (6h). | +#### Parameters -### approveService +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The token id of the tokenManager. | +| to | address | The address to give tokens to. | +| amount | uint256 | The amount of tokens to give. | -```solidity -function approveService() external -``` +#### Return Values -A function to renew approval to the service if we need to. +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | uint256 The amount of token actually given, which could be different for certain token type. | +| [1] | address | address the address of the token. | -### params +### takeToken ```solidity -function params(bytes operator_, address tokenAddress_) external pure returns (bytes params_) +function takeToken(bytes32 tokenId, bool tokenOnly, address from, uint256 amount) external payable returns (uint256) ``` -Getter function for the parameters of a lock/unlock TokenManager. - -_This function will be mainly used by frontends._ +This function takes token from a specified address to the token manager. #### Parameters -| Name | Type | Description | -| -------------- | ------- | --------------------------------- | -| operator\_ | bytes | The operator of the TokenManager. | -| tokenAddress\_ | address | The token to be managed. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The tokenId for the token. | +| tokenOnly | bool | can only be called from the token. | +| from | address | The address to take tokens from. | +| amount | uint256 | The amount of token to take. | #### Return Values -| Name | Type | Description | -| -------- | ----- | --------------------------------------------------------------------- | -| params\_ | bytes | The resulting params to be passed to custom TokenManager deployments. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | uint256 The amount of token actually taken, which could be different for certain token type. | -### mintToken +### transferTokenFrom ```solidity -function mintToken(address tokenAddress_, address to, uint256 amount) external +function transferTokenFrom(bytes32 tokenId, address from, address to, uint256 amount) external returns (uint256, address) ``` -External function to allow the service to mint tokens through the tokenManager - -_This function should revert if called by anyone but the service._ +This function transfers token from and to a specified address. #### Parameters -| Name | Type | Description | -| -------------- | ------- | ----------------------------------------------------------------------------------------------------- | -| tokenAddress\_ | address | The address of the token, since its cheaper to pass it in instead of reading it as the token manager. | -| to | address | The recipient. | -| amount | uint256 | The amount to mint. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The token id of the token manager. | +| from | address | The address to transfer tokens from. | +| to | address | The address to transfer tokens to. | +| amount | uint256 | The amount of token to transfer. | + +#### Return Values -### burnToken +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | uint256 The amount of token actually transferred, which could be different for certain token type. | +| [1] | address | address The address of the token corresponding to the input tokenId. | + +### postTokenManagerDeploy ```solidity -function burnToken(address tokenAddress_, address from, uint256 amount) external +function postTokenManagerDeploy(uint256 tokenManagerType, address tokenManager) external payable ``` -External function to allow the service to burn tokens through the tokenManager - -_This function should revert if called by anyone but the service._ +This function prepares a token manager after it is deployed #### Parameters -| Name | Type | Description | -| -------------- | ------- | ----------------------------------------------------------------------------------------------------- | -| tokenAddress\_ | address | The address of the token, since its cheaper to pass it in instead of reading it as the token manager. | -| from | address | The address to burn the token from. | -| amount | uint256 | The amount to burn. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenManagerType | uint256 | The token manager type. | +| tokenManager | address | The address of the token manager. | ## ITokenManagerDeployer @@ -3790,42 +4364,18 @@ Deploys a new instance of the TokenManagerProxy contract. #### Parameters -| Name | Type | Description | -| ------------------ | ------- | ------------------------------------------------------------- | -| tokenId | bytes32 | The token ID. | -| implementationType | uint256 | Token manager implementation type. | -| params | bytes | Additional parameters used in the setup of the token manager. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The token ID. | +| implementationType | uint256 | Token manager implementation type. | +| params | bytes | Additional parameters used in the setup of the token manager. | #### Return Values -| Name | Type | Description | -| ------------ | ------- | ------------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | tokenManager | address | Address of the deployed tokenManager. | -## ITokenManagerImplementation - -Interface for returning the token manager implementation type. - -### tokenManagerImplementation - -```solidity -function tokenManagerImplementation(uint256 tokenManagerType) external view returns (address tokenManagerAddress_) -``` - -Returns the implementation address for a given token manager type. - -#### Parameters - -| Name | Type | Description | -| ---------------- | ------- | -------------------------- | -| tokenManagerType | uint256 | The type of token manager. | - -#### Return Values - -| Name | Type | Description | -| --------------------- | ------- | ------------------------------------------------ | -| tokenManagerAddress\_ | address | The address of the token manager implementation. | - ## ITokenManagerProxy This interface is for a proxy for token manager contracts. @@ -3846,9 +4396,9 @@ Returns implementation type of this token manager. #### Return Values -| Name | Type | Description | -| ---- | ------- | ------------------------------------------------------ | -| [0] | uint256 | uint256 The implementation type of this token manager. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | uint256 The implementation type of this token manager. | ### interchainTokenId @@ -3860,9 +4410,9 @@ Returns the interchain token ID of the token manager. #### Return Values -| Name | Type | Description | -| ---- | ------- | ----------------------------------------------------- | -| [0] | bytes32 | bytes32 The interchain token ID of the token manager. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 The interchain token ID of the token manager. | ### tokenAddress @@ -3874,9 +4424,9 @@ Returns token address that this token manager manages. #### Return Values -| Name | Type | Description | -| ---- | ------- | -------------------------- | -| [0] | address | address The token address. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | address | address The token address. | ### getImplementationTypeAndTokenAddress @@ -3888,63 +4438,10 @@ Returns implementation type and token address. #### Return Values -| Name | Type | Description | -| ---- | ------- | -------------------------------- | -| [0] | uint256 | uint256 The implementation type. | -| [1] | address | address The token address. | - -## ITokenManagerType - -A simple interface that defines all the token manager types. - -### TokenManagerType - -```solidity -enum TokenManagerType { - NATIVE_INTERCHAIN_TOKEN, - MINT_BURN_FROM, - LOCK_UNLOCK, - LOCK_UNLOCK_FEE, - MINT_BURN -} -``` - -## ITransmitInterchainToken - -Interface for transmiting interchain tokens via the interchain token service - -### transmitInterchainTransfer - -```solidity -function transmitInterchainTransfer(bytes32 tokenId, address sourceAddress, string destinationChain, bytes destinationAddress, uint256 amount, bytes metadata) external payable -``` - -Transmit an interchain transfer for the given tokenId. - -_Only callable by a token registered under a tokenId._ - -#### Parameters - -| Name | Type | Description | -| ------------------ | ------- | ----------------------------------------------------------------------------------------------- | -| tokenId | bytes32 | The tokenId of the token (which must be the msg.sender). | -| sourceAddress | address | The address where the token is coming from. | -| destinationChain | string | The name of the chain to send tokens to. | -| destinationAddress | bytes | The destinationAddress for the interchainTransfer. | -| amount | uint256 | The amount of token to give. | -| metadata | bytes | Optional metadata for the call for additional effects (such as calling a destination contract). | - -## InterchainProxy - -This contract is a proxy for interchainTokenService and interchainTokenFactory. - -_This contract implements Proxy._ - -### constructor - -```solidity -constructor(address implementationAddress, address owner, bytes setupParams) public -``` +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | uint256 The implementation type. | +| [1] | address | address The token address. | ## TokenManagerProxy @@ -4007,12 +4504,12 @@ Constructs the TokenManagerProxy contract. #### Parameters -| Name | Type | Description | -| ------------------------ | ------- | ------------------------------------------------------------- | -| interchainTokenService\_ | address | The address of the interchain token service. | -| implementationType\_ | uint256 | The token manager type. | -| tokenId | bytes32 | The identifier for the token. | -| params | bytes | The initialization parameters for the token manager contract. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| interchainTokenService_ | address | The address of the interchain token service. | +| implementationType_ | uint256 | The token manager type. | +| tokenId | bytes32 | The identifier for the token. | +| params | bytes | The initialization parameters for the token manager contract. | ### contractId @@ -4024,9 +4521,9 @@ Getter for the contract id. #### Return Values -| Name | Type | Description | -| ---- | ------- | ------------------------ | -| [0] | bytes32 | bytes32 The contract id. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 The contract id. | ### getImplementationTypeAndTokenAddress @@ -4038,10 +4535,10 @@ Returns implementation type and token address. #### Return Values -| Name | Type | Description | -| -------------------- | ------- | ------------------------ | -| implementationType\_ | uint256 | The implementation type. | -| tokenAddress\_ | address | The token address. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| implementationType_ | uint256 | The implementation type. | +| tokenAddress_ | address | The token address. | ### implementation @@ -4053,11 +4550,11 @@ Returns the address of the current implementation. #### Return Values -| Name | Type | Description | -| ---------------- | ------- | ------------------------------------------ | -| implementation\_ | address | The address of the current implementation. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| implementation_ | address | The address of the current implementation. | -### \_tokenManagerImplementation +### _tokenManagerImplementation ```solidity function _tokenManagerImplementation(address interchainTokenService_, uint256 implementationType_) internal view returns (address implementation_) @@ -4067,16 +4564,16 @@ Returns the implementation address from the interchain token service for the pro #### Parameters -| Name | Type | Description | -| ------------------------ | ------- | -------------------------------------------- | -| interchainTokenService\_ | address | The address of the interchain token service. | -| implementationType\_ | uint256 | The token manager type. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| interchainTokenService_ | address | The address of the interchain token service. | +| implementationType_ | uint256 | The token manager type. | #### Return Values -| Name | Type | Description | -| ---------------- | ------- | ---------------------------------- | -| implementation\_ | address | The address of the implementation. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| implementation_ | address | The address of the implementation. | ## InvalidService @@ -4108,7 +4605,7 @@ address service bytes32 tokenId ``` -### tokenManagerRequiresApproval\_ +### tokenManagerRequiresApproval_ ```solidity bool tokenManagerRequiresApproval_ @@ -4150,9 +4647,9 @@ _Needs to be overwritten._ #### Return Values -| Name | Type | Description | -| ---- | ------- | ----------- | -| [0] | address | | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | address | | ### interchainTokenId @@ -4166,17 +4663,17 @@ _Needs to be overwritten._ #### Return Values -| Name | Type | Description | -| ---- | ------- | ----------- | -| [0] | bytes32 | | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | | -### \_beforeInterchainTransfer +### _beforeInterchainTransfer ```solidity function _beforeInterchainTransfer(address sender, string, bytes, uint256 amount, bytes) internal ``` -### \_spendAllowance +### _spendAllowance ```solidity function _spendAllowance(address sender, address spender, uint256 amount) internal @@ -4210,13 +4707,13 @@ function burn(address account, uint256 amount) external function setTokenId(bytes32 tokenId_) external ``` -### \_transfer +### _transfer ```solidity function _transfer(address sender, address recipient, uint256 amount) internal virtual ``` -\_Moves tokens `amount` from `sender` to `recipient`. +_Moves tokens `amount` from `sender` to `recipient`. This is internal function is equivalent to {transfer}, and can be used to e.g. implement automatic token fees, slashing mechanisms, etc. @@ -4225,9 +4722,9 @@ Emits a {Transfer} event. Requirements: -- `sender` cannot be the zero address. -- `recipient` cannot be the zero address. -- `sender` must have a balance of at least `amount`.\_ +- `sender` cannot be the zero address. +- `recipient` cannot be the zero address. +- `sender` must have a balance of at least `amount`._ ## TestFeeOnTransferTokenInvalid @@ -4237,7 +4734,7 @@ Requirements: constructor(string name_, string symbol_, uint8 decimals_, address service_, bytes32 tokenId_) public ``` -### \_transfer +### _transfer ```solidity function _transfer(address, address, uint256 amount) internal @@ -4251,13 +4748,13 @@ function _transfer(address, address, uint256 amount) internal constructor(string name_, string symbol_, uint8 decimals_, address service_, bytes32 tokenId_) public ``` -### \_transfer +### _transfer ```solidity function _transfer(address sender, address recipient, uint256 amount) internal ``` -\_Moves tokens `amount` from `sender` to `recipient`. +_Moves tokens `amount` from `sender` to `recipient`. This is internal function is equivalent to {transfer}, and can be used to e.g. implement automatic token fees, slashing mechanisms, etc. @@ -4266,9 +4763,9 @@ Emits a {Transfer} event. Requirements: -- `sender` cannot be the zero address. -- `recipient` cannot be the zero address. -- `sender` must have a balance of at least `amount`.\_ +- `sender` cannot be the zero address. +- `recipient` cannot be the zero address. +- `sender` must have a balance of at least `amount`._ ## TestInterchainExecutable @@ -4290,7 +4787,7 @@ constructor(address interchainTokenService_) public string lastMessage ``` -### \_executeWithInterchainToken +### _executeWithInterchainToken ```solidity function _executeWithInterchainToken(bytes32 commandId, string sourceChain, bytes sourceAddress, bytes data, bytes32 tokenId, address token, uint256 amount) internal @@ -4302,15 +4799,15 @@ _Logic must be implemented by derived contracts._ #### Parameters -| Name | Type | Description | -| ------------- | ------- | -------------------------------------------- | -| commandId | bytes32 | The unique message id. | -| sourceChain | string | The source chain of the token transfer. | -| sourceAddress | bytes | The source address of the token transfer. | -| data | bytes | The data associated with the token transfer. | -| tokenId | bytes32 | The token ID. | -| token | address | The token address. | -| amount | uint256 | The amount of tokens being transferred. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| commandId | bytes32 | The unique message id. | +| sourceChain | string | The source chain of the token transfer. | +| sourceAddress | bytes | The source address of the token transfer. | +| data | bytes | The data associated with the token transfer. | +| tokenId | bytes32 | The token ID. | +| token | address | The token address. | +| amount | uint256 | The amount of tokens being transferred. | ## Invalid @@ -4338,32 +4835,6 @@ constructor() public function spendAllowance(address sender, address spender, uint256 amount) external ``` -## TestInterchainTokenService - -### LatestMetadataVersionMismatch - -```solidity -error LatestMetadataVersionMismatch(uint32 const, uint32 calculated) -``` - -### constructor - -```solidity -constructor(address tokenManagerDeployer_, address interchainTokenDeployer_, address gateway_, address gasService_, address interchainTokenFactory_, string chainName_, address tokenManager_, address tokenHandler_) public -``` - -### setupTest - -```solidity -function setupTest(bytes params) external -``` - -### callContract - -```solidity -function callContract(string destinationChain, bytes payload, enum InterchainTokenService.MetadataVersion metadataVersion, uint256 gasValue) external payable -``` - ## TestInterchainTokenStandard ### service @@ -4378,7 +4849,7 @@ address service bytes32 tokenId ``` -### tokenManagerRequiresApproval\_ +### tokenManagerRequiresApproval_ ```solidity bool tokenManagerRequiresApproval_ @@ -4426,9 +4897,9 @@ _Needs to be overwritten._ #### Return Values -| Name | Type | Description | -| ---- | ------- | ----------- | -| [0] | address | | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | address | | ### interchainTokenId @@ -4442,17 +4913,17 @@ _Needs to be overwritten._ #### Return Values -| Name | Type | Description | -| ---- | ------- | ----------- | -| [0] | bytes32 | | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | | -### \_beforeInterchainTransfer +### _beforeInterchainTransfer ```solidity function _beforeInterchainTransfer(address sender, string, bytes, uint256 amount, bytes) internal ``` -### \_spendAllowance +### _spendAllowance ```solidity function _spendAllowance(address sender, address spender, uint256 amount) internal @@ -4542,23 +5013,23 @@ _Only callable by the interchain token service._ #### Parameters -| Name | Type | Description | -| ------------- | ------- | -------------------------------------------- | -| commandId | bytes32 | The unique message id. | -| sourceChain | string | The source chain of the token transfer. | -| sourceAddress | bytes | The source address of the token transfer. | -| data | bytes | The data associated with the token transfer. | -| tokenId | bytes32 | The token ID. | -| token | address | The token address. | -| amount | uint256 | The amount of tokens to be transferred. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| commandId | bytes32 | The unique message id. | +| sourceChain | string | The source chain of the token transfer. | +| sourceAddress | bytes | The source address of the token transfer. | +| data | bytes | The data associated with the token transfer. | +| tokenId | bytes32 | The token ID. | +| token | address | The token address. | +| amount | uint256 | The amount of tokens to be transferred. | #### Return Values -| Name | Type | Description | -| ---- | ------- | --------------------------------------------------------- | -| [0] | bytes32 | bytes32 Hash indicating success of the express execution. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 Hash indicating success of the express execution. | -### \_executeWithInterchainToken +### _executeWithInterchainToken ```solidity function _executeWithInterchainToken(bytes32 commandId, string sourceChain, bytes sourceAddress, bytes data, bytes32 tokenId, address token, uint256 amount) internal @@ -4570,15 +5041,15 @@ _Logic must be implemented by derived contracts._ #### Parameters -| Name | Type | Description | -| ------------- | ------- | -------------------------------------------- | -| commandId | bytes32 | The unique message id. | -| sourceChain | string | The source chain of the token transfer. | -| sourceAddress | bytes | The source address of the token transfer. | -| data | bytes | The data associated with the token transfer. | -| tokenId | bytes32 | The token ID. | -| token | address | The token address. | -| amount | uint256 | The amount of tokens being transferred. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| commandId | bytes32 | The unique message id. | +| sourceChain | string | The source chain of the token transfer. | +| sourceAddress | bytes | The source address of the token transfer. | +| data | bytes | The data associated with the token transfer. | +| tokenId | bytes32 | The token ID. | +| token | address | The token address. | +| amount | uint256 | The amount of tokens being transferred. | ## TestMintableBurnableERC20 @@ -4637,13 +5108,33 @@ function addOperator(address operator) external ### constructor ```solidity -constructor(address interchainTokenService_, uint256 implementationType_, bytes32 tokenId, bytes params) public +constructor(address interchainTokenService_, uint256 implementationType_, bytes32 tokenId, bytes params) public +``` + +### getContractId + +```solidity +function getContractId() external pure returns (bytes32) +``` + +## TestCreate3Fixed + +### Deployed + +```solidity +event Deployed(address addr) +``` + +### deploy + +```solidity +function deploy(bytes code, bytes32 salt) public payable returns (address addr) ``` -### getContractId +### deployedAddress ```solidity -function getContractId() external pure returns (bytes32) +function deployedAddress(bytes32 salt) public view returns (address addr) ``` ## TestFlowLimit @@ -4732,23 +5223,23 @@ Returns the current flow limit. #### Return Values -| Name | Type | Description | -| ----------- | ------- | ----------------------------- | -| flowLimit\_ | uint256 | The current flow limit value. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowLimit_ | uint256 | The current flow limit value. | -### \_setFlowLimit +### _setFlowLimit ```solidity function _setFlowLimit(uint256 flowLimit_) internal ``` -### \_getFlowOutSlot +### _getFlowOutSlot ```solidity function _getFlowOutSlot(uint256 epoch) internal pure returns (uint256 slot) ``` -### \_getFlowInSlot +### _getFlowInSlot ```solidity function _getFlowInSlot(uint256 epoch) internal pure returns (uint256 slot) @@ -4764,9 +5255,9 @@ Returns the current flow out amount. #### Return Values -| Name | Type | Description | -| --------------- | ------- | ---------------------------- | -| flowOutAmount\_ | uint256 | The current flow out amount. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowOutAmount_ | uint256 | The current flow out amount. | ### flowInAmount @@ -4778,23 +5269,23 @@ Returns the current flow in amount. #### Return Values -| Name | Type | Description | -| -------------- | ------- | --------------------------- | -| flowInAmount\_ | uint256 | The current flow in amount. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowInAmount_ | uint256 | The current flow in amount. | -### \_addFlow +### _addFlow ```solidity function _addFlow(uint256 flowLimit_, uint256 slotToAdd, uint256 slotToCompare, uint256 flowAmount) internal ``` -### \_addFlowOut +### _addFlowOut ```solidity function _addFlowOut(uint256 flowOutAmount_) internal ``` -### \_addFlowIn +### _addFlowIn ```solidity function _addFlowIn(uint256 flowInAmount_) internal @@ -4818,6 +5309,20 @@ function addFlowIn(uint256 flowInAmount_) external function addFlowOut(uint256 flowOutAmount_) external ``` +## TestGatewayCaller + +### DelegatecallFailed + +```solidity +error DelegatecallFailed() +``` + +### delegatecall + +```solidity +function delegatecall(bytes) external pure returns (bool, bytes) +``` + ## TestMinter ### nonce @@ -4896,9 +5401,9 @@ Constructs the TokenManager contract. #### Parameters -| Name | Type | Description | -| ------------------------ | ------- | -------------------------------------------- | -| interchainTokenService\_ | address | The address of the interchain token service. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| interchainTokenService_ | address | The address of the interchain token service. | ### onlyService @@ -4918,9 +5423,9 @@ Getter for the contract id. #### Return Values -| Name | Type | Description | -| ---- | ------- | ------------------------ | -| [0] | bytes32 | bytes32 The contract id. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 The contract id. | ### tokenAddress @@ -4935,9 +5440,9 @@ must be called by the proxy._ #### Return Values -| Name | Type | Description | -| ---- | ------- | ---------------------------------------- | -| [0] | address | tokenAddress\_ The address of the token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | address | tokenAddress_ The address of the token. | ### interchainTokenId @@ -4951,9 +5456,9 @@ _This will only work when implementation is called by a proxy, which stores the #### Return Values -| Name | Type | Description | -| ---- | ------- | -------------------------------- | -| [0] | bytes32 | bytes32 The interchain token ID. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | bytes32 The interchain token ID. | ### implementationType @@ -4965,9 +5470,9 @@ Returns implementation type of this token manager. #### Return Values -| Name | Type | Description | -| ---- | ------- | ------------------------------------------------------ | -| [0] | uint256 | uint256 The implementation type of this token manager. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | uint256 The implementation type of this token manager. | ### getTokenAddressFromParams @@ -4979,15 +5484,15 @@ A function that should return the token address from the setup params. #### Parameters -| Name | Type | Description | -| -------- | ----- | --------------------- | -| params\_ | bytes | The setup parameters. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| params_ | bytes | The setup parameters. | #### Return Values -| Name | Type | Description | -| -------------- | ------- | ------------------ | -| tokenAddress\_ | address | The token address. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress_ | address | The token address. | ### setup @@ -5003,9 +5508,9 @@ for the address of the operator, stored as bytes (to be compatible with non-EVM #### Parameters -| Name | Type | Description | -| -------- | ----- | --------------------------------------------------------- | -| params\_ | bytes | The parameters to be used to initialize the TokenManager. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| params_ | bytes | The parameters to be used to initialize the TokenManager. | ### addFlowIn @@ -5019,6 +5524,23 @@ function addFlowIn(uint256 amount) external function addFlowOut(uint256 amount) external ``` +### transferFlowLimiter + +```solidity +function transferFlowLimiter(address from, address to) external +``` + +This function transfers a flow limiter for this TokenManager. + +_Can only be called by the operator._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| from | address | the address of the old flow limiter. | +| to | address | the address of the new flow limiter. | + ### addFlowLimiter ```solidity @@ -5031,8 +5553,8 @@ _Can only be called by the operator._ #### Parameters -| Name | Type | Description | -| ----------- | ------- | ------------------------------------ | +| Name | Type | Description | +| ---- | ---- | ----------- | | flowLimiter | address | the address of the new flow limiter. | ### removeFlowLimiter @@ -5047,8 +5569,8 @@ _Can only be called by the operator._ #### Parameters -| Name | Type | Description | -| ----------- | ------- | ---------------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | flowLimiter | address | the address of an existing flow limiter. | ### isFlowLimiter @@ -5061,15 +5583,15 @@ Query if an address is a flow limiter. #### Parameters -| Name | Type | Description | -| ---- | ------- | ------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | addr | address | The address to query for. | #### Return Values -| Name | Type | Description | -| ---- | ---- | ----------------------------------------------------------------------------- | -| [0] | bool | bool Boolean value representing whether or not the address is a flow limiter. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | bool Boolean value representing whether or not the address is a flow limiter. | ### setFlowLimit @@ -5083,9 +5605,9 @@ _Can only be called by the flow limiters._ #### Parameters -| Name | Type | Description | -| ----------- | ------- | --------------------------------------------------------------------------------------------------- | -| flowLimit\_ | uint256 | The maximum difference between the tokens flowing in and/or out at any given interval of time (6h). | +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowLimit_ | uint256 | The maximum difference between the tokens flowing in and/or out at any given interval of time (6h). | ### approveService @@ -5107,16 +5629,16 @@ _This function will be mainly used by frontends._ #### Parameters -| Name | Type | Description | -| -------------- | ------- | --------------------------------- | -| operator\_ | bytes | The operator of the TokenManager. | -| tokenAddress\_ | address | The token to be managed. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| operator_ | bytes | The operator of the TokenManager. | +| tokenAddress_ | address | The token to be managed. | #### Return Values -| Name | Type | Description | -| -------- | ----- | --------------------------------------------------------------------- | -| params\_ | bytes | The resulting params to be passed to custom TokenManager deployments. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| params_ | bytes | The resulting params to be passed to custom TokenManager deployments. | ### mintToken @@ -5130,11 +5652,11 @@ _This function should revert if called by anyone but the service._ #### Parameters -| Name | Type | Description | -| -------------- | ------- | ----------------------------------------------------------------------------------------------------- | -| tokenAddress\_ | address | The address of the token, since its cheaper to pass it in instead of reading it as the token manager. | -| to | address | The recipient. | -| amount | uint256 | The amount to mint. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress_ | address | The address of the token, since its cheaper to pass it in instead of reading it as the token manager. | +| to | address | The recipient. | +| amount | uint256 | The amount to mint. | ### burnToken @@ -5148,11 +5670,127 @@ _This function should revert if called by anyone but the service._ #### Parameters -| Name | Type | Description | -| -------------- | ------- | ----------------------------------------------------------------------------------------------------- | -| tokenAddress\_ | address | The address of the token, since its cheaper to pass it in instead of reading it as the token manager. | -| from | address | The address to burn the token from. | -| amount | uint256 | The amount to burn. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenAddress_ | address | The address of the token, since its cheaper to pass it in instead of reading it as the token manager. | +| from | address | The address to burn the token from. | +| amount | uint256 | The amount to burn. | + +## MessageType + +```solidity +enum MessageType { + INTERCHAIN_TRANSFER, + DEPLOY_INTERCHAIN_TOKEN, + DEPLOY_TOKEN_MANAGER +} +``` + +## InterchainTransfer + +```solidity +struct InterchainTransfer { + uint256 messageType; + bytes32 tokenId; + bytes sourceAddress; + bytes destinationAddress; + uint256 amount; + bytes data; +} +``` + +## DeployInterchainToken + +```solidity +struct DeployInterchainToken { + uint256 messageType; + bytes32 tokenId; + string name; + string symbol; + uint8 decimals; + bytes minter; +} +``` + +## DeployTokenManager + +```solidity +struct DeployTokenManager { + uint256 messageType; + bytes32 tokenId; + uint256 tokenManagerType; + bytes params; +} +``` + +## Create3AddressFixed + +This contract can be used to predict the deterministic deployment address of a contract deployed with the `CREATE3` technique. +It is equivalent to the Create3Address found in axelar-gmp-sdk-solidity repo but uses a fixed bytecode for CreateDeploy, +which allows changing compilation options (like number of runs) without affecting the future deployment addresses. + +### CREATE_DEPLOY_BYTECODE + +```solidity +bytes CREATE_DEPLOY_BYTECODE +``` + +### CREATE_DEPLOY_BYTECODE_HASH + +```solidity +bytes32 CREATE_DEPLOY_BYTECODE_HASH +``` + +### _create3Address + +```solidity +function _create3Address(bytes32 deploySalt) internal view returns (address deployed) +``` + +Compute the deployed address that will result from the `CREATE3` method. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| deploySalt | bytes32 | A salt to influence the contract address | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| deployed | address | The deterministic contract address if it was deployed | + +## Create3Fixed + +This contract can be used to deploy a contract with a deterministic address that depends only on +the deployer address and deployment salt, not the contract bytecode and constructor parameters. +It uses a fixed bytecode to allow changing the compilation settings without affecting the deployment address in the future. + +### _create3 + +```solidity +function _create3(bytes bytecode, bytes32 deploySalt) internal returns (address deployed) +``` + +Deploys a new contract using the `CREATE3` method. + +_This function first deploys the CreateDeploy contract using +the `CREATE2` opcode and then utilizes the CreateDeploy to deploy the +new contract with the `CREATE` opcode._ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| bytecode | bytes | The bytecode of the contract to be deployed | +| deploySalt | bytes32 | A salt to influence the contract address | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| deployed | address | The address of the deployed contract | ## FlowLimit @@ -5194,11 +5832,11 @@ Returns the current flow limit. #### Return Values -| Name | Type | Description | -| ----------- | ------- | ----------------------------- | -| flowLimit\_ | uint256 | The current flow limit value. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowLimit_ | uint256 | The current flow limit value. | -### \_setFlowLimit +### _setFlowLimit ```solidity function _setFlowLimit(uint256 flowLimit_, bytes32 tokenId) internal @@ -5208,12 +5846,12 @@ Internal function to set the flow limit. #### Parameters -| Name | Type | Description | -| ----------- | ------- | ---------------------------------------------- | -| flowLimit\_ | uint256 | The value to set the flow limit to. | -| tokenId | bytes32 | The id of the token to set the flow limit for. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowLimit_ | uint256 | The value to set the flow limit to. | +| tokenId | bytes32 | The id of the token to set the flow limit for. | -### \_getFlowOutSlot +### _getFlowOutSlot ```solidity function _getFlowOutSlot(uint256 epoch) internal pure returns (uint256 slot) @@ -5223,17 +5861,17 @@ Returns the slot which is used to get the flow out amount for a specific epoch. #### Parameters -| Name | Type | Description | -| ----- | ------- | ----------------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | epoch | uint256 | The epoch to get the flow out amount for. | #### Return Values -| Name | Type | Description | -| ---- | ------- | ----------------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | slot | uint256 | The slot to get the flow out amount from. | -### \_getFlowInSlot +### _getFlowInSlot ```solidity function _getFlowInSlot(uint256 epoch) internal pure returns (uint256 slot) @@ -5243,14 +5881,14 @@ _Returns the slot which is used to get the flow in amount for a specific epoch._ #### Parameters -| Name | Type | Description | -| ----- | ------- | ---------------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | epoch | uint256 | The epoch to get the flow in amount for. | #### Return Values -| Name | Type | Description | -| ---- | ------- | ---------------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | slot | uint256 | The slot to get the flow in amount from. | ### flowOutAmount @@ -5263,9 +5901,9 @@ Returns the current flow out amount. #### Return Values -| Name | Type | Description | -| --------------- | ------- | ---------------------------- | -| flowOutAmount\_ | uint256 | The current flow out amount. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowOutAmount_ | uint256 | The current flow out amount. | ### flowInAmount @@ -5277,11 +5915,11 @@ Returns the current flow in amount. #### Return Values -| Name | Type | Description | -| -------------- | ------- | --------------------------- | -| flowInAmount\_ | uint256 | The current flow in amount. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowInAmount_ | uint256 | The current flow in amount. | -### \_addFlow +### _addFlow ```solidity function _addFlow(uint256 flowLimit_, uint256 slotToAdd, uint256 slotToCompare, uint256 flowAmount) internal @@ -5291,14 +5929,14 @@ Adds a flow amount while ensuring it does not exceed the flow limit. #### Parameters -| Name | Type | Description | -| ------------- | ------- | ------------------------------------- | -| flowLimit\_ | uint256 | The current flow limit value. | -| slotToAdd | uint256 | The slot to add the flow to. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowLimit_ | uint256 | The current flow limit value. | +| slotToAdd | uint256 | The slot to add the flow to. | | slotToCompare | uint256 | The slot to compare the flow against. | -| flowAmount | uint256 | The flow amount to add. | +| flowAmount | uint256 | The flow amount to add. | -### \_addFlowOut +### _addFlowOut ```solidity function _addFlowOut(uint256 flowOutAmount_) internal @@ -5308,11 +5946,11 @@ Adds a flow out amount. #### Parameters -| Name | Type | Description | -| --------------- | ------- | --------------------------- | -| flowOutAmount\_ | uint256 | The flow out amount to add. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowOutAmount_ | uint256 | The flow out amount to add. | -### \_addFlowIn +### _addFlowIn ```solidity function _addFlowIn(uint256 flowInAmount_) internal @@ -5322,9 +5960,58 @@ Adds a flow in amount. #### Parameters -| Name | Type | Description | -| -------------- | ------- | -------------------------- | -| flowInAmount\_ | uint256 | The flow in amount to add. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| flowInAmount_ | uint256 | The flow in amount to add. | + +## GatewayCaller + +_This contract is used to handle cross-chain ITS calls via the Axelar gateway._ + +### gateway + +```solidity +contract IAxelarGateway gateway +``` + +### gasService + +```solidity +contract IAxelarGasService gasService +``` + +### constructor + +```solidity +constructor(address gateway_, address gasService_) public +``` + +_Constructor to initialize the GatewayCaller contract_ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| gateway_ | address | The address of the AxelarGateway contract | +| gasService_ | address | The address of the AxelarGasService contract | + +### callContract + +```solidity +function callContract(string destinationChain, string destinationAddress, bytes payload, enum IGatewayCaller.MetadataVersion metadataVersion, uint256 gasValue) external payable +``` + +_Calls a contract on a specific destination chain with the given payload_ + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| destinationChain | string | The target chain where the contract will be called | +| destinationAddress | string | The address of the contract to be called on the destination chain | +| payload | bytes | The data payload for the transaction | +| metadataVersion | enum IGatewayCaller.MetadataVersion | The version of metadata to be used | +| gasValue | uint256 | The amount of gas to be paid for the cross-chain message. If this is 0, then gas payment is skipped. `msg.value` must be at least gasValue. | ## InterchainTokenDeployer @@ -5353,9 +6040,9 @@ Constructor for the InterchainTokenDeployer contract. #### Parameters -| Name | Type | Description | -| ----------------------- | ------- | ---------------------------------------- | -| implementationAddress\_ | address | Address of the InterchainToken contract. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| implementationAddress_ | address | Address of the InterchainToken contract. | ### deployInterchainToken @@ -5367,19 +6054,19 @@ Deploys a new instance of the InterchainTokenProxy contract. #### Parameters -| Name | Type | Description | -| -------- | ------- | --------------------------------- | -| salt | bytes32 | The salt used by Create3Deployer. | -| tokenId | bytes32 | TokenId for the token. | -| minter | address | Address of the minter. | -| name | string | Name of the token. | -| symbol | string | Symbol of the token. | -| decimals | uint8 | Decimals of the token. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| salt | bytes32 | The salt used by Create3Deployer. | +| tokenId | bytes32 | TokenId for the token. | +| minter | address | Address of the minter. | +| name | string | Name of the token. | +| symbol | string | Symbol of the token. | +| decimals | uint8 | Decimals of the token. | #### Return Values -| Name | Type | Description | -| ------------ | ------- | ------------------------------ | +| Name | Type | Description | +| ---- | ---- | ----------- | | tokenAddress | address | Address of the deployed token. | ### deployedAddress @@ -5392,14 +6079,14 @@ Returns the interchain token deployment address. #### Parameters -| Name | Type | Description | -| ---- | ------- | -------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | salt | bytes32 | The deployment salt. | #### Return Values -| Name | Type | Description | -| ------------ | ------- | ------------------ | +| Name | Type | Description | +| ---- | ---- | ----------- | | tokenAddress | address | The token address. | ## Minter @@ -5410,7 +6097,7 @@ specific functions. _This module is used through inheritance._ -### \_addMinter +### _addMinter ```solidity function _addMinter(address minter_) internal @@ -5420,9 +6107,9 @@ Internal function that stores the new minter address in the correct storage slot #### Parameters -| Name | Type | Description | -| -------- | ------- | ------------------------------ | -| minter\_ | address | The address of the new minter. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| minter_ | address | The address of the new minter. | ### transferMintership @@ -5436,9 +6123,9 @@ _Can only be called by the current minter._ #### Parameters -| Name | Type | Description | -| -------- | ------- | ------------------------------ | -| minter\_ | address | The address of the new minter. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| minter_ | address | The address of the new minter. | ### proposeMintership @@ -5452,9 +6139,9 @@ _Can only be called by the current minter._ #### Parameters -| Name | Type | Description | -| -------- | ------- | ------------------------------ | -| minter\_ | address | The address of the new minter. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| minter_ | address | The address of the new minter. | ### acceptMintership @@ -5468,8 +6155,8 @@ _Can only be called by the proposed minter._ #### Parameters -| Name | Type | Description | -| ---------- | ------- | -------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | fromMinter | address | The previous minter. | ### isMinter @@ -5482,15 +6169,15 @@ Query if an address is a minter #### Parameters -| Name | Type | Description | -| ---- | ------- | ------------------------ | +| Name | Type | Description | +| ---- | ---- | ----------- | | addr | address | the address to query for | #### Return Values -| Name | Type | Description | -| ---- | ---- | ----------------------------------------------------------------------- | -| [0] | bool | bool Boolean value representing whether or not the address is a minter. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | bool Boolean value representing whether or not the address is a minter. | ## Operator @@ -5500,7 +6187,7 @@ specific functions. _This module is used through inheritance._ -### \_addOperator +### _addOperator ```solidity function _addOperator(address operator) internal @@ -5510,8 +6197,8 @@ Internal function that stores the new operator address in the correct storage sl #### Parameters -| Name | Type | Description | -| -------- | ------- | ------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | operator | address | The address of the new operator | ### transferOperatorship @@ -5526,8 +6213,8 @@ _Can only be called by the current operator._ #### Parameters -| Name | Type | Description | -| -------- | ------- | -------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | operator | address | The address of the new operator. | ### proposeOperatorship @@ -5542,8 +6229,8 @@ _Can only be called by the current operator._ #### Parameters -| Name | Type | Description | -| -------- | ------- | -------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | operator | address | The address of the new operator. | ### acceptOperatorship @@ -5558,8 +6245,8 @@ _Can only be called by the proposed operator._ #### Parameters -| Name | Type | Description | -| ------------ | ------- | -------------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | fromOperator | address | The previous operator of the contract. | ### isOperator @@ -5572,15 +6259,15 @@ Query if an address is a operator. #### Parameters -| Name | Type | Description | -| ---- | ------- | ------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | addr | address | The address to query for. | #### Return Values -| Name | Type | Description | -| ---- | ---- | -------------------------------------------------------------------------- | -| [0] | bool | bool Boolean value representing whether or not the address is an operator. | +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | bool Boolean value representing whether or not the address is an operator. | ## RolesConstants @@ -5590,9 +6277,9 @@ This contract contains enum values representing different contract roles. ```solidity enum Roles { - MINTER, - OPERATOR, - FLOW_LIMITER + MINTER, + OPERATOR, + FLOW_LIMITER } ``` @@ -5610,14 +6297,47 @@ Deploys a new instance of the TokenManagerProxy contract #### Parameters -| Name | Type | Description | -| ------------------ | ------- | ------------------------------------------------------------ | -| tokenId | bytes32 | The unique identifier for the token | -| implementationType | uint256 | Token manager implementation type | -| params | bytes | Additional parameters used in the setup of the token manager | +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | bytes32 | The unique identifier for the token | +| implementationType | uint256 | Token manager implementation type | +| params | bytes | Additional parameters used in the setup of the token manager | #### Return Values -| Name | Type | Description | -| ------------ | ------- | ---------------------------------------- | +| Name | Type | Description | +| ---- | ---- | ----------- | | tokenManager | address | The address of the deployed tokenManager | + +## TestInterchainTokenService + +### LatestMetadataVersionMismatch + +```solidity +error LatestMetadataVersionMismatch(uint32 const, uint32 calculated) +``` + +### constructor + +```solidity +constructor(address tokenManagerDeployer_, address interchainTokenDeployer_, address gateway_, address gasService_, address interchainTokenFactory_, string chainName_, address tokenManager_, address tokenHandler_, address gatewayCaller_) public +``` + +### setupTest + +```solidity +function setupTest(bytes params) external +``` + +## InterchainProxy + +This contract is a proxy for interchainTokenService and interchainTokenFactory. + +_This contract implements Proxy._ + +### constructor + +```solidity +constructor(address implementationAddress, address owner, bytes setupParams) public +``` + diff --git a/scripts/flatten-contracts.sh b/scripts/flatten-contracts.sh index de17476f..06b3e5e2 100755 --- a/scripts/flatten-contracts.sh +++ b/scripts/flatten-contracts.sh @@ -17,7 +17,7 @@ rm -rf "$OUTPUT" mkdir -p "$OUTPUT" # Get compiler version, expected format ".*version: 'x.y.z'," -version=$(grep 'version' ./hardhat.config.js | sed "s/ *version: '//" | sed "s/',$//g") +version='^0.8.0' # Flatten files find "$SOURCE" -name '*.sol' -print | while read -r file; do diff --git a/test/InterchainTokenFactory.js b/test/InterchainTokenFactory.js index 335b2fd6..fa9e687e 100644 --- a/test/InterchainTokenFactory.js +++ b/test/InterchainTokenFactory.js @@ -219,7 +219,7 @@ describe('InterchainTokenFactory', () => { it('Should register a token if the mint amount is zero', async () => { const salt = keccak256('0x1234'); tokenId = await tokenFactory.interchainTokenId(wallet.address, salt); - const tokenAddress = await tokenFactory.interchainTokenAddress(wallet.address, salt); + const tokenAddress = await service.interchainTokenAddress(tokenId); const params = defaultAbiCoder.encode(['bytes', 'address'], [minter, tokenAddress]); const tokenManager = await getContractAt('TokenManager', await service.tokenManagerAddress(tokenId), wallet); @@ -235,7 +235,7 @@ describe('InterchainTokenFactory', () => { it('Should register a token if the mint amount is zero and minter is the zero address', async () => { const salt = keccak256('0x123456'); tokenId = await tokenFactory.interchainTokenId(wallet.address, salt); - const tokenAddress = await tokenFactory.interchainTokenAddress(wallet.address, salt); + const tokenAddress = await service.interchainTokenAddress(tokenId); const minterBytes = new Uint8Array(); const params = defaultAbiCoder.encode(['bytes', 'address'], [minterBytes, tokenAddress]); const tokenManager = await getContractAt('TokenManager', await service.tokenManagerAddress(tokenId), wallet); @@ -252,7 +252,7 @@ describe('InterchainTokenFactory', () => { it('Should register a token if the mint amount is greater than zero and the minter is the zero address', async () => { const salt = keccak256('0x12345678'); tokenId = await tokenFactory.interchainTokenId(wallet.address, salt); - const tokenAddress = await tokenFactory.interchainTokenAddress(wallet.address, salt); + const tokenAddress = await service.interchainTokenAddress(tokenId); const params = defaultAbiCoder.encode(['bytes', 'address'], [tokenFactory.address, tokenAddress]); const tokenManager = await getContractAt('TokenManager', await service.tokenManagerAddress(tokenId), wallet); @@ -268,7 +268,7 @@ describe('InterchainTokenFactory', () => { it('Should register a token', async () => { const salt = keccak256('0x'); tokenId = await tokenFactory.interchainTokenId(wallet.address, salt); - const tokenAddress = await tokenFactory.interchainTokenAddress(wallet.address, salt); + const tokenAddress = await service.interchainTokenAddress(tokenId); const params = defaultAbiCoder.encode(['bytes', 'address'], [tokenFactory.address, tokenAddress]); const tokenManager = await getContractAt('TokenManager', await service.tokenManagerAddress(tokenId), wallet); const token = await getContractAt('InterchainToken', tokenAddress, wallet); @@ -305,7 +305,7 @@ describe('InterchainTokenFactory', () => { const salt = keccak256('0x12'); tokenId = await tokenFactory.interchainTokenId(wallet.address, salt); - const tokenAddress = await tokenFactory.interchainTokenAddress(wallet.address, salt); + const tokenAddress = await service.interchainTokenAddress(tokenId); const params = defaultAbiCoder.encode(['bytes', 'address'], [tokenFactory.address, tokenAddress]); const tokenManager = await getContractAt('TokenManager', await service.tokenManagerAddress(tokenId), wallet); const token = await getContractAt('InterchainToken', tokenAddress, wallet); @@ -495,7 +495,7 @@ describe('InterchainTokenFactory', () => { .connect(otherWallet) .approveDeployRemoteInterchainToken(wallet.address, salt, destinationChain, wallet.address, gasOptions), tokenFactory, - 'InvalidMinter', + 'NotMinter', [otherWallet.address], ); @@ -540,7 +540,7 @@ describe('InterchainTokenFactory', () => { const salt = keccak256('0x1245'); tokenId = await tokenFactory.interchainTokenId(wallet.address, salt); - const tokenAddress = await tokenFactory.interchainTokenAddress(wallet.address, salt); + const tokenAddress = await service.interchainTokenAddress(tokenId); const params = defaultAbiCoder.encode(['bytes', 'address'], [tokenFactory.address, tokenAddress]); const tokenManager = await getContractAt('TokenManager', await service.tokenManagerAddress(tokenId), wallet); const token = await getContractAt('InterchainToken', tokenAddress, wallet); @@ -600,6 +600,18 @@ describe('InterchainTokenFactory', () => { .withArgs(service.address, destinationChain, service.address, keccak256(payload), gasValue, wallet.address) .and.to.emit(gateway, 'ContractCall') .withArgs(service.address, destinationChain, service.address, keccak256(payload), payload); + + await expect( + tokenFactory.deployRemoteInterchainTokenWithMinter(salt, AddressZero, destinationChain, '0x', gasValue, { + value: gasValue, + }), + ) + .to.emit(service, 'InterchainTokenDeploymentStarted') + .withArgs(tokenId, name, symbol, decimals, '0x', destinationChain) + .and.to.emit(gasService, 'NativeGasPaidForContractCall') + .withArgs(service.address, destinationChain, service.address, keccak256(payload), gasValue, wallet.address) + .and.to.emit(gateway, 'ContractCall') + .withArgs(service.address, destinationChain, service.address, keccak256(payload), payload); }); }); });