@beluswap/sdk 0.1.0

package/README.md

@@ -0,0 +1,292 @@
+# BeluSwap SDK
+
+Human-friendly TypeScript SDK for BeluSwap concentrated liquidity AMM on Stellar.
+
+## Why BeluSwap SDK?
+
+**No more manual conversions!** Use normal numbers instead of:
+- ❌ Converting amounts to stroops (7 decimals)
+- ❌ Calculating sqrt_price_x64 in Q64.64 format
+- ❌ Converting prices to ticks
+- ❌ Aligning ticks to spacing
+- ❌ Converting days to ledgers
+- ❌ Converting percentages to basis points
+
+✅ **Just use human-readable inputs!**
+
+## Installation
+
+```bash
+npm install @beluswap/sdk
+```
+
+## Quick Start
+
+```typescript
+import BeluSwapSDK from '@beluswap/sdk';
+
+// Initialize SDK
+const sdk = new BeluSwapSDK({
+  factoryAddress: 'CFACTORY...',
+  network: 'testnet', // or 'mainnet'
+});
+
+// Create pool with NORMAL numbers!
+const pool = await sdk.factory.createPool({
+  creator: 'GCREATOR...',
+  tokenA: 'CDUSDC...',
+  tokenB: 'CDXLM...',
+  feeTier: 'VOLATILE',           // Not 30 bps!
+  creatorFeePercent: 1,          // 1%, not 100 bps!
+  initialPrice: 1.0,             // Normal price!
+  amount0: 100,                  // 100 tokens, not stroops!
+  amount1: 100,
+  priceRangeLower: 0.95,         // Normal price range!
+  priceRangeUpper: 1.05,
+  lockDurationDays: 7,           // Days, not ledgers!
+});
+
+console.log(pool.summary);
+// {
+//   pair: "CDUSDC.../CDXLM...",
+//   fee: "0.3%",
+//   initialPrice: 1,
+//   priceRange: "0.95 - 1.05",
+//   amounts: "100 + 100",
+//   lockDuration: "7 days"
+// }
+```
+
+## Features
+
+### ✅ Human-Friendly Inputs
+- Normal prices (1.0, 2.5) instead of sqrt_price_x64
+- Normal amounts (100, 500) instead of stroops
+- Percentages (1% slippage) instead of basis points
+- Days for lock duration instead of ledgers
+- Fee tier names ('VOLATILE') instead of numbers
+
+### ✅ Complete Integration
+- **Factory SDK**: Create pools
+- **Pool SDK**: Add/remove liquidity, swap, collect fees
+- **Automatic Conversions**: All technical formats handled
+
+### ✅ Type-Safe
+- Full TypeScript support
+- Autocomplete for all parameters
+- Compile-time error checking
+
+## Usage Examples
+
+### 1. Initialize SDK
+
+```typescript
+import BeluSwapSDK from '@beluswap/sdk';
+
+// Option A: Use predefined network
+const sdk = new BeluSwapSDK({
+  factoryAddress: 'CFACTORY...',
+  network: 'testnet', // or 'mainnet'
+});
+
+// Option B: Custom network
+const sdk = new BeluSwapSDK({
+  factoryAddress: 'CFACTORY...',
+  rpcUrl: 'https://your-rpc-url',
+  networkPassphrase: 'Your Network ; Passphrase',
+});
+```
+
+### 2. Add Liquidity
+
+```typescript
+// Connect to pool
+const pool = await sdk.getAndConnectPool({
+  tokenA: 'CDUSDC...',
+  tokenB: 'CDXLM...',
+  feeTier: 'VOLATILE',
+});
+
+// Add liquidity with normal numbers!
+const addLiq = await pool.addLiquidity({
+  owner: 'GOWNER...',
+  amount0: 50,                   // 50 tokens!
+  amount1: 50,
+  priceRangeLower: 0.95,         // Normal prices!
+  priceRangeUpper: 1.05,
+  feeTier: 'VOLATILE',
+});
+
+console.log(addLiq.summary);
+// { priceRange: "0.9500 - 1.0500", amounts: "50 + 50" }
+```
+
+### 3. Execute Swap
+
+```typescript
+const swap = await pool.swap({
+  sender: 'GTRADER...',
+  tokenIn: 'USDC',
+  amountIn: 10,                  // Normal amount!
+  slippagePercent: 1,            // 1%, not 100 bps!
+  priceLimit: 0.95,              // Optional
+});
+
+console.log(swap.summary);
+// {
+//   swapping: "10 USDC",
+//   estimatedOutput: "~9.9700",
+//   minimumOutput: "9.9003",
+//   slippage: "1%"
+// }
+```
+
+### 4. Check Position
+
+```typescript
+const position = await pool.getPosition({
+  owner: 'GOWNER...',
+  priceRangeLower: 0.95,
+  priceRangeUpper: 1.05,
+  feeTier: 'VOLATILE',
+});
+
+console.log(position);
+// {
+//   amount0: 100,        // Human-readable!
+//   amount1: 100,
+//   feesOwed0: 0.5,
+//   feesOwed1: 0.5
+// }
+```
+
+## API Reference
+
+### BeluSwapSDK
+
+Main SDK class.
+
+#### Constructor
+
+```typescript
+new BeluSwapSDK(config: {
+  factoryAddress: string;
+  poolAddress?: string;
+  network?: 'testnet' | 'mainnet';
+  rpcUrl?: string;
+  networkPassphrase?: string;
+})
+```
+
+#### Properties
+
+- `factory: BelugaFactorySDK` - Factory operations
+- `pool?: BelugaPoolSDK` - Pool operations (if connected)
+
+#### Methods
+
+- `connectPool(address: string): BelugaPoolSDK` - Connect to specific pool
+- `getAndConnectPool(params): Promise<BelugaPoolSDK>` - Get and connect pool
+
+---
+
+### BelugaFactorySDK
+
+Factory operations for pool creation.
+
+#### Methods
+
+##### `createPool(params): Promise<CreatePoolResult>`
+
+Create a new pool.
+
+**Parameters:**
+- `creator: string` - Creator address
+- `tokenA: string` - Token A address
+- `tokenB: string` - Token B address
+- `feeTier: 'STABLE' | 'VOLATILE' | 'EXOTIC'` - Fee tier
+- `creatorFeePercent: number` - Creator fee (0.1-10%)
+- `initialPrice: number` - Initial price
+- `amount0: number` - Initial token0 amount
+- `amount1: number` - Initial token1 amount
+- `priceRangeLower: number` - Lower price bound
+- `priceRangeUpper: number` - Upper price bound
+- `lockDurationDays?: number` - Lock duration in days
+- `permanent?: boolean` - Permanent lock?
+
+**Returns:** Object with `summary`, `contractParams`, and `technical` details.
+
+##### `getPool(params): Promise<string | null>`
+
+Get pool address.
+
+##### `poolExists(params): Promise<boolean>`
+
+Check if pool exists.
+
+---
+
+### BelugaPoolSDK
+
+Pool operations for liquidity and swaps.
+
+#### Methods
+
+##### `addLiquidity(params): Promise<AddLiquidityResult>`
+
+Add liquidity to pool.
+
+##### `removeLiquidity(params)`
+
+Remove liquidity from pool.
+
+##### `swap(params): Promise<SwapResult>`
+
+Execute a swap.
+
+##### `previewSwap(params): Promise<PreviewSwapResult>`
+
+Preview swap output (read-only, no gas).
+
+##### `getPosition(params): Promise<PositionInfo>`
+
+Get position information.
+
+##### `collectFees(params)`
+
+Collect accumulated fees.
+
+##### `getPoolState(): Promise<PoolState>`
+
+Get current pool state.
+
+---
+
+## Fee Tiers
+
+Three predefined fee tiers:
+
+| Tier | Fee | Tick Spacing | Use Case |
+|------|-----|--------------|----------|
+| STABLE | 0.05% | 10 | Stablecoin pairs |
+| VOLATILE | 0.30% | 60 | Normal volatile pairs |
+| EXOTIC | 1.00% | 200 | Exotic/meme tokens |
+
+## Examples
+
+See [examples/](examples/) directory for complete examples:
+- `create-pool.ts` - Create a new pool
+- `add-liquidity.ts` - Add liquidity to pool
+- `swap.ts` - Execute swaps
+- `monitor-position.ts` - Monitor position value
+
+
+## License
+
+Apache 2.0
+
+## Support
+
+- GitHub Issues: [github.com/Beluga-Swap/sdk/issues](https://github.com/Beluga-Swap/sdk/issues)
+- Discord: [discord.gg/belugaswap](https://discord.gg/belugaswap)
+- Email: support@beluswap.io

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@beluswap/sdk",
+  "version": "0.1.0",
+  "description": "BelugaSwap TypeScript SDK with human-friendly inputs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepublish": "npm run clean && npm run build",
+    "test": "jest",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\""
+  },
+  "keywords": [
+    "belugaswap",
+    "stellar",
+    "soroban",
+    "dex",
+    "amm",
+    "concentrated-liquidity",
+    "sdk",
+    "typescript"
+  ],
+  "author": "BelugaSwap Team",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Beluga-Swap/sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Beluga-Swap/sdk/issues"
+  },
+  "homepage": "https://github.com/Beluga-Swap/sdk#readme",
+  "dependencies": {
+    "@stellar/stellar-sdk": "^12.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.0.0",
+    "prettier": "^3.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,82 @@
+// src/config.ts
+// BelugaSwap SDK Configuration
+
+/**
+ * SDK Configuration Constants
+ */
+export const BELUGA_CONFIG = {
+  // Stellar stroops (7 decimals)
+  STROOPS_DECIMALS: 7,
+  STROOPS_MULTIPLIER: 10_000_000,
+  
+  // Q64.64 format
+  Q64: BigInt(2) ** BigInt(64),
+  ONE_X64: BigInt(2) ** BigInt(64), // 18446744073709551616
+  
+  // Tick constants
+  MIN_TICK: -887272,
+  MAX_TICK: 887272,
+  TICK_BASE: 1.0001,
+  
+  // Fee tiers
+  FEE_TIERS: {
+    STABLE: {
+      name: 'STABLE' as const,
+      bps: 5,
+      spacing: 10,
+      percent: 0.05,
+      description: 'For stablecoin pairs (0.05% fee)',
+    },
+    VOLATILE: {
+      name: 'VOLATILE' as const,
+      bps: 30,
+      spacing: 60,
+      percent: 0.30,
+      description: 'For volatile pairs (0.30% fee)',
+    },
+    EXOTIC: {
+      name: 'EXOTIC' as const,
+      bps: 100,
+      spacing: 200,
+      percent: 1.00,
+      description: 'For exotic/meme pairs (1.00% fee)',
+    },
+  },
+  
+  // Validation limits
+  MIN_LOCK_DURATION_LEDGERS: 120_960, // ~7 days
+  MIN_INITIAL_LIQUIDITY: 1_000_000,   // 0.1 tokens
+  MIN_CREATOR_FEE_BPS: 10,             // 0.1%
+  MAX_CREATOR_FEE_BPS: 1000,           // 10%
+  MAX_SLIPPAGE_BPS: 5000,              // 50%
+} as const;
+
+/**
+ * Fee tier type
+ */
+export type FeeTier = keyof typeof BELUGA_CONFIG.FEE_TIERS;
+
+/**
+ * Network configuration
+ */
+export interface NetworkConfig {
+  rpcUrl: string;
+  networkPassphrase: string;
+  name?: string;
+}
+
+/**
+ * Predefined networks
+ */
+export const NETWORKS = {
+  TESTNET: {
+    rpcUrl: 'https://soroban-testnet.stellar.org',
+    networkPassphrase: 'Test SDF Network ; September 2015',
+    name: 'Testnet',
+  },
+  MAINNET: {
+    rpcUrl: 'https://soroban-mainnet.stellar.org',
+    networkPassphrase: 'Public Global Stellar Network ; September 2015',
+    name: 'Mainnet',
+  },
+} as const;

package/src/converters.ts

@@ -0,0 +1,153 @@
+// src/converters.ts
+// Core conversion utilities
+
+import { BELUGA_CONFIG } from './config';
+
+/**
+ * Price Converters
+ */
+export class PriceConverter {
+  /**
+   * Convert human price to sqrt_price_x64
+   */
+  static toSqrtPrice(price: number): bigint {
+    if (price <= 0) throw new Error("Price must be positive");
+    const sqrtPrice = Math.sqrt(price);
+    return BigInt(Math.floor(sqrtPrice * Number(BELUGA_CONFIG.Q64)));
+  }
+  
+  /**
+   * Convert sqrt_price_x64 to human price
+   */
+  static fromSqrtPrice(sqrtPriceX64: bigint): number {
+    const sqrtPrice = Number(sqrtPriceX64) / Number(BELUGA_CONFIG.Q64);
+    return sqrtPrice * sqrtPrice;
+  }
+  
+  /**
+   * Format price for display
+   */
+  static format(sqrtPriceX64: bigint, decimals: number = 6): string {
+    const price = this.fromSqrtPrice(sqrtPriceX64);
+    return price.toFixed(decimals);
+  }
+}
+
+/**
+ * Tick Converters
+ */
+export class TickConverter {
+  /**
+   * Convert human price to tick
+   */
+  static priceToTick(price: number): number {
+    if (price <= 0) throw new Error("Price must be positive");
+    return Math.floor(Math.log(price) / Math.log(BELUGA_CONFIG.TICK_BASE));
+  }
+  
+  /**
+   * Convert tick to human price
+   */
+  static tickToPrice(tick: number): number {
+    return Math.pow(BELUGA_CONFIG.TICK_BASE, tick);
+  }
+  
+  /**
+   * Align tick to spacing
+   */
+  static align(tick: number, spacing: number): number {
+    return Math.floor(tick / spacing) * spacing;
+  }
+  
+  /**
+   * Create tick range from price range
+   */
+  static createRange(
+    lowerPrice: number,
+    upperPrice: number,
+    spacing: number
+  ): { lowerTick: number; upperTick: number } {
+    return {
+      lowerTick: this.align(this.priceToTick(lowerPrice), spacing),
+      upperTick: this.align(this.priceToTick(upperPrice), spacing),
+    };
+  }
+}
+
+/**
+ * Amount Converters (Stroops ↔ Human)
+ */
+export class AmountConverter {
+  /**
+   * Convert human amount to stroops
+   */
+  static toStroops(amount: number): bigint {
+    return BigInt(Math.floor(amount * BELUGA_CONFIG.STROOPS_MULTIPLIER));
+  }
+  
+  /**
+   * Convert stroops to human amount
+   */
+  static fromStroops(stroops: bigint | number): number {
+    const stroopsNum = typeof stroops === 'bigint' ? Number(stroops) : stroops;
+    return stroopsNum / BELUGA_CONFIG.STROOPS_MULTIPLIER;
+  }
+  
+  /**
+   * Format amount for display
+   */
+  static format(stroops: bigint | number, decimals: number = 7): string {
+    const amount = this.fromStroops(stroops);
+    return amount.toFixed(decimals);
+  }
+  
+  /**
+   * Format with token symbol
+   */
+  static formatWithSymbol(
+    stroops: bigint | number,
+    symbol: string,
+    decimals: number = 7
+  ): string {
+    return `${this.format(stroops, decimals)} ${symbol}`;
+  }
+}
+
+/**
+ * Fee Converters
+ */
+export class FeeConverter {
+  /**
+   * Convert percent to basis points
+   */
+  static percentToBps(percent: number): number {
+    return Math.floor(percent * 100);
+  }
+  
+  /**
+   * Convert basis points to percent
+   */
+  static bpsToPercent(bps: number): number {
+    return bps / 100;
+  }
+}
+
+/**
+ * Time Converters
+ */
+export class TimeConverter {
+  /**
+   * Convert days to ledgers
+   */
+  static daysToLedgers(days: number): number {
+    // 1 day ≈ 17,280 ledgers (5s per ledger)
+    return Math.floor(days * 17_280);
+  }
+  
+  /**
+   * Convert ledgers to days
+   */
+  static ledgersToDays(ledgers: number): number {
+    return ledgers / 17_280;
+  }
+}

package/src/factory.ts

@@ -0,0 +1,151 @@
+// src/factory.ts
+// Factory SDK for pool creation
+
+import { Contract, SorobanRpc } from '@stellar/stellar-sdk';
+import { BELUGA_CONFIG } from './config';
+import { PriceConverter, TickConverter, AmountConverter, FeeConverter, TimeConverter } from './converters';
+import type { CreatePoolParams, CreatePoolResult, GetPoolParams } from './types';
+
+/**
+ * BelugaSwap Factory SDK
+ * Create pools with human-friendly inputs
+ */
+export class BelugaFactorySDK {
+  private contract: Contract;
+  
+  constructor(
+    private contractId: string,
+    private rpc: SorobanRpc.Server,
+    private networkPassphrase: string
+  ) {
+    this.contract = new Contract(contractId);
+  }
+  
+  /**
+   * Create a new pool with human-friendly inputs
+   */
+  async createPool(params: CreatePoolParams): Promise<CreatePoolResult> {
+    // 1. Get fee tier info
+    const feeTier = BELUGA_CONFIG.FEE_TIERS[params.feeTier];
+    const feeBps = feeTier.bps;
+    const tickSpacing = feeTier.spacing;
+    
+    // 2. Convert creator fee
+    const creatorFeeBps = FeeConverter.percentToBps(params.creatorFeePercent);
+    if (creatorFeeBps < BELUGA_CONFIG.MIN_CREATOR_FEE_BPS || 
+        creatorFeeBps > BELUGA_CONFIG.MAX_CREATOR_FEE_BPS) {
+      throw new Error("Creator fee must be between 0.1% and 10%");
+    }
+    
+    // 3. Convert initial price
+    const initialSqrtPrice = PriceConverter.toSqrtPrice(params.initialPrice);
+    const currentTick = TickConverter.priceToTick(params.initialPrice);
+    
+    // 4. Convert amounts to stroops
+    const amount0Stroops = AmountConverter.toStroops(params.amount0);
+    const amount1Stroops = AmountConverter.toStroops(params.amount1);
+    
+    // Validate minimum
+    if (amount0Stroops < BELUGA_CONFIG.MIN_INITIAL_LIQUIDITY || 
+        amount1Stroops < BELUGA_CONFIG.MIN_INITIAL_LIQUIDITY) {
+      throw new Error("Minimum amount is 0.1 tokens each");
+    }
+    
+    // 5. Convert price range to ticks
+    const range = TickConverter.createRange(
+      params.priceRangeLower,
+      params.priceRangeUpper,
+      tickSpacing
+    );
+    
+    if (range.lowerTick >= range.upperTick) {
+      throw new Error("Lower price must be less than upper price");
+    }
+    
+    // 6. Convert lock duration
+    let lockDuration: number;
+    if (params.permanent) {
+      lockDuration = 0;
+    } else if (params.lockDurationDays) {
+      lockDuration = TimeConverter.daysToLedgers(params.lockDurationDays);
+      if (lockDuration < BELUGA_CONFIG.MIN_LOCK_DURATION_LEDGERS) {
+        throw new Error("Minimum lock duration is 7 days");
+      }
+    } else {
+      lockDuration = BELUGA_CONFIG.MIN_LOCK_DURATION_LEDGERS;
+    }
+    
+    // 7. Prepare contract params
+    const contractParams = {
+      creator: params.creator,
+      params: {
+        token_a: params.tokenA,
+        token_b: params.tokenB,
+        fee_bps: feeBps,
+        creator_fee_bps: creatorFeeBps,
+        initial_sqrt_price_x64: initialSqrtPrice.toString(),
+        amount0_desired: amount0Stroops.toString(),
+        amount1_desired: amount1Stroops.toString(),
+        lower_tick: range.lowerTick,
+        upper_tick: range.upperTick,
+        lock_duration: lockDuration,
+      }
+    };
+    
+    // 8. Return result
+    return {
+      summary: {
+        pair: `${params.tokenA}/${params.tokenB}`,
+        fee: `${feeTier.percent}%`,
+        creatorFee: `${params.creatorFeePercent}%`,
+        initialPrice: params.initialPrice,
+        priceRange: `${params.priceRangeLower} - ${params.priceRangeUpper}`,
+        amounts: `${params.amount0} + ${params.amount1}`,
+        lockDuration: params.permanent 
+          ? 'Permanent' 
+          : `${params.lockDurationDays} days`,
+      },
+      contractParams,
+      technical: {
+        feeBps,
+        creatorFeeBps,
+        sqrtPriceX64: initialSqrtPrice.toString(),
+        currentTick,
+        tickSpacing,
+        lowerTick: range.lowerTick,
+        upperTick: range.upperTick,
+        amount0Stroops: amount0Stroops.toString(),
+        amount1Stroops: amount1Stroops.toString(),
+        lockDurationLedgers: lockDuration,
+      },
+    };
+  }
+  
+  /**
+   * Get pool address
+   */
+  async getPool(params: GetPoolParams): Promise<string | null> {
+    const feeBps = BELUGA_CONFIG.FEE_TIERS[params.feeTier].bps;
+    
+    // TODO: Implement contract call
+    // const result = await this.contract.call('get_pool_address', ...);
+    
+    throw new Error("Not implemented - add contract integration");
+  }
+  
+  /**
+   * Check if pool exists
+   */
+  async poolExists(params: GetPoolParams): Promise<boolean> {
+    const pool = await this.getPool(params);
+    return pool !== null;
+  }
+  
+  /**
+   * Get total number of pools
+   */
+  async getTotalPools(): Promise<number> {
+    // TODO: Implement contract call
+    throw new Error("Not implemented - add contract integration");
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+// BelugaSwap SDK - Main Export
+// Version: 0.1.0
+
+export { BelugaSwapSDK as default, BelugaSwapSDK } from './sdk';
+export { BelugaFactorySDK } from './factory';
+export { BelugaPoolSDK } from './pool';
+export { BELUGA_CONFIG } from './config';
+export * from './types';
+export * from './converters';
+
+// Re-export for convenience
+import { BelugaSwapSDK } from './sdk';
+export default BelugaSwapSDK;

package/src/pool.ts

@@ -0,0 +1,265 @@
+// src/pool.ts
+// Pool SDK for liquidity and swap operations
+
+import { Contract, SorobanRpc } from '@stellar/stellar-sdk';
+import { BELUGA_CONFIG } from './config';
+import { PriceConverter, TickConverter, AmountConverter } from './converters';
+import type {
+  AddLiquidityParams,
+  AddLiquidityResult,
+  RemoveLiquidityParams,
+  SwapParams,
+  SwapResult,
+  PreviewSwapResult,
+  GetPositionParams,
+  PositionInfo,
+  CollectFeesParams,
+  PoolState,
+} from './types';
+
+/**
+ * BelugaSwap Pool SDK
+ * Interact with pools using human-friendly inputs
+ */
+export class BelugaPoolSDK {
+  private contract: Contract;
+  
+  constructor(
+    private contractId: string,
+    private rpc: SorobanRpc.Server,
+    private networkPassphrase: string
+  ) {
+    this.contract = new Contract(contractId);
+  }
+  
+  /**
+   * Add liquidity with human-friendly inputs
+   */
+  async addLiquidity(params: AddLiquidityParams): Promise<AddLiquidityResult> {
+    // 1. Get tick spacing
+    const tickSpacing = BELUGA_CONFIG.FEE_TIERS[params.feeTier].spacing;
+    
+    // 2. Convert price range to ticks
+    const range = TickConverter.createRange(
+      params.priceRangeLower,
+      params.priceRangeUpper,
+      tickSpacing
+    );
+    
+    // 3. Convert amounts to stroops
+    const amount0Stroops = AmountConverter.toStroops(params.amount0);
+    const amount1Stroops = AmountConverter.toStroops(params.amount1);
+    
+    // 4. Prepare contract params
+    const contractParams = {
+      owner: params.owner,
+      lower_tick: range.lowerTick,
+      upper_tick: range.upperTick,
+      amount0_desired: amount0Stroops.toString(),
+      amount1_desired: amount1Stroops.toString(),
+    };
+    
+    return {
+      summary: {
+        priceRange: `${params.priceRangeLower.toFixed(4)} - ${params.priceRangeUpper.toFixed(4)}`,
+        amounts: `${params.amount0} + ${params.amount1}`,
+      },
+      contractParams,
+      technical: {
+        lowerTick: range.lowerTick,
+        upperTick: range.upperTick,
+        tickSpacing,
+        amount0Stroops: amount0Stroops.toString(),
+        amount1Stroops: amount1Stroops.toString(),
+      }
+    };
+  }
+  
+  /**
+   * Remove liquidity with human-friendly inputs
+   */
+  async removeLiquidity(params: RemoveLiquidityParams) {
+    if (params.liquidityPercent <= 0 || params.liquidityPercent > 100) {
+      throw new Error("Liquidity percent must be between 0 and 100");
+    }
+    
+    const tickSpacing = BELUGA_CONFIG.FEE_TIERS[params.feeTier].spacing;
+    const range = TickConverter.createRange(
+      params.priceRangeLower,
+      params.priceRangeUpper,
+      tickSpacing
+    );
+    
+    return {
+      summary: {
+        removing: `${params.liquidityPercent}% of liquidity`,
+        priceRange: `${params.priceRangeLower} - ${params.priceRangeUpper}`,
+      },
+      contractParams: {
+        owner: params.owner,
+        lower_tick: range.lowerTick,
+        upper_tick: range.upperTick,
+      },
+      technical: {
+        lowerTick: range.lowerTick,
+        upperTick: range.upperTick,
+        percentToRemove: params.liquidityPercent,
+      }
+    };
+  }
+  
+  /**
+   * Execute swap with human-friendly inputs
+   */
+  async swap(params: SwapParams): Promise<SwapResult> {
+    // 1. Convert amount to stroops
+    const amountInStroops = AmountConverter.toStroops(params.amountIn);
+    
+    // 2. Calculate slippage in bps
+    const slippageBps = Math.floor(params.slippagePercent * 100);
+    if (slippageBps > BELUGA_CONFIG.MAX_SLIPPAGE_BPS) {
+      throw new Error("Slippage cannot exceed 50%");
+    }
+    
+    // 3. Estimate output (placeholder - should call preview_swap)
+    const currentPrice = 1.0; // TODO: Get from pool state
+    const estimatedOut = params.amountIn * currentPrice;
+    const minAmountOut = estimatedOut * (1 - params.slippagePercent / 100);
+    const minAmountOutStroops = AmountConverter.toStroops(minAmountOut);
+    
+    // 4. Convert price limit
+    const sqrtPriceLimitX64 = params.priceLimit 
+      ? PriceConverter.toSqrtPrice(params.priceLimit)
+      : BigInt(0);
+    
+    // 5. Prepare contract params
+    const contractParams = {
+      sender: params.sender,
+      token_in: params.tokenIn,
+      amount_in: amountInStroops.toString(),
+      amount_out_min: minAmountOutStroops.toString(),
+      sqrt_price_limit_x64: sqrtPriceLimitX64.toString(),
+    };
+    
+    return {
+      summary: {
+        swapping: `${params.amountIn} ${params.tokenIn}`,
+        estimatedOutput: `~${estimatedOut.toFixed(4)}`,
+        minimumOutput: `${minAmountOut.toFixed(4)}`,
+        slippage: `${params.slippagePercent}%`,
+        priceLimit: params.priceLimit ? `${params.priceLimit}` : 'None',
+      },
+      contractParams,
+      technical: {
+        amountInStroops: amountInStroops.toString(),
+        minAmountOutStroops: minAmountOutStroops.toString(),
+        slippageBps,
+        sqrtPriceLimitX64: sqrtPriceLimitX64.toString(),
+      }
+    };
+  }
+  
+  /**
+   * Preview swap output (read-only)
+   */
+  async previewSwap(params: {
+    tokenIn: string;
+    amountIn: number;
+  }): Promise<PreviewSwapResult> {
+    const amountInStroops = AmountConverter.toStroops(params.amountIn);
+    
+    // TODO: Call contract preview_swap
+    
+    // Placeholder
+    return {
+      amountOut: params.amountIn * 0.997,
+      priceImpact: 0.3,
+      newPrice: 1.003,
+    };
+  }
+  
+  /**
+   * Get position info (human-readable)
+   */
+  async getPosition(params: GetPositionParams): Promise<PositionInfo> {
+    const tickSpacing = BELUGA_CONFIG.FEE_TIERS[params.feeTier].spacing;
+    const range = TickConverter.createRange(
+      params.priceRangeLower,
+      params.priceRangeUpper,
+      tickSpacing
+    );
+    
+    // TODO: Call contract get_position
+    
+    // Mock result
+    const result = {
+      liquidity: 10000000,
+      amount0: BigInt(50_000_000),
+      amount1: BigInt(50_000_000),
+      fees_owed_0: BigInt(500_000),
+      fees_owed_1: BigInt(500_000),
+    };
+    
+    return {
+      liquidity: result.liquidity,
+      amount0: AmountConverter.fromStroops(result.amount0),
+      amount1: AmountConverter.fromStroops(result.amount1),
+      feesOwed0: AmountConverter.fromStroops(result.fees_owed_0),
+      feesOwed1: AmountConverter.fromStroops(result.fees_owed_1),
+      formatted: {
+        liquidity: result.liquidity.toLocaleString(),
+        amounts: `${AmountConverter.fromStroops(result.amount0)} + ${AmountConverter.fromStroops(result.amount1)}`,
+        fees: `${AmountConverter.fromStroops(result.fees_owed_0)} + ${AmountConverter.fromStroops(result.fees_owed_1)}`,
+      }
+    };
+  }
+  
+  /**
+   * Collect fees
+   */
+  async collectFees(params: CollectFeesParams) {
+    const tickSpacing = BELUGA_CONFIG.FEE_TIERS[params.feeTier].spacing;
+    const range = TickConverter.createRange(
+      params.priceRangeLower,
+      params.priceRangeUpper,
+      tickSpacing
+    );
+    
+    return {
+      contractParams: {
+        owner: params.owner,
+        lower_tick: range.lowerTick,
+        upper_tick: range.upperTick,
+      },
+      technical: {
+        lowerTick: range.lowerTick,
+        upperTick: range.upperTick,
+      }
+    };
+  }
+  
+  /**
+   * Get current pool state (human-readable)
+   */
+  async getPoolState(): Promise<PoolState> {
+    // TODO: Call contract get_pool_state
+    
+    // Mock state
+    const state = {
+      sqrt_price_x64: (BigInt(1) << BigInt(64)).toString(),
+      current_tick: 0,
+      liquidity: 100_000_000,
+    };
+    
+    return {
+      currentPrice: PriceConverter.fromSqrtPrice(BigInt(state.sqrt_price_x64)),
+      currentTick: state.current_tick,
+      liquidity: state.liquidity,
+      technical: {
+        sqrtPriceX64: state.sqrt_price_x64,
+        currentTick: state.current_tick,
+        liquidity: state.liquidity,
+      }
+    };
+  }
+}

package/src/sdk.ts

@@ -0,0 +1,110 @@
+// src/sdk.ts
+// Main SDK class combining Factory and Pool
+
+import { SorobanRpc } from '@stellar/stellar-sdk';
+import { BelugaFactorySDK } from './factory';
+import { BelugaPoolSDK } from './pool';
+import { NETWORKS } from './config';
+import type { NetworkConfig } from './config';
+
+/**
+ * SDK Configuration
+ */
+export interface BelugaSDKConfig {
+  factoryAddress: string;
+  poolAddress?: string;
+  rpcUrl?: string;
+  networkPassphrase?: string;
+  network?: 'testnet' | 'mainnet';
+}
+
+/**
+ * Main BelugaSwap SDK
+ * Complete integration from Factory to Pool operations
+ */
+export class BelugaSwapSDK {
+  public factory: BelugaFactorySDK;
+  public pool?: BelugaPoolSDK;
+  private rpc: SorobanRpc.Server;
+  private networkPassphrase: string;
+  
+  constructor(config: BelugaSDKConfig) {
+    // Determine network configuration
+    let networkConfig: NetworkConfig;
+    
+    if (config.network) {
+      // Use predefined network
+      networkConfig = NETWORKS[config.network.toUpperCase() as keyof typeof NETWORKS];
+    } else if (config.rpcUrl && config.networkPassphrase) {
+      // Use custom network
+      networkConfig = {
+        rpcUrl: config.rpcUrl,
+        networkPassphrase: config.networkPassphrase,
+      };
+    } else {
+      throw new Error(
+        'Must provide either "network" (testnet/mainnet) or both "rpcUrl" and "networkPassphrase"'
+      );
+    }
+    
+    this.rpc = new SorobanRpc.Server(networkConfig.rpcUrl);
+    this.networkPassphrase = networkConfig.networkPassphrase;
+    
+    // Initialize factory
+    this.factory = new BelugaFactorySDK(
+      config.factoryAddress,
+      this.rpc,
+      this.networkPassphrase
+    );
+    
+    // Initialize pool if address provided
+    if (config.poolAddress) {
+      this.pool = new BelugaPoolSDK(
+        config.poolAddress,
+        this.rpc,
+        this.networkPassphrase
+      );
+    }
+  }
+  
+  /**
+   * Connect to a specific pool
+   */
+  connectPool(poolAddress: string): BelugaPoolSDK {
+    this.pool = new BelugaPoolSDK(
+      poolAddress,
+      this.rpc,
+      this.networkPassphrase
+    );
+    return this.pool;
+  }
+  
+  /**
+   * Get pool address and connect in one step
+   */
+  async getAndConnectPool(params: {
+    tokenA: string;
+    tokenB: string;
+    feeTier: 'STABLE' | 'VOLATILE' | 'EXOTIC';
+  }): Promise<BelugaPoolSDK> {
+    const poolAddress = await this.factory.getPool(params);
+    if (!poolAddress) {
+      throw new Error('Pool does not exist');
+    }
+    return this.connectPool(poolAddress);
+  }
+  
+  /**
+   * Get RPC server instance
+   */
+  getRpc(): SorobanRpc.Server {
+    return this.rpc;
+  }
+  
+  /**
+   * Get network passphrase
+   */
+  getNetworkPassphrase(): string {
+    return this.networkPassphrase;
+  }
+}

package/src/types.ts

@@ -0,0 +1,202 @@
+// src/types.ts
+// TypeScript type definitions
+
+import { FeeTier } from './config';
+
+/**
+ * Pool Creation Parameters
+ */
+export interface CreatePoolParams {
+  creator: string;
+  tokenA: string;
+  tokenB: string;
+  feeTier: FeeTier;
+  creatorFeePercent: number;
+  initialPrice: number;
+  amount0: number;
+  amount1: number;
+  priceRangeLower: number;
+  priceRangeUpper: number;
+  lockDurationDays?: number;
+  permanent?: boolean;
+}
+
+/**
+ * Pool Creation Result
+ */
+export interface CreatePoolResult {
+  summary: {
+    pair: string;
+    fee: string;
+    creatorFee: string;
+    initialPrice: number;
+    priceRange: string;
+    amounts: string;
+    lockDuration: string;
+  };
+  contractParams: any;
+  technical: {
+    feeBps: number;
+    creatorFeeBps: number;
+    sqrtPriceX64: string;
+    currentTick: number;
+    tickSpacing: number;
+    lowerTick: number;
+    upperTick: number;
+    amount0Stroops: string;
+    amount1Stroops: string;
+    lockDurationLedgers: number;
+  };
+}
+
+/**
+ * Add Liquidity Parameters
+ */
+export interface AddLiquidityParams {
+  owner: string;
+  amount0: number;
+  amount1: number;
+  priceRangeLower: number;
+  priceRangeUpper: number;
+  feeTier: FeeTier;
+}
+
+/**
+ * Add Liquidity Result
+ */
+export interface AddLiquidityResult {
+  summary: {
+    priceRange: string;
+    amounts: string;
+  };
+  contractParams: {
+    owner: string;
+    lower_tick: number;
+    upper_tick: number;
+    amount0_desired: string;
+    amount1_desired: string;
+  };
+  technical: {
+    lowerTick: number;
+    upperTick: number;
+    tickSpacing: number;
+    amount0Stroops: string;
+    amount1Stroops: string;
+  };
+}
+
+/**
+ * Remove Liquidity Parameters
+ */
+export interface RemoveLiquidityParams {
+  owner: string;
+  liquidityPercent: number;
+  priceRangeLower: number;
+  priceRangeUpper: number;
+  feeTier: FeeTier;
+}
+
+/**
+ * Swap Parameters
+ */
+export interface SwapParams {
+  sender: string;
+  tokenIn: string;
+  amountIn: number;
+  slippagePercent: number;
+  priceLimit?: number;
+}
+
+/**
+ * Swap Result
+ */
+export interface SwapResult {
+  summary: {
+    swapping: string;
+    estimatedOutput: string;
+    minimumOutput: string;
+    slippage: string;
+    priceLimit: string;
+  };
+  contractParams: {
+    sender: string;
+    token_in: string;
+    amount_in: string;
+    amount_out_min: string;
+    sqrt_price_limit_x64: string;
+  };
+  technical: {
+    amountInStroops: string;
+    minAmountOutStroops: string;
+    slippageBps: number;
+    sqrtPriceLimitX64: string;
+  };
+}
+
+/**
+ * Preview Swap Result
+ */
+export interface PreviewSwapResult {
+  amountOut: number;
+  priceImpact: number;
+  newPrice: number;
+}
+
+/**
+ * Position Info
+ */
+export interface PositionInfo {
+  liquidity: number;
+  amount0: number;
+  amount1: number;
+  feesOwed0: number;
+  feesOwed1: number;
+  formatted: {
+    liquidity: string;
+    amounts: string;
+    fees: string;
+  };
+}
+
+/**
+ * Pool State
+ */
+export interface PoolState {
+  currentPrice: number;
+  currentTick: number;
+  liquidity: number;
+  technical: {
+    sqrtPriceX64: string;
+    currentTick: number;
+    liquidity: number;
+  };
+}
+
+/**
+ * Get Position Parameters
+ */
+export interface GetPositionParams {
+  owner: string;
+  priceRangeLower: number;
+  priceRangeUpper: number;
+  feeTier: FeeTier;
+}
+
+/**
+ * Collect Fees Parameters
+ */
+export interface CollectFeesParams {
+  owner: string;
+  priceRangeLower: number;
+  priceRangeUpper: number;
+  feeTier: FeeTier;
+}
+
+/**
+ * Get Pool Parameters
+ */
+export interface GetPoolParams {
+  tokenA: string;
+  tokenB: string;
+  feeTier: FeeTier;
+}