ZO SDK - Multi-LP Token Architecture

A re-architected TypeScript SDK for interacting with multiple LP tokens on Sui Network: ZLP (ZO Liquidity Provider), SLP (Sudo Liquidity Provider), and USDZ (USD Stablecoin).

Installation

npm install zo-sdk
# or
yarn add zo-sdk
# or
pnpm add zo-sdk

Architecture Overview

The SDK supports multiple LP tokens through a unified interface:

• ZLP (ZO Liquidity Provider): Original ZO Protocol LP token
• SLP (Sudo Liquidity Provider): Sudo SDK-based LP token
• USDZ (USD Stablecoin): Stablecoin LP token

Key Components

1. Common Interfaces: Unified API surface for all LP tokens (IBaseAPI, IBaseDataAPI)
2. Abstract Base Classes: Shared logic with delegation to DataAPI (BaseAPI, BaseDataAPI)
3. Concrete Implementations: LP-specific functionality (ZLPAPI, SLPAPI, USDZAPI)
4. Factory Pattern: Type-safe instance creation via SDK (e.g. SDK.createZLPAPI())
5. Legacy Compatibility: Backward compatible API for existing integrations

How to Use the APIs

1. Create an API or DataAPI instance

Use the SDK factory (exported as SDK from zo-sdk) to create LP-specific instances. You need a Sui client, network, API endpoint, and connection URL.

import { SDK, LPToken, Network } from 'zo-sdk'
import { SuiClient } from '@mysten/sui/client'

const provider = new SuiClient({ url: 'https://fullnode.mainnet.sui.io' })
const network = Network.MAINNET
const apiEndpoint = 'https://api.zo.xyz'
const connectionURL = 'wss://api.zo.xyz/ws'

// Create API instances (transactions + data)
const zlpAPI = SDK.createZLPAPI(network, provider, apiEndpoint, connectionURL)
const slpAPI = SDK.createSLPAPI(network, provider, apiEndpoint, connectionURL)
const usdzAPI = SDK.createUSDZAPI(network, provider, apiEndpoint, connectionURL)

// Or create by LP token enum
const api = SDK.createAPI(LPToken.ZLP, network, provider, apiEndpoint, connectionURL)

// Create DataAPI instances (read-only; no transaction methods)
const zlpDataAPI = SDK.createZLPDataAPI(network, provider, apiEndpoint, connectionURL)
const slpDataAPI = SDK.createSLPDataAPI(network, provider, apiEndpoint, connectionURL)
const usdzDataAPI = SDK.createUSDZDataAPI(network, provider, apiEndpoint, connectionURL)

// Or create DataAPI by LP token
const dataAPI = SDK.createDataAPI(LPToken.SLP, network, provider, apiEndpoint, connectionURL)

2. API vs DataAPI

| Use case | Class | Use | |----------|--------|-----| | Build transactions + read data | API (ZLPAPI, SLPAPI, etc.) | Deposit, withdraw, open/close positions, stake, and also call data methods (market info, vaults, positions, etc.). | | Read-only | DataAPI (ZLPDataAPI, SLPDataAPI, etc.) | Only query chain/API state (market valuation, vault info, positions, orders, history). No transaction building. |

API instances expose both transaction methods and data methods. Data methods (e.g. getMarketInfo, valuateMarket, getVaultInfo) are implemented by delegating to the internal dataAPI, so you can call them directly on the API or via api.dataAPI:

const zlpAPI = SDK.createZLPAPI(network, provider, apiEndpoint, connectionURL)

// Data methods are available directly on the API (same result either way)
const marketData = await zlpAPI.valuateMarket()
const marketDataAlt = await zlpAPI.dataAPI.valuateMarket()

// Transaction methods exist only on the API
const depositTx = await zlpAPI.deposit('usdc', ['coinId'], 1000000)

DataAPI instances are for read-only usage when you don’t need to build transactions:

const zlpDataAPI = SDK.createZLPDataAPI(network, provider, apiEndpoint, connectionURL)
const marketData = await zlpDataAPI.valuateMarket()
const vaultInfo = await zlpDataAPI.getVaultInfo('usdc')
// zlpDataAPI.deposit(...) does not exist

Common Operations Across All LP Tokens

// Data / read operations (use API or DataAPI; same methods)
const zlpMarket = await zlpAPI.valuateMarket()
const slpMarket = await slpAPI.getMarketInfo()
const vaultInfo = await usdzAPI.getVaultInfo('usdc')
const positionCaps = await zlpAPI.getPositionCapInfoList(ownerAddress)
const positions = await zlpAPI.getPositionInfoList(positionCaps, ownerAddress)

// Deposit (all LP tokens)
const depositTx = await zlpAPI.deposit(
  'usdc',       // coin type
  ['coinObjectId'], // coin object IDs
  1000000,      // amount
  0,            // minimum amount out (optional)
  'referralAddress', // optional referral
  'senderAddress'    // optional sender
)
const slpDepositTx = await slpAPI.deposit('usdc', ['coinObjectId'], 1000000)
const usdzDepositTx = await usdzAPI.deposit('usdc', ['coinObjectId'], 1000000)

// Withdraw
const withdrawTx = await zlpAPI.withdraw(
  'usdc',
  ['lpCoinObjectId'],
  1000000,
  0
)

// Swap
const swapTx = await zlpAPI.swap(
  'usdc',           // from token
  'sui',            // to token
  BigInt(1000000),  // amount
  ['coinObjectId']  // coin objects
)

LP-Specific Features

// ZLP-specific: Advanced trading operations
// Open leveraged position
const openPositionTx = await zlpAPI.openPosition(
  'usdc', // collateral token
  'btc', // index token
  BigInt(1000000), // size
  BigInt(100000), // collateral amount
  ['coinObjectId'], // coin objects
  true, // long position
  BigInt(50000), // reserve amount
  30000, // index price
  1.5, // collateral price
  false, // is limit order
  false, // is IOC order
  0.003, // price slippage
  0.5, // collateral slippage
  BigInt(500), // relayer fee
  'referralAddress', // referral
  'senderAddress' // sender
)

// SLP-specific: Sudo SDK operations
// Stake SLP tokens
const stakeTx = await slpAPI.stake(
  ['slpCoinObjectId'], // LP coin objects
  BigInt(1000000), // amount
  'poolId' // staking pool
)

// Unstake SLP tokens
const unstakeTx = await slpAPI.unstake(
  credentials, // SLP credentials
  BigInt(500000), // amount
  'poolId' // staking pool
)

// USDZ-specific: Stablecoin operations
const usdzSwapTx = await usdzAPI.swap(
  'usdc',
  'usdt',
  BigInt(1000000),
  ['coinObjectId']
)

Legacy SDK Usage (Backward Compatible)

Quick Start

import { API, Network } from 'zo-sdk'
import { SuiClient } from '@mysten/sui/client'

// Initialize the API
const provider = new SuiClient({ url: 'https://sui-rpc.url' })
const api = API.getInstance(
  Network.MAINNET,
  provider,
  'https://api-endpoint',
  'https://price-feed-url'
)

// Example: Get market information
const marketInfo = await api.getMarketInfo()

// Example: Get oracle price for a token
const price = await api.getOraclePrice('sui')

Key Features

Market Operations

// Deposit tokens to get ZLP
const tx = await api.deposit(
  'sui', // token
  ['coinObjectId'], // coin object IDs
  1000000, // amount
  0 // minimum amount out
)

// Withdraw tokens by burning ZLP
const tx = await api.withdraw(
  'sui', // token
  ['zlpCoinObjectId'], // ZLP coin object IDs
  1000000, // amount
  0 // minimum amount out
)

// Swap tokens
const tx = await api.swap(
  'sui', // from token
  'usdc', // to token
  BigInt(1000000), // amount
  ['coinObjectId'] // coin object IDs
)

Trading Operations

// Open a position
const tx = await api.openPosition(
  'sui', // collateral token
  'btc', // index token
  BigInt(1000000), // size
  BigInt(100000), // collateral amount
  ['coinObjectId'], // coin object IDs
  true, // long position
  BigInt(100000), // reserve amount
  30000, // index price
  1.5, // collateral price
  false, // is limit order
  false, // is IOC order
  0.003, // price slippage
  0.5, // collateral slippage
  BigInt(500), // relayer fee
  'referralAddress', // referral address
  'senderAddress' // sender address
)

// Decrease a position
const tx = await api.decreasePosition(
  'positionCapId',
  'sui', // collateral token
  'btc', // index token
  BigInt(500000), // amount to decrease
  true, // long position
  30000, // index price
  1.5, // collateral price
)

// Cancel an order
const tx = await api.cancelOrder(
  'orderCapId',
  'sui',
  'btc',
  true, // long position
  'OPEN_POSITION' // order type
)

Data Queries

// Get market information
const marketInfo = await api.getMarketInfo()

// Get oracle price for a token
const price = await api.getOraclePrice('sui')

// Get vault information
const vaultInfo = await api.getVaultInfo('sui')

// Get symbol information
const symbolInfo = await api.getSymbolInfo('btc', true) // true for long

// Get market valuation
const valuation = await api.valuateMarket()

// Get position cap info list
const positionCaps = await api.getPositionCapInfoList('ownerAddress')

// Get order cap info list
const orderCaps = await api.getOrderCapInfoList('ownerAddress')

// Get position information
const positions = await api.getPositionInfoList(positionCaps, 'ownerAddress')

// Get order information
const orders = await api.getOrderInfoList(orderCaps, 'ownerAddress')

Staking Operations

// Stake ZLP tokens
const stakeTx = await api.stake(
  ['zlpCoinObjectId'], // ZLP coin object IDs
  BigInt(1000000), // amount to stake
  'poolId' // staking pool ID
)

// Unstake ZLP tokens
const unstakeTx = await api.unstake(
  credentials, // staking credentials
  BigInt(1000000), // amount to unstake
  'poolId' // staking pool ID
)

// Get staked information
const stakedInfo = await api.getStaked('ownerAddress')

Type Safety and Interfaces

The SDK is built with TypeScript and provides comprehensive type definitions:

import type {
  IBaseAPI,
  IBaseDataAPI,
  IZLPAPI,
  ISLPAPI,
  IUSDZAPI,
  IBaseMarketValuationInfo,
  IBaseVaultInfo,
  IBaseSymbolInfo,
  IBasePositionInfo,
  IBaseOrderInfo
} from 'zo-sdk'

// All APIs implement their respective interfaces
const zlpAPI: IZLPAPI = SDK.createZLPAPI(network, provider, apiEndpoint, connectionURL)
const slpAPI: ISLPAPI = SDK.createSLPAPI(network, provider, apiEndpoint, connectionURL)
const usdzAPI: IUSDZAPI = SDK.createUSDZAPI(network, provider, apiEndpoint, connectionURL)

// Type-safe data: call data methods directly on the API or via .dataAPI
const marketInfo: IBaseMarketValuationInfo = await zlpAPI.valuateMarket()
const vaultInfo: IBaseVaultInfo = await zlpAPI.getVaultInfo('usdc')

Error Handling

The SDK throws errors for invalid operations and network issues. Always wrap API calls in try-catch blocks:

try {
  const marketInfo = await api.getMarketInfo()
  const depositTx = await api.deposit('usdc', ['coinId'], 1000000)
} catch (error) {
  console.error('SDK operation failed:', error)
  // Handle specific error types
  if (error.message.includes('Unsupported LP token')) {
    console.error('Invalid LP token type provided')
  }
}

Migration Guide

From Legacy SDK (v0.0.x)

If you're upgrading from an older version of the SDK:

// Old way (still supported for backward compatibility)
import { API, Network } from 'zo-sdk'
const api = API.getInstance(network, provider, apiEndpoint, connectionURL)

// New way (recommended)
import { SDK, LPToken, Network } from 'zo-sdk'
const zlpAPI = SDK.createZLPAPI(network, provider, apiEndpoint, connectionURL)
const slpAPI = SDK.createSLPAPI(network, provider, apiEndpoint, connectionURL)
const usdzAPI = SDK.createUSDZAPI(network, provider, apiEndpoint, connectionURL)
// Or generic:
const api = SDK.createAPI(LPToken.ZLP, network, provider, apiEndpoint, connectionURL)

Key Changes

1. Multi-LP Token Support: The SDK supports ZLP, SLP, and USDZ tokens.
2. Factory Pattern: Use SDK.createZLPAPI(), SDK.createSLPAPI(), SDK.createUSDZAPI(), or SDK.createAPI(LPToken.XXX, ...).
3. API includes data methods: API instances expose both transaction methods and data methods (e.g. getMarketInfo, valuateMarket); you can call them on the API or on api.dataAPI.
4. Optional DataAPI-only: Use SDK.createZLPDataAPI() (etc.) when you only need read-only operations.
5. Type Safety: TypeScript interfaces (IBaseAPI, IBaseDataAPI, IZLPAPI, etc.) for all operations.

Documentation

API Reference

• Factory – API (full): SDK.createZLPAPI(), SDK.createSLPAPI(), SDK.createUSDZAPI(), SDK.createAPI(LPToken, ...)
• Factory – DataAPI (read-only): SDK.createZLPDataAPI(), SDK.createSLPDataAPI(), SDK.createUSDZDataAPI(), SDK.createDataAPI(LPToken, ...)
• Base interfaces: IBaseAPI, IBaseDataAPI for common operations
• LP-specific interfaces: IZLPAPI, ISLPAPI, IUSDZAPI for typed usage
• Data types: IBaseMarketValuationInfo, IBaseVaultInfo, IBaseSymbolInfo, IBasePositionInfo, IBaseOrderInfo, etc.

Source Code

For detailed implementation details and advanced usage:

• Interfaces: /src/interfaces/ - TypeScript interface definitions
• Implementations: /src/implementations/ - Concrete API implementations
• Abstract Classes: /src/abstract/ - Shared base functionality
• Factory: /src/factory/SDKFactory.ts - SDK instance creation
• Legacy API: /src/api.ts - Backward compatible API

Examples

Check the source code comments and type definitions for comprehensive examples of all available methods and their parameters.