@nemoprotocol/points-sdk
Version:
1. [Overview](#overview) 2. [Installation](#installation) 3. [Core Features](#core-features) 4. [API Reference](#api-reference) 5. [Type Definitions](#type-definitions)
561 lines (475 loc) • 12.8 kB
Markdown
# NEMO Protocol SDK Documentation
## Table of Contents
1. [Overview](#overview)
2. [Installation](#installation)
3. [Core Features](#core-features)
4. [API Reference](#api-reference)
5. [Type Definitions](#type-definitions)
## Overview
The NEMO Protocol SDK provides core functionality for querying user positions, calculating market values, and managing yield distributions in the NEMO protocol.
### Key Features
- **Position Query**: Query all positions for any Sui address
- **Holder Statistics**: Get PT, YT, LP holder counts and position quantities
- **Market Value Calculation**: Calculate current market values in SUI or underlying assets
- **Yield Management**: Query and claim available yield
- **Pool Information**: Get comprehensive pool statistics and market data
## Installation
### Package Installation
```bash
npm install @nemoprotocol/contract-sdk
# or
yarn add @nemoprotocol/contract-sdk
# or
pnpm add @nemoprotocol/contract-sdk
```
### Environment Configuration
```bash
# Build-time configuration
API_BASE_URL=https://api.nemoprotocol.com npm run build
# Development configuration (.env file)
API_BASE_URL=https://api.nemoprotocol.com
```
### SDK Initialization
```typescript
import { PositionQuery, PoolQuery } from '@nemoprotocol/contract-sdk'
const positionQuery = new PositionQuery({
network: 'mainnet', // or 'testnet', 'devnet', 'localnet'
rpcUrl: 'https://sui-mainnet.mystenlabs.com' // optional
})
const poolQuery = new PoolQuery()
```
## Core Features
### 1. Position Query
Query all positions for a specific Sui address in the NEMO protocol.
#### LP Position Query
```typescript
const lpPositions = await positionQuery.queryLpPositions({
address: '0x...', // user address
positionTypes: [
'0x...::market::LpPosition<0x...::coin::SUI>',
'0x...::market::LpPosition<0x...::coin::USDC>'
],
maturity: '2024-12-31', // optional filter
marketStateId: '0x...' // optional filter
})
// Response format:
// [
// {
// id: { id: '0x...' },
// name: 'LP-SUI-2024-12-31',
// expiry: '2024-12-31',
// lpAmount: '1000000000',
// description: 'LP position for SUI',
// marketStateId: '0x...'
// }
// ]
```
#### PY Position Query
```typescript
const pyPositions = await positionQuery.queryPyPositions({
address: '0x...', // user address
positionTypes: [
'0x...::py_state::PyState<0x...::coin::SUI>',
'0x...::py_state::PyState<0x...::coin::USDC>'
],
maturity: '2024-12-31', // optional filter
pyStateId: '0x...' // optional filter
})
// Response format:
// [
// {
// id: '0x...',
// maturity: '2024-12-31',
// ptBalance: '500000000',
// ytBalance: '300000000',
// pyStateId: '0x...'
// }
// ]
```
### 2. Holder Statistics
Get users holding different asset types (PT, YT, LP) and their position quantities.
#### PT/YT Holder Count
```typescript
const holdersCount = await positionQuery.queryPyPositionHoldersCount({
positionTypes: [
'0x...::py_state::PyState<0x...::coin::SUI>',
'0x...::py_state::PyState<0x...::coin::USDC>'
],
maturity: '2024-12-31',
pyStateId: '0x...',
pageSize: 50 // optional
})
console.log('PT Holders:', holdersCount.ptHolders)
console.log('YT Holders:', holdersCount.ytHolders)
console.log('Total Holders:', holdersCount.totalHolders)
console.log('Holders by Type:', holdersCount.holdersByType)
console.log('Total Positions:', holdersCount.totalPositions)
```
#### LP Holder Count
```typescript
const lpHoldersCount = await positionQuery.queryLpPositionHoldersCount({
positionTypes: [
'0x...::market::LpPosition<0x...::coin::SUI>',
'0x...::market::LpPosition<0x...::coin::USDC>'
],
maturity: '2024-12-31',
marketStateId: '0x...',
pageSize: 50 // optional
})
console.log('LP Holders:', lpHoldersCount.totalHolders)
console.log('Holders by Type:', lpHoldersCount.holdersByType)
console.log('Total Positions:', lpHoldersCount.totalPositions)
```
### 3. Market Value Calculation
Calculate and display current market values of user positions (priced in SUI or underlying assets).
#### Yield Query
```typescript
const yieldResult = await positionQuery.queryYield({
address: '0x...',
ytBalance: '1000000000',
pyPositions: [
{
id: '0x...',
maturity: '2024-12-31',
ptBalance: '500000000',
ytBalance: '300000000',
pyStateId: '0x...'
}
],
receivingType: 'sy', // or 'underlying'
config: {
nemoContractId: '0x...',
version: '1.0.0',
coinType: '0x...::coin::SUI',
pyStateId: '0x...',
syCoinType: '0x...::sy_coin::SyCoin<0x...::coin::SUI>',
yieldFactoryConfigId: '0x...',
marketStateId: '0x...',
underlyingCoinType: '0x...::coin::SUI',
underlyingProtocol: 'Scallop',
priceOracleConfigId: '0x...',
oraclePackageId: '0x...',
oracleTicket: '0x...',
oracleVoucherPackageId: '0x...'
}
})
console.log('Output Value:', yieldResult.outputValue)
console.log('Output Amount:', yieldResult.outputAmount)
```
### 4. Rewards query
Query and claim available yield rewards in the NEMO protocol.
```typescript
// Query rewards for multiple reward metrics
const rewards = await positionQuery.queryRewards({
address: '0x...', // user address
config: {
nemoContractId: '0x...',
version: '0x...',
marketStateId: '0x...',
// other required config fields
},
lpPositions: [
{
id: { id: '0x...' },
name: 'LP-SUI-2024-12-31',
expiry: '2024-12-31',
lpAmount: '1000000000',
description: 'LP position for SUI',
marketStateId: '0x...'
}
],
rewardMetrics: [
{
tokenType: '0x...::coin::SUI',
syCoinType: '0x...::sy_coin::SyCoin<0x...::coin::SUI>',
tokenLogo: 'https://...',
dailyEmission: '1000000000',
tokenPrice: '1.23',
tokenName: 'SUI',
decimal: '9'
},
{
tokenType: '0x...::coin::USDC',
syCoinType: '0x...::sy_coin::SyCoin<0x...::coin::USDC>',
tokenLogo: 'https://...',
dailyEmission: '500000000',
tokenPrice: '1.00',
tokenName: 'USDC',
decimal: '6'
}
]
});
// Response format:
// [
// {
// coinType: '0x...::coin::SUI',
// coinName: 'SUI',
// amount: '1.234567890'
// },
// {
// coinType: '0x...::coin::USDC',
// coinName: 'USDC',
// amount: '100.123456'
// }
// ]
```
### 5. Pool Information
Query basic information and statistics for different pools.
#### Pool Query
```typescript
const pools = await poolQuery.queryPools()
// Response format:
// [
// {
// id: '0x...',
// tvl: '1000000000000',
// tvlRateChange: '5.2',
// coinLogo: 'https://...',
// maturity: '2024-12-31',
// startTime: '2024-01-01',
// coinName: 'SUI',
// coinType: '0x...::coin::SUI',
// ptTokenType: '0x...::pt_coin::PtCoin<0x...::coin::SUI>',
// nemoContractId: '0x...',
// boost: '1.5',
// provider: 'Scallop',
// providerLogo: 'https://...',
// cap: '10000000000000',
// marketStateId: '0x...',
// syCoinType: '0x...::sy_coin::SyCoin<0x...::coin::SUI>',
// underlyingCoinType: '0x...::coin::SUI',
// providerMarket: '0x...',
// providerVersion: '1.0.0',
// priceOracleConfigId: '0x...',
// decimal: '9',
// underlyingApy: '8.5',
// coinPrice: '1.2',
// underlyingPrice: '1.2',
// pyStateId: '0x...',
// syStateId: '0x...',
// conversionRate: '1.0',
// marketFactoryConfigId: '0x...',
// swapFeeForLpHolder: '0.003',
// underlyingCoinName: 'SUI',
// underlyingCoinLogo: 'https://...',
// version: '1.0.0',
// perPoints: '1000000',
// oraclePackageId: '0x...',
// oracleTicket: '0x...',
// oracleVoucherPackageId: '0x...',
// yieldTokenType: '0x...::yt_coin::YtCoin<0x...::coin::SUI>',
// tokenRegistryState: '0x...',
// ptPrice: '0.95',
// ptTvl: '500000000000',
// syTvl: '500000000000',
// marketState: {
// marketCap: '1000000000000',
// totalSy: '500000000000',
// lpSupply: '1000000000000',
// totalPt: '500000000000',
// rewardMetrics: [...]
// },
// scaledPtApy: '12.5',
// scaledUnderlyingApy: '8.5',
// feeApy: '2.0',
// sevenAvgUnderlyingApy: '8.2',
// sevenAvgUnderlyingApyRateChange: '0.3',
// ytPrice: '0.15',
// lpPrice: '1.0',
// ytTokenLogo: 'https://...',
// ptTokenLogo: 'https://...',
// lpTokenLogo: 'https://...',
// ytReward: '150000000',
// underlyingProtocol: 'Scallop',
// yieldFactoryConfigId: '0x...',
// pyPositionTypeList: ['0x...::py_state::PyState<0x...::coin::SUI>'],
// marketPositionTypeList: ['0x...::market::LpPosition<0x...::coin::SUI>'],
// lpPriceRateChange: '2.1',
// ptPriceRateChange: '-1.5',
// ytPriceRateChange: '5.2',
// incentiveApy: '3.0',
// incentives: [...],
// poolApy: '15.5',
// tradeStatus: 'active'
// }
// ]
```
## API Reference
### PositionQuery Class
#### Constructor
```typescript
new PositionQuery(config: PositionQueryConfig)
```
**Parameters:**
- `config.network`: Network type ('mainnet' | 'testnet' | 'devnet' | 'localnet')
- `config.rpcUrl`: Custom RPC URL (optional)
#### Methods
##### queryLpPositions()
```typescript
async queryLpPositions(options: {
address: string;
positionTypes: string[];
maturity?: string;
marketStateId?: string;
}): Promise<LpPosition[]>
```
##### queryPyPositions()
```typescript
async queryPyPositions(options: {
address: string;
positionTypes: string[];
maturity?: string;
pyStateId?: string;
}): Promise<PyPosition[]>
```
##### queryPyPositionHoldersCount()
```typescript
async queryPyPositionHoldersCount(options: {
positionTypes: string[];
maturity?: string;
pyStateId?: string;
pageSize?: number;
}): Promise<{
ptHolders: number;
ytHolders: number;
totalHolders: number;
holdersByType: Record<string, { ptHolders: number; ytHolders: number }>;
totalPositions: number;
}>
```
##### queryLpPositionHoldersCount()
```typescript
async queryLpPositionHoldersCount(options: {
positionTypes: string[];
maturity?: string;
marketStateId?: string;
pageSize?: number;
}): Promise<{
totalHolders: number;
holdersByType: Record<string, number>;
totalPositions: number;
}>
```
##### queryYield()
```typescript
async queryYield(params: QueryYieldParams): Promise<{
outputValue: string;
outputAmount: string;
}>
```
### PoolQuery Class
#### Constructor
```typescript
new PoolQuery()
```
#### Methods
##### queryPools()
```typescript
async queryPools(): Promise<PortfolioItem[]>
```
## Type Definitions
### PositionQueryConfig
```typescript
interface PositionQueryConfig {
network?: 'mainnet' | 'testnet' | 'devnet' | 'localnet';
rpcUrl?: string;
}
```
### LpPosition
```typescript
interface LpPosition {
id: { id: string };
name: string;
expiry: string;
lpAmount: string;
description: string;
marketStateId: string;
}
```
### PyPosition
```typescript
interface PyPosition {
id: string;
maturity: string;
ptBalance: string;
ytBalance: string;
pyStateId: string;
}
```
### PortfolioItem
```typescript
interface PortfolioItem {
id: string;
tvl: string;
tvlRateChange: string;
coinLogo: string;
maturity: string;
startTime: string;
coinName: string;
coinType: string;
ptTokenType: string;
nemoContractId: string;
boost: string;
provider: string;
providerLogo: string;
cap: string;
marketStateId: string;
syCoinType: string;
underlyingCoinType: string;
providerMarket: string;
providerVersion: string;
priceOracleConfigId: string;
decimal: string;
underlyingApy: string;
coinPrice: string;
underlyingPrice: string;
pyStateId: string;
syStateId: string;
conversionRate: string;
marketFactoryConfigId: string;
swapFeeForLpHolder: string;
underlyingCoinName: string;
underlyingCoinLogo: string;
version: string;
perPoints: string;
oraclePackageId: string;
oracleTicket: string;
oracleVoucherPackageId: string;
yieldTokenType: string;
tokenRegistryState: string;
ptPrice: string;
ptTvl: string;
syTvl: string;
marketState: MarketState;
scaledPtApy: string;
scaledUnderlyingApy: string;
feeApy: string;
sevenAvgUnderlyingApy: string;
sevenAvgUnderlyingApyRateChange: string;
ytPrice: string;
lpPrice: string;
ytTokenLogo: string;
ptTokenLogo: string;
lpTokenLogo: string;
ytReward: string;
underlyingProtocol: string;
yieldFactoryConfigId: string;
pyPositionTypeList: string[];
marketPositionTypeList: string[];
lpPriceRateChange: string;
ptPriceRateChange: string;
ytPriceRateChange: string;
incentiveApy: string;
incentives: Incentive[];
poolApy: string;
tradeStatus: string;
}
```
**Document Version**: 1.0
**Last Updated**: [Date]