@coinbarrel/sdk 1.1.0 → 1.3.0

package/README.md

@@ -1,253 +1,305 @@
-# @coinbarrel/sdk
-
-SDK for integrating with CoinBarrel AMM - bonding curves and liquidity pools on Solana.
-
-## Installation
-
-```bash
-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';
-
-// 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)
-
-### Get Buy Quote
-
-```typescript
-const quote = await sdk.curve.getBuyQuote(
-	tokenMint,
-	solToLamports(0.1) // 0.1 SOL
-);
-
-if (quote) {
-	console.log(`Tokens out: ${quote.tokensOut}`);
-	console.log(`Price impact: ${quote.priceImpactBps / 100}%`);
-}
-```
-
-### Buy Tokens
-
-```typescript
-import { Transaction, sendAndConfirmTransaction } from '@solana/web3.js';
-
-const instructions = await sdk.curve.buildBuyInstruction({
-	tokenMint,
-	buyer: wallet.publicKey,
-	lamportsIn: solToLamports(0.1),
-});
-
-const tx = new Transaction().add(...instructions);
-const signature = await sendAndConfirmTransaction(connection, tx, [wallet]);
-```
-
-### Sell Tokens
-
-```typescript
-const instructions = await sdk.curve.buildSellInstruction({
-	tokenMint,
-	seller: wallet.publicKey,
-	tokenAmount: BigInt(1_000_000), // 1 token (6 decimals)
-});
-
-// Or sell entire balance
-const sellMaxIx = await sdk.curve.buildSellMaxInstruction({
-	tokenMint,
-	seller: wallet.publicKey,
-});
-```
-
-## AMM Pool Trading (Post-Graduation)
-
-### Get Swap Quote
-
-```typescript
-const quote = await sdk.pool.getSwapSolToTokenQuote(
-	tokenMint,
-	solToLamports(1.0) // 1 SOL
-);
-
-if (quote) {
-	console.log(`Tokens out: ${quote.amountOut}`);
-	console.log(`Fee: ${quote.fee} lamports`);
-}
-```
-
-### Swap SOL for Tokens
-
-```typescript
-const instructions = await sdk.pool.buildSwapSolToTokenInstruction({
-	tokenMint,
-	user: wallet.publicKey,
-	lamportsIn: solToLamports(1.0),
-	minimumAmountOut: BigInt(900_000), // Slippage protection
-});
-```
-
-### Swap Tokens for SOL
-
-```typescript
-const instructions = await sdk.pool.buildSwapTokenToSolInstruction({
-	tokenMint,
-	user: wallet.publicKey,
-	amountIn: BigInt(1_000_000),
-	minimumLamportsOut: solToLamports(0.09),
-});
-
-// Or sell entire balance
-const sellMaxIx = await sdk.pool.buildSwapTokenToSolMaxInstruction({
-	tokenMint,
-	user: wallet.publicKey,
-});
-```
-
-## 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}%`);
-}
-```
-
-### Check Token Phase
-
-```typescript
-if (await sdk.isOnCurve(tokenMint)) {
-	// Use curve methods
-} else if (await sdk.isOnPool(tokenMint)) {
-	// Use pool methods
-}
-```
-
-## Networks
-
-The SDK supports both devnet and mainnet:
-
-```typescript
-// Devnet
-const devnetSdk = new CoinBarrel({
-	connection: new Connection('https://api.devnet.solana.com'),
-	network: 'devnet',
-});
-
-// Mainnet
-const mainnetSdk = new CoinBarrel({
-	connection: new Connection('https://api.mainnet-beta.solana.com'),
-	network: 'mainnet',
-});
-```
-
-## Utility Functions
-
-```typescript
-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
-
-// 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}`);
-}
-```
-
-## PDA Helpers
-
-```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
-```
-
-## Fee Structure
-
-CoinBarrel fees are enforced at the program level and cannot be bypassed:
-
-- **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%)
-
-Example: If `trader_rewards_share_bps = 3000` (30%):
-
-- 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,
-	Network,
-	TokenMetadata,
-	TokenMetadataJson,
-} from '@coinbarrel/sdk';
-```
-
-## License
-
-MIT
+# @coinbarrel/sdk
+
+SDK for integrating with CoinBarrel AMM - bonding curves and liquidity pools on Solana.
+
+## Installation
+
+```bash
+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';
+
+// 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)
+
+### Get Buy Quote
+
+```typescript
+const quote = await sdk.curve.getBuyQuote(
+	tokenMint,
+	solToLamports(0.1) // 0.1 SOL
+);
+
+if (quote) {
+	console.log(`Tokens out: ${quote.tokensOut}`);
+	console.log(`Price impact: ${quote.priceImpactBps / 100}%`);
+}
+```
+
+### Buy Tokens
+
+```typescript
+import { Transaction, sendAndConfirmTransaction } from '@solana/web3.js';
+
+const instructions = await sdk.curve.buildBuyInstruction({
+	tokenMint,
+	buyer: wallet.publicKey,
+	lamportsIn: solToLamports(0.1),
+});
+
+const tx = new Transaction().add(...instructions);
+const signature = await sendAndConfirmTransaction(connection, tx, [wallet]);
+```
+
+### Sell Tokens
+
+```typescript
+const instructions = await sdk.curve.buildSellInstruction({
+	tokenMint,
+	seller: wallet.publicKey,
+	tokenAmount: BigInt(1_000_000), // 1 token (6 decimals)
+});
+
+// Or sell entire balance
+const sellMaxIx = await sdk.curve.buildSellMaxInstruction({
+	tokenMint,
+	seller: wallet.publicKey,
+});
+```
+
+## AMM Pool Trading (Post-Graduation)
+
+### Get Swap Quote
+
+```typescript
+const quote = await sdk.pool.getSwapSolToTokenQuote(
+	tokenMint,
+	solToLamports(1.0) // 1 SOL
+);
+
+if (quote) {
+	console.log(`Tokens out: ${quote.amountOut}`);
+	console.log(`Fee: ${quote.fee} lamports`);
+}
+```
+
+### Swap SOL for Tokens
+
+```typescript
+const instructions = await sdk.pool.buildSwapSolToTokenInstruction({
+	tokenMint,
+	user: wallet.publicKey,
+	lamportsIn: solToLamports(1.0),
+	minimumAmountOut: BigInt(900_000), // Slippage protection
+});
+```
+
+### Swap Tokens for SOL
+
+```typescript
+const instructions = await sdk.pool.buildSwapTokenToSolInstruction({
+	tokenMint,
+	user: wallet.publicKey,
+	amountIn: BigInt(1_000_000),
+	minimumLamportsOut: solToLamports(0.09),
+});
+
+// Or sell entire balance
+const sellMaxIx = await sdk.pool.buildSwapTokenToSolMaxInstruction({
+	tokenMint,
+	user: wallet.publicKey,
+});
+```
+
+## Token Creation
+
+### Create a New Token
+
+```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)
+});
+
+// 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()}`);
+```
+
+The token is created with:
+
+- **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)
+
+## Holder Rewards
+
+### Claim Rewards from Bonding Curve
+
+```typescript
+const instructions = await sdk.buildClaimRewardsCurveInstruction(tokenMint, wallet.publicKey);
+
+const tx = new Transaction().add(...instructions);
+const signature = await sendAndConfirmTransaction(connection, tx, [wallet]);
+```
+
+### Claim Rewards from AMM Pool (Post-Graduation)
+
+```typescript
+const instructions = await sdk.buildClaimRewardsPoolInstruction(tokenMint, wallet.publicKey);
+
+const tx = new Transaction().add(...instructions);
+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}%`);
+}
+```
+
+### Check Token Phase
+
+```typescript
+if (await sdk.isOnCurve(tokenMint)) {
+	// Use curve methods
+} else if (await sdk.isOnPool(tokenMint)) {
+	// Use pool methods
+}
+```
+
+## Networks
+
+The SDK supports both devnet and mainnet:
+
+```typescript
+// Devnet
+const devnetSdk = new CoinBarrel({
+	connection: new Connection('https://api.devnet.solana.com'),
+	network: 'devnet',
+});
+
+// Mainnet
+const mainnetSdk = new CoinBarrel({
+	connection: new Connection('https://api.mainnet-beta.solana.com'),
+	network: 'mainnet',
+});
+```
+
+## Utility Functions
+
+```typescript
+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
+
+// 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}`);
+}
+```
+
+## PDA Helpers
+
+```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
+```
+
+## Fee Structure
+
+CoinBarrel fees are enforced at the program level and cannot be bypassed:
+
+- **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%)
+
+Example: If `trader_rewards_share_bps = 3000` (30%):
+
+- 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,
+	Network,
+	TokenMetadata,
+	TokenMetadataJson,
+	CreateBarrelTokenParams,
+	ClaimHolderRewardsParams,
+	ClaimHolderRewardsCurveParams,
+} from '@coinbarrel/sdk';
+```
+
+## License
+
+MIT