@clawnch/clawncher-sdk 0.1.0

package/README.md

@@ -0,0 +1,603 @@
+# @clawnch/clawncher-sdk
+
+TypeScript SDK for [Clawncher](https://clawn.ch/er) - deploy tokens on Base with Uniswap V4 pools, MEV protection, and configurable fee distribution.
+
+## Installation
+
+```bash
+npm install @clawnch/clawncher-sdk viem
+```
+
+## Quick Start - Token Deployment
+
+```typescript
+import { ClawnchDeployer } from '@clawnch/clawncher-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
+  },
+});
+```
+
+### 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%** to deployer/reward recipients
+- **20%** protocol (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
+
+Vanity addresses (0xb07 suffix) are handled by Clanker's remote service. Pass `vanity: true` (default) or `vanity: false` to disable.
+
+## Extension Constraints
+
+| Extension | Min | Max | Notes |
+|-----------|-----|-----|-------|
+| Vault | 1% | 90% | Lockup min 7 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/clawncher-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 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 Clawncher
+const isClawnch = await reader.isClawnchToken('0xTokenAddress');
+```
+
+## Claiming Fees
+
+```typescript
+import { ClawncherClaimer } from '@clawnch/clawncher-sdk';
+
+const claimer = new ClawncherClaimer({ wallet, publicClient, network: 'mainnet' });
+
+// Collect LP rewards (triggers fee collection from positions)
+await claimer.collectRewards('0xToken...');
+
+// Claim fees from FeeLocker
+await claimer.claimFees('0xWallet...', '0xToken...');
+
+// Claim vault allocation
+await claimer.claimVault('0xToken...');
+
+// Claim everything at once
+await claimer.claimAll('0xToken...', { claimVault: true });
+
+// Batch claim across multiple tokens
+const result = await claimer.claimBatch(tokens, feeOwner, {
+  onProgress: (token, step) => console.log(`${token}: ${step}`),
+});
+```
+
+## Dry Run
+
+```typescript
+const result = await deployer.deploy({
+  ...options,
+  dryRun: true,
+});
+// result.translatedConfig - the Clanker config (for inspection)
+// result.estimatedGas - estimated gas
+// result.estimatedCostEth - estimated cost in ETH
+```
+
+## Error Handling
+
+```typescript
+import { ClawnchDeployError, ClawnchErrorCode, isClawnchError } from '@clawnch/clawncher-sdk';
+
+const result = await deployer.deploy(options);
+if (isClawnchError(result.error)) {
+  console.log(result.error.code);  // e.g. ClawnchErrorCode.INSUFFICIENT_FUNDS
+  console.log(result.error.cause); // original error if any
+}
+```
+
+## Portfolio Tracking
+
+```typescript
+import { ClawnchPortfolio } from '@clawnch/clawncher-sdk';
+
+const portfolio = new ClawnchPortfolio({ publicClient, network: 'mainnet' });
+const tokens = await portfolio.getTokensForWallet(wallet, knownTokens);
+const claimable = await portfolio.getTotalClaimable(wallet, knownTokens);
+```
+
+## Live Watching
+
+```typescript
+import { ClawnchWatcher } from '@clawnch/clawncher-sdk';
+
+const watcher = new ClawnchWatcher({ publicClient, network: 'mainnet' });
+const unwatch = watcher.watchDeployments((event) => {
+  console.log(`New: ${event.tokenSymbol} at ${event.tokenAddress}`);
+});
+```
+
+## Batch Fee Claiming
+
+```typescript
+const result = await claimer.claimBatch(tokens, feeOwner, {
+  onProgress: (token, step) => console.log(`${token}: ${step}`),
+});
+```
+
+## Token Swaps
+
+Execute token swaps via 0x aggregation for best price across all Base DEXes.
+Swaps are routed through the Clawnch API — no API key needed.
+
+```typescript
+import { ClawnchSwapper, NATIVE_TOKEN_ADDRESS } from '@clawnch/clawncher-sdk';
+import { parseEther } from 'viem';
+
+const swapper = new ClawnchSwapper({
+  wallet,
+  publicClient,
+});
+
+// Get indicative price (read-only, no commitment)
+const price = await swapper.getPrice({
+  sellToken: NATIVE_TOKEN_ADDRESS,  // ETH
+  buyToken: '0xTokenAddress...',
+  sellAmount: parseEther('0.01'),
+});
+console.log('You would receive:', price.buyAmount);
+console.log('Liquidity:', price.liquidityAvailable);
+
+// Get firm quote (market makers commit assets)
+const quote = await swapper.getQuote({
+  sellToken: NATIVE_TOKEN_ADDRESS,
+  buyToken: '0xTokenAddress...',
+  sellAmount: parseEther('0.01'),
+});
+
+// Full swap execution: quote → approve → send → wait
+const result = await swapper.swap({
+  sellToken: NATIVE_TOKEN_ADDRESS,
+  buyToken: '0xTokenAddress...',
+  sellAmount: parseEther('0.01'),
+  slippageBps: 100,  // 1% (default)
+});
+console.log('Tx:', result.txHash);
+console.log('Received:', result.buyAmount);
+```
+
+### Swap Helpers
+
+```typescript
+// Token balance (ETH or ERC20)
+const balance = await swapper.getBalance(tokenAddress);
+
+// Token metadata
+const decimals = await swapper.getDecimals(tokenAddress);
+const symbol = await swapper.getSymbol(tokenAddress);
+
+// Allowance management
+const allowance = await swapper.getAllowance(token, owner, spender);
+await swapper.approveToken(token, spender);
+
+// Format amount to human-readable
+const formatted = await swapper.formatAmount(tokenAddress, rawAmount);
+```
+
+### Swap Constants
+
+```typescript
+import {
+  NATIVE_TOKEN_ADDRESS,  // 0xEeee...eEEeE (0x representation of native ETH)
+  BASE_WETH,             // 0x4200...0006
+  BASE_CHAIN_ID,         // 8453
+  ZEROX_API_BASE,        // https://api.0x.org
+} from '@clawnch/clawncher-sdk';
+```
+
+## Liquidity Management
+
+Manage Uniswap V3 and V4 liquidity positions on Base.
+
+```typescript
+import { ClawnchLiquidity } from '@clawnch/clawncher-sdk';
+
+const liquidity = new ClawnchLiquidity({ wallet, publicClient });
+```
+
+### V3 Positions (Full CRUD)
+
+```typescript
+// List all positions for a wallet
+const positions = await liquidity.v3GetPositionsForWallet('0xWallet...');
+
+// Get single position
+const pos = await liquidity.v3GetPosition(tokenId);
+console.log(pos.liquidity, pos.unclaimedFees);
+
+// Mint new position
+const result = await liquidity.v3MintPosition({
+  token0: '0xTokenA...',
+  token1: '0xTokenB...',
+  fee: 3000,
+  tickLower: -887220,
+  tickUpper: 887220,
+  amount0Desired: parseEther('1'),
+  amount1Desired: parseUnits('2000', 6),
+});
+
+// Add liquidity to existing position
+await liquidity.v3AddLiquidity(tokenId, {
+  amount0Desired: parseEther('0.5'),
+  amount1Desired: parseUnits('1000', 6),
+});
+
+// Remove 50% of liquidity
+await liquidity.v3RemoveLiquidity(tokenId, {
+  percentageToRemove: 0.5,
+});
+
+// Remove 100% and burn NFT
+await liquidity.v3RemoveLiquidity(tokenId, {
+  percentageToRemove: 1.0,
+  burnToken: true,
+});
+
+// Collect unclaimed fees
+const fees = await liquidity.v3CollectFees(tokenId);
+
+// Filter positions by token
+const tokenPositions = await liquidity.getPositionsForToken('0xToken...');
+```
+
+### V4 Pool Reading
+
+```typescript
+// Read V4 pool state
+const state = await liquidity.v4GetPoolState({
+  currency0: '0xTokenA...',
+  currency1: '0xTokenB...',
+  fee: 3000,
+  tickSpacing: 60,
+  hooks: '0x0000000000000000000000000000000000000000',
+});
+
+// Read V4 position
+const pos = await liquidity.v4GetPosition(tokenId);
+
+// Execute V4 multicall (use with @uniswap/v4-sdk calldata)
+const { txHash, receipt } = await liquidity.v4ExecuteMulticall(calldata, ethValue);
+```
+
+### Uniswap Addresses
+
+```typescript
+import {
+  getUniswapV4Addresses,
+  getUniswapV3Addresses,
+  getCommonAddresses,
+} from '@clawnch/clawncher-sdk';
+
+const v4 = getUniswapV4Addresses('mainnet');
+// v4.poolManager, v4.positionManager, v4.stateView, v4.quoter, v4.permit2, ...
+
+const v3 = getUniswapV3Addresses('mainnet');
+// v3.factory, v3.nonfungiblePositionManager, v3.swapRouter, v3.quoterV2
+
+const common = getCommonAddresses('mainnet');
+// common.weth, common.usdc
+```
+
+## API Client (Optional)
+
+For API-based operations (tokens list, launches, analytics):
+
+```typescript
+import { ClawnchClient } from '@clawnch/clawncher-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/clawncher-sdk';
+
+const addresses = getAddresses('mainnet'); // or 'sepolia'
+console.log(addresses.clawnch.factory);
+console.log(addresses.clawnch.devBuy);
+```
+
+### Base Mainnet (v3 via Clanker)
+
+| Contract | Address |
+|----------|---------|
+| Factory | `0xE85A59c628F7d27878ACeB4bf3b35733630083a9` |
+| Hook | `0x6F5e57a4e81E93b8235710E3aA14E8c1d3d3bcb8` |
+| LP Locker | `0x63D2DfEA64b3433F4071A98665bcD7Ca14d93496` |
+| FeeLocker | `0x42A95190B4088C88Dd904d930c79deC1158bF09D` |
+| Vault | `0xcC80d1226F899a78fC2E459a1500A13C373CE0A5` |
+| DevBuy | `0x97fd42fcc8c4E2A5a45d0e28E14EC60FF7c10D9C` |
+
+### Base Sepolia (v3 via Clanker)
+
+| Contract | Address |
+|----------|---------|
+| Factory | `0xE85A59c628F7d27878ACeB4bf3b35733630083a9` |
+| Hook | `0x6F5e57a4e81E93b8235710E3aA14E8c1d3d3bcb8` |
+| LP Locker | `0x63D2DfEA64b3433F4071A98665bcD7Ca14d93496` |
+| FeeLocker | `0x42A95190B4088C88Dd904d930c79deC1158bF09D` |
+| Vault | `0xcC80d1226F899a78fC2E459a1500A13C373CE0A5` |
+| DevBuy | `0x97fd42fcc8c4E2A5a45d0e28E14EC60FF7c10D9C` |
+
+## Types
+
+```typescript
+import type {
+  // Deployer types
+  DeployOptions,
+  DeployResult,
+  VaultConfig,
+  DevBuyConfig,
+  RewardRecipient,
+  FeePreference,
+  NetworkName,
+  // Reader types
+  TokenDetails,
+  VaultAllocation,
+  MevConfigInfo,
+  TokenRewardInfo,
+  WalletFeeInfo,
+  // Error types
+  ClawnchErrorCode,
+  ClawnchDeployError,
+  // Dry run
+  DryRunResult,
+  // Batch claiming
+  BatchClaimResult,
+  // Portfolio
+  PortfolioToken,
+  // Watcher
+  NewTokenEvent,
+  // Swap types
+  SwapperConfig,
+  SwapParams,
+  SwapPriceResult,
+  SwapQuoteResult,
+  SwapResult,
+  SwapTransaction,
+  // Liquidity types
+  LiquidityConfig,
+  V4PoolKey,
+  V4PoolState,
+  V3MintParams,
+  V3AddLiquidityParams,
+  V3RemoveLiquidityParams,
+  PositionInfo,
+  MintResult,
+  ModifyLiquidityResult,
+  CollectFeesResult,
+  // Uniswap address types
+  UniswapV4Addresses,
+  UniswapV3Addresses,
+  CommonAddresses,
+  // Verified agent launch types
+  ClawnchApiDeployer,
+  ApiDeployerConfig,
+  RegisterConfig,
+  RegisterRequest,
+  VerifyResponse,
+  AgentStatus,
+  ApiDeployRequest,
+  ApiDeployResponse,
+  ApprovalResult,
+  CaptchaChallenge,
+  CaptchaSolution,
+} from '@clawnch/clawncher-sdk';
+```
+
+## Verified Agent Launches
+
+Deploy tokens via the Clawnch API to receive a verified badge. The `ClawnchApiDeployer` handles registration, captcha solving, and deployment.
+
+> **Note:** Server-side API endpoints are pending deployment. The SDK client is ready.
+
+```typescript
+import { ClawnchApiDeployer } from '@clawnch/clawncher-sdk';
+
+// One-time registration (returns API key)
+const { apiKey } = await ClawnchApiDeployer.register(
+  { wallet, publicClient },
+  { name: 'MyAgent', wallet: account.address, description: 'AI trading agent' }
+);
+
+// Create deployer with API key
+const apiDeployer = new ClawnchApiDeployer({
+  apiKey,
+  wallet,
+  publicClient,
+});
+
+// One-time $CLAWNCH approval
+await apiDeployer.approveClawnch();
+
+// Deploy a verified token
+const result = await apiDeployer.deploy({
+  name: 'My Token',
+  symbol: 'MYTKN',
+  image: 'https://example.com/logo.png',
+});
+console.log('Token:', result.tokenAddress);
+```
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `ClawnchApiDeployer.register(config, request)` | Register agent, receive API key |
+| `getStatus()` | Agent verification status and balance |
+| `approveClawnch(spender?)` | One-time $CLAWNCH max approval |
+| `getClawnchAllowance(spender)` | Check $CLAWNCH allowance |
+| `getClawnchBalance()` | Check $CLAWNCH balance |
+| `deploy(request)` | Full verified deploy flow |
+
+## Links
+
+- **Website:** https://clawn.ch/er
+- **CLI:** `npm install -g clawncher`
+- **Documentation:** https://clawn.ch/er/docs
+
+## License
+
+MIT