# @escapehub/token-creator

Framework-agnostic SDK for deploying ERC-20 tokens on 40+ EVM chains with advanced features like fees, limits, anti-bot protection, and vanity addresses.

## Features

- **Multi-chain**: Deploy on Ethereum, Base, BSC, Polygon, Arbitrum, and 35+ other chains
- **Built-in chain configs**: Factory addresses, RPC URLs, and Multicall3 support included
- **Customizable tokens**: Fees, limits, blacklist, whitelist, anti-dump protection
- **Vanity addresses**: Mine custom token addresses (e.g., `0xCAFE...`, `0xDEAD...`)
- **Framework-agnostic**: Works with React, Vue, Angular, Svelte, Node.js, or vanilla JS
- **TypeScript-first**: Full type definitions included
- **Contract verification**: Built-in Etherscan verification support

## Installation

```bash
npm install @escapehub/token-creator ethers
```

## Quick Start

### 1. Basic Token Deployment

```typescript
import { deployToken, createDefaultConfig, getChainConfig } from '@escapehub/token-creator';
import { BrowserProvider } from 'ethers';

// Connect wallet
const provider = new BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
const address = await signer.getAddress();

// Create token configuration
const config = createDefaultConfig('My Token', 'MTK', '1000000', address);

// Get chain config from SDK (includes factory address, RPC, multicall3)
const chainConfig = getChainConfig(11155111); // Sepolia

// Deploy!
const result = await deployToken(signer, config, chainConfig);
console.log('Token deployed at:', result.tokenAddress);
console.log('Transaction hash:', result.txHash);
```

### 2. Token with Fees

```typescript
import { createDefaultConfig, deployToken, getChainConfig } from '@escapehub/token-creator';

const config = createDefaultConfig('Fee Token', 'FEE', '1000000', ownerAddress);

// Enable 3% buy fee, 3% sell fee
config.fees = {
  enabled: true,
  buyFee: 300,      // 3% (basis points)
  sellFee: 300,     // 3%
  transferFee: 0,   // No transfer fee
  recipients: [
    { address: treasuryAddress, share: 10000 },  // 100% to treasury
  ],
};

const chainConfig = getChainConfig(8453); // Base
const result = await deployToken(signer, config, chainConfig);
```

### 3. Vanity Address Mining

```typescript
import {
  generateSaltAsync,
  getMinimalProxyInitCodeHash,
  getChainConfig
} from '@escapehub/token-creator';

const chainConfig = getChainConfig(1); // Ethereum mainnet

// Mine an address starting with "CAFE"
const initCodeHash = getMinimalProxyInitCodeHash(implementationAddress);

const result = await generateSaltAsync(chainConfig.factoryAddress, initCodeHash, {
  pattern: 'CAFE',
  mode: 'prefix',
  maxAttempts: 500_000,
  onProgress: (attempts, hashRate) => {
    console.log(`${attempts} attempts (${hashRate} H/s)`);
  },
});

if (result) {
  console.log('Found:', result.address);  // 0xCAFE...
  console.log('Salt:', result.salt);

  // Use salt in deployment
  await deployToken(signer, config, chainConfig, result.salt);
}
```

### 4. Reading Token Data

```typescript
import { readTokenData, createProvider, getChainConfig } from '@escapehub/token-creator';

const chainConfig = getChainConfig(1); // Ethereum
const provider = createProvider(chainConfig.rpcUrl);

const tokenData = await readTokenData(provider, tokenAddress, {
  multicall3Address: chainConfig.multicall3Address,
});

console.log('Name:', tokenData.name);
console.log('Symbol:', tokenData.symbol);
console.log('Total Supply:', tokenData.totalSupply);
console.log('Fees Enabled:', tokenData.fees.enabled);
```

### 5. List All Supported Chains

```typescript
import { SUPPORTED_CHAINS, getMainnets, getTestnets } from '@escapehub/token-creator';

// All 41 chains
console.log('Total chains:', SUPPORTED_CHAINS.length);

// Filter by network type
const mainnets = getMainnets();
const testnets = getTestnets();

// Each chain includes:
// - chainId, name, factoryAddress, rpcUrl, multicall3Address, testnet flag
```

## Exports

### Chain Configuration

| Function | Description |
|----------|-------------|
| `SUPPORTED_CHAINS` | Array of all 41 supported chains with configs |
| `CHAIN_MAP` | Map of chainId → chain config |
| `getChainConfig` | Get config for a specific chain |
| `getFactoryAddress` | Get factory address for a chain |
| `isChainSupported` | Check if a chain is supported |
| `getMainnets` | Get all mainnet chains |
| `getTestnets` | Get all testnet chains |

### Deployment Functions

| Function | Description |
|----------|-------------|
| `deployToken` | Deploy a new ERC20 token |
| `estimateGas` | Estimate gas for deployment |
| `getCreationFee` | Get the factory creation fee |
| `predictAddress` | Predict token address before deployment |
| `predictAddressLocal` | Predict address locally (no RPC call) |
| `waitForDeployment` | Wait for deployment transaction confirmation |
| `encodeTokenConfig` | Encode config for contract call |

### Token Reading Functions

| Function | Description |
|----------|-------------|
| `readTokenData` | Read all token data from chain (uses Multicall3) |
| `readTokenDataIndividual` | Read token data without Multicall3 |
| `fetchInitialDistribution` | Fetch token distribution data |
| `createProvider` | Create a provider for reading |
| `checkMulticall3Available` | Check if Multicall3 is deployed |

### CREATE2 & Vanity Address Utilities

| Function | Description |
|----------|-------------|
| `computeCreate2Address` | Compute CREATE2 address |
| `generateSalt` | Generate a random salt |
| `generateSaltAsync` | Generate salt asynchronously |
| `matchesVanityPattern` | Check if address matches pattern |
| `isValidHexPattern` | Validate hex pattern |
| `estimateVanityAttempts` | Estimate attempts for vanity address |
| `estimateVanityTime` | Estimate time for vanity mining |
| `buildMinimalProxyBytecode` | Build EIP-1167 proxy bytecode |

### Configuration Helpers

| Function | Description |
|----------|-------------|
| `createDefaultConfig` | Create a default token configuration |
| `isAddress` | Validate Ethereum address |
| `isTxHash` | Validate transaction hash |

### Types

```typescript
// Deployment
import type {
  TokenConfig,
  ChainConfig,
  DeploymentResult,
  DeploymentStatus,
  GasEstimation,
  ValidationResult,
  Address,
  TxHash,
} from '@escapehub/token-creator';

// Token Data
import type {
  TokenData,
  TokenDataFlat,
  FeeConfig,
  LimitConfig,
  BlacklistConfig,
  WhitelistConfig,
  AntiDumpConfig,
  DeadblockConfig,
  DistributionEntry,
} from '@escapehub/token-creator';

// CREATE2
import type {
  VanityPatternMode,
  VanityResult,
  VanityMiningOptions,
} from '@escapehub/token-creator';

// Chains
import type { SupportedChainConfig } from '@escapehub/token-creator';
```

### Enums & Constants

```typescript
import {
  DeadblockMode,
  WhitelistMode,
  AntiDumpType,
  BatchTransferAccess,
  BatchTransferFees,
  ZERO_ADDRESS,
  ZERO_SALT,
  STANDARD_MULTICALL3,
} from '@escapehub/token-creator';
```

### ABIs

```typescript
import {
  LaunchERC20ABI,
  LaunchERC20FactoryABI,
  LaunchERC20ReadABI,
  LaunchERC20FactoryReadABI,
} from '@escapehub/token-creator';

// Or import from subpath
import { LaunchERC20ABI } from '@escapehub/token-creator/abis';
```

### Contract Verification

```typescript
import {
  STANDARD_JSON_INPUT,    // Solidity standard JSON for Etherscan verification
  SOLC_VERSION,           // Compiler version
  CONTRACT_NAME,          // Contract path
  ETHERSCAN_API_URLS,     // API URLs per chain ID
  getEtherscanApiUrl,     // Get API URL for a chain
} from '@escapehub/token-creator';
```

## Subpath Exports

```typescript
// Types only
import type { TokenConfig, ChainConfig } from '@escapehub/token-creator/types';

// ABIs only
import { LaunchERC20ABI } from '@escapehub/token-creator/abis';

// Verification only
import { STANDARD_JSON_INPUT, ETHERSCAN_API_URLS } from '@escapehub/token-creator/verification';

// Chains only
import { SUPPORTED_CHAINS, getChainConfig } from '@escapehub/token-creator/chains';
```

## Supported Chains (41 total)

### Mainnets

| Network | Chain ID | Factory Address |
|---------|----------|-----------------|
| Ethereum | 1 | `0x1d83c38c19bfc3b06ca00cfb23062e906ffcc4cb` |
| BNB Smart Chain | 56 | `0x66466a3081052d6a819a08d1813d2782bc0f8405` |
| Polygon | 137 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Arbitrum One | 42161 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Optimism | 10 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Base | 8453 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Avalanche | 43114 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Linea | 59144 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Scroll | 534352 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Mantle | 5000 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Blast | 81457 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Celo | 42220 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Moonbeam | 1284 | `0x98642b5ac10167c2794729f196dcaa4db9cefa66` |
| Arbitrum Nova | 42170 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Sonic | 146 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Swell | 1923 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Sei | 1329 | `0x98642b5ac10167c2794729f196dcaa4db9cefa66` |
| Gnosis | 100 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Flare | 14 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| X Layer | 196 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Kaia | 8217 | `0x98642b5ac10167c2794729f196dcaa4db9cefa66` |
| Unichain | 130 | `0x98642b5ac10167c2794729f196dcaa4db9cefa66` |
| Monad | 143 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Pepe Unchained | 97741 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |

### Testnets

| Network | Chain ID | Factory Address |
|---------|----------|-----------------|
| Sepolia | 11155111 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Hoodi | 560048 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| BSC Testnet | 97 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Polygon Amoy | 80002 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Arbitrum Sepolia | 421614 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| OP Sepolia | 11155420 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Base Sepolia | 84532 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Avalanche Fuji | 43113 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Scroll Sepolia | 534351 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Mantle Sepolia | 5003 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Sonic Testnet | 14601 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Monad Testnet | 10143 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Gnosis Chiado | 10200 | `0x98642b5ac10167c2794729f196dcaa4db9cefa66` |
| Flare Coston2 | 114 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| X Layer Testnet | 1952 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Kaia Kairos | 1001 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |
| Celo Alfajores | 44787 | `0x10ca27bc0c4f9c1ea9169a76270c0c136d160a54` |

## Requirements

- Node.js 18+
- ethers.js v6

## Documentation

- Token Creator App: [app.escapehub.ai](https://app.escapehub.ai)
- Docs: [app.escapehub.ai/docs](https://app.escapehub.ai/docs/getting-started/intro)

## License

BUSL-1.1 (Business Source License)

This package uses the LaunchERC20 smart contracts which are licensed under BUSL-1.1.
You may use this SDK freely for token deployment. See LICENSE file for full terms.