@paul.lumberwork/bonding-curve-sdk 1.0.0

package/README.md

@@ -0,0 +1,484 @@
+# Pump.fun SDK
+
+Solana program with Linear Bonding Curve for token launches, similar to pump.fun.
+
+## Overview
+
+- **Program ID**: `6o7oTqg2CfvcMCJTLNEJsef7c875zGpTvcnFctNAjudL`
+- **Admin Wallet**: `7eGpbyRpcM7WpNKQtd6XkteNQWHbWXP7icZjKzNK2aTk`
+- **Network**: Devnet / Localnet
+
+## Token Allocation
+
+| Allocation | Percent | Description |
+|------------|---------|-------------|
+| Bonding Curve | 80% | Available for trading |
+| LP Reserve | 20% | Reserved for DEX migration |
+
+## Trading Fees (Hardcoded)
+
+| Fee | Percent | Recipient |
+|-----|---------|-----------|
+| Creator Fee | 0.5% | Token creator |
+| Admin Fee | 0.5% | Platform admin |
+| **Total** | **1%** | |
+
+## Bonding Curve Formula
+
+```
+Price = K × sold_supply
+Cost  = K × (s2² - s1²) / 2 / K_SCALE
+```
+
+Where `K_SCALE = 10^22`
+
+### K Value Reference
+
+| K Value | Target SOL | Use Case |
+|---------|------------|----------|
+| 60 | ~2 SOL | Testing |
+| 312 | ~10 SOL | Small launch |
+| 2156 | ~69 SOL | pump.fun style |
+| 3125 | ~100 SOL | Large launch |
+
+**Formula**: `Target SOL ≈ K × 0.032`
+
+---
+
+## SDK Usage
+
+### Installation
+
+```bash
+npm install github:lumberworks/kickdotfun-contracts-sdk
+```
+
+### Setup
+
+```typescript
+import * as anchor from "@coral-xyz/anchor";
+import { Program } from "@coral-xyz/anchor";
+import { Connection, Keypair, PublicKey } from "@solana/web3.js";
+import { PumpFunSDK, formatTokens, formatSol, PROGRAM_ID } from "pump-fun-sdk";
+import idl from "pump-fun-sdk/idl/pump_fun_program.json";
+
+// Setup connection and wallet
+const connection = new Connection("https://api.devnet.solana.com", "confirmed");
+const wallet = new anchor.Wallet(keypair);
+const provider = new anchor.AnchorProvider(connection, wallet, { commitment: "confirmed" });
+
+// Create program instance
+const program = new Program(idl as anchor.Idl, provider);
+
+// Create SDK instance
+const sdk = new PumpFunSDK(program, wallet);
+```
+
+### 1. Initialize Launchpad (one-time)
+
+```typescript
+const result = await sdk.initializeLaunchpad();
+// Returns: "already_initialized" or transaction signature
+```
+
+### 2. Create Token Launch
+
+**Default (creator = transaction signer):**
+```typescript
+const { txSignature, addresses, mintKeypair } = await sdk.createTokenLaunch({
+  name: "My Token",
+  symbol: "MTK",
+  uri: "https://example.com/metadata.json",
+  totalSupply: 1_000_000_000,  // 1B tokens
+  k: 60,                        // ~2 SOL target
+});
+
+const mint = mintKeypair.publicKey;
+console.log("Mint:", mint.toString());
+console.log("Token Launch PDA:", addresses.tokenLaunch.toString());
+```
+
+**With Custom Creator Wallet:**
+```typescript
+import { PublicKey } from "@solana/web3.js";
+
+const customCreator = new PublicKey("YourCreatorWalletAddress...");
+
+const { txSignature, addresses, mintKeypair } = await sdk.createTokenLaunch({
+  name: "My Token",
+  symbol: "MTK",
+  uri: "https://example.com/metadata.json",
+  totalSupply: 1_000_000_000,
+  k: 60,
+  creatorWallet: customCreator,  // Optional: receives 0.5% trading fees
+});
+```
+
+**Parameters:**
+- `name`: Token name
+- `symbol`: Token symbol
+- `uri`: Metadata URI
+- `totalSupply`: Total supply in tokens (e.g., 1B)
+- `k`: K value for bonding curve
+- `creatorWallet`: (Optional) Custom creator wallet to receive trading fees. Defaults to SDK wallet if not provided.
+
+**Returns:**
+- `txSignature`: Transaction hash
+- `addresses.mint`: Token mint address
+- `addresses.tokenLaunch`: Token launch PDA
+- `addresses.bondingCurve`: Bonding curve PDA
+- `addresses.vault`: SOL vault PDA
+- `mintKeypair`: Keypair of the new token
+
+**Note:** The creator wallet will receive 0.5% of all trading fees (buy/sell). Use `creatorWallet` parameter if you want fees to go to a different address than the transaction signer.
+
+### 3. Buy Tokens
+
+```typescript
+const result = await sdk.buy(mint, 0.5, { computeUnits: 400_000 });
+
+console.log("Tokens received:", formatTokens(result.tokensTraded));
+console.log("Progress:", result.newProgress.toFixed(2) + "%");
+console.log("Curve complete:", result.isCurveComplete);
+console.log("Tx:", result.txSignature);
+```
+
+**Parameters:**
+- `mint`: Token mint address (PublicKey)
+- `solAmount`: SOL to spend (number, e.g., 0.5 for 0.5 SOL)
+- `options.computeUnits`: Optional compute budget (default: none)
+
+**Returns:**
+- `txSignature`: Transaction hash
+- `tokensTraded`: Tokens received (bigint, raw with 6 decimals)
+- `solTraded`: SOL spent (bigint, lamports)
+- `newProgress`: Progress percentage (0-100)
+- `isCurveComplete`: True if 80% sold
+
+### 4. Sell Tokens
+
+```typescript
+const result = await sdk.sell(mint, 10_000_000, 0, { computeUnits: 400_000 });
+
+console.log("SOL received:", formatSol(result.solTraded));
+console.log("Progress:", result.newProgress.toFixed(2) + "%");
+```
+
+**Parameters:**
+- `mint`: Token mint address (PublicKey)
+- `tokenAmount`: Tokens to sell (number, e.g., 10_000_000 for 10M)
+- `minSolOut`: Minimum SOL to receive, slippage protection (default: 0)
+- `options.computeUnits`: Optional compute budget
+
+### 5. Estimate Buy
+
+```typescript
+const estimate = await sdk.estimateBuy(mint, 0.5);
+
+console.log("Tokens out:", formatTokens(estimate.tokensOut));
+console.log("Fee (1%):", formatSol(estimate.feeAmount));
+console.log("Price impact:", estimate.priceImpactBps, "bps");
+```
+
+### 6. Estimate Sell
+
+```typescript
+const estimate = await sdk.estimateSell(mint, 10_000_000);
+
+console.log("SOL out:", formatSol(estimate.solCost));
+console.log("Fee (1%):", formatSol(estimate.feeAmount));
+```
+
+### 7. Get Progress
+
+```typescript
+const progress = await sdk.getProgress(mint);
+
+console.log("Progress:", progress.percent + "%");
+console.log("SOL raised:", formatSol(progress.solRaised));
+console.log("Current price:", progress.currentPrice.toString(), "lamports/token");
+console.log("Complete:", progress.isComplete);
+```
+
+### 8. Get Curve State
+
+```typescript
+const curve = await sdk.getCurveState(mint);
+
+console.log("K:", curve.k.toString());
+console.log("Sold:", formatTokens(curve.soldSupply));
+console.log("Available:", formatTokens(curve.tokensForCurve));
+console.log("SOL reserves:", formatSol(curve.realSolReserves));
+console.log("Complete:", curve.complete);
+```
+
+### 9. Get Token Launch State
+
+```typescript
+const launch = await sdk.getTokenLaunchState(mint);
+
+console.log("Name:", launch.name, `(${launch.symbol})`);
+console.log("Creator:", launch.creator.toString());
+console.log("Trading active:", launch.tradingActive);
+console.log("Migrated:", launch.migrated);
+```
+
+### 10. Admin Withdraw (Admin Only)
+
+```typescript
+// Only ADMIN_WALLET can call this
+if (wallet.publicKey.equals(ADMIN_WALLET)) {
+  const result = await sdk.adminWithdraw(mint);
+  console.log("SOL withdrawn:", formatSol(result.solWithdrawn));
+  console.log("LP tokens:", formatTokens(result.tokensWithdrawn));
+}
+```
+
+**Requirements:**
+- Caller must be `ADMIN_WALLET`
+- Curve must be complete (80% sold)
+- Token not already migrated
+
+---
+
+## Event Listeners
+
+Subscribe to real-time events from the Pump.fun program.
+
+### Available Events
+
+| Event | Description |
+|-------|-------------|
+| `LaunchCreated` | New token launch created |
+| `TokensPurchased` | Tokens bought on bonding curve |
+| `TokensSold` | Tokens sold on bonding curve |
+| `CurveComplete` | Bonding curve reached 100% |
+| `AdminWithdraw` | Admin withdrew SOL + LP tokens |
+
+### Listen for Token Purchases
+
+```typescript
+// Subscribe to buy events
+const listenerId = sdk.onTokensPurchased((event, slot, signature) => {
+  console.log("Buy Event:", {
+    buyer: event.buyer.toString(),
+    mint: event.mint.toString(),
+    tokensReceived: formatTokens(event.tokensReceived),
+    solSpent: formatSol(event.solAmount),
+    progress: event.progress + "%",
+    complete: event.isCurveComplete,
+    slot,
+    signature,
+  });
+});
+
+// Unsubscribe when done
+await sdk.removeEventListener(listenerId);
+```
+
+### Listen for Token Sales
+
+```typescript
+const listenerId = sdk.onTokensSold((event, slot, signature) => {
+  console.log("Sell Event:", {
+    seller: event.seller.toString(),
+    tokensSold: formatTokens(event.tokensSold),
+    solReceived: formatSol(event.netSolRefund),
+    progress: event.progress + "%",
+  });
+});
+```
+
+### Listen for New Launches
+
+```typescript
+sdk.onLaunchCreated((event, slot, signature) => {
+  console.log("New Launch:", {
+    name: event.name,
+    symbol: event.symbol,
+    mint: event.mint.toString(),
+    creator: event.creator.toString(),
+    totalSupply: formatTokens(event.totalSupply),
+    initialK: event.initialK.toString(),
+  });
+});
+```
+
+### Listen for Curve Completion
+
+```typescript
+sdk.onCurveComplete((event, slot, signature) => {
+  console.log("Curve Complete!", {
+    mint: event.mint.toString(),
+    totalSolRaised: formatSol(event.totalSolRaised),
+    finalPrice: event.finalPrice.toString(),
+  });
+});
+```
+
+### Listen for Admin Withdrawals
+
+```typescript
+sdk.onAdminWithdraw((event, slot, signature) => {
+  console.log("Admin Withdrawal:", {
+    mint: event.mint.toString(),
+    solWithdrawn: formatSol(event.solWithdrawn),
+    tokensWithdrawn: formatTokens(event.tokensWithdrawn),
+  });
+});
+```
+
+### Complete Event Listener Example
+
+```typescript
+import { PumpFunSDK, formatTokens, formatSol } from "pump-fun-sdk";
+
+async function watchToken(sdk: PumpFunSDK, mint: PublicKey) {
+  // Track buys
+  const buyListener = sdk.onTokensPurchased((event, slot, sig) => {
+    if (event.mint.equals(mint)) {
+      console.log(`[Buy] ${formatTokens(event.tokensReceived)} tokens bought`);
+
+      if (event.isCurveComplete) {
+        console.log("🎉 Curve completed!");
+      }
+    }
+  });
+
+  // Track sells
+  const sellListener = sdk.onTokensSold((event, slot, sig) => {
+    if (event.mint.equals(mint)) {
+      console.log(`[Sell] ${formatTokens(event.tokensSold)} tokens sold`);
+    }
+  });
+
+  // Wait for curve completion
+  const completeListener = sdk.onCurveComplete((event, slot, sig) => {
+    if (event.mint.equals(mint)) {
+      console.log(`Curve complete! Total raised: ${formatSol(event.totalSolRaised)} SOL`);
+
+      // Clean up listeners
+      sdk.removeEventListener(buyListener);
+      sdk.removeEventListener(sellListener);
+      sdk.removeEventListener(completeListener);
+    }
+  });
+}
+```
+
+---
+
+## Utility Functions
+
+```typescript
+import { formatTokens, formatSol, parseSol, parseTokens } from "./sdk";
+
+// Format raw values to readable strings
+formatTokens(1000000000000n);  // "1,000,000" (1M tokens)
+formatSol(500000000n);          // "0.5000" (0.5 SOL)
+
+// Parse human values to raw
+parseSol(0.5);                  // 500000000n (lamports)
+parseTokens(1000000);           // 1000000000000n (raw with 6 decimals)
+```
+
+---
+
+## Constants
+
+```typescript
+import { ADMIN_WALLET, K_SCALE, TOKEN_DECIMALS, FEE_BPS } from "./sdk";
+
+ADMIN_WALLET    // PublicKey: "7eGpbyRpcM7WpNKQtd6XkteNQWHbWXP7icZjKzNK2aTk"
+K_SCALE         // 10^22 (bigint)
+TOKEN_DECIMALS  // 6
+FEE_BPS         // 100 (1%)
+```
+
+---
+
+## PDA Seeds
+
+| PDA | Seeds |
+|-----|-------|
+| Launchpad | `["launchpad"]` |
+| Token Launch | `["token_launch", mint]` |
+| Bonding Curve | `["bonding_curve", token_launch]` |
+| Vault | `["vault", token_launch]` |
+| User Position | `["user_position", token_launch, user]` |
+
+---
+
+## Full Example
+
+```typescript
+import * as anchor from "@coral-xyz/anchor";
+import { Program } from "@coral-xyz/anchor";
+import { PumpFunProgram } from "./target/types/pump_fun_program";
+import { PumpFunSDK, formatTokens, formatSol, ADMIN_WALLET } from "./sdk";
+
+async function main() {
+  const provider = anchor.AnchorProvider.env();
+  anchor.setProvider(provider);
+  const program = anchor.workspace.PumpFunProgram as Program<PumpFunProgram>;
+  const wallet = provider.wallet as anchor.Wallet;
+  const sdk = new PumpFunSDK(program, wallet);
+
+  // 1. Initialize launchpad
+  await sdk.initializeLaunchpad();
+
+  // 2. Create token
+  const { addresses, mintKeypair } = await sdk.createTokenLaunch({
+    name: "Test Token",
+    symbol: "TEST",
+    uri: "https://example.com/metadata.json",
+    totalSupply: 1_000_000_000,
+    k: 60,
+  });
+  const mint = mintKeypair.publicKey;
+
+  // 3. Buy tokens
+  const buy = await sdk.buy(mint, 0.5, { computeUnits: 400_000 });
+  console.log("Bought:", formatTokens(buy.tokensTraded));
+
+  // 4. Sell tokens
+  const sell = await sdk.sell(mint, 10_000_000, 0, { computeUnits: 400_000 });
+  console.log("Sold for:", formatSol(sell.solTraded), "SOL");
+
+  // 5. Check progress
+  const progress = await sdk.getProgress(mint);
+  console.log("Progress:", progress.percent + "%");
+
+  // 6. Admin withdraw (when curve complete)
+  if (progress.isComplete && wallet.publicKey.equals(ADMIN_WALLET)) {
+    const withdraw = await sdk.adminWithdraw(mint);
+    console.log("Withdrawn:", formatSol(withdraw.solWithdrawn), "SOL");
+  }
+}
+
+main().catch(console.error);
+```
+
+---
+
+## Running Tests
+
+```bash
+# Start local validator
+solana-test-validator --reset
+
+# In another terminal
+cd pump_fun_program
+anchor build && anchor deploy
+
+# Run test
+ANCHOR_PROVIDER_URL=http://127.0.0.1:8899 \
+ANCHOR_WALLET=./test-keypair.json \
+npx ts-node test-sdk.ts
+```
+
+---
+
+## License
+
+MIT