Main SDK API Overview

Architecture guide for the actual functional Saros Main SDK (@saros-finance/sdk)

This overview explains the architecture and design patterns of the actual Saros Main SDK, which uses functional programming patterns rather than object-oriented classes.

⚠️ Architecture Reality CheckThe Main SDK does not use object-oriented classes or modules. It exports individual functions and service objects using functional programming patterns.Actual Architecture:

// Functional exports - individual functions
import { getSwapAmountSaros, swapSaros } from '@saros-finance/sdk';

// Service objects from default export
import sarosSdk from '@saros-finance/sdk';
const { SarosFarmService, SarosStakeServices } = sarosSdk;

NOT This (fictional OOP):

const sdk = new MainSDK(); // ❌ This class doesn't exist
const quote = sdk.swaps.getQuote(); // ❌ No nested modules

Actual SDK Architecture

Package Structure

@saros-finance/sdk
├── Default Export (sarosSdk)
│   ├── SarosFarmService
│   │   ├── stakePool()
│   │   └── unStakePool()
│   └── SarosStakeServices
│       └── [staking methods]
│
└── Named Exports (functions)
    ├── getSwapAmountSaros()
    ├── swapSaros()
    ├── getPoolInfo()
    ├── depositAllTokenTypes()
    └── withdrawAllTokenTypes()

Import Patterns

Core Functions (Named Exports)

import { 
  getSwapAmountSaros,    // Get swap quotes
  swapSaros,             // Execute swaps
  getPoolInfo,           // Get pool information
  depositAllTokenTypes,  // Add liquidity
  withdrawAllTokenTypes  // Remove liquidity
} from '@saros-finance/sdk';

Service Objects (Default Export)

import sarosSdk from '@saros-finance/sdk';

// Destructure service objects
const { 
  SarosFarmService,    // Farm staking operations
  SarosStakeServices   // General staking operations
} = sarosSdk;

Combined Import Pattern

// Most common pattern - import both
import sarosSdk, {
  getSwapAmountSaros,
  swapSaros,
  getPoolInfo
} from '@saros-finance/sdk';

// Use functions directly
const quote = await getSwapAmountSaros(...params);

// Use services from default export
const { SarosFarmService } = sarosSdk;
const farmResult = await SarosFarmService.stakePool(...params);

API Categories

1. AMM Trading Functions

Purpose: Traditional constant product AMM operations

// Get swap estimate
const estimate = await getSwapAmountSaros(
  connection,
  fromMint,
  toMint, 
  fromAmount,
  slippage,
  poolParams
);

// Execute swap
const result = await swapSaros(
  connection,
  wallet,
  fromMint,
  toMint,
  fromAmount,
  minAmountOut,
  slippage
);

Key Characteristics:

Pure functional calls
Individual parameters (not config objects)
Connection required for each call
No state management or caching

2. Pool Information Functions

Purpose: Query pool state and metadata

// Get pool information
const poolInfo = await getPoolInfo(connection, poolAddress);

Functionality:

Pool reserve data
Fee information
Token pair details
Current pool state

3. Liquidity Management Functions

Purpose: Add and remove liquidity from pools

// Add liquidity to pool
const depositResult = await depositAllTokenTypes(
  connection,
  wallet,
  poolAddress,
  amounts
);

// Remove liquidity from pool  
const withdrawResult = await withdrawAllTokenTypes(
  connection,
  wallet,
  poolAddress,
  lpTokenAmount
);

Operation Pattern:

Direct function calls
Wallet required for signing
Returns transaction signatures
No position tracking

4. Farm Service (SarosFarmService)

Purpose: Yield farming operations with LP tokens

const { SarosFarmService } = sarosSdk;

// Stake LP tokens in farm
const stakeResult = await SarosFarmService.stakePool(
  connection,
  payerAccount,
  farmAddress,        // PublicKey
  amount,            // BN
  sarosFarmAddress,  // PublicKey  
  rewardsArray,      // Complex rewards config
  lpTokenAddress     // PublicKey
);

// Unstake from farm (similar parameters)
const unstakeResult = await SarosFarmService.unStakePool(...params);

Key Features:

Service object (not individual functions)
Complex parameter structure
Rewards configuration required
BN (BigNumber) amounts

5. Stake Services (SarosStakeServices)

Purpose: General token staking operations

const { SarosStakeServices } = sarosSdk;

// Staking methods available but exact API needs to be determined
// from SDK implementation

Status:

✅ Available in SDK
⚠️ Exact method signatures need investigation
📋 Not governance-related (that’s unimplemented)

Architecture Principles

Functional Programming

The SDK follows functional programming principles:

// Pure functions with explicit parameters
const quote = await getSwapAmountSaros(connection, fromMint, toMint, amount, slippage, poolParams);

// No global state or configuration
// Connection passed to each function
// No method chaining or fluent APIs

Stateless Operations

// Each function call is independent
const quote1 = await getSwapAmountSaros(connection1, ...params1);
const quote2 = await getSwapAmountSaros(connection2, ...params2);

// No shared state between calls
// No SDK initialization required
// No connection pooling or caching

Direct Solana Integration

import { Connection, PublicKey } from '@solana/web3.js';
import BN from 'bn.js';

// SDK functions expect Solana Web3.js types
const connection = new Connection('https://api.devnet.solana.com');
const pubkey = new PublicKey("address");
const amount = new BN(1000000);

// Direct integration, no wrapper types
const result = await SarosFarmService.stakePool(
  connection,  // Solana Connection
  payer,       // Solana account
  pubkey,      // Solana PublicKey  
  amount,      // BN from bn.js
  // ... other params
);

Usage Patterns

Basic Swap Flow

import { getSwapAmountSaros, swapSaros } from '@saros-finance/sdk';
import { Connection } from '@solana/web3.js';

async function performSwap() {
  const connection = new Connection('https://api.devnet.solana.com');
  
  // 1. Get quote
  const estimate = await getSwapAmountSaros(
    connection,
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC
    "So11111111111111111111111111111111111111112",   // SOL
    1000000, // 1 USDC
    0.5,     // 0.5% slippage
    poolParams
  );
  
  // 2. Execute swap
  const result = await swapSaros(
    connection,
    wallet,
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "So11111111111111111111111111111111111111112",
    1000000,
    estimate.amountOut,
    0.5
  );
  
  console.log(`Swap completed: ${result.signature}`);
}

Farm Staking Flow

import sarosSdk from '@saros-finance/sdk';
import { Connection, PublicKey } from '@solana/web3.js';
import BN from 'bn.js';

async function stakeFarm() {
  const { SarosFarmService } = sarosSdk;
  const connection = new Connection('https://api.devnet.solana.com');
  
  const stakeResult = await SarosFarmService.stakePool(
    connection,
    payerAccount,
    new PublicKey("FarmAddress"),
    new BN(1000000), // Amount to stake
    new PublicKey("SFarmWM5wLFNEw1q5ofqL7CrwBMwdcqQgK6oQuoBGZJ"), // Saros farm address
    [], // Rewards configuration
    new PublicKey("LPTokenAddress")
  );
  
  console.log(`Farm staking completed: ${stakeResult.signature}`);
}

Error Handling Patterns

Function-Level Error Handling

try {
  const quote = await getSwapAmountSaros(connection, fromMint, toMint, amount, slippage, poolParams);
  return quote;
} catch (error) {
  console.error('Swap quote failed:', error.message);
  // Handle specific errors based on error message/type
  throw error;
}

Service-Level Error Handling

try {
  const { SarosFarmService } = sarosSdk;
  const result = await SarosFarmService.stakePool(...params);
  return result;
} catch (error) {
  console.error('Farm staking failed:', error.message);
  // Error handling depends on Solana transaction errors
  throw error;
}

Dependencies and Requirements

Required Dependencies

{
  "@saros-finance/sdk": "^2.4.0",
  "@solana/web3.js": "^1.31.0",
  "@project-serum/anchor": "^0.25.0-beta.1",
  "bn.js": "^5.2.0"
}

TypeScript Support

// Basic type inference available
import { getSwapAmountSaros } from '@saros-finance/sdk';

// Types inferred from usage
const quote = await getSwapAmountSaros(connection, fromMint, toMint, amount, slippage, poolParams);
// quote type inferred as SwapEstimate-like object

// Explicit typing requires custom interfaces
interface SwapEstimate {
  amountOut: number;
  priceImpact?: number;
  fee?: number;
}

Limitations and Considerations

What’s Available (✅)

✅ AMM swap operations (getSwapAmountSaros, swapSaros)
✅ Pool information queries (getPoolInfo)
✅ Liquidity management (depositAllTokenTypes, withdrawAllTokenTypes)
✅ Farm staking (SarosFarmService.stakePool, SarosFarmService.unStakePool)
✅ General staking (SarosStakeServices)

What’s Not Available (❌)

❌ Governance functionality (planned but not implemented)
❌ Advanced routing or aggregation
❌ MEV protection
❌ Price feeds or oracles
❌ Portfolio management utilities
❌ Historical data or analytics

Architecture Constraints

No State Management: Each function call is independent
No Configuration: No global SDK configuration or initialization
Limited Caching: No built-in response caching
Manual Connection Management: Connection must be passed to each function
Basic Error Handling: Errors depend on underlying Solana transaction errors

Migration from Fictional APIs

If you’ve seen documentation referencing fictional OOP APIs, here’s how to migrate:

❌ Fictional Pattern

// This doesn't exist
import { MainSDK } from '@saros-finance/main-sdk';
const sdk = new MainSDK(connection);
const quote = await sdk.swaps.getQuote({...});

✅ Actual Pattern

// This is the real API
import { getSwapAmountSaros } from '@saros-finance/sdk';
const quote = await getSwapAmountSaros(connection, fromMint, toMint, amount, slippage, poolParams);

Reference Documentation

Main SDK Methods → - Complete functional API reference
Main SDK Types → - TypeScript type definitions
DLMM API Overview → - Concentrated liquidity architecture
DLMM Rust API → - High-performance Rust patterns

Getting Started (Tutorials)

Main SDK Quick Start → - Build your first DeFi app
First DeFi App Tutorial → - Complete implementation guide
DeFi Protocols Tutorial → - Multi-feature protocols

Solve Problems (How-To Guides)

Swaps → - AMM swap implementation
Liquidity Management → - Pool operations
Yield Farming → - Farm integration
Governance & Staking → - DAO participation

Quick Start

Integration Tutorials

Production Examples

How-to Guides

API Reference