@coinbarrel/sdk 3.2.6 → 3.2.7

package/README.md

@@ -1,6 +1,6 @@
 # @coinbarrel/sdk
 
-SDK for integrating with CoinBarrel AMM - bonding curves and liquidity pools on Solana.
+SDK for launching and trading tokens on CoinBarrel — instant Meteora DAMM V2 pools on Solana.
 
 ## Installation
 
@@ -11,87 +11,87 @@ npm install @coinbarrel/sdk @solana/web3.js @solana/spl-token
 ## Quick Start
 
 ```typescript
-import { Connection, Keypair, Transaction } from '@solana/web3.js';
-import { CoinBarrel, solToLamports } from '@coinbarrel/sdk';
+import { Connection, Keypair, PublicKey, Transaction, sendAndConfirmTransaction } from '@solana/web3.js';
+import { CoinBarrel, solToLamports, InstantTokenVariant, LaunchTier } from '@coinbarrel/sdk';
 
-// Initialize SDK
 const connection = new Connection('https://api.mainnet-beta.solana.com');
 const sdk = new CoinBarrel({
 	connection,
 	network: 'mainnet', // or 'devnet'
 });
-
-// Token to trade
-const tokenMint = new PublicKey('YOUR_TOKEN_MINT');
 ```
 
-## Bonding Curve Trading (Pre-Graduation)
+## Launch a Token
 
-### Get Buy Quote
+Tokens launch directly to Meteora DAMM V2 pools using Token2022 with native metadata — no bonding curve, no graduation.
 
 ```typescript
-const quote = await sdk.curve.getBuyQuote(
-	tokenMint,
-	solToLamports(0.1) // 0.1 SOL
-);
+const { instructions, mintKeypair, adminTokenAccount } = sdk.buildCreateInstantTokenV2Instruction({
+	payer: wallet.publicKey,
+	creator: wallet.publicKey,
+	name: 'My Token',
+	symbol: 'MTK',
+	uri: 'https://arweave.net/...', // Metadata JSON URI
+	variant: InstantTokenVariant.Standard,
+	traderRewardsShareBps: 2500, // 25% of fees to holders
+	launchTier: LaunchTier.Standard,
+});
 
-if (quote) {
-	console.log(`Tokens out: ${quote.tokensOut}`);
-	console.log(`Price impact: ${quote.priceImpactBps / 100}%`);
-}
+const tx = new Transaction().add(...instructions);
+const signature = await sendAndConfirmTransaction(connection, tx, [wallet, mintKeypair]);
+
+console.log(`Token created: ${mintKeypair.publicKey.toBase58()}`);
 ```
 
-### Buy Tokens
+The token is created with:
 
-```typescript
-import { Transaction, sendAndConfirmTransaction } from '@solana/web3.js';
+- **Token Program**: Token2022 (with native metadata extension — no Metaplex)
+- **Mint authority**: Revoked immediately after minting 1B tokens
+- **Freeze authority**: Never set
+- **Total supply**: 1,000,000,000 tokens (6 decimals)
+- **Creation fee**: 0.03 SOL
+- **Pool creation**: Backend automatically creates the Meteora pool after token creation
 
-// Get quote first to calculate minimum output with slippage
-const quote = await sdk.curve.getBuyQuote(tokenMint, solToLamports(0.1));
-const slippageBps = 100; // 1%
-const minimumTokensOut = quote
-	? (quote.tokensOut * BigInt(10000 - slippageBps)) / 10000n
-	: 0n;
+### Variants
 
-const instructions = await sdk.curve.buildBuyInstruction({
-	tokenMint,
-	buyer: wallet.publicKey,
-	lamportsIn: solToLamports(0.1),
-	minimumTokensOut, // Slippage protection - tx fails if output is less
-});
+| Variant | Virtual Liquidity | Use Case |
+|---------|------------------|----------|
+| Standard (0) | 90 SOL | Normal launches |
+| Deep (1) | 120 SOL | Lower price impact |
 
-const tx = new Transaction().add(...instructions);
-const signature = await sendAndConfirmTransaction(connection, tx, [wallet]);
-```
+### Launch Tiers
 
-### Sell Tokens
+| Tier | Trading Fee | Use Case |
+|------|-------------|----------|
+| Standard (0) | 1.25% | Default, lower fees |
+| Premium (1) | 5% | Higher creator revenue |
 
-```typescript
-// Get quote first to calculate minimum output with slippage
-const sellQuote = await sdk.curve.getSellQuote(tokenMint, BigInt(1_000_000));
-const slippageBps = 100; // 1%
-const minimumLamportsOut = sellQuote
-	? (sellQuote.solOut * BigInt(10000 - slippageBps)) / 10000n
-	: 0n;
+### Advanced Options
 
-const instructions = await sdk.curve.buildSellInstruction({
-	tokenMint,
-	seller: wallet.publicKey,
-	tokenAmount: BigInt(1_000_000), // 1 token (6 decimals)
-	minimumLamportsOut, // Slippage protection
-});
-
-// Or sell entire balance
-const sellMaxIx = await sdk.curve.buildSellMaxInstruction({
-	tokenMint,
-	seller: wallet.publicKey,
-	minimumLamportsOut: 0n, // Use 0 to accept any amount, or calculate from quote
+```typescript
+sdk.buildCreateInstantTokenV2Instruction({
+	payer: wallet.publicKey,
+	creator: wallet.publicKey,
+	name: 'My Token',
+	symbol: 'MTK',
+	uri: 'https://arweave.net/...',
+	variant: InstantTokenVariant.Deep,      // 120 SOL virtual liquidity
+	traderRewardsShareBps: 3000,            // 30% of fees to holders
+	launchTier: LaunchTier.Premium,         // 5% trading fee
+	burnFeeBps: 1000,                       // 10% burn fee
+	devBuyAmountLamports: solToLamports(1), // 1 SOL dev buy
+	recipients: [                           // Multi-recipient fee split (up to 25)
+		{ recipientType: 0, twitterId: 0n, wallet: wallet1, bps: 7000 },
+		{ recipientType: 0, twitterId: 0n, wallet: wallet2, bps: 3000 },
+	],
 });
 ```
 
-## AMM Pool Trading (Post-Graduation)
+## Trading
 
-### Get Swap Quote
+Once the Meteora pool is live, use pool methods to trade.
+
+### Get a Buy Quote
 
 ```typescript
 const quote = await sdk.pool.getSwapSolToTokenQuote(
@@ -102,81 +102,115 @@ const quote = await sdk.pool.getSwapSolToTokenQuote(
 if (quote) {
 	console.log(`Tokens out: ${quote.amountOut}`);
 	console.log(`Fee: ${quote.fee} lamports`);
+	console.log(`Price impact: ${quote.priceImpactBps / 100}%`);
 }
 ```
 
-### Swap SOL for Tokens
+### Buy Tokens (SOL -> Token)
 
 ```typescript
+const quote = await sdk.pool.getSwapSolToTokenQuote(tokenMint, solToLamports(1.0));
+const slippageBps = 100; // 1%
+const minimumAmountOut = quote
+	? (quote.amountOut * BigInt(10000 - slippageBps)) / 10000n
+	: 0n;
+
 const instructions = await sdk.pool.buildSwapSolToTokenInstruction({
 	tokenMint,
 	user: wallet.publicKey,
 	lamportsIn: solToLamports(1.0),
-	minimumAmountOut: BigInt(900_000), // Slippage protection
+	minimumAmountOut,
 });
+
+const tx = new Transaction().add(...instructions);
+const signature = await sendAndConfirmTransaction(connection, tx, [wallet]);
+```
+
+### Get a Sell Quote
+
+```typescript
+const quote = await sdk.pool.getSwapTokenToSolQuote(
+	tokenMint,
+	BigInt(1_000_000) // 1 token (6 decimals)
+);
+
+if (quote) {
+	console.log(`SOL out: ${quote.amountOut} lamports`);
+	console.log(`Fee: ${quote.fee} lamports`);
+}
 ```
 
-### Swap Tokens for SOL
+### Sell Tokens (Token -> SOL)
 
 ```typescript
+const quote = await sdk.pool.getSwapTokenToSolQuote(tokenMint, BigInt(1_000_000));
+const slippageBps = 100; // 1%
+const minimumLamportsOut = quote
+	? (quote.amountOut * BigInt(10000 - slippageBps)) / 10000n
+	: 0n;
+
 const instructions = await sdk.pool.buildSwapTokenToSolInstruction({
 	tokenMint,
 	user: wallet.publicKey,
 	amountIn: BigInt(1_000_000),
-	minimumLamportsOut: solToLamports(0.09),
+	minimumLamportsOut,
 });
 
-// Or sell entire balance
-const sellMaxIx = await sdk.pool.buildSwapTokenToSolMaxInstruction({
-	tokenMint,
-	user: wallet.publicKey,
-});
+const tx = new Transaction().add(...instructions);
+const signature = await sendAndConfirmTransaction(connection, tx, [wallet]);
 ```
 
-## Token Creation
-
-### Create a New Token
+### Sell All Tokens
 
 ```typescript
-// Build create token instruction
-const { instructions, mintKeypair } = sdk.buildCreateTokenInstruction({
-	payer: wallet.publicKey,
-	name: 'My Token',
-	symbol: 'MTK',
-	uri: 'https://arweave.net/...', // Metadata JSON URI
-	creatorFeeRecipient: wallet.publicKey,
-	traderRewardsShareBps: 3000, // 30% of fees to holders (optional, default 2500)
+const instructions = await sdk.pool.buildSwapTokenToSolMaxInstruction({
+	tokenMint,
+	user: wallet.publicKey,
 });
 
-// Build and send transaction
 const tx = new Transaction().add(...instructions);
-const signature = await sendAndConfirmTransaction(connection, tx, [wallet, mintKeypair]);
-
-console.log(`Token created: ${mintKeypair.publicKey.toBase58()}`);
+const signature = await sendAndConfirmTransaction(connection, tx, [wallet]);
 ```
 
-The token is created with:
+## Holder Rewards
 
-- **Mint authority**: Revoked immediately after minting 1B tokens
-- **Freeze authority**: Never set (null from creation)
-- **Total supply**: 1,000,000,000 tokens (6 decimals)
-- **Metadata**: Created via Metaplex (update_authority = creator)
+Token holders earn a share of trading fees. The SDK handles claiming automatically.
 
-## Holder Rewards
+### Check Pending Rewards
+
+```typescript
+const pending = await sdk.getPendingHolderRewards(tokenMint, wallet.publicKey);
 
-### Claim Rewards from Bonding Curve
+if (pending) {
+	console.log(`Pending: ${Number(pending.pendingLamports) / 1e9} SOL`);
+	console.log(`Token balance: ${pending.tokenBalance}`);
+}
+```
+
+### Claim Rewards
 
 ```typescript
-const instructions = await sdk.buildClaimRewardsCurveInstruction(tokenMint, wallet.publicKey);
+const pending = await sdk.getPendingHolderRewards(tokenMint, wallet.publicKey);
 
-const tx = new Transaction().add(...instructions);
-const signature = await sendAndConfirmTransaction(connection, tx, [wallet]);
+if (pending && pending.pendingLamports > 0n) {
+	const instructions = await sdk.buildClaimInstructions(pending);
+	const tx = new Transaction().add(...instructions);
+	const signature = await sendAndConfirmTransaction(connection, tx, [wallet]);
+}
 ```
 
-### Claim Rewards from AMM Pool (Post-Graduation)
+### Claim Creator Trading Fees
+
+Token creators can claim their accumulated trading fee share:
 
 ```typescript
-const instructions = await sdk.buildClaimRewardsPoolInstruction(tokenMint, wallet.publicKey);
+import { buildClaimCreatorTraderFeesInstruction } from '@coinbarrel/sdk';
+
+const instructions = await buildClaimCreatorTraderFeesInstruction(
+	connection,
+	{ tokenMint, creator: wallet.publicKey },
+	sdk.programId
+);
 
 const tx = new Transaction().add(...instructions);
 const signature = await sendAndConfirmTransaction(connection, tx, [wallet]);
@@ -184,33 +218,50 @@ const signature = await sendAndConfirmTransaction(connection, tx, [wallet]);
 
 ## Market Info
 
-### Get Token Market State
-
 ```typescript
 const info = await sdk.getMarketInfo(tokenMint);
 
 if (info) {
-	console.log(`Phase: ${info.phase}`); // 'curve' or 'pool'
 	console.log(`Price: ${info.price} lamports/token`);
 	console.log(`Market Cap: ${info.marketCapSol} lamports`);
 	console.log(`Fee: ${info.feeBps / 100}%`);
+	console.log(`SOL reserve: ${info.solReserve}`);
+	console.log(`Token reserve: ${info.tokenReserve}`);
+	console.log(`Circulating supply: ${info.circulatingSupply}`);
 }
 ```
 
-### Check Token Phase
+## Token Metadata
+
+The SDK supports both Token2022 native metadata and Metaplex metadata. Use the universal methods to handle either automatically:
 
 ```typescript
-if (await sdk.isOnCurve(tokenMint)) {
-	// Use curve methods
-} else if (await sdk.isOnPool(tokenMint)) {
-	// Use pool methods
+// Auto-detects Token2022 vs SPL Token
+const metadata = await sdk.getUniversalTokenMetadata(tokenMint);
+if (metadata) {
+	console.log(metadata.name);   // "My Token"
+	console.log(metadata.symbol); // "MTK"
+	console.log(metadata.uri);    // "https://..."
 }
+
+// Full metadata including off-chain JSON (image, socials)
+const full = await sdk.getUniversalTokenMetadataJson(tokenMint);
+if (full) {
+	console.log(full.image);       // "https://..."
+	console.log(full.description); // "A cool token"
+	console.log(full.twitter);     // "@mytoken"
+	console.log(full.website);     // "https://..."
+}
+
+// Check if a token is Token2022
+const isT22 = await sdk.isToken2022Mint(tokenMint);
+
+// Batch fetch for multiple tokens
+const metadataMap = await sdk.batchGetTokenMetadata([mint1, mint2, mint3]);
 ```
 
 ## Networks
 
-The SDK supports both devnet and mainnet:
-
 ```typescript
 // Devnet
 const devnetSdk = new CoinBarrel({
@@ -231,90 +282,58 @@ const mainnetSdk = new CoinBarrel({
 import { solToLamports, lamportsToSol, toRawAmount, toUiAmount } from '@coinbarrel/sdk';
 
 // SOL conversions
-const lamports = solToLamports(1.5); // 1_500_000_000n
-const sol = lamportsToSol(1_500_000_000n); // 1.5
+const lamports = solToLamports(1.5);          // 1_500_000_000n
+const sol = lamportsToSol(1_500_000_000n);    // 1.5
 
 // Token amount conversions (default 6 decimals)
-const raw = toRawAmount(100); // 100_000_000n
-const ui = toUiAmount(100_000_000n); // 100
-```
-
-## Token Metadata
-
-Fetch token metadata from the Metaplex Token Metadata program:
-
-```typescript
-// Get on-chain metadata (fast - just name, symbol, uri)
-const metadata = await sdk.getTokenMetadata(tokenMint);
-if (metadata) {
-	console.log(metadata.name); // "My Token"
-	console.log(metadata.symbol); // "MTK"
-	console.log(metadata.uri); // "https://..."
-}
-
-// Get full metadata including off-chain JSON (image, socials)
-const fullMetadata = await sdk.getTokenMetadataJson(tokenMint);
-if (fullMetadata) {
-	console.log(fullMetadata.image); // "https://..." or "ipfs://..."
-	console.log(fullMetadata.description); // "A cool token"
-	console.log(fullMetadata.twitter); // "@mytoken"
-	console.log(fullMetadata.website); // "https://..."
-}
-
-// Batch fetch for multiple tokens (more efficient)
-const mints = [mint1, mint2, mint3];
-const metadataMap = await sdk.batchGetTokenMetadata(mints);
-for (const [mintStr, meta] of metadataMap) {
-	console.log(`${mintStr}: ${meta?.name}`);
-}
+const raw = toRawAmount(100);                 // 100_000_000n
+const ui = toUiAmount(100_000_000n);          // 100
 ```
 
-## PDA Helpers
+## Fee Structure
 
-```typescript
-// Get PDAs for a token
-const bondingCurve = sdk.getBondingCurvePda(tokenMint);
-const pool = sdk.getPoolPda(tokenMint);
-const holderReward = sdk.getHolderRewardPda(tokenMint, wallet.publicKey);
-const metadataPda = sdk.getMetadataPda(tokenMint); // Metaplex metadata PDA
-```
+Fees are enforced on-chain and cannot be bypassed:
 
-## Fee Structure
+- **Platform**: 50% of total fee (fixed)
+- **Holder rewards**: 0–50% of total fee (set at launch via `traderRewardsShareBps`)
+- **Creator**: remainder after platform + holders
+- **Burn** (optional): 0–50% of creator portion (set at launch via `burnFeeBps`)
 
-CoinBarrel fees are enforced at the program level and cannot be bypassed:
+The trading fee rate depends on the launch tier:
 
-- **1% total fee** on all trades
-- **50%** goes to CoinBarrel (protocol) - fixed
-- **25-40%** goes to holder rewards pool (of total fee, configured by token launcher via `trader_rewards_share_bps`)
-- **10-25%** goes to token creator (remainder: 50% - holder%)
+| Tier | Fee Rate |
+|------|----------|
+| Standard | 1.25% |
+| Premium | 5% |
 
-Example: If `trader_rewards_share_bps = 3000` (30%):
+Example with `traderRewardsShareBps = 3000` (30%) on a Standard tier (1.25% fee):
 
 - Platform: 50% of fee
 - Holders: 30% of fee
 - Creator: 20% of fee
 
-The split is set when the token is launched (`trader_rewards_share_bps` must be 2500-4000). The SDK reads fee recipients from on-chain state. Integrators cannot modify or bypass fees.
-
 ## TypeScript
 
 The SDK is fully typed:
 
 ```typescript
 import type {
-	BondingCurveState,
-	PoolState,
 	MarketInfo,
-	BuyQuote,
-	SellQuote,
 	SwapQuote,
+	PoolState,
 	Network,
 	TokenMetadata,
 	TokenMetadataJson,
-	CreateBarrelTokenParams,
-	ClaimHolderRewardsParams,
-	ClaimHolderRewardsCurveParams,
+	CreateInstantTokenV2Params,
+	InstantTokenV2State,
+	SwapSolToTokenParams,
+	SwapTokenToSolParams,
+	SwapTokenToSolMaxParams,
+	PendingHolderRewards,
+	FeeRecipient,
 } from '@coinbarrel/sdk';
+
+import { InstantTokenVariant, LaunchTier } from '@coinbarrel/sdk';
 ```
 
 ## License

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@coinbarrel/sdk",
-	"version": "3.2.6",
-	"description": "SDK for CoinBarrel AMM - bonding curves and liquidity pools on Solana",
+	"version": "3.2.7",
+	"description": "SDK for launching and trading tokens on CoinBarrel - instant Meteora DAMM V2 pools on Solana",
 	"author": "CoinBarrel",
 	"license": "MIT",
 	"type": "module",