zo-sdk

v0.1.62

Published

18 hours ago

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).

0High
0Medium
0Low

cosmoszo

theosudofi

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

Architecture Overview

The SDK has been re-architected to support multiple LP tokens through a unified interface pattern:

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

Common Interfaces: Unified API surface for all LP tokens (IBaseAPI, IBaseDataAPI)
Abstract Base Classes: Shared implementation logic (BaseAPI, BaseDataAPI)
Concrete Implementations: LP-specific functionality (ZLPAPI, SLPAPI, USDZAPI)
Factory Pattern: Type-safe SDK instance creation (SDKFactory)
Legacy Compatibility: Backward compatible API for existing integrations

New SDK Usage (Recommended)

Factory-based Approach

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

// Initialize 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 LP-specific API instances
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 use generic factory
const api = SDK.createAPI(LPToken.ZLP, network, provider, apiEndpoint, connectionURL)

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

API vs DataAPI

The SDK provides two types of interfaces:

API Classes (ZLPAPI, SLPAPI, USDZAPI): Full functionality including trading operations that create transactions
DataAPI Classes (ZLPDataAPI, SLPDataAPI, USDZDataAPI): Read-only operations for querying blockchain state

// API instances include both data access and transaction creation
const zlpAPI = SDK.createZLPAPI(network, provider, apiEndpoint, connectionURL)
const marketData = await zlpAPI.dataAPI.valuateMarket() // Data access
const depositTx = await zlpAPI.deposit('usdc', ['coinId'], 1000000) // Transaction creation

// DataAPI instances are for read-only operations only
const zlpDataAPI = SDK.createZLPDataAPI(network, provider, apiEndpoint, connectionURL)
const marketData = await zlpDataAPI.valuateMarket() // Data access only

Common Operations Across All LP Tokens

// Market valuation (all LP tokens)
const zlpMarket = await zlpAPI.dataAPI.valuateMarket()
const slpMarket = await slpAPI.dataAPI.valuateMarket()
const usdzMarket = await usdzAPI.dataAPI.valuateMarket()

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

// Similar for SLP and USDZ
const slpDepositTx = await slpAPI.deposit('usdc', ['coinObjectId'], 1000000)
const usdzDepositTx = await usdzAPI.deposit('usdc', ['coinObjectId'], 1000000)

// Withdraw operations
const withdrawTx = await zlpAPI.withdraw(
  'usdc', // coin to withdraw
  ['lpCoinObjectId'], // LP coin object IDs
  1000000, // amount
  0 // minimum amount out
)

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

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
// (Similar deposit/withdraw/swap operations optimized for stablecoin use cases)
const usdzSwapTx = await usdzAPI.swap(
  'usdc', // from stable
  'usdt', // to stable
  BigInt(1000000), // amount
  ['coinObjectId'] // coin objects
)

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 structures
const marketInfo: IBaseMarketValuationInfo = await zlpAPI.dataAPI.valuateMarket()
const vaultInfo: IBaseVaultInfo = await zlpAPI.dataAPI.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)

Key Changes

Multi-LP Token Support: The SDK now supports ZLP, SLP, and USDZ tokens
Factory Pattern: Use SDK.createXXXAPI() methods instead of singleton instances
Separate DataAPI: Read-only operations are available through dedicated DataAPI classes
Enhanced Type Safety: Comprehensive TypeScript interfaces for all operations
Modular Architecture: Each LP token has its own implementation while sharing common interfaces

Documentation

API Reference

Factory Methods: SDK.createZLPAPI(), SDK.createSLPAPI(), SDK.createUSDZAPI()
Base Interfaces: IBaseAPI, IBaseDataAPI for common operations
LP-Specific Interfaces: IZLPAPI, ISLPAPI, IUSDZAPI for specialized features
Data Types: IBaseMarketValuationInfo, IBaseVaultInfo, IBaseSymbolInfo, 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.