@zofai/zo-sdk 0.2.29 → 0.2.30

package/docs/common-operations.md

@@ -2,6 +2,27 @@
 
 These operations work across all LP tokens (ZLP, SLP, USDZ).
 
+## Oracle model (Pyth Pro + Stork)
+
+Newer market methods use **Pyth Pro** update bytes (verified on-chain) plus **Stork** where enabled, instead of per-token legacy Pyth feeder objects.
+
+| Operation | How oracle updates are supplied |
+|-----------|----------------------------------|
+| **Deposit / withdraw** | Fetched automatically inside the SDK (`initValuationOracle`) |
+| **Swap / open / decrease / redeem (v3+)** | Pass `pythProUpdateBytes` from `api.fetchPythProUpdateBytesForTokens(...)` |
+
+```typescript
+// Tokens needed for a trade (collateral + index)
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(['nusdc', 'btc'])
+
+// Tokens needed for a vault swap (all vaults are valued)
+const swapUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(
+  Object.keys(zlpAPI.consts.zoCore.vaults) // or sudoCore.vaults for SLP
+)
+```
+
+Legacy `openPositionV2` / `swap` / `swapV2Ptb` paths still exist, but new integrations should use the Pyth Pro methods below.
+
 ## Data / read operations
 
 Use the API or DataAPI; the methods are the same.
@@ -14,11 +35,15 @@ const positionCaps = await zlpAPI.getPositionCapInfoList(ownerAddress)
 const positions = await zlpAPI.getPositionInfoList(positionCaps, ownerAddress)
 ```
 
+`valuateMarket()` on SLP (and similar valuation helpers) resolves vault/symbol USD prices from Pyth Pro, including LST vaults as RR × SUI.
+
 ## Deposit
 
+Deposit builds valuation on-chain with Pyth Pro automatically — no update bytes argument.
+
 ```typescript
 const depositTx = await zlpAPI.deposit(
-  'usdc',             // coin type
+  'nusdc',            // coin type
   ['coinObjectId'],   // coin object IDs
   1000000,            // amount
   0,                  // minimum amount out (optional)
@@ -31,22 +56,45 @@ const usdzDepositTx = await usdzAPI.deposit('usdc', ['coinObjectId'], 1000000)
 
 ## Withdraw
 
+Same as deposit: valuation oracle is initialized inside the SDK.
+
 ```typescript
 const withdrawTx = await zlpAPI.withdraw(
-  'usdc',
+  'nusdc',
   ['lpCoinObjectId'],
   1000000,
   0
 )
 ```
 
-## Swap
+## Swap (Pyth Pro)
+
+Prefer the Pyth Pro swap methods:
+
+| LP | Method | PTB (returns coin) |
+|----|--------|--------------------|
+| **ZLP / USDZ** | `swapV3` | `swapV3Ptb` |
+| **SLP** | `swapV4` | `swapV4Ptb` |
 
 ```typescript
-const swapTx = await zlpAPI.swap(
-  'usdc',             // from token
-  'sui',              // to token
-  BigInt(1000000),    // amount
-  ['coinObjectId']    // coin objects
+const vaultTokens = Object.keys(zlpAPI.consts.zoCore.vaults)
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(vaultTokens)
+
+const swapTx = await zlpAPI.swapV3(
+  'nusdc',              // from token
+  'sui',                // to token
+  BigInt(1000000),      // amount
+  ['coinObjectId'],     // coin objects
+  pythProUpdateBytes,
+  0                     // minAmountOut (optional)
+)
+
+// SLP uses swapV4 with the same argument shape
+const slpSwapTx = await slpAPI.swapV4(
+  'usdc',
+  'sui',
+  BigInt(1000000),
+  ['coinObjectId'],
+  await slpAPI.fetchPythProUpdateBytesForTokens(Object.keys(slpAPI.consts.sudoCore.vaults)),
 )
 ```

package/docs/getting-started.md

@@ -46,8 +46,11 @@ const zlpAPI = SDK.createZLPAPI(network, provider, apiEndpoint, connectionURL)
 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)
+// Deposit / withdraw fetch Pyth Pro valuation updates internally
+const depositTx = await zlpAPI.deposit('nusdc', ['coinId'], 1000000)
+
+// Trading / swap (v3+) need update bytes first
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(['nusdc', 'btc'])
 ```
 
 **DataAPI** instances are for read-only usage when you don't need to build transactions:
@@ -55,6 +58,8 @@ const depositTx = await zlpAPI.deposit('usdc', ['coinId'], 1000000)
 ```typescript
 const zlpDataAPI = SDK.createZLPDataAPI(network, provider, apiEndpoint, connectionURL)
 const marketData = await zlpDataAPI.valuateMarket()
-const vaultInfo = await zlpDataAPI.getVaultInfo('usdc')
+const vaultInfo = await zlpDataAPI.getVaultInfo('nusdc')
 // zlpDataAPI.deposit(...) does not exist
 ```
+
+For Pyth Pro trading and swap examples, see [Common Operations](common-operations.md), [Trading Examples](lp-specific-features.md), and [Swap Integration](swap-integration.md).

package/docs/lp-specific-features.md

@@ -14,15 +14,27 @@ When you open or decrease a position, you choose how the order is executed:
 - **Limit**: best when you want a specific price; order stays pending until the price condition is met.
 - **IOC limit**: “fill at my price or not at all” in one block.
 
+## Pyth Pro trading methods
+
+Use **`openPositionV3`** / **`decreasePositionV3`** (and SCard / coin variants) for ZLP, SLP, and USDZ. These take `pythProUpdateBytes` from `fetchPythProUpdateBytesForTokens`.
+
+| Action | Method |
+|--------|--------|
+| Open | `openPositionV3`, `openPositionWithCoinV3`, `openPositionWithSCardV3`, `openPositionWithCoinAndSCardV3` |
+| Decrease | `decreasePositionV3`, `decreasePositionWithSCardV3` |
+| Redeem collateral | ZLP / USDZ: `redeemFromPositionV2` · SLP: `redeemFromPositionV3` |
+
 ---
 
-## ZLP / SLP: Open position (market order)
+## Open position (market order)
 
 Execute immediately with slippage protection:
 
 ```typescript
-const tx = await zlpAPI.openPositionV2(
-  'usdc',             // collateral token
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(['nusdc', 'btc'])
+
+const tx = await zlpAPI.openPositionV3(
+  'nusdc',            // collateral token
   'btc',              // index token
   BigInt(1000000),    // size
   BigInt(100000),     // collateral amount
@@ -30,7 +42,8 @@ const tx = await zlpAPI.openPositionV2(
   true,               // long position
   BigInt(50000),      // reserve amount
   30000,              // index price (reference)
-  1.5,                // collateral price (reference)
+  1.0,                // collateral price (reference)
+  pythProUpdateBytes, // Pyth Pro update bytes
   false,              // isLimitOrder: false = market order
   false,              // isIocOrder (ignored for market)
   0.003,              // pricesSlippage: 0.3% for market
@@ -41,15 +54,19 @@ const tx = await zlpAPI.openPositionV2(
 )
 ```
 
+The same `openPositionV3` signature works on `slpAPI` and `usdzAPI`.
+
 ---
 
-## ZLP / SLP: Open position (limit order)
+## Open position (limit order)
 
 Pending order at your limit price; use zero or small slippage:
 
 ```typescript
-const tx = await zlpAPI.openPositionV2(
-  'usdc',
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(['nusdc', 'btc'])
+
+const tx = await zlpAPI.openPositionV3(
+  'nusdc',
   'btc',
   BigInt(1000000),
   BigInt(100000),
@@ -57,7 +74,8 @@ const tx = await zlpAPI.openPositionV2(
   true,                // long
   BigInt(50000),
   30000,               // your limit price (index)
-  1.5,                 // collateral price
+  1.0,                 // collateral price
+  pythProUpdateBytes,
   true,                // isLimitOrder: true = limit order
   false,               // isIocOrder: false = pending until price is met
   0,                   // pricesSlippage: 0 for limit (exact price)
@@ -70,13 +88,15 @@ const tx = await zlpAPI.openPositionV2(
 
 ---
 
-## ZLP / SLP: Open position (IOC limit order)
+## Open position (IOC limit order)
 
 Fill only if the limit can be met immediately; otherwise the order does not execute:
 
 ```typescript
-const tx = await zlpAPI.openPositionV2(
-  'usdc',
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(['nusdc', 'btc'])
+
+const tx = await zlpAPI.openPositionV3(
+  'nusdc',
   'btc',
   BigInt(1000000),
   BigInt(100000),
@@ -84,7 +104,8 @@ const tx = await zlpAPI.openPositionV2(
   true,
   BigInt(50000),
   30000,
-  1.5,
+  1.0,
+  pythProUpdateBytes,
   true,                // isLimitOrder: true
   true,                // isIocOrder: true = fill now or cancel
   0,
@@ -94,3 +115,59 @@ const tx = await zlpAPI.openPositionV2(
   'senderAddress'
 )
 ```
+
+---
+
+## Decrease position
+
+```typescript
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(['nusdc', 'btc'])
+
+const tx = await zlpAPI.decreasePositionV3(
+  positionCapId,
+  'nusdc',             // collateral token
+  'btc',               // index token
+  BigInt(500000),      // decrease amount
+  true,                // long
+  30000,               // index price
+  1.0,                 // collateral price
+  pythProUpdateBytes,
+  false,               // isTriggerOrder
+  true,                // isTakeProfitOrder
+  false,               // isIocOrder
+  0.003,               // pricesSlippage
+  0.5,                 // collateralSlippage
+  BigInt(500),         // relayer fee
+  ['coinObjectId'],    // fee coin objects (or pass sender)
+  false,               // sponsoredTx
+  'senderAddress'
+)
+```
+
+---
+
+## Redeem collateral from a position
+
+```typescript
+const pythProUpdateBytes = await zlpAPI.fetchPythProUpdateBytesForTokens(['nusdc', 'btc'])
+
+// ZLP / USDZ
+const redeemTx = await zlpAPI.redeemFromPositionV2(
+  positionCapId,
+  'nusdc',
+  'btc',
+  100000,              // amount
+  true,                // long
+  pythProUpdateBytes,
+)
+
+// SLP
+const slpRedeemTx = await slpAPI.redeemFromPositionV3(
+  positionCapId,
+  'usdc',
+  'btc',
+  100000,
+  true,
+  pythProUpdateBytes,
+)
+```

package/docs/swap-integration.md

@@ -1,15 +1,25 @@
 # Swap Integration
 
-This guide covers how to integrate swaps using the ZO SDK. Swaps are supported on **ZLP**, **SLP**, and **USDZ** via `api.swap()`, `api.swapV2Ptb()`, and fee estimation via `dataAPI.calculateSwapFeeBreakdown()`.
+This guide covers how to integrate swaps using the ZO SDK. Swaps are supported on **ZLP**, **SLP**, and **USDZ**.
+
+Prefer the **Pyth Pro** methods:
+
+| LP | Swap (transfer output) | Swap PTB (return coin) |
+|----|------------------------|-------------------------|
+| **ZLP / USDZ** | `swapV3` | `swapV3Ptb` |
+| **SLP** | `swapV4` | `swapV4Ptb` |
+
+Fee estimation is available via `dataAPI.calculateSwapFeeBreakdown()`. Legacy `swap()` / `swapV2Ptb()` remain available but are not recommended for new integrations.
 
 ## Overview
 
 A swap flow typically involves:
 
 1. **Estimate fees** – Get the expected fee breakdown for the swap.
-2. **Set slippage protection** – Compute `minAmountOut` based on expected output and slippage tolerance.
-3. **Build transaction** – Call `api.swap()` to construct the transaction.
-4. **Sign and send** – Sign with the wallet and submit to the network.
+2. **Fetch Pyth Pro update bytes** – Required for vault valuation on the Pyth Pro path.
+3. **Set slippage protection** – Compute `minAmountOut` based on expected output and slippage tolerance.
+4. **Build transaction** – Call `swapV3` (ZLP/USDZ) or `swapV4` (SLP).
+5. **Sign and send** – Sign with the wallet and submit to the network.
 
 ## Amounts and units
 
@@ -27,7 +37,7 @@ const fromAmount = BigInt(100 * 1e6)  // 100_000_000 atomic units
 Before building the swap transaction, you can estimate the fee breakdown to display to the user or compute a safe `minAmountOut`.
 
 ```typescript
-import { SDK, LPToken, Network } from '@zofai/zo-sdk'
+import { SDK, Network } from '@zofai/zo-sdk'
 import { SuiClient } from '@mysten/sui/client'
 
 const provider = new SuiClient({ url: 'https://fullnode.mainnet.sui.io' })
@@ -58,13 +68,14 @@ console.log(`Total fee: ${feeBreakdown.totalFeeValue.toFixed(4)} USD`)
 console.log(`Fee rate: ${(feeBreakdown.totalFeeRate * 100).toFixed(2)}%`)
 ```
 
-## Build and submit swap transaction
+## Build and submit swap transaction (Pyth Pro)
 
-Use the **API** instance to build the swap transaction. You need:
+You need:
 
 - `fromToken`, `toToken` – token identifiers (e.g. `'usdc'`, `'sui'`).
 - `fromAmount` – amount in atomic units (bigint).
 - `fromCoinObjects` – owned coin object IDs for the source token.
+- `pythProUpdateBytes` – from `fetchPythProUpdateBytesForTokens` over **all vault tokens** (swap values every vault).
 - `minAmountOut` – optional; minimum output amount in atomic units (slippage protection).
 
 ```typescript
@@ -72,39 +83,48 @@ const slpAPI = SDK.createSLPAPI(network, provider, apiEndpoint, connectionURL)
 
 const fromAmount = BigInt(100 * 1e6)  // 100 USDC
 const fromCoinObjects = ['0x...']     // user's USDC coin IDs
+const minAmountOut = 0                // or compute from oracle + slippage
 
-// Optional: set minAmountOut to protect against slippage
-// e.g. 1% slippage: minAmountOut = expectedOut * 0.99
-const minAmountOut = 0  // or compute from oracle + slippage
+const vaultTokens = Object.keys(slpAPI.consts.sudoCore.vaults)
+const pythProUpdateBytes = await slpAPI.fetchPythProUpdateBytesForTokens(vaultTokens)
 
-const tx = await slpAPI.swap(
+const tx = await slpAPI.swapV4(
   'usdc',
   'sui',
   fromAmount,
   fromCoinObjects,
+  pythProUpdateBytes,
   minAmountOut
 )
 
+// ZLP / USDZ: use swapV3 with the same argument shape
+// const tx = await zlpAPI.swapV3('nusdc', 'sui', fromAmount, fromCoinObjects, pythProUpdateBytes, minAmountOut)
+
 // Sign with wallet and execute
 // const signed = await signAndExecuteTransaction({ transaction: tx })
 ```
 
-## Swap and return coin to user (swapV2Ptb)
+## Swap and return coin (PTB)
 
-Use `swapV2Ptb()` when you need the output coin returned as a `TransactionObjectArgument`—for example, to pass into another move call or to transfer it within the same transaction. Unlike `swap()`, which consumes the output internally, `swapV2Ptb()` returns the output coin so you can compose it into larger transactions.
+Use `swapV3Ptb` (ZLP/USDZ) or `swapV4Ptb` (SLP) when you need the output coin as a `TransactionObjectArgument`—for example, to pass into another move call or transfer it in the same transaction.
 
 Pass an optional `tx` to compose into an existing transaction; otherwise a new transaction is created (you must sign and execute it via your wallet).
 
 ```typescript
+import { Transaction } from '@mysten/sui/transactions'
+
 const slpAPI = SDK.createSLPAPI(network, provider, apiEndpoint, connectionURL)
+const vaultTokens = Object.keys(slpAPI.consts.sudoCore.vaults)
+const pythProUpdateBytes = await slpAPI.fetchPythProUpdateBytesForTokens(vaultTokens)
 
-// Option 1: Standalone swap (tx created internally)
+// Option 1: Standalone swap (tx created / passed in)
 const tx = new Transaction()
-const outputCoin = await slpAPI.swapV2Ptb(
+const outputCoin = await slpAPI.swapV4Ptb(
   'usdc',
   'sui',
   BigInt(100 * 1e6),
   fromCoinObjects,
+  pythProUpdateBytes,
   minAmountOut,
   tx
 )
@@ -112,14 +132,22 @@ const outputCoin = await slpAPI.swapV2Ptb(
 
 // Option 2: Compose with other move calls
 const composedTx = new Transaction()
-const swapCoin = await slpAPI.swapV2Ptb('usdc', 'sui', BigInt(100 * 1e6), fromCoinObjects, minAmountOut, composedTx)
+const swapCoin = await slpAPI.swapV4Ptb(
+  'usdc',
+  'sui',
+  BigInt(100 * 1e6),
+  fromCoinObjects,
+  pythProUpdateBytes,
+  minAmountOut,
+  composedTx
+)
 composedTx.transferObjects([swapCoin], composedTx.pure.address(recipientAddress))
 ```
 
 ## Complete integration example
 
 ```typescript
-import { SDK, LPToken, Network } from '@zofai/zo-sdk'
+import { SDK, Network } from '@zofai/zo-sdk'
 import { SuiClient } from '@mysten/sui/client'
 
 async function swapWithFeeEstimate(
@@ -151,12 +179,16 @@ async function swapWithFeeEstimate(
   const expectedOutAtomic = (netValueUsd * (10 ** toDecimals)) / toPrice
   const minAmountOut = Math.floor(expectedOutAtomic * (1 - slippageBps / 10000))
 
-  // 3. Build transaction
-  const tx = await api.swap(
+  // 3. Fetch Pyth Pro update for all vaults, then build transaction
+  const vaultTokens = Object.keys(api.consts.sudoCore.vaults)
+  const pythProUpdateBytes = await api.fetchPythProUpdateBytesForTokens(vaultTokens)
+
+  const tx = await api.swapV4(
     fromToken,
     toToken,
     BigInt(fromAmountAtomic),
     fromCoinObjects,
+    pythProUpdateBytes,
     minAmountOut
   )
 
@@ -180,4 +212,4 @@ Use `calculateSwapFeeBreakdown` to get the USD value of each component and the t
 
 ## Token identifiers
 
-Tokens are identified by their symbol in the deployment config, e.g. `'sui'`, `'usdc'`, `'usdt'`, `'eth'`, `'btc'`. Ensure the `fromToken` and `toToken` values match those in the LP’s supported tokens.
+Tokens are identified by their symbol in the deployment config, e.g. `'sui'`, `'usdc'`, `'nusdc'`, `'usdt'`, `'eth'`, `'btc'`. Ensure the `fromToken` and `toToken` values match those in the LP’s supported tokens.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zofai/zo-sdk",
   "type": "module",
-  "version": "0.2.29",
+  "version": "0.2.30",
   "author": "zo",
   "exports": {
     ".": {

package/src/consts/deployments-zlp-mainnet.json

@@ -1,7 +1,7 @@
 {
   "zo_core": {
     "package": "0xf7fade57462e56e2eff1d7adef32e4fd285b21fd81f983f407bb7110ca766cda",
-    "upgraded_package": "0x0c846bf17f6870e1ee87f0dbad62d58c6e33b7a9a23f227fc632fccc6183786e",
+    "upgraded_package": "0x79e9959dd864f2f073caf507228afaaccfb09276ced183dd15abcdf8375d4a88",
     "upgrade_cap": "0xcc96f78abe0b868afaab05954ccc6357afb5d379a21389d6eb88dda8b1f60052",
     "admin_cap": "0xbc10f6481f2b5d6185c73ee680aa90a60fe3854d9f638e00f7e00d3b6a88e2b8",
     "market": "0x35c667bd8c401036103992791a924f31df0d104256a9e2313acee5b1bcf05b7e",

package/src/consts/deployments-zo-oracle-mainnet.json

@@ -33,7 +33,24 @@
       "eba0732395fae9dec4bae12e52760b35fc1c5671e2da8b449c9af4efe5d54341": 624,
       "44465e17d2e9d390e70c999d5a11fda4f092847fcd2e3e5aa089d96c98a30e67": 172,
       "925ca92ff005ae943c158e3563f59698ce7e75c5a8c8dd43303a0a154887b3e6": 657,
-      "8cead549d0e770dea8fdf5e018a85d59585265cf8bff16ba83962fc7996dbb7f": 2998
+      "8cead549d0e770dea8fdf5e018a85d59585265cf8bff16ba83962fc7996dbb7f": 2998,
+      "2b89b9dc8fdf9f34709a5b106b472f0f39bb6ca9ce04b0fd7f2e971688e2e53b": 8,
+      "2f95862b045670cd22bee3114c39763a4a08beeb663b145d283c31d7d1101c4f": 15,
+      "2a01deaec9e51a579277b34b122399984d0bbf57e2458a7e42fecd2829867a0d": 16,
+      "93da3352f9f1d105fdfe4971cfa80e9dd777bfc5d0f683ebb6e1294b92137bb7": 18,
+      "2b9ab1e972a281585084148ba1389800799bd4be63b957507db1349314e47445": 29,
+      "0a0408d619e9380abad35060f9192039ed5042fa6f82301d0e48bb52be830996": 92,
+      "4279e31cc369bbcc2faf022b382b080e32a8e689ff20fbc530d2a603eb6cd98b": 110,
+      "273717b49430906f4b0c230e99aa1007f83758e3199edbc887c0d06c3e332494": 163,
+      "58cd29ef0e714c5affc44f269b2c1899a52da4169d7acc147b9da692e6953608": 182,
+      "d40472610abe56d36d065a0cf889fc8f1dd9f3b7f2a478231a5fc6df07ea5ce3": 201,
+      "e67d98cc1fbd94f569d5ba6c3c3c759eb3ffc5d2b28e64538a53ae13efad8fd1": 648,
+      "2b529621fa6e2c8429f623ba705572aa64175d7768365ef829df6a12c9f365f4": 1818,
+      "8414cfadf82f6bed644d2e399c11df21ec0131aa574c56030b132113dbbf3a0a": 1841,
+      "d41369178d64f41d51ca95465c144a2c74d2fff30be69164835911943fa64c3e": 1854,
+      "a903b5a82cb572397e3d47595d2889cf80513f5b4cf7a36b513ae10cc8b1e338": 2310,
+      "fa9e8d4591613476ad0961732475dc08969d248faca270cc6c47efe009ea3070": 2311,
+      "1fc9127232d059b415f7b11989d06aa11a3563619e5b7a8e44ae440f0b95e4e1": 2700
     }
   },
   "stork_feeder": {