@solsdk/tokenflow_sdk/README.md

A simple SDK for interacting with tokenflow

# @solsdk/tokenflow_sdk SDK

## Overview

@solsdk/tokenflow_sdk SDK is a robust and secure toolkit for interacting with decentralized applications on the Solana blockchain. It provides a simple and type-safe interface for creating, buying, and selling tokens, as well as subscribing to on-chain events. Designed for developers who value reliability, security, and best practices, @solsdk/tokenflow_sdk SDK streamlines Solana token operations for both beginners and professionals.

## Features

- Create, buy, and sell tokens with a single call
- Full support for Solana's latest standards
- Event subscription for real-time updates (createEvent, tradeEvent, completeEvent, setGlobalCfgEvent)
- Strict TypeScript typings (no `any`, no type assertions)
- Bonding curve configuration management
- Automatic metadata upload to IPFS
- Priority fee support for faster transaction processing
- Follows KISS, DRY, YAGNI, SOLID, and other best practices
- Actively maintained and open to contributions

## Installation

```bash
npm install @solsdk/tokenflow_sdk
# or
yarn add @solsdk/tokenflow_sdk
# or
pnpm add @solsdk/tokenflow_sdk
```

## Imports

The SDK provides multiple import options for different use cases:

### Main SDK Class

```typescript
import { HappyPumpSDK } from "@solsdk/tokenflow_sdk";
```

### Types and Interfaces

```typescript
import type {
  CreateTokenMetadata,
  PriorityFee,
  TransactionResult,
  CreateEvent,
  TradeEvent,
  CompleteEvent,
  SetGlobalCfgEvent,
} from "@solsdk/tokenflow_sdk";
```

### Utility Functions

```typescript
import {
  calculateWithSlippageBuy,
  calculateWithSlippageSell,
  buildVersionedTx,
  sendTx,
  getTxDetails,
} from "@solsdk/tokenflow_sdk";
```

### Constants

```typescript
import {
  DEFAULT_DECIMALS,
  DEFAULT_COMMITMENT,
  DEFAULT_FINALITY,
  GLOBAL_ACCOUNT_SEED,
  MINT_AUTHORITY_SEED,
  BONDING_CURVE_SEED,
  METADATA_SEED,
} from "@solsdk/tokenflow_sdk";
```

### Account Classes

```typescript
import { GlobalAccount, BondingCurveAccount, AMM } from "@solsdk/tokenflow_sdk";
```

### Event Processing Functions

```typescript
import {
  toCreateEvent,
  toTradeEvent,
  toCompleteEvent,
  toSetGlobalCfgEvent,
} from "@solsdk/tokenflow_sdk";
```

## Quick Start

1. Create a `.env` file and set your Solana RPC URL (see `.env.example` for reference).
2. Fund your test account with at least 0.004 SOL.

### Example Usage

```typescript
import dotenv from "dotenv";
import {
  Connection,
  Keypair,
  LAMPORTS_PER_SOL,
  PublicKey,
} from "@solana/web3.js";
import { HappyPumpSDK } from "@solsdk/tokenflow_sdk";
import { AnchorProvider } from "@coral-xyz/anchor";
import NodeWallet from "@coral-xyz/anchor/dist/cjs/nodewallet";

dotenv.config();

const SLIPPAGE_BASIS_POINTS = 500n; // Default slippage

const getProvider = () => {
  if (!process.env.SOLANA_RPC_URL) {
    throw new Error("Please set SOLANA_RPC_URL in your .env file");
  }
  const connection = new Connection(process.env.SOLANA_RPC_URL);
  const wallet = new NodeWallet(new Keypair());
  return new AnchorProvider(connection, wallet, { commitment: "finalized" });
};

const main = async () => {
  const provider = getProvider();
  const sdk = new HappyPumpSDK(provider);

  const creator = Keypair.generate();
  const mint = Keypair.generate();
  const tradeAuthority = Keypair.generate(); // Optional trade authority

  // Create a file blob for the token image
  const imageFile = new Blob(
    [
      /* your image data */
    ],
    { type: "image/png" }
  );

  // Example: Create and buy a new token
  const tokenMetadata = {
    name: "EXAMPLE",
    symbol: "EXMPL",
    description: "Example token for demonstration",
    file: imageFile, // Must be a Blob object
    twitter: "https://twitter.com/example", // Optional
    telegram: "https://t.me/example", // Optional
    website: "https://example.com", // Optional
  };

  const result = await sdk.createAndBuy(
    creator,
    mint,
    tokenMetadata,
    BigInt(0.0001 * LAMPORTS_PER_SOL),
    SLIPPAGE_BASIS_POINTS,
    tradeAuthority, // Optional
    {
      unitLimit: 250_000,
      unitPrice: 250_000,
    }
  );

  if (result.success) {
    console.log("Token created and purchased successfully!");
    console.log("Transaction signature:", result.signature);
  } else {
    console.error("Operation failed:", result.error);
  }
};

main();
```

## API Reference

### Core Methods

#### `create`

Creates a new token without purchasing it.

```typescript
async create(
  creator: Keypair,
  mint: Keypair,
  createTokenMetadata: CreateTokenMetadata,
  tradeAuthority?: Keypair,
  priorityFees?: PriorityFee,
  commitment?: Commitment,
  finality?: Finality
): Promise<TransactionResult>
```

#### `createAndBuy`

Creates a new token and immediately purchases it.

```typescript
async createAndBuy(
  creator: Keypair,
  mint: Keypair,
  createTokenMetadata: CreateTokenMetadata,
  buyAmountSol: bigint,
  slippageBasisPoints: bigint = 500n,
  tradeAuthority?: Keypair,
  priorityFees?: PriorityFee,
  commitment?: Commitment,
  finality?: Finality
): Promise<TransactionResult>
```

#### `buy`

Purchases tokens for a given mint.

```typescript
async buy(
  buyer: Keypair,
  mint: Keypair,
  buyAmountSol: bigint,
  slippageBasisPoints: bigint = 500n,
  tradeAuthority?: Keypair,
  priorityFees?: PriorityFee,
  commitment?: Commitment,
  finality?: Finality
): Promise<TransactionResult>
```

#### `sell`

Sells a specified amount of tokens.

```typescript
async sell(
  seller: Keypair,
  mint: Keypair,
  sellTokenAmount: bigint,
  slippageBasisPoints: bigint = 500n,
  priorityFees?: PriorityFee,
  commitment?: Commitment,
  finality?: Finality
): Promise<TransactionResult>
```

#### `setBondingCurveCfg`

Configures bonding curve settings for a token.

```typescript
async setBondingCurveCfg(
  user: Keypair,
  mint: PublicKey,
  tradeAuthority: PublicKey,
  priorityFees?: PriorityFee,
  commitment?: Commitment,
  finality?: Finality
): Promise<TransactionResult>
```

### Account Management

#### `getGlobalAccount`

Retrieves the global account configuration.

```typescript
async getGlobalAccount(commitment?: Commitment): Promise<GlobalAccount>
```

#### `getBondingCurveAccount`

Retrieves bonding curve account data for a specific mint.

```typescript
async getBondingCurveAccount(
  mint: PublicKey,
  commitment?: Commitment
): Promise<BondingCurveAccount | undefined>
```

#### `getBondingCurvePDA`

Generates the Program Derived Address for a bonding curve.

```typescript
getBondingCurvePDA(mint: PublicKey): PublicKey
```

### Event Subscription

Subscribe to on-chain events for real-time updates.

```typescript
// Available event types: 'createEvent', 'tradeEvent', 'completeEvent', 'setGlobalCfgEvent'
const eventId = sdk.addEventListener("tradeEvent", (event, slot, signature) => {
  console.log("Trade event:", event, slot, signature);
  console.log("Token amount:", event.tokenAmount);
  console.log("SOL amount:", event.solAmount);
  console.log("Is buy:", event.isBuy);
});

// Subscribe to token creation events
const createEventId = sdk.addEventListener(
  "createEvent",
  (event, slot, signature) => {
    console.log("New token created:", event.name, event.symbol);
    console.log("Mint address:", event.mint.toString());
  }
);

// Subscribe to bonding curve completion events
const completeEventId = sdk.addEventListener(
  "completeEvent",
  (event, slot, signature) => {
    console.log("Bonding curve completed for mint:", event.mint.toString());
  }
);

// To remove listeners:
sdk.removeEventListener(eventId);
sdk.removeEventListener(createEventId);
sdk.removeEventListener(completeEventId);
```

## Types and Interfaces

### `CreateTokenMetadata`

Metadata structure for creating new tokens.

```typescript
type CreateTokenMetadata = {
  name: string;
  symbol: string;
  description: string;
  file: Blob; // Image file as Blob object
  twitter?: string; // Optional Twitter URL
  telegram?: string; // Optional Telegram URL
  website?: string; // Optional website URL
};
```

### `PriorityFee`

Priority fee configuration for faster transaction processing.

```typescript
type PriorityFee = {
  unitLimit: number; // Compute unit limit
  unitPrice: number; // Price per compute unit in micro-lamports
};
```

### `TransactionResult`

Result object returned by all transaction methods.

```typescript
type TransactionResult = {
  signature?: string; // Transaction signature if successful
  error?: unknown; // Error object if failed
  results?: VersionedTransactionResponse; // Full transaction response
  success: boolean; // Whether transaction succeeded
};
```

### Event Types

#### `CreateEvent`

```typescript
type CreateEvent = {
  name: string;
  symbol: string;
  uri: string;
  mint: PublicKey;
  bondingCurve: PublicKey;
  user: PublicKey;
  tradeAuthority?: PublicKey;
  timestamp: number;
  virtualTokenReserves: bigint;
  virtualSolReserves: bigint;
  realTokenReserves: bigint;
  realSolReserves: bigint;
};
```

#### `TradeEvent`

```typescript
type TradeEvent = {
  mint: PublicKey;
  solAmount: bigint;
  tokenAmount: bigint;
  isBuy: boolean;
  user: PublicKey;
  timestamp: number;
  virtualSolReserves: bigint;
  virtualTokenReserves: bigint;
  realSolReserves: bigint;
  realTokenReserves: bigint;
};
```

#### `CompleteEvent`

```typescript
type CompleteEvent = {
  user: PublicKey;
  mint: PublicKey;
  bondingCurve: PublicKey;
  timestamp: number;
};
```

## Utility Functions

The SDK exports several utility functions for common operations:

### `calculateWithSlippageBuy`

Calculates buy amount with slippage protection.

```typescript
function calculateWithSlippageBuy(amount: bigint, basisPoints: bigint): bigint;
```

### `calculateWithSlippageSell`

Calculates sell amount with slippage protection.

```typescript
function calculateWithSlippageSell(amount: bigint, basisPoints: bigint): bigint;
```

### `buildVersionedTx`

Builds a versioned transaction from instructions.

```typescript
function buildVersionedTx(
  connection: Connection,
  payer: PublicKey,
  instructions: TransactionInstruction[],
  commitment?: Commitment
): Promise<VersionedTransaction>;
```

### `sendTx`

Sends a transaction with proper error handling.

```typescript
function sendTx(
  connection: Connection,
  instructions: TransactionInstruction[],
  payer: PublicKey,
  signers: Keypair[],
  priorityFees?: PriorityFee,
  commitment?: Commitment,
  finality?: Finality
): Promise<TransactionResult>;
```

## Constants

The SDK exports several useful constants:

```typescript
// Program seeds
export const GLOBAL_ACCOUNT_SEED = "global";
export const MINT_AUTHORITY_SEED = "mint-authority";
export const BONDING_CURVE_SEED = "bonding-curve";
export const METADATA_SEED = "metadata";

// Default values
export const DEFAULT_DECIMALS = 6;
export const DEFAULT_COMMITMENT = "finalized";
export const DEFAULT_FINALITY = "finalized";
```

## Complete Usage Examples

### Creating a Token Only

```typescript
import { HappyPumpSDK } from "@solsdk/tokenflow_sdk";
import { Keypair, LAMPORTS_PER_SOL } from "@solana/web3.js";

const creator = Keypair.generate();
const mint = Keypair.generate();
const imageFile = new Blob(
  [
    /* image data */
  ],
  { type: "image/png" }
);

const metadata = {
  name: "My Token",
  symbol: "MTK",
  description: "A sample token",
  file: imageFile,
  website: "https://mytoken.com",
};

const result = await sdk.create(
  creator,
  mint,
  metadata,
  undefined, // No trade authority
  { unitLimit: 200_000, unitPrice: 200_000 }
);
```

### Buying Existing Tokens

```typescript
const buyer = Keypair.generate();
const mintKeypair = Keypair.fromSecretKey(/* existing mint secret key */);

const result = await sdk.buy(
  buyer,
  mintKeypair,
  BigInt(0.001 * LAMPORTS_PER_SOL), // Buy with 0.001 SOL
  300n, // 3% slippage
  undefined, // No trade authority
  { unitLimit: 150_000, unitPrice: 150_000 }
);
```

### Selling Tokens

```typescript
const seller = Keypair.generate();
const mintKeypair = Keypair.fromSecretKey(/* mint secret key */);
const tokenAmount = BigInt(1000000); // Amount of tokens to sell

const result = await sdk.sell(
  seller,
  mintKeypair,
  tokenAmount,
  500n, // 5% slippage
  { unitLimit: 150_000, unitPrice: 150_000 }
);
```

## Security & Best Practices

### Type Safety

- All operations are strictly type-checked with TypeScript
- No use of `any` or type assertions in the SDK
- Comprehensive type definitions for all parameters and return values

### Transaction Security

- Always validate transaction results using the `success` property
- Handle errors gracefully using the `error` property in `TransactionResult`
- Use appropriate slippage settings to protect against MEV attacks
- Set reasonable priority fees to ensure transaction inclusion

### Key Management

- Never expose private keys in client-side code
- Use environment variables for sensitive configuration
- Generate new keypairs for testing, never reuse production keys

### File Handling

- Always pass image files as `Blob` objects to `CreateTokenMetadata`
- Validate file types and sizes before uploading
- The SDK automatically uploads metadata to IPFS

### Best Practices

- Use appropriate commitment levels (`finalized` for production)
- Monitor transaction confirmations using the returned signatures
- Implement proper error handling for network failures
- Test thoroughly on devnet before mainnet deployment
- Follow Solana's official documentation and standards

### Performance Optimization

- Reuse SDK instances when possible
- Use batch operations for multiple transactions
- Set appropriate compute unit limits in priority fees
- Monitor and adjust slippage based on market conditions

## Contributing

Contributions are welcome! Please open an issue or submit a pull request to discuss improvements or new features.

## License

MIT

---

## Disclaimer

This software is provided "as is," without warranty of any kind, express or implied. Use at your own risk. The authors are not responsible for any damages or losses resulting from the use of this software. By using this SDK, you acknowledge that you have read and understood this disclaimer.

---

By following this guide, you can quickly integrate @solsdk/tokenflow_sdk SDK into your Solana projects and benefit from a secure, developer-friendly toolkit for token operations and event handling.