diff --git a/README.md b/README.md index 2b3e8f98e..458a96cc7 100644 --- a/README.md +++ b/README.md @@ -37,9 +37,10 @@ These links redirect to pages in the documentation whose slugs may otherwise be ### ITS - **Introduction:** https://docs.axelar.dev/its/intro -- **No-Code ITS Setup:** https://docs.axelar.dev/dev/send-tokens/interchain-tokens/quick-start/no-code/ -- **Programmatic ITS Setup:** https://docs.axelar.dev/dev/send-tokens/interchain-tokens/quick-start/programmatic/ +- **No-Code ITS Setup:** https://docs.axelar.dev/dev/send-tokens/interchain-tokens/no-code/ +- **Create New Interchain Token:** https://docs.axelar.dev/dev/its/create-new-token/ - **Upgrade Token:** https://docs.axelar.dev/its/upgrade-token +- **Integrate Custom Token:** https://docs.axelar.dev/dev/its/custom-token/ - **Interchain Token Executable:** https://docs.axelar.dev/its/token-executable - **Flow Limit:** https://docs.axelar.dev/its/flow-limit - **Programmatically Create a Token:** https://docs.axelar.dev/its/create-token-tutorial diff --git a/src/components/interchain-token-intro.astro b/src/components/interchain-token-intro.astro index b7ae48a50..b5213fa1f 100644 --- a/src/components/interchain-token-intro.astro +++ b/src/components/interchain-token-intro.astro @@ -6,18 +6,18 @@ const cards = [ title: "Create a new Interchain Token", description: "Register and create new Interchain Token(s) using the Interchain Token Portal, or create custom Interchain Tokens.", - url: "/dev/send-tokens/interchain-tokens/quick-start/no-code/", + url: "/dev/send-tokens/interchain-tokens/no-code/", }, { title: "Programmatically create a new Interchain Token", description: "Create new Interchain Tokens using code.", - url: "/dev/send-tokens/interchain-tokens/quick-start/programmatic/", + url: "/dev/send-tokens/interchain-tokens/create-new-interchain-token/", }, { title: "Make an existing ERC-20 token an Interchain Token", description: "Upgrade existing tokens to canonical tokens, or link tokens deployed on multiple chains into Interchain Tokens.", - url: "/dev/send-tokens/interchain-tokens/quick-start/programmatic/#integrate-an-existing-custom-token-with-its", + url: "/dev/send-tokens/interchain-tokens/register-existing-token/", }, { title: "Check out the Interchain Portal", diff --git a/src/content/docs/dev/send-tokens/interchain-tokens/create-new-interchain-token.mdx b/src/content/docs/dev/send-tokens/interchain-tokens/create-new-interchain-token.mdx new file mode 100644 index 000000000..10a5c6f45 --- /dev/null +++ b/src/content/docs/dev/send-tokens/interchain-tokens/create-new-interchain-token.mdx @@ -0,0 +1,61 @@ +import { Callout } from "/src/components/callout"; + +# Create New Token + +Interchain Tokens are tokens deployed via the [Interchain Token Service (ITS)](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenService.sol). These tokens are relatively simple ERC-20s with a built-in integration to ITS, making them bridgeable to other blockchains as soon as the token is deployed. If you are starting fresh and want to deploy a brand new token that will have bridging capabilities from day one, ITS offers you the ability to deploy a token directly through its own contract. + +## Install the Axelar ITS Dependency + +Install the Axelar Interchain Token Service (ITS) package using npm or any other node package manager: + +```bash +npm i @axelar-network/interchain-token-service +``` + +## Deploy an Interchain Token + +Use the `deployInterchainToken` function to deploy a new interchain token on the current chain: + +```solidity +bytes32 tokenId = its.deployInterchainToken( + 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefab, // unique salt for token deployment + 'My Interchain Token', // token name + 'ITS', // token symbol + 18, // token decimals + 1000000, // initial token Supply + msg.sender // address receiving initially minted tokens +); +``` + +This function [deploys an interchain token](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenFactory.sol#L118), connects it to ITS upon deployment and returns the unique token ID. + +## Deploy a Remote Interchain Token + +Use the `deployRemoteInterchainToken` function to deploy the token on a remote chain as a cross-chain transaction: + +```solidity +bytes32 tokenId = its.deployRemoteInterchainToken{value: msg.value}( + 'Ethereum', // original chain Name + 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefab, // salt + msg.sender, // address to distribute token on destination chain + "Avalanche", // destination chain name + msg.value // gas sent for token deployment +); +``` + +This function [deploys a remote interchain token](https://github.com/axelarnetwork/interchain-token-service/blob/b4a68708c9a2e8098d1cac51d487b9d54661f66a/contracts/InterchainTokenFactory.sol#L168) on a specified destination chain and returns a token ID. + + + {" "} + **NOTE:** The security of your token is limited to the security of the chains + it integrates with. When making a token interchain, ensure that all the chains + it will be deployed to are trustworthy.{" "} + + +## What's Next + +For further examples utilizing the Interchain Token Service, check out the [`axelar-examples`](https://github.com/axelarnetwork/axelar-examples/tree/main/examples/evm) repository on GitHub. There, you can find an example implementation titled [`its-interchain-token`](https://github.com/axelarnetwork/axelar-examples/tree/main/examples/evm/its-interchain-token), which demonstrates how to deploy Interchain Tokens connected across EVM chains and how to send tokens across them. + +## Tutorial + +For a step-by-step guide on deploying an Interchain Token, check out the [Programmatically Create a New Token Using the Interchain Token Service](/dev/send-tokens/interchain-tokens/developer-guides/programmatically-create-a-token/) tutorial. diff --git a/src/content/docs/dev/send-tokens/interchain-tokens/developer-guides/link-custom-tokens-deployed-across-multiple-chains-into-interchain-tokens.mdx b/src/content/docs/dev/send-tokens/interchain-tokens/developer-guides/link-custom-tokens-deployed-across-multiple-chains-into-interchain-tokens.mdx index 4d2fe9599..37f3138c4 100644 --- a/src/content/docs/dev/send-tokens/interchain-tokens/developer-guides/link-custom-tokens-deployed-across-multiple-chains-into-interchain-tokens.mdx +++ b/src/content/docs/dev/send-tokens/interchain-tokens/developer-guides/link-custom-tokens-deployed-across-multiple-chains-into-interchain-tokens.mdx @@ -26,12 +26,12 @@ Deploy the following `SimpleCustomToken` on the Fantom and Polygon testnets. This code utilizes OpenZeppelin's libraries to create a custom ERC20 token with functionalities for minting, burning, and access control. The token includes a minter role, which enables designated addresses to mint or burn tokens. Additionally, it incorporates ERC20Permit for gasless transactions. The contract starts with a predefined supply of tokens minted to the deployer's address and establishes roles for a default administrator and minter: -```Solidity +```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.18; -// Import OpenZeppelin contracts for ERC20 standard token implementations, +// Import OpenZeppelin contracts for ERC-20 standard token implementations, // burnable tokens, access control mechanisms, and permit functionality import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol"; diff --git a/src/content/docs/dev/send-tokens/interchain-tokens/developer-guides/programmatically-create-a-canonical-token.mdx b/src/content/docs/dev/send-tokens/interchain-tokens/developer-guides/programmatically-create-a-canonical-token.mdx index c62caac02..4497c02c5 100644 --- a/src/content/docs/dev/send-tokens/interchain-tokens/developer-guides/programmatically-create-a-canonical-token.mdx +++ b/src/content/docs/dev/send-tokens/interchain-tokens/developer-guides/programmatically-create-a-canonical-token.mdx @@ -4,7 +4,7 @@ import { Callout } from "/src/components/callout"; If you have an [ERC-20](https://docs.openzeppelin.com/contracts/4.x/erc20) token on one or more blockchains and you want to make the token interoperable across chains, the [Interchain Token Service](/dev/send-tokens/interchain-tokens/intro/) provides a solution. You can transform an ERC-20 token into an Interchain Token by deploying a [token manager](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/token-manager/TokenManager.sol). -If you would like to create a wrapped, bridgeable version of your ERC-20 token on other chains, you can register it as a [Canonical Interchain Token](/dev/send-tokens/interchain-tokens/quick-start/programmatic/#integrate-existing-interchain-token-with-its) using the [`InterchainTokenFactory`](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenFactory.sol) [contract](https://etherscan.io/address/0x83a93500d23Fbc3e82B410aD07A6a9F7A0670D66). +If you would like to create a wrapped, bridgeable version of your ERC-20 token on other chains, you can register it as a [Canonical Interchain Token](/dev/send-tokens/interchain-tokens/register-existing-token/) using the [`InterchainTokenFactory`](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenFactory.sol) [contract](https://etherscan.io/address/0x83a93500d23Fbc3e82B410aD07A6a9F7A0670D66). **Each token can only be registered once as a Canonical Interchain Token.** This ensures unique and streamlined token management across different blockchains. Though you can register your Canonical Interchain Token directly through the [Interchain Token Portal](https://testnet.interchain.axelar.dev/), there are times where you may want to do so programmatically, such as when you have already deployed a token on one chain and wish to deploy a wrapped version of that token on another chain. @@ -24,7 +24,7 @@ You will need: ## Deploy an ERC-20 token on the Fantom testnet -[Create a SimpleERC20 token](https://bakemytoken.com/ftm) and give it a name and symbol. You can skip this step if you already have an ERC-20 token deployed on the Fantom testnet. +[Create a Simple ERC-20 token](https://bakemytoken.com/ftm) and give it a name and symbol. You can skip this step if you already have an ERC-20 token deployed on the Fantom testnet. ## **Set up your development environment** diff --git a/src/content/docs/dev/send-tokens/interchain-tokens/integrate-custom-token.mdx b/src/content/docs/dev/send-tokens/interchain-tokens/integrate-custom-token.mdx new file mode 100644 index 000000000..d2062a2e4 --- /dev/null +++ b/src/content/docs/dev/send-tokens/interchain-tokens/integrate-custom-token.mdx @@ -0,0 +1,128 @@ +import { Callout } from "/src/components/callout"; + +# Integrate Custom Token + +Custom tokens are tokens that are independently deployed, as opposed to tokens deployed via the [Interchain Token Service (ITS)](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenService.sol). These tokens are integrated with ITS across different chains by deploying a Token Manager for them. Once a custom token has a Token Manager deployed for a given chain, it becomes bridgeable between different blockchains that also have a token connected to a Token Manager sharing the same [interchainTokenId](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenService.sol#L228). + +## Install the Axelar ITS Dependency + +Install the Axelar Interchain Token Service (ITS) package using npm or any other node package manager: + +```bash +npm i @axelar-network/interchain-token-service +``` + +## Build and Deploy Your ERC-20 Token on Multiple Chains + +Build your ERC-20 token and deploy it on multiple chains. You can use a tool like the [Create3 Deployer](/dev/solidity-utilities/#create3-deployer) to give your token the same address across multiple chains. + +Example token contract: + +```solidity +import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; +import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol"; + +contract MyInterchainToken is ERC20, ERC20Burnable { + constructor(address initialOwner) + ERC20("My Interchain Token", "ITS") + { + // Initialization code here + } + + function mint(address to, uint256 amount) public onlyMinter { + _mint(to, amount); + } + + function burn(address from, uint256 amount) public onlyMinter { + _burn(from, amount); + } +} +``` + +This token is a simple implementation of an ERC20 token but includes the critical functionality needed to integrate with ITS: the ability to `mint()` and `burn()` tokens. ITS interacts with these functions when bridging tokens between chains. + +You also have the option to inherit from the [InterchainTokenStandard](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/interchain-token/InterchainTokenStandard.sol#L12) so that your token has cross-chain functionality built-in, such as the `interchainTransfer()` function. + +## Integrate the Custom Token with ITS by Deploying a Token Manager + +Use the `deployTokenManager` function to create a Token Manager for your token: + +```solidity +bytes32 interchainTokenId = its.deployTokenManager( + 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefab, // unique salt for token manager deployment + '', // destination chain name (empty string for current chain) + ITokenManagerType.TokenManagerType.MINT_BURN, // Token Manager type + abi.encode(msg.sender.toBytes(), newTokenProxy), // parameters + 0 // gas value (zero for local deployment) +); +``` + +This function deploys a Token Manager for your token, connects it to ITS upon deployment, and returns the unique interchain token ID. + +## Assign the `minter` Role to Your Token's Token Manager + +Transfer the minter role to the Token Manager using the `transferMintership` function: + +```solidity +myToken.transferMintership(tokenManagerAddress); +``` + +The [`transferMintership()`](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/utils/Minter.sol#L31) function transfers the minter role to the Token Manager. This is necessary because when your token is bridged into a destination chain, the `msg.sender` of the `mint()` call will be the Token Manager. + +## Send Token using Interchain Transfer Function + +An Interchain Token is an ERC20 that is connected to [ITS](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenService.sol) upon deployment comes built-in with the `interchainTransfer()` function, which allows users to bridge their token between any blockchain to which it is deployed. Take a look at the diagram below to see how the `interchainTransfer()` function works. + + + This diagram is interactive click on the function names! + + + + + Your browser does not support SVG + + +Use the `interchainTransfer` function to send tokens across chains: + +```solidity +its.interchainTransfer{value: msg.value}( + interchainTokenId, // token ID + 'Ethereum', // destination chain name + address(1), // receiver address on destination chain + 123, // amount to transfer + 0x, // metadata (optional) + msg.value // gas value sent for the transfer +); +``` + +The [`interchainTransfer()`](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/interfaces/IInterchainTokenService.sol#L210) function sends a cross-chain transfer via the Interchain Token Service. + + + **Security Note:** The key used to deploy custom tokens (`deployTokenManager`) is critical for security. If that key is compromised, the token can be compromised across multiple chains. + +- Interchain native tokens can only be deployed to more chains via the same deployer key, so that key must be securely retained. +- Tokens registered on ITS should be cautious about granting mint/burn permissions to other contracts. For example, sharing mint permission with the Polygon native bridge is not supported (the Polygon native bridge only looks for burns, which ITS uses, potentially allowing duplicate sends). + + + +## What's Next + +For further examples utilizing the Interchain Token Service, check out the [`axelar-examples`](https://github.com/axelarnetwork/axelar-examples/tree/main/examples/evm) repository on GitHub. There, you can find example implementations such as: + +- [`its-custom-token`](https://github.com/axelarnetwork/axelar-examples/tree/main/examples/evm/its-custom-token) β€” Demonstrates how to use ITS with a custom token implementation. +- [`its-executable`](https://github.com/axelarnetwork/axelar-examples/tree/main/examples/evm/its-executable) β€” Demonstrates how to deploy an interchain token and send a cross-chain transfer along with a message. +- [`its-mint-burn-from`](https://github.com/axelarnetwork/axelar-examples/tree/main/examples/evm/its-mint-burn-from) β€” Demonstrates how to deploy an interchain token that uses `burnFrom()` instead of `burn()` when bridging tokens. + +## Tutorial + +For a step-by-step guide on integrating a custom token, check out the [Link Custom Tokens Deployed Across Multiple Chains into Interchain Tokens](/dev/send-tokens/interchain-tokens/developer-guides/link-custom-tokens-deployed-across-multiple-chains-into-interchain-tokens/) tutorial. diff --git a/src/content/docs/dev/send-tokens/interchain-tokens/interchain-token-executable.mdx b/src/content/docs/dev/send-tokens/interchain-tokens/interchain-token-executable.mdx index fde1ea03e..4637f63ee 100644 --- a/src/content/docs/dev/send-tokens/interchain-tokens/interchain-token-executable.mdx +++ b/src/content/docs/dev/send-tokens/interchain-tokens/interchain-token-executable.mdx @@ -8,13 +8,13 @@ ITS also allows you to send [GMP messages](https://docs.axelar.dev/dev/general-m If you are looking to have an ITS compatible token that can send GMP messages, the token must inherit from the [InterchainExecutable](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/executable/InterchainTokenExecutable.sol#L15) contract. -Once the token has been deployed and [integrated with ITS](/dev/send-tokens/interchain-tokens/quick-start/programmatic/#integrate-existing-interchain-token-with-its) you can use the executable functionality to send messages along with your cross-chain token transfer. +Once the token has been deployed and [integrated with ITS](/dev/send-tokens/interchain-tokens/register-existing-token) you can use the executable functionality to send messages along with your cross-chain token transfer. ## Send Token + Message from Source Chain Send a message alongside a token using the [`callContractWithInterchainToken()`](https://github.com/axelarnetwork/interchain-token-service/blob/4e5f878dafb764ad37728ea239850b6a18a21d85/contracts/InterchainTokenService.sol#L491) function from the [Interchain Token Service](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenService.sol). You should provide the `tokenId`, `destinationChain`, `destinationAddress`, `amount`, `message`, and `gasValue` as parameters. -```Solidity +```solidity /** * @notice Initiates an interchain call contract with interchain token to a destination chain. * @param tokenId The unique identifier of the token to be transferred. diff --git a/src/content/docs/dev/send-tokens/interchain-tokens/intro.mdx b/src/content/docs/dev/send-tokens/interchain-tokens/intro.mdx index 4e780bfc2..79629b75d 100644 --- a/src/content/docs/dev/send-tokens/interchain-tokens/intro.mdx +++ b/src/content/docs/dev/send-tokens/interchain-tokens/intro.mdx @@ -1,16 +1,15 @@ - import { Callout } from "../../../../../components/callout"; import InterchainTokenIntro from "../../../../../components/interchain-token-intro.astro"; - The [Token Whitelisting for Squid Router form](https://github.com/axelarnetwork/axelar-configs/blob/main/cli/wizard/commands/list-squid-token/README.md) is now live! Download the [axelar-configs](https://github.com/axelarnetwork/axelar-configs) repo, install dependencies, and `npm run wizard` on the command line to access - the interactive form through the wizard. +The [Token Whitelisting for Squid Router form](https://github.com/axelarnetwork/axelar-configs/blob/main/cli/wizard/commands/list-squid-token/README.md) is now live! Download the [axelar-configs](https://github.com/axelarnetwork/axelar-configs) repo, install dependencies, and `npm run wizard` on the command line to access +the interactive form through the wizard. -
+
# Interchain Tokens and the Interchain Token Service @@ -18,14 +17,12 @@ Web3 has gone cross-chain, with assets bridging between blockchains and developers deploying applications on multiple chains. However, connecting tokens that are deployed on multiple chains has always been a cumbersome process. - -Interchain Tokens go beyond legacy bridges. The [Interchain Token Service (ITS)](https://axelar.network/interchaintokens) allows ERC-20 tokens to be available on multiple blockchains. It preserves native +Interchain Tokens go beyond legacy bridges. The [Interchain Token Service (ITS)](https://axelar.network/its) allows ERC-20 tokens to be available on multiple blockchains. It preserves native token qualities while allowing you to easily manage token features and token supply. Interchain Tokens run on [open-source code](https://github.com/axelarnetwork/interchain-token-service/tree/main) via smart contracts on a public blockchain secured by a dynamic validator set. With ITS, you can have multiple blockchains with canonical versions of your token that all share a single EVM address. - You can either create new [Interchain Tokens](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/interchain-token/InterchainToken.sol#L19) from scratch or update tokens that already exist on a [supported blockchain](/resources/contract-addresses/mainnet/). ### Key ITS Contract addresses @@ -34,82 +31,3 @@ You can either create new [Interchain Tokens](https://github.com/axelarnetwork/i **Interchain Token Factory:** [0x83a93500d23Fbc3e82B410aD07A6a9F7A0670D66](https://etherscan.io/address/0x83a93500d23Fbc3e82B410aD07A6a9F7A0670D66) - - -This diagram is interactive click on the function names! - -## ITS Overview - - The main functionalities of ITS can be broken down in the diagrams below. - These are the ability to connect tokens across multiple blockchains and - transfer connected tokens between multiple blockchains. Note: ITS is designed - to be a flexible permisionless process, meaning that the way tokens are - connected between the chains can vary for different usecases (see [token managers](/dev/send-tokens/interchain-tokens/token-manager/) for more info). - - - -## Deploy Interchain Token - -ITS allows you to deploy [Interchain Tokens](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/interchain-token/InterchainToken.sol). An Interchain Token is an ERC20 that is connected to [ITS](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenService.sol) upon deployment. It comes built-in with the `interchainTransfer()` function, which allows users to bridge their token between any blockchain to which it is deployed. To deploy this token, you can go through the [Interchain Token Factory](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenFactory.sol) contract. - -When you trigger the `registerCanonicalInterchainToken()` function, that will initiate the process of registering your custom token with a `Lock/Unlock` [token manager](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/token-manager/TokenManager.sol) type to your token's *home chain*. Now that you have registered your token on the home chain, you can call the `deployRemoteCanonicalInterchainToken()`. This will deploy an Interchain Token on a different blockchain that will be connected to your canonical token on the home chain you registered when you called the previous function. - -Note: This is just one of many different flows you can choose to follow when interacting with ITS. - -This diagram is interactive click on the function names! - - - - Your browser does not support SVG - - -## Interchain Transfer - -

- Once your token is connected to ITS you can call the interchaintTransfer() function to send a cross chain transaction for your token. If your token inherits - the [Interchain Token Standard](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/interchain-token/InterchainTokenStandard.sol) then you will have this function built into the token. The interchainTransfer() will trigger a flow that will interact with ITS to either lock or - burn your token on the source chain (depending on the Token Manager type) and then - mint your token on the destination chain. -

- - - - - - - - Your browser does not support SVG - - - - - **NOTE:** The security of your token is limited to the security of the chains - it integrates with. Since blockchains can have different security practices, - we recommend doing due diligence on all chains your token will be deployed to. - diff --git a/src/content/docs/dev/send-tokens/interchain-tokens/quick-start/no-code.mdx b/src/content/docs/dev/send-tokens/interchain-tokens/no-code.mdx similarity index 92% rename from src/content/docs/dev/send-tokens/interchain-tokens/quick-start/no-code.mdx rename to src/content/docs/dev/send-tokens/interchain-tokens/no-code.mdx index 4c2d66cc9..92f0682b9 100644 --- a/src/content/docs/dev/send-tokens/interchain-tokens/quick-start/no-code.mdx +++ b/src/content/docs/dev/send-tokens/interchain-tokens/no-code.mdx @@ -1,5 +1,3 @@ -# No-Code (ITS Portal) - The [Token Whitelisting for Squid Router form](https://github.com/axelarnetwork/axelar-configs/blob/main/cli/wizard/commands/list-squid-token/README.md) @@ -9,9 +7,11 @@ interactive form through the wizard. +# No-Code (ITS Portal) + import { Callout } from "/src/components/callout"; -The quickest way to begin exploring and deploying [interchain tokens](/dev/send-tokens/interchain-tokens/quick-start/programmatic/#interchain-token) is with Axelar's no code [frontend portal](https://interchain.axelar.dev/). (Click [here](https://testnet.interchain.axelar.dev/) for testnet) +The quickest way to begin exploring and deploying [interchain tokens](/dev/send-tokens/glossary/#interchain-token) is with Axelar's no code [frontend portal](https://interchain.axelar.dev/). (Click [here](https://testnet.interchain.axelar.dev/) for testnet) The portal offers two main paths. You can either deploy a fresh new token on multiple chains at once or you can connect a pre-existing token to ITS. Once integrated, you can then deploy additional interchain tokens on other blockchains to be bridgeable with your token that you had previously integrated. diff --git a/src/content/docs/dev/send-tokens/interchain-tokens/quick-start/programmatic.mdx b/src/content/docs/dev/send-tokens/interchain-tokens/quick-start/programmatic.mdx deleted file mode 100644 index 22f2f03b2..000000000 --- a/src/content/docs/dev/send-tokens/interchain-tokens/quick-start/programmatic.mdx +++ /dev/null @@ -1,183 +0,0 @@ -# Programmatic - - - The [Token Whitelisting for Squid Router - form](https://github.com/axelarnetwork/axelar-configs/blob/main/cli/wizard/commands/list-squid-token/README.md) - is now live! Download the - [`axelar-configs`](https://github.com/axelarnetwork/axelar-configs) repo, - install dependencies, and `npm run wizard` on the command line to access the - interactive form through the wizard. - - -import { Callout } from "/src/components/callout"; - -## Interchain Token - -[Interchain Tokens](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/interchain-token/InterchainToken.sol) are tokens [deployed](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenService.sol#L327) via ITS itself. These are relatively simple ERC20s with a built in integration to ITS so that they are bridgeable to other blockchains they are wired up to as soon as the token is deployed. - - - **NOTE:** The security of your token is limited to the security of the chains - it integrates with. When making a token interchain, make sure that all the - chains it will be deployed to are trustworthy. - - -### Deploy new interchain token with ITS - -If you are starting fresh and want to deploy a brand new token that will have bridging from day one, then ITS offers you the ability to deploy a token directly through its own contract. - -1. Install the [Axelar ITS](https://www.npmjs.com/package/@axelar-network/interchain-token-service) dependency - ```bash - npm i @axelar-network/interchain-token-service - ``` -1. Deploy an interchain token - - ```solidity - bytes32 tokenId = its.deployInterchainToken( - 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefab, //salt - 'My Interchain Token', //name - 'ITS', //symbol - 18, //decimals - 1000000, //initialSupply - msg.sender //address receiving initially minted tokens - ) - ``` - - [deploy an interchain token](https://github.com/axelarnetwork/interchain-token-service/blob/9edc4318ac1c17231e65886eea72c0f55469d7e5/contracts/InterchainTokenFactory.sol#L118) on the same chain. This token will be connected to ITS upon deployment. - -1. Deploy a remote interchain token - ```solidity - bytes32 tokenId = its.deployRemoteInterchainToken{value: msg.value}( - 'Ethereum', //originalChainName - 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefab, //salt - msg.sender, //address to distribute token on dest chain - "Avalanche", //destinationChain - msg.value //gas sent for deployment - ) - ``` - [deploy a remote interchain token](https://github.com/axelarnetwork/interchain-token-service/blob/9edc4318ac1c17231e65886eea72c0f55469d7e5/contracts/InterchainTokenFactory.sol#L163) as a cross-chain transaction. This token will be connected to ITS upon deployment. - -### Integrate existing interchain token with ITS - -If you own an ERC-20 token on a single chain and want a wrapped, bridgeable version on other chains, register it as a [Canonical Interchain Token](/dev/send-tokens/glossary/#canonical-interchain-token) using the [Interchain Token Factory contract](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenFactory.sol#L20). Each token can only be registered a single time as a canonical chain on its "home chain". This can be done via the [ITS Portal](/dev/send-tokens/interchain-tokens/quick-start/no-code/) no-code solution, but it can also be done directly via the contract. - -1. Install the [Axelar ITS](https://www.npmjs.com/package/@axelar-network/interchain-token-service) dependency - - ```bash - npm i @axelar-network/interchain-token-service - ``` - -1. Register your token as a canonical token using [Interchain Token Factory](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenFactory.sol#L20) - - ```solidity - bytes32 tokenId =its.registerCanonicalInterchainToken( - myTokenAddress //address of canonical token - ) - ``` - - The [`registerCanonicalInterchainToken`](https://github.com/axelarnetwork/interchain-token-service/blob/9edc4318ac1c17231e65886eea72c0f55469d7e5/contracts/InterchainTokenFactory.sol#L240) will deploy a [Lock/Unlock](/dev/send-tokens/glossary/#lockunlock) - [Token Manager](/dev/send-tokens/glossary/#token-manager) on the source chain - -1. Deploy a remote canonical interchain token - ```solidity - bytes32 tokenId = its.deployRemoteCanonicalInterchainToken{value: msg.value}( - 'Ethereum', //originalChain - myTokenAddress, //originalTokenAddress - 'Avalanche', //destinationChain - msg.value //gas sent for deployment - ) - ``` - The [deploy remote canonical interchain](https://github.com/axelarnetwork/interchain-token-service/blob/9edc4318ac1c17231e65886eea72c0f55469d7e5/contracts/InterchainTokenFactory.sol#L257) token will deploy a token that will be connected to your token that you registered on the home chain. Tokens being bridged out of the home chain will be locked there and tokens on the remote blockchains can be traced back to a locked token on the home chain. - -## Custom Token - -Custom tokens are tokens that are deployed on their own as opposed to tokens deployed via ITS itself. These tokens are then integrated with ITS across different chains by deploying a token manager for those tokens. Once a custom token has a token manager deployed for a given chain it becomes bridgeable between different blockchains also have a token connected to a token manager and shares the same [interchainTokenId](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenService.sol#L228). - -### Integrate an existing custom token with ITS - -1. Install the [Axelar ITS](https://www.npmjs.com/package/@axelar-network/interchain-token-service) dependency - - ```bash - npm i @axelar-network/interchain-token-service - ``` - -1. [Build your ERC-20](https://docs.alchemy.com/docs/how-to-create-an-erc-20-token-4-steps) token and deploy it on multiple chains. You can use a tool such as the [Create3 Deployer](/dev/solidity-utilities/#create3-deployer) to give it the same address everywhere. - - ```solidity - import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; - import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol"; - - - contract MyInterchainToken is ERC20, ERC20Burnable { - constructor(address initialOwner) - ERC20("My Interchain Token", "ITS") - {} - - function mint(address to, uint256 amount) public onlyMinter { - _mint(to, amount); - } - } - ``` - - This token is a very simple implementation of an ERC20 but it contains all the critical functionality that would be needed to integrate with ITS. Namely, the ability to `mint()` and `burn()` tokens as ITS will interact with those functions while bridging the tokens between chains. - - You also have the option to inherit from the the [InterchainTokenStandard](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/interchain-token/InterchainTokenStandard.sol#L12) so that your token has cross-chain functionality built into the token itself such as the `interchainTransfer()` function. - -1. Integrate the token with ITS by calling [`deployTokenManager()`](https://github.com/axelarnetwork/interchain-token-service/blob/9edc4318ac1c17231e65886eea72c0f55469d7e5/contracts/InterchainTokenService.sol#L276). - - ```solidity - bytes32 interchainTokenId = its.deployTokenManager( - 0xabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefab, //salt - '', //destChain - ITokenManagerType.TokenManagerType.MINT_BURN, //tokenManager type - abi.encode(msg.sender.toBytes(), newTokenProxy), //params - 0 //gasValue - ); - ``` - - When the Token Manager is created it will facilitate connections for your token with ITS. There are several different types of Token Managers that are available to you. More info on Token Manager's an integrating with them can be found in the [Token Manager](/dev/send-tokens/interchain-tokens/token-manager/) section - -1. Add the `minter` role to your token's Token Manager. - - ```solidity - itsToken.transferMintership(newMinter); - ``` - - The [`transferMintership()`](https://github.com/axelarnetwork/interchain-token-service/blob/9223108211b977d9138fdd67d5b4a641fc35c18c/contracts/utils/Minter.sol#L31) on your token can be called to transfer the minter role to the Token Manager. The reason for this is when your token is bridged into a destination chain, the `msg.sender` of the `mint()` call will be the Token Manager. - -1. Send an interchain transfer - ```solidity - its.interchainTransfer{value: msg.value}( - interchainTokenId, //tokenId - 'Ethereum', //destinationChain - address(1), //receiver address - 123, //amount - 0x, //metadata - msg.value //gasValue - ) - ``` - The [`interchainTransfer()`](https://github.com/axelarnetwork/interchain-token-service/blob/9223108211b977d9138fdd67d5b4a641fc35c18c/contracts/interfaces/IInterchainTokenService.sol#L210) sends a cross-chain transfer between chains via the Interchain Token Service. - - - The key used to deploy custom tokens (`deployTokenManager`) is critical for - security. If that key is compromised, then that token can be compromised - across multiple chains. * Interchain native tokens can only be deployed to - more chains via the same deployer key, so that needs to be retained. * Tokens - registered on ITS should be careful about giving mint/burn permissions to - other contracts. For example, shared mint permission with the Polygon native - bridge is not supported (the Polygon native bridge only looks for burns, which - ITS uses, meaning it can allow duplicate sends). - - -### Tutorial - -For detailed steps on creating a custom Interchain Token, check out the [Link Custom Tokens Deployed Across Multiple Chains into Interchain Tokens](/dev/send-tokens/interchain-tokens/developer-guides/link-custom-tokens-deployed-across-multiple-chains-into-interchain-tokens/) tutorial. - -## What’s next - -For further examples utilizing the Interchain Token Service, check out the following in the [`axelar-examples`](https://github.com/axelarnetwork/axelar-examples/tree/main) repo on GitHub: - -- [`its-custom-token`](https://github.com/axelarnetwork/axelar-examples/tree/main/examples/evm/its-custom-token) β€” Demonstrates how to use the ITS with a custom token implementation. -- [`its-interchain-token`](https://github.com/axelarnetwork/axelar-examples/tree/main/examples/evm/its-interchain-token) β€” Demonstrates how to deploy Interchain Tokens that are connected across EVM chains and how to send some tokens across. -- [`its-canonical-token`](https://github.com/axelarnetwork/axelar-examples/tree/main/examples/evm/its-canonical-token) - Demonstrates how to deploy canonical Interchain Token and send cross-chain transfer for these tokens. -- [`its-lock-unlock-fee`](https://github.com/axelarnetwork/axelar-examples/tree/main/examples/evm/its-lock-unlock-fee) Demonstrates how to deploy deploy interchain token with lock/unlock_fee token manager type. -- [`its-executable`](https://github.com/axelarnetwork/axelar-examples/tree/main/examples/evm/its-executable) Demonstrates how to deploy interchain token and send a cross-chain transfer along with a message. -- [`its-mint-burn-from`](https://github.com/axelarnetwork/axelar-examples/tree/main/examples/evm/its-mint-burn-from) Demonstrates how to deploy interchain token with uses `burnFrom()` on token being bridged rather than `burn()`. diff --git a/src/content/docs/dev/send-tokens/interchain-tokens/register-existing-token.mdx b/src/content/docs/dev/send-tokens/interchain-tokens/register-existing-token.mdx new file mode 100644 index 000000000..3faacbf7d --- /dev/null +++ b/src/content/docs/dev/send-tokens/interchain-tokens/register-existing-token.mdx @@ -0,0 +1,77 @@ +import { Callout } from "/src/components/callout"; + +# Register Existing Token + +If you own an ERC-20 token on a single chain and want a wrapped, bridgeable version on other chains, you can register it as a [Canonical Interchain Token](/dev/send-tokens/glossary/#canonical-interchain-token) using the [Interchain Token Factory contract](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenFactory.sol#L20). Each token can only be registered once as a canonical token on its "home chain". + +You can register your existing token directly via the contract or use the [ITS Portal](/dev/send-tokens/interchain-tokens/no-code/) no-code solution. Take a look at the diagram below to understand the process of registering an existing token as a Canonical Interchain Token. + + + This diagram is interactive click on the function names! + + + + + Your browser does not support SVG + + +## Install the Axelar ITS Dependency + +Install the Axelar Interchain Token Service (ITS) package using npm or any other node package manager: + +```bash +npm i @axelar-network/interchain-token-service +``` + +## Register Your Token as a Canonical Token + +Use the `registerCanonicalInterchainToken` function to register your token: + +```solidity +bytes32 tokenId = its.registerCanonicalInterchainToken( + myTokenAddress // address of your canonical token +); +``` + +The [`registerCanonicalInterchainToken`](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenFactory.sol#L240) function deploys a [Lock/Unlock Token Manager](/dev/send-tokens/glossary/#lockunlock) on the source chain, connects it to ITS upon deployment, and returns a unique token ID. When you trigger the `registerCanonicalInterchainToken()` function, that will initiate the process of registering your custom token with a `Lock/Unlock` [token manager](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/token-manager/TokenManager.sol) type to your token's _home chain_. Now that you have registered your token on the home chain, you can call the `deployRemoteCanonicalInterchainToken()`. This will deploy an Interchain Token on a different blockchain that will be connected to your canonical token on the home chain you registered when you called the previous function. + +Note: This is just one of many different flows you can choose to follow when interacting with ITS. + +## Deploy a Remote Canonical Interchain Token + +Use the `deployRemoteCanonicalInterchainToken` function to deploy the token on a remote chain as a cross-chain transaction: + +```solidity +bytes32 tokenId = its.deployRemoteCanonicalInterchainToken{value: msg.value}( + 'Ethereum', // original chain name + myTokenAddress, // original token address + 'Avalanche', // destination chain name + msg.value // gas sent for token deployment +); +``` + +The [`deployRemoteCanonicalInterchainToken`](https://github.com/axelarnetwork/interchain-token-service/blob/main/contracts/InterchainTokenFactory.sol#L257) function deploys a token connected to your registered token on the home chain, making it bridgeable to the destination chain, and returns a token ID. + + + **NOTE:** The security of your token is limited to the security of the chains + it integrates with. When making a token interchain, ensure that all the chains + it will be deployed to are trustworthy. + + +## What's Next + +For further examples utilizing the Interchain Token Service, check out the [`axelar-examples`](https://github.com/axelarnetwork/axelar-examples/tree/main/examples/evm) repository on GitHub. There, you can find an example implementation titled [`its-canonical-token`](https://github.com/axelarnetwork/axelar-examples/tree/main/examples/evm/its-canonical-token), which demonstrates how to deploy canonical Interchain Tokens and send cross-chain transfers. + +## Tutorial + +For a step-by-step guide on registering an existing token, check out the [Programmatically Create a Canonical Interchain Token Using the Interchain Token Service](/dev/send-tokens/interchain-tokens/developer-guides/programmatically-create-a-canonical-token/) tutorial. diff --git a/src/content/docs/learn/cli/axl-from-evm.mdx b/src/content/docs/learn/cli/axl-from-evm.mdx index c395ca12d..575a0c8e4 100644 --- a/src/content/docs/learn/cli/axl-from-evm.mdx +++ b/src/content/docs/learn/cli/axl-from-evm.mdx @@ -32,7 +32,7 @@ axelard q nexus latest-deposit-address {EVM_CHAIN} axelarnet {MY_ADDR} Use MetaMask to send some wrapped AXL tokens on `{EVM_CHAIN}` to the new temporary deposit address `{EVM_TEMP_ADDR}`. Save the transaction hash `{EVM_TX_HASH}` for later. - Danger: Send only `Axelar` ERC20 tokens to `{EVM_TEMP_ADDR}`. Any other token + Danger: Send only `Axelar` ERC-20 tokens to `{EVM_TEMP_ADDR}`. Any other token sent to `{EVM_TEMP_ADDR}` will be lost. diff --git a/src/content/docs/learn/cli/ust-from-evm.mdx b/src/content/docs/learn/cli/ust-from-evm.mdx index 15af4d519..bf55f6ada 100644 --- a/src/content/docs/learn/cli/ust-from-evm.mdx +++ b/src/content/docs/learn/cli/ust-from-evm.mdx @@ -27,7 +27,7 @@ successfully linked {EVM_TEMP_ADDR} and {TERRA_DEST_ADDR} Use MetaMask to send some wrapped AXL tokens on `{EVM_CHAIN}` to the new temporary deposit address `{EVM_TEMP_ADDR}`. Save the transaction hash `{EVM_TX_HASH}` for later. - Danger: Send only `Axelar Wrapped UST` ERC20 tokens to `{EVM_TEMP_ADDR}`. Any + Danger: Send only `Axelar Wrapped UST` ERC-20 tokens to `{EVM_TEMP_ADDR}`. Any other token sent to `{EVM_TEMP_ADDR}` will be lost. diff --git a/src/content/docs/resources/metamask.mdx b/src/content/docs/resources/metamask.mdx index 66c84067b..441658dc4 100644 --- a/src/content/docs/resources/metamask.mdx +++ b/src/content/docs/resources/metamask.mdx @@ -4,7 +4,7 @@ import AddToWeb3 from "../../../components/web3"; 1. Connect MetaMask to other EVM chains 2. Get testnet tokens for other EVM chains to pay for gas -3. Import Axelar ERC20 tokens on other EVM chains +3. Import Axelar ERC-20 tokens on other EVM chains 4. Enable hex data in transactions ## Connect MetaMask to other EVM chains @@ -47,13 +47,13 @@ You can get native tokens from a faucet. Search the internet for "`[chain]` test - [Moonbeam](https://docs.moonbeam.network/builders/get-started/moonbase/#get-tokens) -- No known web faucet; need to join the [Moonbeam discord](https://discord.gg/PfpUATX). - [Polygon](https://faucet.polygon.technology/) -## Import Axelar ERC20 tokens +## Import Axelar ERC-20 tokens Tokens transferred to an EVM chain using Axelar are not visible in MetaMask until you import them. 1. Use the "Networks" dropdown list, select your desired `[chain]`. 2. View "Assets" and select "Import Tokens". -3. Paste into "Token Contract Address" the ERC20 address for the token. ("Token symbol" and "token decimal" should be fetched automatically.) +3. Paste into "Token Contract Address" the ERC-20 address for the token. ("Token symbol" and "token decimal" should be fetched automatically.) Axelar token contract addresses for each `[chain]` can be found at [Testnet Resources](/resources/contract-addresses/testnet/). diff --git a/src/layouts/navigation.ts b/src/layouts/navigation.ts index 8d334b13e..b91482a4f 100644 --- a/src/layouts/navigation.ts +++ b/src/layouts/navigation.ts @@ -1,3 +1,5 @@ +import { title } from "process"; + export const topLevelNav = [ { title: "Developers", @@ -35,22 +37,24 @@ export const getNavigation = (section) => { title: "Interchain Tokens", children: [ { - title: "Introduction", + title: "Overview", href: "/dev/send-tokens/interchain-tokens/intro/", }, { - title: "Quick Start", - href: "/dev/send-tokens/interchain-tokens/quick-start/", - children: [ - { - title: "No Code", - href: "/dev/send-tokens/interchain-tokens/quick-start/no-code/", - }, - { - title: "Programmatic", - href: "/dev/send-tokens/interchain-tokens/quick-start/programmatic/", - }, - ], + title: "No Code Setup", + href: "/dev/send-tokens/interchain-tokens/no-code/", + }, + { + title: "Create New Token", + href: "/dev/send-tokens/interchain-tokens/create-new-interchain-token/", + }, + { + title: "Register Existing Token", + href: "/dev/send-tokens/interchain-tokens/register-existing-token/", + }, + { + title: "Integrate Custom Token", + href: "/dev/send-tokens/interchain-tokens/integrate-custom-token/", }, { title: "Token Manager", diff --git a/vercel.json b/vercel.json index 805808923..73ef5ea5b 100644 --- a/vercel.json +++ b/vercel.json @@ -63,7 +63,7 @@ }, { "source": "/its/upgrade-token/", - "destination": "/dev/send-tokens/interchain-tokens/upgrade-tokens/" + "destination": "/dev/send-tokens/interchain-tokens/register-existing-token/" }, { "source": "/its/token-executable/", @@ -523,6 +523,31 @@ "source": "/dev/cosmos-gmp/", "destination": "/dev/cosmos-gmp/overview/", "permanent": true + }, + { + "source": "/dev/its/create-new-token/", + "destination": "/dev/send-tokens/interchain-tokens/create-new-interchain-token/", + "permanent": true + }, + { + "source": "/dev/its/custom-token/", + "destination": "/dev/send-tokens/interchain-tokens/integrate-custom-token/", + "permanent": true + }, + { + "source": "/dev/send-tokens/interchain-tokens/quick-start/no-code/", + "destination": "/dev/send-tokens/interchain-tokens/no-code/", + "permanent": true + }, + { + "source": "/dev/send-tokens/interchain-tokens/quick-start/", + "destination": "/dev/send-tokens/interchain-tokens/intro/", + "permanent": true + }, + { + "source": "/dev/send-tokens/interchain-tokens/quick-start/programmatic/", + "destination": "/dev/send-tokens/interchain-tokens/create-new-interchain-token/", + "permanent": true } ] }