feat: restructure and enhance ITS documentation with improved organiz…

…ation and visual aids (#1230)

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

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",

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.
+
+<Callout emoji="🚨">
+  {" "}
+  **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.{" "}
+</Callout>
+
+## 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.

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";

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**
 

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.
+
+<Callout type="warning">
+  This diagram is interactive click on the function names!
+</Callout>
+
+<object
+  type="image/svg+xml"
+  data="/images/its-transfer.svg"
+  class="hidden dark:block w-full max-w-[50rem] mx-auto py-6"
+>
+  Your browser does not support SVG
+</object>
+<object
+  type="image/svg+xml"
+  data="/images/its-transfer-light.svg"
+  class=" dark:hidden w-full max-w-[50rem] mx-auto py-6"
+>
+  Your browser does not support SVG
+</object>
+
+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.
+
+<Callout emoji="🚨">
+  **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).
+
+</Callout>
+
+## 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.

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.