interchain-token-sdk/README.md

SDK for deploying and managing interchain tokens across multiple chains using Axelar network

# Interchain Tokens SDK

A TypeScript SDK for deploying new tokens across multiple chains using the Axelar network. This SDK allows you to deploy a new token on one chain and automatically deploy its corresponding versions on other supported chains.

## Currently Supported Networks (Testnet Only)

- Base Sepolia
- Optimism Sepolia
- Arbitrum Sepolia

## Installation

```bash
npm install interchain-tokens-sdk
```

## Usage

### Basic Setup

```typescript
import { 
  deployInterchainTokenMulticall, 
  registerAndDeployCanonicalInterchainTokenMulticall,
  estimateRemoteDeploymentGas,
  SUPPORTED_CHAINS,
  isValidERC20Token 
} from "interchain-tokens-sdk";
import { createWalletClient, createPublicClient, http } from "viem";
import { baseSepolia } from "viem/chains";

// Create wallet and public clients for your source chain (e.g., Base Sepolia)
const walletClient = createWalletClient({
  account,
  chain: baseSepolia,
  transport: http(RPC_URL)
});

const publicClient = createPublicClient({
  chain: baseSepolia,
  transport: http(RPC_URL)
});
```

### Deploying a New Token

```typescript
// Deploy your token across chains
const result = await deployInterchainTokenMulticall(
  tokenName,            // string: your token name
  tokenSymbol,          // string: your token symbol
  decimals,            // number: number of decimals (e.g., 18)
  initialSupply,       // number: initial token supply
  minterAddress,       // string: address that can mint tokens
  destinationChains,   // string[]: array of supported chain names
  walletClient,
  publicClient
);
```

### Registering an Existing Token

```typescript
// Register and deploy an existing ERC20 token across chains
const result = await registerAndDeployCanonicalInterchainTokenMulticall(
  tokenAddress,        // string: address of your existing ERC20 token
  destinationChains,   // string[]: array of supported chain names
  walletClient,
  publicClient
);
```

### Estimating Gas for Remote Deployment

There are two ways to estimate gas for remote deployments:

1. **For New Tokens**:
```typescript
// Estimate gas required for deploying a new token
const gasEstimate = await estimateNewTokenDeploymentGas(
  sourceChainName,     // string: name of the source chain (e.g., "base-sepolia")
  destinationChain,    // string: name of the destination chain
  tokenName,          // string: name of the token
  tokenSymbol,        // string: symbol of the token
  decimals,           // number: number of decimals
  initialSupply,      // number: initial token supply
  minterAddress       // string: address that can mint tokens
);
```

2. **For Existing Tokens**:
```typescript
// Estimate gas required for deploying an existing token
const gasEstimate = await estimateExistingTokenDeploymentGas(
  sourceChainName,     // string: name of the source chain (e.g., "base-sepolia")
  destinationChain,    // string: name of the destination chain
  tokenAddress        // string: address of the existing token
);
```

### Gas Estimation Results

Both gas estimation functions return a `bigint` representing the estimated gas in wei. The estimation includes:
- Base gas cost for the operation
- 20% buffer for safety
- Cross-chain messaging fees
- If estimation fails, a default value of 600,000 gas units is returned

### Validating ERC20 Tokens

```typescript
// Check if an address is a valid ERC20 token
const isValid = await isValidERC20Token(
  tokenAddress,        // string: address to validate
  publicClient        // PublicClient: viem public client
);
```

## API Reference

### Deployment Result

```typescript
interface DeploymentResult {
  hash: `0x${string}`;              // transaction hash
  tokenDeployed?: {
    tokenId: `0x${string}`;         // unique identifier across chains
    tokenAddress: `0x${string}`;    // token contract address
    minter: `0x${string}`;          // minter address
    name: string;                   // token name
    symbol: string;                 // token symbol
    decimals: number;               // token decimals
    salt: `0x${string}`;           // deployment salt
  };
}
```

### Gas Estimation Result

```typescript
// Returns a bigint representing the estimated gas in wei
const gasEstimate: bigint = await estimateRemoteDeploymentGas(...);
```

## Important Notes

1. **Token Types**:
   - New Tokens: Use `deployInterchainTokenMulticall` to deploy a new token across chains
   - Existing Tokens: Use `registerAndDeployCanonicalInterchainTokenMulticall` to register and deploy an existing ERC20 token

2. **Source Chain**: You can deploy from any of the supported chains, but make sure your wallet has enough native tokens for:
   - The deployment transaction
   - Gas fees for cross-chain messaging (use `estimateRemoteDeploymentGas` to estimate)

3. **Destination Chains**: When specifying destination chains, use the chain identifiers exactly as follows:
   - "base-sepolia"
   - "optimism-sepolia"
   - "arbitrum-sepolia"

4. **Gas Estimation**:
   - Always estimate gas before deployment using `estimateRemoteDeploymentGas`
   - The estimation includes a 20% buffer for safety
   - If estimation fails, a default value of 600,000 gas units is returned

5. **Token Validation**:
   - Use `isValidERC20Token` to validate token addresses before deployment
   - This helps prevent deployment of invalid tokens

6. **Axelar Network**: This SDK uses Axelar's infrastructure for cross-chain communication. The deployment process:
   - Deploys the token on the source chain
   - Creates token managers on destination chains
   - Sets up the cross-chain token mapping

## Development

To contribute or modify the SDK:

1. Clone the repository
2. Install dependencies:
   ```bash
   npm install
   ```
3. Build:
   ```bash
   npm run build
   ```
4. Test:
   ```bash
   npm test
   ```

## License

MIT