@paul.lumberwork/bonding-curve-sdk 1.4.0 → 1.6.0

package/README.md

@@ -1,6 +1,6 @@
-# Pump.fun SDK
+# Kick.fun SDK
 
-Solana program with Linear Bonding Curve for token launches, similar to pump.fun.
+Solana program with Linear Bonding Curve for token launches. SDK package: `@paul.lumberwork/bonding-curve-sdk`
 
 ## Overview
 
@@ -12,22 +12,23 @@ Solana program with Linear Bonding Curve for token launches, similar to pump.fun
 
 | Allocation | Percent | Description |
 |------------|---------|-------------|
-| Bonding Curve | 80% | Available for trading |
+| Bonding Curve | 70% | Available for trading |
 | LP Reserve | 20% | Reserved for DEX migration |
+| Treasury | 10% | Platform treasury |
 
 ## Trading Fees (Hardcoded)
 
 | Fee | Percent | Recipient |
 |-----|---------|-----------|
-| Creator Fee | 0.5% | Token creator |
-| Admin Fee | 0.5% | Platform admin |
+| Accumulated Fee | 0.5% | Accumulated in curve (withdrawn by admin) |
+| Admin Fee | 0.5% | Platform admin (immediate) |
 | **Total** | **1%** | |
 
 ## Bonding Curve Formula
 
 ```
-Price = K × sold_supply
-Cost  = K × (s2² - s1²) / 2 / K_SCALE
+Price = K x sold_supply
+Cost  = K x (s2² - s1²) / 2 / K_SCALE
 ```
 
 Where `K_SCALE = 10^22`
@@ -41,7 +42,9 @@ Where `K_SCALE = 10^22`
 | 2156 | ~69 SOL | pump.fun style |
 | 3125 | ~100 SOL | Large launch |
 
-**Formula**: `Target SOL ≈ K × 0.032`
+**Formula**: `Target SOL = K x 0.032`
+
+> **Note:** `total_supply` and `k` are configured by admin in the Launchpad contract. Creators do not set these values.
 
 ---
 
@@ -50,7 +53,7 @@ Where `K_SCALE = 10^22`
 ### Installation
 
 ```bash
-npm install github:lumberworks/kickdotfun-contracts-sdk
+npm install @paul.lumberwork/bonding-curve-sdk
 ```
 
 ### Setup
@@ -59,8 +62,8 @@ npm install github:lumberworks/kickdotfun-contracts-sdk
 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";
+import { KickFunSDK, formatTokens, formatSol, PROGRAM_ID } from "@paul.lumberwork/bonding-curve-sdk";
+import idl from "@paul.lumberwork/bonding-curve-sdk/idl/kick_fun_program.json";
 
 // Setup connection and wallet
 const connection = new Connection("https://api.devnet.solana.com", "confirmed");
@@ -71,10 +74,10 @@ const provider = new anchor.AnchorProvider(connection, wallet, { commitment: "co
 const program = new Program(idl as anchor.Idl, provider);
 
 // Create SDK instance
-const sdk = new PumpFunSDK(program, wallet);
+const sdk = new KickFunSDK(program, wallet);
 ```
 
-### 1. Initialize Launchpad (one-time)
+### 1. Initialize Launchpad (one-time, admin only)
 
 ```typescript
 const result = await sdk.initializeLaunchpad();
@@ -83,14 +86,11 @@ const result = await sdk.initializeLaunchpad();
 
 ### 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;
@@ -100,38 +100,29 @@ 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
+  creatorWallet: new PublicKey("YourCreatorWalletAddress..."),
 });
 ```
 
 **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.
+- `uri`: Metadata URI (Metaplex standard)
+- `creatorWallet`: (Optional) Custom creator wallet. Defaults to SDK wallet.
 
 **Returns:**
 - `txSignature`: Transaction hash
-- `addresses.mint`: Token mint address
 - `addresses.tokenLaunch`: Token launch PDA
 - `addresses.bondingCurve`: Bonding curve PDA
 - `addresses.vault`: SOL vault PDA
+- `addresses.curveTokenAccount`: Token account for curve
+- `addresses.metadata`: Metaplex metadata 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
@@ -140,7 +131,6 @@ 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:**
@@ -148,13 +138,6 @@ console.log("Tx:", result.txSignature);
 - `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
@@ -170,26 +153,52 @@ console.log("Progress:", result.newProgress.toFixed(2) + "%");
 - `minSolOut`: Minimum SOL to receive, slippage protection (default: 0)
 - `options.computeUnits`: Optional compute budget
 
-### 5. Estimate Buy
+### 5. Estimate Buy (SOL -> Tokens)
 
 ```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("SOL in (total):", formatSol(estimate.solIn));
+console.log("SOL after fee:", formatSol(estimate.solAfterFee));
+console.log("Fee:", formatSol(estimate.fee));
 console.log("Price impact:", estimate.priceImpactBps, "bps");
 ```
 
-### 6. Estimate Sell
+### 6. Estimate Buy by Tokens (Tokens -> SOL needed)
+
+```typescript
+const estimate = await sdk.estimateBuyByTokens(mint, 1_000_000); // 1M tokens
+
+console.log("SOL needed:", formatSol(estimate.solIn));
+console.log("SOL to curve:", formatSol(estimate.solAfterFee));
+console.log("Fee:", formatSol(estimate.fee));
+console.log("Tokens out:", formatTokens(estimate.tokensOut));
+```
+
+### 7. Estimate Sell (Tokens -> SOL)
 
 ```typescript
 const estimate = await sdk.estimateSell(mint, 10_000_000);
 
-console.log("SOL out:", formatSol(estimate.solCost));
-console.log("Fee (1%):", formatSol(estimate.feeAmount));
+console.log("SOL before fee:", formatSol(estimate.solBeforeFee));
+console.log("SOL out (net):", formatSol(estimate.solOut));
+console.log("Fee:", formatSol(estimate.fee));
+console.log("Tokens in:", formatTokens(estimate.tokensIn));
+```
+
+### 8. Estimate Sell by SOL (SOL desired -> Tokens to sell)
+
+```typescript
+const estimate = await sdk.estimateSellBySol(mint, 0.5); // want 0.5 SOL
+
+console.log("Tokens to sell:", formatTokens(estimate.tokensIn));
+console.log("SOL before fee:", formatSol(estimate.solBeforeFee));
+console.log("SOL out (net):", formatSol(estimate.solOut));
+console.log("Fee:", formatSol(estimate.fee));
 ```
 
-### 7. Get Progress
+### 9. Get Progress
 
 ```typescript
 const progress = await sdk.getProgress(mint);
@@ -200,19 +209,19 @@ console.log("Current price:", progress.currentPrice.toString(), "lamports/token"
 console.log("Complete:", progress.isComplete);
 ```
 
-### 8. Get Curve State
+### 10. 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("For curve:", formatTokens(curve.tokensForCurve));
 console.log("SOL reserves:", formatSol(curve.realSolReserves));
 console.log("Complete:", curve.complete);
 ```
 
-### 9. Get Token Launch State
+### 11. Get Token Launch State
 
 ```typescript
 const launch = await sdk.getTokenLaunchState(mint);
@@ -223,27 +232,64 @@ console.log("Trading active:", launch.tradingActive);
 console.log("Migrated:", launch.migrated);
 ```
 
-### 10. Admin Withdraw (Admin Only)
+### 12. 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));
+  console.log("Fees to treasury:", formatSol(result.feesToTreasury));
+  console.log("Treasury tokens:", formatTokens(result.treasuryTokens));
 }
 ```
 
 **Requirements:**
 - Caller must be `ADMIN_WALLET`
-- Curve must be complete (80% sold)
+- Curve must be complete (70% sold)
 - Token not already migrated
 
 ---
 
+## Estimate Return Types
+
+### EstimateBuyResult
+
+```typescript
+interface EstimateBuyResult {
+  solIn: bigint;          // Total SOL user pays (including fee)
+  solAfterFee: bigint;    // SOL that goes into the curve (after fee)
+  tokensOut: bigint;      // Tokens user receives
+  fee: bigint;            // Fee in SOL (lamports)
+  pricePerToken: bigint;
+  priceImpactBps: number;
+}
+```
+
+Used by: `estimateBuy()`, `estimateBuyByTokens()`
+
+### EstimateSellResult
+
+```typescript
+interface EstimateSellResult {
+  tokensIn: bigint;       // Tokens user sells
+  solBeforeFee: bigint;   // Gross SOL from curve (before fee)
+  solOut: bigint;         // Net SOL user receives (after fee)
+  fee: bigint;            // Fee in SOL (lamports)
+  pricePerToken: bigint;
+  priceImpactBps: number;
+}
+```
+
+Used by: `estimateSell()`, `estimateSellBySol()`
+
+> **Note:** Fee is always denominated in SOL (lamports).
+
+---
+
 ## Event Listeners
 
-Subscribe to real-time events from the Pump.fun program.
+Subscribe to real-time events from the program.
 
 ### Available Events
 
@@ -258,17 +304,17 @@ Subscribe to real-time events from the Pump.fun program.
 ### 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(),
+    solAmount: formatSol(event.solAmount),
+    solAfterFees: formatSol(event.solAfterFees),
     tokensReceived: formatTokens(event.tokensReceived),
-    solSpent: formatSol(event.solAmount),
+    curveFee: formatSol(event.curveFee),
+    adminFee: formatSol(event.adminFee),
     progress: event.progress + "%",
     complete: event.isCurveComplete,
-    slot,
-    signature,
   });
 });
 
@@ -283,7 +329,10 @@ const listenerId = sdk.onTokensSold((event, slot, signature) => {
   console.log("Sell Event:", {
     seller: event.seller.toString(),
     tokensSold: formatTokens(event.tokensSold),
-    solReceived: formatSol(event.netSolRefund),
+    grossSolRefund: formatSol(event.grossSolRefund),
+    netSolRefund: formatSol(event.netSolRefund),
+    curveFee: formatSol(event.curveFee),
+    adminFee: formatSol(event.adminFee),
     progress: event.progress + "%",
   });
 });
@@ -299,6 +348,9 @@ sdk.onLaunchCreated((event, slot, signature) => {
     mint: event.mint.toString(),
     creator: event.creator.toString(),
     totalSupply: formatTokens(event.totalSupply),
+    curveAllocation: formatTokens(event.curveAllocation),
+    lpAllocation: formatTokens(event.lpAllocation),
+    treasuryAllocation: formatTokens(event.treasuryAllocation),
     initialK: event.initialK.toString(),
   });
 });
@@ -324,54 +376,18 @@ sdk.onAdminWithdraw((event, slot, signature) => {
     mint: event.mint.toString(),
     solWithdrawn: formatSol(event.solWithdrawn),
     tokensWithdrawn: formatTokens(event.tokensWithdrawn),
+    feesToTreasury: formatSol(event.feesToTreasury),
+    treasuryTokens: formatTokens(event.treasuryTokens),
   });
 });
 ```
 
-### 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";
+import { formatTokens, formatSol, parseSol, parseTokens } from "@paul.lumberwork/bonding-curve-sdk";
 
 // Format raw values to readable strings
 formatTokens(1000000000000n);  // "1,000,000" (1M tokens)
@@ -387,12 +403,16 @@ parseTokens(1000000);           // 1000000000000n (raw with 6 decimals)
 ## Constants
 
 ```typescript
-import { ADMIN_WALLET, K_SCALE, TOKEN_DECIMALS, FEE_BPS } from "./sdk";
+import { ADMIN_WALLET, K_SCALE, TOKEN_DECIMALS, FEE_BPS, PROGRAM_ID } from "@paul.lumberwork/bonding-curve-sdk";
 
+PROGRAM_ID      // PublicKey: "6o7oTqg2CfvcMCJTLNEJsef7c875zGpTvcnFctNAjudL"
 ADMIN_WALLET    // PublicKey: "7eGpbyRpcM7WpNKQtd6XkteNQWHbWXP7icZjKzNK2aTk"
 K_SCALE         // 10^22 (bigint)
 TOKEN_DECIMALS  // 6
 FEE_BPS         // 100 (1%)
+CURVE_PERCENT   // 70
+LP_PERCENT      // 20
+TREASURY_PERCENT // 10
 ```
 
 ---
@@ -414,42 +434,50 @@ FEE_BPS         // 100 (1%)
 ```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";
+import { Connection, Keypair } from "@solana/web3.js";
+import { KickFunSDK, formatTokens, formatSol, ADMIN_WALLET } from "@paul.lumberwork/bonding-curve-sdk";
+import idl from "@paul.lumberwork/bonding-curve-sdk/idl/kick_fun_program.json";
 
 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);
+  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" });
+  const program = new Program(idl as anchor.Idl, provider) as any;
+  const sdk = new KickFunSDK(program, wallet);
 
-  // 1. Initialize launchpad
+  // 1. Initialize launchpad (admin only, one-time)
   await sdk.initializeLaunchpad();
 
-  // 2. Create token
+  // 2. Create token (total_supply and k are set by admin)
   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
+  // 3. Estimate before buying
+  const buyEstimate = await sdk.estimateBuy(mint, 0.5);
+  console.log("Will receive:", formatTokens(buyEstimate.tokensOut), "tokens");
+  console.log("Fee:", formatSol(buyEstimate.fee));
+
+  // 4. Buy tokens
   const buy = await sdk.buy(mint, 0.5, { computeUnits: 400_000 });
   console.log("Bought:", formatTokens(buy.tokensTraded));
 
-  // 4. Sell tokens
+  // 5. Estimate sell by desired SOL
+  const sellEstimate = await sdk.estimateSellBySol(mint, 0.3);
+  console.log("Need to sell:", formatTokens(sellEstimate.tokensIn), "tokens to get 0.3 SOL");
+
+  // 6. 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
+  // 7. Check progress
   const progress = await sdk.getProgress(mint);
   console.log("Progress:", progress.percent + "%");
 
-  // 6. Admin withdraw (when curve complete)
+  // 8. 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");
@@ -468,7 +496,7 @@ main().catch(console.error);
 solana-test-validator --reset
 
 # In another terminal
-cd pump_fun_program
+cd kick_fun_program
 anchor build && anchor deploy
 
 # Run test

package/dist/index.d.mts

@@ -11,7 +11,7 @@ import { PublicKey, Connection, Keypair } from '@solana/web3.js';
 type KickFunProgram = {
     "address": "6o7oTqg2CfvcMCJTLNEJsef7c875zGpTvcnFctNAjudL";
     "metadata": {
-        "name": "pumpFunProgram";
+        "name": "kickFunProgram";
         "version": "0.1.0";
         "spec": "0.1.0";
         "description": "Kick.fun Clone - IDO Launchpad with Bonding Curve";
@@ -2403,13 +2403,78 @@ type KickFunProgram = {
     "errors": [
         {
             "code": 6000;
-            "name": "overflow";
-            "msg": "Math overflow in linear curve calculation";
+            "name": "platformPaused";
+            "msg": "Platform is currently paused";
         },
         {
             "code": 6001;
-            "name": "divisionByZero";
-            "msg": "Division by zero";
+            "name": "unauthorized";
+            "msg": "Unauthorized: only authority can perform this action";
+        },
+        {
+            "code": 6002;
+            "name": "tradingNotActive";
+            "msg": "Trading is not active";
+        },
+        {
+            "code": 6003;
+            "name": "alreadyMigrated";
+            "msg": "Token has already migrated to DEX";
+        },
+        {
+            "code": 6004;
+            "name": "insufficientSol";
+            "msg": "Insufficient SOL balance";
+        },
+        {
+            "code": 6005;
+            "name": "insufficientTokens";
+            "msg": "Insufficient token balance";
+        },
+        {
+            "code": 6006;
+            "name": "slippageExceeded";
+            "msg": "Slippage tolerance exceeded";
+        },
+        {
+            "code": 6007;
+            "name": "mathOverflow";
+            "msg": "Math overflow error";
+        },
+        {
+            "code": 6008;
+            "name": "invalidAmount";
+            "msg": "Invalid amount: must be greater than zero";
+        },
+        {
+            "code": 6009;
+            "name": "alreadyClaimed";
+            "msg": "Tokens already claimed";
+        },
+        {
+            "code": 6010;
+            "name": "noTokensToClaim";
+            "msg": "No tokens to claim";
+        },
+        {
+            "code": 6011;
+            "name": "invalidFee";
+            "msg": "Invalid fee: must be less than 10000 basis points";
+        },
+        {
+            "code": 6012;
+            "name": "invalidReserves";
+            "msg": "Invalid virtual reserves";
+        },
+        {
+            "code": 6013;
+            "name": "launchNotMigrated";
+            "msg": "Launch not migrated yet";
+        },
+        {
+            "code": 6014;
+            "name": "curveNotComplete";
+            "msg": "Bonding curve is not complete yet";
         }
     ];
     "types": [
@@ -3418,6 +3483,23 @@ declare class KickFunSDK {
         currentPrice: bigint;
         isComplete: boolean;
     }>;
+    /**
+     * Get the initial/starting price for a token launch.
+     * Linear curve starts at price=0, so this returns the theoretical price
+     * after 1 display token is sold — useful as the "open" price for the first candle.
+     */
+    getInitialPrice(mint: PublicKey): Promise<{
+        priceLamports: bigint;
+        priceSol: number;
+    }>;
+    /**
+     * Get the price at any given sold supply (display tokens).
+     * Useful for calculating open/close prices on candlestick charts.
+     */
+    getPriceAtSupply(k: bigint, soldDisplayTokens: number): {
+        priceLamports: bigint;
+        priceSol: number;
+    };
     /**
      * Listen for LaunchCreated events
      * @param callback Function to call when event is emitted
@@ -3453,8 +3535,13 @@ declare class KickFunSDK {
      * @param listenerId The ID returned from addEventListener
      */
     removeEventListener(listenerId: number): Promise<void>;
-    /** Calculate price at a given supply: price = k × supply / K_SCALE */
+    /** Calculate price at a given supply in lamports per display token.
+     *  Formula: price = k × supply × 10^DECIMALS / K_SCALE
+     *  Returns lamports per 1 display token (not per raw token). */
     calculatePrice(k: bigint, supply: bigint): bigint;
+    /** Calculate price per display token in SOL (float).
+     *  Useful for charts where sub-lamport precision matters. */
+    calculatePriceSol(k: bigint, supply: bigint): number;
     /** Calculate cost to buy from s1 to s2: cost = (k/2) × (s2² - s1²) / K_SCALE */
     calculateCost(k: bigint, s1: bigint, s2: bigint): bigint;
     /** Calculate tokens received for SOL: s2 = sqrt(s1² + 2×sol×K_SCALE/k) */