@clawnch/clawncher-sdk 2.0.0

package/README.md

@@ -0,0 +1,331 @@
+# @clawnch/sdk
+
+TypeScript SDK for [Clawnch](https://clawn.ch) - deploy tokens on Base with Uniswap V4 pools, earn trading fees.
+
+## Installation
+
+```bash
+npm install @clawnch/sdk
+```
+
+## Quick Start - Token Deployment
+
+```typescript
+import { ClawnchDeployer } from '@clawnch/sdk';
+import { createWalletClient, createPublicClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { baseSepolia } from 'viem/chains';
+
+const account = privateKeyToAccount('0x...');
+const wallet = createWalletClient({
+  account,
+  chain: baseSepolia,
+  transport: http(),
+});
+const publicClient = createPublicClient({
+  chain: baseSepolia,
+  transport: http(),
+});
+
+const deployer = new ClawnchDeployer({
+  wallet,
+  publicClient,
+  network: 'sepolia', // or 'mainnet'
+});
+
+const result = await deployer.deploy({
+  name: 'My Token',
+  symbol: 'MYTKN',
+  tokenAdmin: account.address,
+  rewards: {
+    recipients: [{
+      recipient: account.address,
+      admin: account.address,
+      bps: 10000, // 100%
+      feePreference: 'Paired', // Receive fees in WETH
+    }],
+  },
+});
+
+const { address } = await result.waitForTransaction();
+console.log('Token deployed:', address);
+```
+
+## Deployment Options
+
+### Basic Deployment
+
+```typescript
+const result = await deployer.deploy({
+  name: 'My Token',
+  symbol: 'MYTKN',
+  tokenAdmin: account.address,
+  image: 'https://example.com/logo.png',
+  metadata: {
+    description: 'A great token',
+    socialMediaUrls: [{ platform: 'twitter', url: 'https://twitter.com/mytoken' }],
+  },
+  rewards: {
+    recipients: [{
+      recipient: account.address,
+      admin: account.address,
+      bps: 10000,
+      feePreference: 'Paired',
+    }],
+  },
+});
+```
+
+### With Vault (Token Lockup + Vesting)
+
+```typescript
+const result = await deployer.deploy({
+  // ... basic options ...
+  vault: {
+    percentage: 10,              // 10% of supply
+    lockupDuration: 7 * 24 * 60 * 60,   // 7 days (minimum)
+    vestingDuration: 30 * 24 * 60 * 60, // 30 days linear vesting after lockup
+    recipient: account.address,
+  },
+});
+```
+
+### With Dev Buy (Instant)
+
+Buy tokens at launch with ETH - tokens sent directly to recipient:
+
+```typescript
+import { parseEther } from 'viem';
+
+const result = await deployer.deploy({
+  // ... basic options ...
+  devBuy: {
+    ethAmount: parseEther('0.1'),  // Spend 0.1 ETH
+    recipient: account.address,    // Tokens sent immediately
+  },
+});
+```
+
+### With Vested Dev Buy (Lockup + Vesting)
+
+Buy tokens at launch with ETH - tokens held with lockup and linear vesting:
+
+```typescript
+const result = await deployer.deploy({
+  // ... basic options ...
+  vestedDevBuy: {
+    ethAmount: parseEther('0.1'),
+    recipient: account.address,
+    lockupDuration: 7 * 24 * 60 * 60,   // 7 days minimum
+    vestingDuration: 90 * 24 * 60 * 60, // 90 days (30-365 days allowed)
+  },
+});
+```
+
+### Multiple Reward Recipients
+
+```typescript
+const result = await deployer.deploy({
+  // ... basic options ...
+  rewards: {
+    recipients: [
+      {
+        recipient: creatorAddress,
+        admin: creatorAddress,
+        bps: 8000, // 80%
+        feePreference: 'Paired',
+      },
+      {
+        recipient: platformAddress,
+        admin: platformAddress,
+        bps: 2000, // 20%
+        feePreference: 'Paired',
+      },
+    ],
+  },
+});
+```
+
+## Fee Structure
+
+**1% LP fee per swap**
+- **80%** → Deployer/reward recipients (default: in token)
+- **20%** → Protocol (Clawncher, in WETH)
+
+### Fee Preferences
+
+- `'Clawnch'` - Receive fees in the deployed token (default)
+- `'Paired'` - Receive fees in WETH
+- `'Both'` - Receive fees in both tokens
+
+## Vanity Addresses
+
+By default, all tokens are deployed with addresses starting with `0xccc`:
+
+```typescript
+// Default: mines for 0xccc... address
+const result = await deployer.deploy({
+  name: 'My Token',
+  symbol: 'MYTKN',
+  // ... other options
+});
+
+// Custom prefix
+const result = await deployer.deploy({
+  // ... other options
+  vanity: {
+    prefix: 'dead',  // Will be 0xdead...
+    onProgress: (attempts, rate) => {
+      console.log(`Mining: ${attempts} attempts, ${rate}/sec`);
+    },
+  },
+});
+
+// Disable vanity mining
+const result = await deployer.deploy({
+  // ... other options
+  vanity: { enabled: false },
+});
+
+// Result includes vanity mining stats
+console.log(result.vanityResult?.attempts);  // Number of attempts
+console.log(result.vanityResult?.timeMs);    // Time taken in ms
+console.log(result.vanityResult?.address);   // Predicted address
+```
+
+## Extension Constraints
+
+| Extension | Min | Max | Notes |
+|-----------|-----|-----|-------|
+| Vault | 1% | 90% | Lockup min 7 days |
+| Vested Dev Buy | - | - | Lockup min 7 days, vesting 30-365 days |
+| Dev Buy | > 0 ETH | - | Instant transfer |
+| Airdrop | 1% | 90% | Lockup min 1 day |
+
+## Reading On-Chain Data
+
+Use `ClawnchReader` to read token data directly from the blockchain:
+
+```typescript
+import { ClawnchReader } from '@clawnch/sdk';
+import { createPublicClient, http } from 'viem';
+import { base } from 'viem/chains';
+
+const publicClient = createPublicClient({
+  chain: base,
+  transport: http(),
+});
+
+const reader = new ClawnchReader({
+  publicClient,
+  network: 'mainnet', // or 'sepolia'
+});
+
+// Get full token details (deployment, rewards, vault, vesting, MEV config)
+const details = await reader.getTokenDetails('0xTokenAddress');
+
+// Get vault allocation (lockup + vesting)
+const vault = await reader.getVaultAllocation('0xTokenAddress');
+
+// Get vested dev buy allocation
+const vested = await reader.getVestedDevBuyAllocation('0xTokenAddress');
+
+// Get MEV protection config
+const mev = await reader.getMevConfig('0xTokenAddress');
+
+// Get available fees for a wallet
+const fees = await reader.getAvailableFees('0xWallet', '0xToken');
+
+// Check if token was deployed via Clawnch
+const isClawnch = await reader.isClawnchToken('0xTokenAddress');
+```
+
+## API Client (Optional)
+
+For API-based operations (tokens list, launches, analytics):
+
+```typescript
+import { ClawnchClient } from '@clawnch/sdk';
+
+const client = new ClawnchClient();
+
+// Get all tokens from API
+const tokens = await client.getTokens();
+
+// Get launch history
+const launches = await client.getLaunches({ limit: 10 });
+
+// Get market stats
+const stats = await client.getStats();
+```
+
+## Contract Addresses
+
+```typescript
+import { getAddresses } from '@clawnch/sdk';
+
+const addresses = getAddresses('sepolia'); // or 'mainnet'
+console.log(addresses.clawnch.factory);
+console.log(addresses.clawnch.vestedDevBuy);
+```
+
+### Base Mainnet
+
+| Contract | Address |
+|----------|---------|
+| Factory | `0xe31CD9ED1fF67ba51B337C17C2f7da57f7be0166` |
+| Hook | `0x194Ba81CBfd2a7d7E3dFb58969D5E82da31a28CC` |
+| Locker | `0x1c0FF3bB6aBb661e108Ab5A1C003a64316ca20B9` |
+| FeeLocker | `0x3325a1BDc3d28510761bA51Ac9A6995911B183ec` |
+| MevModule | `0xe835EC85aA00195d4AF865a31500bF50da63A715` |
+| Vault | `0xf9e53eCB6221B052ba32595449633dAf5cbe14e2` |
+| AirdropV2 | `0x0DF681a4895853a45Fe08729db034B270445226c` |
+| DevBuy | `0x34722dAf010EB0a5BD70Fb4f660D3C0080879208` |
+| VestedDevBuy | `0x699bcd1df91571F4B150E07B7A1b042Fc8616b8C` |
+
+### Base Sepolia (Testnet)
+
+| Contract | Address |
+|----------|---------|
+| Factory | `0xC5F06159BBFfb0eBEA6354fE5fD442329C064138` |
+| Hook | `0x63CFA9D50828d9bC54e089D9f2fC24B423bD28cC` |
+| Locker | `0xE60dCA4727A18e8D5b4BFd05E1cd22bad447DEf3` |
+| FeeLocker | `0x52f90A2Eb0a61cc0e91D5C49F37370de3BC32D73` |
+| MevModule | `0x0270f63E75646eB7E2CbCA41a1140314b312005A` |
+| Vault | `0x106654Cd164c7aFE673CA998987418fb94b7F85f` |
+| AirdropV2 | `0x8F4aD2EE724Ed79C570f99F8A5716A04053beC15` |
+| DevBuy | `0xBF75163C21a044AA06130d22bFb26bF5eD2af0Cc` |
+| VestedDevBuy | `0x06A192ef88cAc5eF4b11fE039346406cA32f8C34` |
+
+## Types
+
+```typescript
+import type {
+  // Deployer types
+  DeployOptions,
+  DeployResult,
+  VaultConfig,
+  DevBuyConfig,
+  VestedDevBuyConfig,
+  RewardRecipient,
+  FeePreference,
+  NetworkName,
+  // Reader types
+  TokenDetails,
+  VaultAllocation,
+  VestedDevBuyAllocation,
+  MevConfigInfo,
+  TokenRewardInfo,
+  WalletFeeInfo,
+} from '@clawnch/sdk';
+```
+
+## Links
+
+- **Website:** https://clawn.ch
+- **CLI:** `npm install -g clawnch`
+- **Docs:** https://clawn.ch/docs
+
+## License
+
+MIT