@zofai/zo-sdk 0.2.13 → 0.2.15

package/src/implementations/USDZAPI.ts

@@ -10,6 +10,7 @@ import { Transaction } from '@mysten/sui/transactions'
 import { SUI_CLOCK_OBJECT_ID } from '@mysten/sui/utils'
 
 import { BaseAPI } from '../abstract'
+import { resolveSpendableSuiCoin } from '../coins'
 import type { Network } from '../consts'
 import { ALLOW_TRADE_CAN_TRADE, ALLOW_TRADE_MUST_TRADE, ALLOW_TRADE_NO_TRADE, LPToken } from '../consts'
 import type {
@@ -17,8 +18,11 @@ import type {
   IUSDZAPI,
   IUSDZCredential,
 } from '../interfaces'
+import type { IInitPythProOracleOptions } from '../oracle'
+import type { OracleInputs, OracleInputsAlt } from '../oraclePro'
+import { buildOracleInputsAlt, oracleArgsAlt, oracleArgsStandard, oracleArgsWithClock } from '../oraclePro'
 import type { SuiClient } from '../suiClient'
-import { joinSymbol } from '../utils'
+import { joinSymbol, parseSymbolKey } from '../utils'
 import { USDZDataAPI } from './USDZDataAPI'
 
 export class USDZAPI extends BaseAPI implements IUSDZAPI {
@@ -34,6 +38,85 @@ export class USDZAPI extends BaseAPI implements IUSDZAPI {
     this.dataAPI = new USDZDataAPI(network, provider, apiEndpoint, connectionURL)
   }
 
+  private usdzLpType(): string {
+    return `${this.consts.zoCore.package}::usdz::USDZ`
+  }
+
+  private positionTypeArgs(collateralToken: string, indexToken: string, long: boolean): string[] {
+    return [
+      this.usdzLpType(),
+      this.consts.coins[collateralToken].module,
+      this.consts.coins[indexToken].module,
+      `${this.consts.zoCore.package}::market::${long ? 'LONG' : 'SHORT'}`,
+      this.consts.coins[collateralToken].module,
+    ]
+  }
+
+  private redeemTypeArgs(collateralToken: string, indexToken: string, long: boolean): string[] {
+    return [
+      this.usdzLpType(),
+      this.consts.coins[collateralToken].module,
+      this.consts.coins[indexToken].module,
+      `${this.consts.zoCore.package}::market::${long ? 'LONG' : 'SHORT'}`,
+    ]
+  }
+
+  private async initV3OracleForTokens(
+    tokens: string[],
+    tx: Transaction,
+    pythProUpdateBytes: Uint8Array | number[],
+    includeEmaPrice?: boolean,
+    options?: Pick<IInitPythProOracleOptions, 'storkUpdateData' | 'skipStork' | 'storkFeeSource' | 'kronosUrl'>,
+  ): Promise<{ tx: Transaction, oracle: OracleInputs }> {
+    const result = await this.initV3OracleTxb(tokens, tx, {
+      rawUpdateBytes: pythProUpdateBytes,
+      includeEmaPrice,
+      ...options,
+    })
+    return { tx: result.tx, oracle: result.oracle }
+  }
+
+  /** Vault + symbol index tokens required for valuate_vault_v2 / valuate_symbol_v2. */
+  private getValuationOracleTokens(): string[] {
+    const tokens = new Set(Object.keys(this.consts.zoCore.vaults))
+    for (const key of Object.keys(this.consts.zoCore.symbols)) {
+      const [, token] = parseSymbolKey(key)
+      tokens.add(token)
+    }
+    return [...tokens]
+  }
+
+  /** Pyth Pro oracle init for deposit / withdraw market valuation. */
+  private async initValuationOracle(
+    tx: Transaction,
+  ): Promise<{ tx: Transaction, oracle: OracleInputs }> {
+    const tokens = this.getValuationOracleTokens()
+    const pythProUpdateBytes = await this.fetchPythProUpdateBytesForTokens(tokens)
+    return this.initV3OracleForTokens(tokens, tx, pythProUpdateBytes)
+  }
+
+  private async resolveSponsoredSui(
+    tx: Transaction,
+    collateralToken: string,
+    relayerFee: bigint,
+    sponsoredTx?: boolean,
+    sender?: string,
+  ): Promise<TransactionObjectArgument | undefined> {
+    if (!sponsoredTx) {
+      return undefined
+    }
+    const additional = collateralToken === 'sui' ? relayerFee : 0n
+    if (additional === 0n) {
+      return undefined
+    }
+    return resolveSpendableSuiCoin(
+      tx,
+      this.provider,
+      this.requireSenderForSponsored(sender),
+      additional,
+    )
+  }
+
   public calcPositionReserveFeeAmount(_position: IBasePositionInfo): Promise<number> {
     throw new Error(`Method not implemented in ${this.constructor.name}.`)
   }
@@ -1059,53 +1142,18 @@ export class USDZAPI extends BaseAPI implements IUSDZAPI {
       tx = await this.addReferral(referralAddress, tx)
     }
 
-    // Initialize oracle transaction
-    const pythFeederKeys = Object.keys(this.consts.pythFeeder.feeder)
-
-    // Handle sponsored transaction case
-    if (sponsoredTx) {
-      const oracle = await this.initOracleTxb(pythFeederKeys, tx, true, {
-        sender: this.requireSenderForSponsored(sender),
-        additionalSuiAmount: coin === 'sui' ? BigInt(amount) : 0n,
-      })
-      tx = oracle.tx
-
-      const depositObject = await this.resolveSplitCoinObject(
-        tx,
-        coin,
-        BigInt(amount),
-        coinObjects,
-        { sponsoredTx: true, suiCoinObject: oracle.suiCoinObject, sender },
-      )
-
-      const { vaultsValuation, symbolsValuation } = this.dataAPI.valuate(tx)
-
-      tx.moveCall({
-        target: `${this.consts.zoCore.upgradedPackage}::market::deposit`,
-        typeArguments: [`${this.consts.zoCore.package}::usdz::USDZ`, this.consts.coins[coin].module],
-        arguments: [
-          tx.object(this.consts.zoCore.market),
-          tx.object(this.consts.zoCore.rebaseFeeModel),
-          depositObject,
-          tx.pure.u64(minAmountOut),
-          vaultsValuation,
-          symbolsValuation,
-        ],
-      })
-      return tx
-    }
+    const { tx: txWithOracle, oracle: oracleBundle } = await this.initValuationOracle(tx)
+    tx = txWithOracle
 
-    // Handle non-sponsored transaction case
-    tx = (await this.initOracleTxb(pythFeederKeys, tx)).tx
     const depositObject = await this.resolveSplitCoinObject(
       tx,
       coin,
       BigInt(amount),
       coinObjects,
-      { sender },
+      { sponsoredTx, sender },
     )
 
-    const { vaultsValuation, symbolsValuation } = this.dataAPI.valuate(tx)
+    const { vaultsValuation, symbolsValuation } = this.dataAPI.valuateV2(tx, oracleBundle)
 
     tx.moveCall({
       target: `${this.consts.zoCore.upgradedPackage}::market::deposit`,
@@ -1147,53 +1195,18 @@ export class USDZAPI extends BaseAPI implements IUSDZAPI {
       tx = await this.addReferral(referralAddress, tx)
     }
 
-    // Initialize oracle transaction
-    const pythFeederKeys = Object.keys(this.consts.pythFeeder.feeder)
-
-    // Handle sponsored transaction case
-    if (sponsoredTx) {
-      const oracle = await this.initOracleTxb(pythFeederKeys, tx, true, {
-        sender: this.requireSenderForSponsored(sender),
-        additionalSuiAmount: coin === 'sui' ? BigInt(amount) : 0n,
-      })
-      tx = oracle.tx
-
-      const depositObject = await this.resolveSplitCoinObject(
-        tx,
-        coin,
-        BigInt(amount),
-        coinObjects,
-        { sponsoredTx: true, suiCoinObject: oracle.suiCoinObject, sender },
-      )
-
-      const { vaultsValuation, symbolsValuation } = this.dataAPI.valuate(tx)
-
-      const [mintedCoin] = tx.moveCall({
-        target: `${this.consts.zoCore.upgradedPackage}::market::deposit_ptb`,
-        typeArguments: [`${this.consts.zoCore.package}::usdz::USDZ`, this.consts.coins[coin].module],
-        arguments: [
-          tx.object(this.consts.zoCore.market),
-          tx.object(this.consts.zoCore.rebaseFeeModel),
-          depositObject,
-          tx.pure.u64(minAmountOut),
-          vaultsValuation,
-          symbolsValuation,
-        ],
-      })
-      return mintedCoin
-    }
+    const { tx: txWithOracle, oracle: oracleBundle } = await this.initValuationOracle(tx)
+    tx = txWithOracle
 
-    // Handle non-sponsored transaction case
-    tx = (await this.initOracleTxb(pythFeederKeys, tx)).tx
     const depositObject = await this.resolveSplitCoinObject(
       tx,
       coin,
       BigInt(amount),
       coinObjects,
-      { sender },
+      { sponsoredTx, sender },
     )
 
-    const { vaultsValuation, symbolsValuation } = this.dataAPI.valuate(tx)
+    const { vaultsValuation, symbolsValuation } = this.dataAPI.valuateV2(tx, oracleBundle)
 
     const [mintedCoin] = tx.moveCall({
       target: `${this.consts.zoCore.upgradedPackage}::market::deposit_ptb`,
@@ -1231,30 +1244,17 @@ export class USDZAPI extends BaseAPI implements IUSDZAPI {
 
     let tx = new Transaction()
 
-    // Initialize oracle transaction
-    const pythFeederKeys = Object.keys(this.consts.pythFeeder.feeder)
-
-    let suiCoinObject
-    if (sponsoredTx) {
-      const oracle = await this.initOracleTxb(pythFeederKeys, tx, true, {
-        sender: this.requireSenderForSponsored(sender),
-        additionalSuiAmount: 0n,
-      })
-      tx = oracle.tx
-      suiCoinObject = oracle.suiCoinObject
-    }
-    else {
-      tx = (await this.initOracleTxb(pythFeederKeys, tx)).tx
-    }
+    const { tx: txWithOracle, oracle: oracleBundle } = await this.initValuationOracle(tx)
+    tx = txWithOracle
 
     const withdrawObject = await this.resolveSplitCoinObject(
       tx,
       'usdz',
       BigInt(amount),
       lpCoinObjects,
-      { sponsoredTx, suiCoinObject, sender },
+      { sponsoredTx, sender },
     )
-    const { vaultsValuation, symbolsValuation } = this.dataAPI.valuate(tx)
+    const { vaultsValuation, symbolsValuation } = this.dataAPI.valuateV2(tx, oracleBundle)
 
     tx.moveCall({
       target: `${this.consts.zoCore.upgradedPackage}::market::withdraw`,
@@ -1287,11 +1287,9 @@ export class USDZAPI extends BaseAPI implements IUSDZAPI {
       tx = new Transaction()
     }
 
-    // Initialize oracle transaction
-    const pythFeederKeys = Object.keys(this.consts.pythFeeder.feeder)
-
-    tx = (await this.initOracleTxb(pythFeederKeys, tx)).tx
-    const { vaultsValuation, symbolsValuation } = this.dataAPI.valuate(tx)
+    const { tx: txWithOracle, oracle: oracleBundle } = await this.initValuationOracle(tx)
+    tx = txWithOracle
+    const { vaultsValuation, symbolsValuation } = this.dataAPI.valuateV2(tx, oracleBundle)
 
     tx.moveCall({
       target: `${this.consts.zoCore.upgradedPackage}::market::withdraw`,
@@ -2639,4 +2637,636 @@ export class USDZAPI extends BaseAPI implements IUSDZAPI {
       ],
     })
   }
+
+  // --- Pyth Pro + Stork (v3) ---
+
+  /**
+   * Swaps tokens using swap_v3 (Pyth Pro + Stork). Transfers output to sender.
+   */
+  public async swapV3(
+    fromToken: string,
+    toToken: string,
+    fromAmount: bigint,
+    fromCoinObjects: string[],
+    pythProUpdateBytes: Uint8Array | number[],
+    minAmountOut?: number,
+    tx?: Transaction,
+  ): Promise<Transaction> {
+    if (!tx) {
+      tx = new Transaction()
+    }
+    const { tx: tx_, oracle } = await this.initV3OracleForTokens(
+      Object.keys(this.consts.zoCore.vaults),
+      tx,
+      pythProUpdateBytes,
+      true,
+    )
+    const fromCoinObject = this.processCoins(tx_, fromToken, fromCoinObjects)
+    const [fromDepositObject] = tx_.splitCoins(fromCoinObject, [tx_.pure.u64(fromAmount)])
+    const vaultsValuation = this.dataAPI.valuateVaultsV2(tx_, oracle)
+
+    tx_.moveCall({
+      target: `${this.consts.zoCore.upgradedPackage}::market::swap_v3`,
+      typeArguments: [
+        this.usdzLpType(),
+        this.consts.coins[fromToken].module,
+        this.consts.coins[toToken].module,
+      ],
+      arguments: [
+        tx_.object(this.consts.zoCore.market),
+        tx_.object(this.consts.zoCore.rebaseFeeModel),
+        fromDepositObject,
+        tx_.pure.u64(minAmountOut || 0),
+        vaultsValuation,
+        ...oracleArgsWithClock(oracle),
+      ],
+    })
+    return tx_
+  }
+
+  /**
+   * Swaps tokens and returns the output coin (swap_v3_ptb).
+   */
+  public async swapV3Ptb(
+    fromToken: string,
+    toToken: string,
+    fromAmount: bigint,
+    fromCoinObjects: string[],
+    pythProUpdateBytes: Uint8Array | number[],
+    minAmountOut?: number,
+    tx?: Transaction,
+  ): Promise<TransactionObjectArgument> {
+    if (!tx) {
+      tx = new Transaction()
+    }
+    const { tx: tx_, oracle } = await this.initV3OracleForTokens(
+      Object.keys(this.consts.zoCore.vaults),
+      tx,
+      pythProUpdateBytes,
+      true,
+    )
+    const fromCoinObject = this.processCoins(tx_, fromToken, fromCoinObjects)
+    const [fromDepositObject] = tx_.splitCoins(fromCoinObject, [tx_.pure.u64(fromAmount)])
+    const vaultsValuation = this.dataAPI.valuateVaultsV2(tx_, oracle)
+
+    const [outputCoin] = tx_.moveCall({
+      target: `${this.consts.zoCore.upgradedPackage}::market::swap_v3_ptb`,
+      typeArguments: [
+        this.usdzLpType(),
+        this.consts.coins[fromToken].module,
+        this.consts.coins[toToken].module,
+      ],
+      arguments: [
+        tx_.object(this.consts.zoCore.market),
+        tx_.object(this.consts.zoCore.rebaseFeeModel),
+        fromDepositObject,
+        tx_.pure.u64(minAmountOut || 0),
+        vaultsValuation,
+        ...oracleArgsWithClock(oracle),
+      ],
+    })
+    return outputCoin
+  }
+
+  /**
+   * Opens a position using open_position_v3 (Pyth Pro + Stork).
+   */
+  public async openPositionV3(
+    collateralToken: string,
+    indexToken: string,
+    size: bigint,
+    collateralAmount: bigint,
+    coinObjects: string[],
+    long: boolean,
+    reserveAmount: bigint,
+    indexPrice: number,
+    collateralPrice: number,
+    pythProUpdateBytes: Uint8Array | number[],
+    isLimitOrder?: boolean,
+    isIocOrder?: boolean,
+    pricesSlippage = 0.003,
+    collateralSlippage = 0.5,
+    relayerFee = BigInt(0.5),
+    referralAddress?: string,
+    sender?: string,
+    sponsoredTx?: boolean,
+  ): Promise<Transaction> {
+    let tx = new Transaction()
+    if (referralAddress && !(await this.dataAPI.hasReferral(sender || ''))) {
+      tx = await this.addReferral(referralAddress, tx)
+    }
+
+    const symbol = joinSymbol(long ? 'long' : 'short', indexToken)
+    const adjustPrice = this.processSlippage(indexPrice, long, isLimitOrder ? 0 : pricesSlippage)
+    const adjustCollateralPrice = this.processSlippage(collateralPrice, false, collateralSlippage)
+    const indexPriceThreshold = this.processPriceThreshold(indexPrice, pricesSlippage)
+
+    let allowTrade = ALLOW_TRADE_MUST_TRADE
+    if (isLimitOrder) {
+      allowTrade = isIocOrder ? ALLOW_TRADE_NO_TRADE : ALLOW_TRADE_CAN_TRADE
+    }
+
+    const { tx: tx_, oracle } = await this.initV3OracleForTokens(
+      [collateralToken, indexToken],
+      tx,
+      pythProUpdateBytes,
+    )
+    tx = tx_
+
+    const suiCoinObject = await this.resolveSponsoredSui(tx, collateralToken, relayerFee, sponsoredTx, sender)
+    const [depositObject, feeObject] = this.processCoinSplitting(
+      tx,
+      collateralToken,
+      coinObjects,
+      [tx.pure.u64(collateralAmount), tx.pure.u64(relayerFee)],
+      sponsoredTx,
+      suiCoinObject,
+    )
+
+    tx.moveCall({
+      target: `${this.consts.zoCore.upgradedPackage}::market::open_position_v3`,
+      typeArguments: this.positionTypeArgs(collateralToken, indexToken, long),
+      arguments: [
+        tx.object(SUI_CLOCK_OBJECT_ID),
+        tx.object(this.consts.zoCore.market),
+        tx.object(this.consts.zoCore.symbols[symbol].positionConfig),
+        ...oracleArgsStandard(oracle),
+        depositObject,
+        feeObject,
+        tx.pure.u8(allowTrade),
+        tx.pure.u64(size),
+        tx.pure.u64(reserveAmount),
+        tx.pure.u256(adjustCollateralPrice),
+        tx.pure.u256(adjustPrice),
+        tx.pure.u256(indexPriceThreshold),
+      ],
+    })
+
+    return tx
+  }
+
+  /**
+   * Opens a position with S Card using open_position_with_scard_v3.
+   */
+  public async openPositionWithSCardV3(
+    collateralToken: string,
+    indexToken: string,
+    size: bigint,
+    collateralAmount: bigint,
+    coinObjects: string[],
+    long: boolean,
+    reserveAmount: bigint,
+    indexPrice: number,
+    collateralPrice: number,
+    kioskClient: KioskClient,
+    kioskCap: KioskOwnerCap,
+    scard: string,
+    pythProUpdateBytes: Uint8Array | number[],
+    isLimitOrder?: boolean,
+    isIocOrder?: boolean,
+    pricesSlippage = 0.003,
+    collateralSlippage = 0.5,
+    relayerFee = BigInt(0.5),
+    referralAddress?: string,
+    sender?: string,
+    sponsoredTx?: boolean,
+  ): Promise<Transaction> {
+    let tx = new Transaction()
+    if (referralAddress && !(await this.dataAPI.hasReferral(sender || ''))) {
+      tx = await this.addReferral(referralAddress, tx)
+    }
+
+    const symbol = joinSymbol(long ? 'long' : 'short', indexToken)
+    const adjustPrice = this.processSlippage(indexPrice, long, isLimitOrder ? 0 : pricesSlippage)
+    const adjustCollateralPrice = this.processSlippage(collateralPrice, false, collateralSlippage)
+    const indexPriceThreshold = this.processPriceThreshold(indexPrice, pricesSlippage)
+
+    let allowTrade = ALLOW_TRADE_MUST_TRADE
+    if (isLimitOrder) {
+      allowTrade = isIocOrder ? ALLOW_TRADE_NO_TRADE : ALLOW_TRADE_CAN_TRADE
+    }
+
+    const kioskTx = new KioskTransaction({
+      transaction: tx,
+      kioskClient,
+      cap: kioskCap,
+    })
+
+    const [sudoCard, promise] = kioskTx.borrow({
+      itemType: `0xe7e651e4974fe367aa2837712d68081efb299c470242a15e2b9c26ea326159ec::card::SudoCard`,
+      itemId: scard,
+    })
+
+    const { tx: tx_, oracle } = await this.initV3OracleForTokens(
+      [collateralToken, indexToken],
+      tx,
+      pythProUpdateBytes,
+    )
+    tx = tx_
+
+    const suiCoinObject = await this.resolveSponsoredSui(tx, collateralToken, relayerFee, sponsoredTx, sender)
+    const [depositObject, feeObject] = this.processCoinSplitting(
+      tx,
+      collateralToken,
+      coinObjects,
+      [tx.pure.u64(collateralAmount), tx.pure.u64(relayerFee)],
+      sponsoredTx,
+      suiCoinObject,
+    )
+
+    tx.moveCall({
+      target: `${this.consts.zoCore.upgradedPackage}::market::open_position_with_scard_v3`,
+      typeArguments: this.positionTypeArgs(collateralToken, indexToken, long),
+      arguments: [
+        tx.object(SUI_CLOCK_OBJECT_ID),
+        tx.object(this.consts.zoCore.market),
+        tx.object(this.consts.zoCore.symbols[symbol].positionConfig),
+        ...oracleArgsStandard(oracle),
+        depositObject,
+        feeObject,
+        tx.pure.u8(allowTrade),
+        tx.pure.u64(size),
+        tx.pure.u64(reserveAmount),
+        tx.pure.u256(adjustCollateralPrice),
+        tx.pure.u256(adjustPrice),
+        tx.pure.u256(indexPriceThreshold),
+        sudoCard,
+      ],
+    })
+
+    kioskTx
+      .return({
+        itemType: `0xe7e651e4974fe367aa2837712d68081efb299c470242a15e2b9c26ea326159ec::card::SudoCard`,
+        item: sudoCard,
+        promise,
+      })
+      .finalize()
+
+    return tx
+  }
+
+  /**
+   * Decreases a position using decrease_position_v3.
+   */
+  public async decreasePositionV3(
+    pcpId: string,
+    collateralToken: string,
+    indexToken: string,
+    amount: bigint,
+    long: boolean,
+    indexPrice: number,
+    collateralPrice: number,
+    pythProUpdateBytes: Uint8Array | number[],
+    isTriggerOrder = false,
+    isTakeProfitOrder = true,
+    isIocOrder = false,
+    pricesSlippage = 0.003,
+    collateralSlippage = 0.5,
+    relayerFee = BigInt(0.5),
+    coinObjects?: string[],
+    sponsoredTx?: boolean,
+    sender?: string,
+  ): Promise<Transaction> {
+    if (!coinObjects?.length && !sender) {
+      throw new Error(`${this.constructor.name}: coinObjects or sender is required`)
+    }
+
+    let tx = new Transaction()
+
+    const adjustPrice = this.processSlippage(indexPrice, !long, isTriggerOrder ? 0 : pricesSlippage)
+    const adjustCollateralPrice = this.processSlippage(collateralPrice, false, collateralSlippage)
+    const indexPriceThreshold = this.processPriceThreshold(indexPrice, pricesSlippage)
+
+    let allowTrade = ALLOW_TRADE_MUST_TRADE
+    if (isTriggerOrder) {
+      allowTrade = isIocOrder || !isTakeProfitOrder ? ALLOW_TRADE_NO_TRADE : ALLOW_TRADE_CAN_TRADE
+    }
+    else {
+      isTakeProfitOrder = true
+    }
+
+    const { tx: tx_, oracle } = await this.initV3OracleForTokens(
+      [collateralToken, indexToken],
+      tx,
+      pythProUpdateBytes,
+    )
+    tx = tx_
+
+    const suiCoinObject = await this.resolveSponsoredSui(tx, collateralToken, relayerFee, sponsoredTx, sender)
+    const feeObject = await this.resolveRelayerFeeObject(
+      tx,
+      collateralToken,
+      coinObjects ?? [],
+      relayerFee,
+      sponsoredTx,
+      suiCoinObject,
+      sender,
+    )
+
+    tx.moveCall({
+      target: `${this.consts.zoCore.upgradedPackage}::market::decrease_position_v3`,
+      typeArguments: this.positionTypeArgs(collateralToken, indexToken, long),
+      arguments: [
+        tx.object(SUI_CLOCK_OBJECT_ID),
+        tx.object(this.consts.zoCore.market),
+        tx.object(pcpId),
+        ...oracleArgsStandard(oracle),
+        feeObject,
+        tx.pure.u8(allowTrade),
+        tx.pure.bool(isTakeProfitOrder),
+        tx.pure.u64(amount),
+        tx.pure.u256(adjustCollateralPrice),
+        tx.pure.u256(adjustPrice),
+        tx.pure.u256(indexPriceThreshold),
+      ],
+    })
+
+    return tx
+  }
+
+  /**
+   * Decreases a position with S Card using decrease_position_with_scard_v3.
+   */
+  public async decreasePositionWithSCardV3(
+    pcpId: string,
+    collateralToken: string,
+    indexToken: string,
+    amount: bigint,
+    long: boolean,
+    indexPrice: number,
+    collateralPrice: number,
+    kioskClient: KioskClient,
+    kioskCap: KioskOwnerCap,
+    scard: string,
+    pythProUpdateBytes: Uint8Array | number[],
+    isTriggerOrder = false,
+    isTakeProfitOrder = true,
+    isIocOrder = false,
+    pricesSlippage = 0.003,
+    collateralSlippage = 0.5,
+    relayerFee = BigInt(0.5),
+    coinObjects?: string[],
+    sponsoredTx?: boolean,
+    sender?: string,
+  ): Promise<Transaction> {
+    if (!coinObjects?.length && !sender) {
+      throw new Error(`${this.constructor.name}: coinObjects or sender is required`)
+    }
+
+    let tx = new Transaction()
+
+    const kioskTx = new KioskTransaction({
+      transaction: tx,
+      kioskClient,
+      cap: kioskCap,
+    })
+
+    const [sudoCard, promise] = kioskTx.borrow({
+      itemType: `0xe7e651e4974fe367aa2837712d68081efb299c470242a15e2b9c26ea326159ec::card::SudoCard`,
+      itemId: scard,
+    })
+
+    const adjustPrice = this.processSlippage(indexPrice, !long, isTriggerOrder ? 0 : pricesSlippage)
+    const adjustCollateralPrice = this.processSlippage(collateralPrice, false, collateralSlippage)
+    const indexPriceThreshold = this.processPriceThreshold(indexPrice, pricesSlippage)
+
+    let allowTrade = ALLOW_TRADE_MUST_TRADE
+    if (isTriggerOrder) {
+      allowTrade = isIocOrder || !isTakeProfitOrder ? ALLOW_TRADE_NO_TRADE : ALLOW_TRADE_CAN_TRADE
+    }
+    else {
+      isTakeProfitOrder = true
+    }
+
+    const { tx: tx_, oracle } = await this.initV3OracleForTokens(
+      [collateralToken, indexToken],
+      tx,
+      pythProUpdateBytes,
+    )
+    tx = tx_
+
+    const suiCoinObject = await this.resolveSponsoredSui(tx, collateralToken, relayerFee, sponsoredTx, sender)
+    const feeObject = await this.resolveRelayerFeeObject(
+      tx,
+      collateralToken,
+      coinObjects ?? [],
+      relayerFee,
+      sponsoredTx,
+      suiCoinObject,
+      sender,
+    )
+
+    tx.moveCall({
+      target: `${this.consts.zoCore.upgradedPackage}::market::decrease_position_with_scard_v3`,
+      typeArguments: this.positionTypeArgs(collateralToken, indexToken, long),
+      arguments: [
+        tx.object(SUI_CLOCK_OBJECT_ID),
+        tx.object(this.consts.zoCore.market),
+        tx.object(pcpId),
+        ...oracleArgsStandard(oracle),
+        feeObject,
+        tx.pure.u8(allowTrade),
+        tx.pure.bool(isTakeProfitOrder),
+        tx.pure.u64(amount),
+        tx.pure.u256(adjustCollateralPrice),
+        tx.pure.u256(adjustPrice),
+        tx.pure.u256(indexPriceThreshold),
+        sudoCard,
+      ],
+    })
+
+    kioskTx
+      .return({
+        itemType: `0xe7e651e4974fe367aa2837712d68081efb299c470242a15e2b9c26ea326159ec::card::SudoCard`,
+        item: sudoCard,
+        promise,
+      })
+      .finalize()
+    return tx
+  }
+
+  /**
+   * Redeems collateral from a position via redeem_from_position_v2 (Pyth Pro path).
+   */
+  public async redeemFromPositionV2(
+    pcpId: string,
+    collateralToken: string,
+    indexToken: string,
+    amount: number,
+    long: boolean,
+    pythProUpdateBytes: Uint8Array | number[],
+    tx?: Transaction,
+  ): Promise<Transaction> {
+    if (!tx) {
+      tx = new Transaction()
+    }
+
+    const { tx: tx_, oracle } = await this.initV3OracleForTokens(
+      [collateralToken, indexToken],
+      tx,
+      pythProUpdateBytes,
+    )
+
+    tx_.moveCall({
+      target: `${this.consts.zoCore.upgradedPackage}::market::redeem_from_position_v2`,
+      typeArguments: this.redeemTypeArgs(collateralToken, indexToken, long),
+      arguments: [
+        tx_.object(SUI_CLOCK_OBJECT_ID),
+        tx_.object(this.consts.zoCore.market),
+        tx_.object(pcpId),
+        ...oracleArgsStandard(oracle),
+        tx_.pure.u64(amount),
+      ],
+    })
+
+    return tx_
+  }
+
+  /**
+   * Liquidates a position (PTB-only public fun). Use liquidate_position_v3_1, not v3.
+   */
+  public liquidatePositionV3_1(
+    tx: Transaction,
+    owner: string,
+    positionId: string,
+    collateralToken: string,
+    indexToken: string,
+    long: boolean,
+    oracle: OracleInputsAlt,
+  ): void {
+    tx.moveCall({
+      target: `${this.consts.zoCore.upgradedPackage}::market::liquidate_position_v3_1`,
+      typeArguments: this.redeemTypeArgs(collateralToken, indexToken, long),
+      arguments: [
+        tx.object(this.consts.zoCore.market),
+        ...oracleArgsAlt(oracle),
+        tx.object(owner),
+        tx.object(positionId),
+      ],
+    })
+  }
+
+  /**
+   * Builds a full liquidate PTB including Pyth Pro verification.
+   */
+  public async liquidatePositionV3_1Tx(
+    owner: string,
+    positionId: string,
+    collateralToken: string,
+    indexToken: string,
+    long: boolean,
+    pythProUpdateBytes: Uint8Array | number[],
+    tx?: Transaction,
+  ): Promise<Transaction> {
+    if (!tx) {
+      tx = new Transaction()
+    }
+    const { tx: tx_, oracle } = await this.initV3OracleForTokens(
+      [collateralToken, indexToken],
+      tx,
+      pythProUpdateBytes,
+    )
+    this.liquidatePositionV3_1(
+      tx_,
+      owner,
+      positionId,
+      collateralToken,
+      indexToken,
+      long,
+      buildOracleInputsAlt(oracle),
+    )
+    return tx_
+  }
+
+  /** Keeper/bot: execute_open_position_order_v3_1 (compose in PTB). */
+  public executeOpenPositionOrderV3_1(
+    tx: Transaction,
+    owner: string,
+    orderId: string,
+    collateralToken: string,
+    indexToken: string,
+    long: boolean,
+    oracle: OracleInputsAlt,
+  ): void {
+    tx.moveCall({
+      target: `${this.consts.zoCore.upgradedPackage}::market::execute_open_position_order_v3_1`,
+      typeArguments: this.positionTypeArgs(collateralToken, indexToken, long),
+      arguments: [
+        tx.object(this.consts.zoCore.market),
+        ...oracleArgsAlt(oracle),
+        tx.object(owner),
+        tx.object(orderId),
+      ],
+    })
+  }
+
+  /** Keeper/bot: execute_open_market_order_v3_1. */
+  public executeOpenMarketOrderV3_1(
+    tx: Transaction,
+    owner: string,
+    orderId: string,
+    collateralToken: string,
+    indexToken: string,
+    long: boolean,
+    oracle: OracleInputsAlt,
+  ): void {
+    tx.moveCall({
+      target: `${this.consts.zoCore.upgradedPackage}::market::execute_open_market_order_v3_1`,
+      typeArguments: this.positionTypeArgs(collateralToken, indexToken, long),
+      arguments: [
+        tx.object(this.consts.zoCore.market),
+        ...oracleArgsAlt(oracle),
+        tx.object(owner),
+        tx.object(orderId),
+      ],
+    })
+  }
+
+  /** Keeper/bot: execute_decrease_market_order_v3_1. */
+  public executeDecreaseMarketOrderV3_1(
+    tx: Transaction,
+    owner: string,
+    orderId: string,
+    positionId: string,
+    collateralToken: string,
+    indexToken: string,
+    long: boolean,
+    oracle: OracleInputsAlt,
+  ): void {
+    tx.moveCall({
+      target: `${this.consts.zoCore.upgradedPackage}::market::execute_decrease_market_order_v3_1`,
+      typeArguments: this.positionTypeArgs(collateralToken, indexToken, long),
+      arguments: [
+        tx.object(this.consts.zoCore.market),
+        ...oracleArgsAlt(oracle),
+        tx.object(owner),
+        tx.object(orderId),
+        tx.object(positionId),
+      ],
+    })
+  }
+
+  /** Keeper/bot: execute_decrease_position_order_v3_1. */
+  public executeDecreasePositionOrderV3_1(
+    tx: Transaction,
+    owner: string,
+    orderId: string,
+    positionId: string,
+    collateralToken: string,
+    indexToken: string,
+    long: boolean,
+    oracle: OracleInputsAlt,
+  ): void {
+    tx.moveCall({
+      target: `${this.consts.zoCore.upgradedPackage}::market::execute_decrease_position_order_v3_1`,
+      typeArguments: this.positionTypeArgs(collateralToken, indexToken, long),
+      arguments: [
+        tx.object(this.consts.zoCore.market),
+        ...oracleArgsAlt(oracle),
+        tx.object(owner),
+        tx.object(orderId),
+        tx.object(positionId),
+      ],
+    })
+  }
 }