@zofai/zo-sdk 0.2.14 → 0.2.16

package/src/storkClient.ts

@@ -0,0 +1,328 @@
+/** Kronos Stork price REST client + update payload parsing. */
+
+export interface IStorkEvmSignature {
+  r: string
+  s: string
+  v: string | number
+}
+
+export interface IStorkSignedPrice {
+  public_key?: string
+  encoded_asset_id?: string
+  /** Stork quantized price used for on-chain signature verification. */
+  quantized_price?: string
+  price?: string
+  timestamped_signature?: {
+    timestamp?: number | string
+    /** Nanosecond timestamp used for on-chain updates (preferred). */
+    timestamp_nano?: number | string
+    signature?: IStorkEvmSignature
+    msg_hash?: string
+  }
+  publisher_merkle_root?: string
+  calculation_alg?: {
+    type?: string
+    version?: string
+    checksum?: string
+  }
+}
+
+export interface IStorkKronosPriceEntry {
+  asset_id: string
+  price: string
+  priceUsd?: number
+  timestamp?: number
+  signature_type?: string
+  stork_signed_price?: IStorkSignedPrice
+  signed_prices?: unknown[]
+  /** Pre-parsed on-chain update payload from kronos (preferred). */
+  update_data?: IStorkUpdateDataRaw
+}
+
+export interface IStorkUpdateDataRaw {
+  id?: string | number[]
+  temporal_numeric_value_timestamp_ns?: number | string
+  temporal_numeric_value_magnitude?: string | number
+  temporal_numeric_value_negative?: boolean
+  publisher_merkle_root?: string | number[]
+  value_compute_alg_hash?: string | number[]
+  r?: string | number[]
+  s?: string | number[]
+  v?: number | string
+}
+
+/** Normalized update payload for Stork Move calls. */
+export interface IStorkUpdateData {
+  id: Uint8Array
+  temporalNumericValueTimestampNs: bigint
+  temporalNumericValueMagnitude: bigint
+  temporalNumericValueNegative: boolean
+  publisherMerkleRoot: Uint8Array
+  valueComputeAlgHash: Uint8Array
+  r: Uint8Array
+  s: Uint8Array
+  v: number
+}
+
+export interface IStorkLatestPriceData {
+  prices: Record<string, IStorkKronosPriceEntry>
+}
+
+export interface IStorkLatestPriceResponse {
+  success: boolean
+  timestamp?: string
+  data?: IStorkLatestPriceData
+  message?: string
+}
+
+export interface IGetLatestStorkPricesOptions {
+  assets: string[]
+  /** Override kronos REST base URL. */
+  kronosUrl?: string
+}
+
+function normalizeBaseUrl(baseUrl: string): string {
+  return baseUrl.replace(/\/+$/, '')
+}
+
+function parseLatestStorkResponse(json: IStorkLatestPriceResponse): IStorkLatestPriceData {
+  if (!json.success || !json.data) {
+    throw new Error(json.message ?? 'Stork latest-price request failed')
+  }
+  return json.data
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  const normalized = hex.startsWith('0x') ? hex.slice(2) : hex
+  if (normalized.length % 2 !== 0) {
+    throw new Error(`Invalid hex length: ${hex}`)
+  }
+  const bytes = new Uint8Array(normalized.length / 2)
+  for (let i = 0; i < normalized.length; i += 2) {
+    bytes[i / 2] = Number.parseInt(normalized.slice(i, i + 2), 16)
+  }
+  return bytes
+}
+
+export function base64ToBytes(base64: string): Uint8Array {
+  const normalized = base64.replaceAll('-', '+').replaceAll('_', '/')
+  const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4)
+  const binary = atob(padded)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i)
+  }
+  return bytes
+}
+
+function toBytes(value: string | number[] | Uint8Array | undefined, field: string): Uint8Array {
+  if (value === undefined || value === null) {
+    throw new Error(`Missing Stork field: ${field}`)
+  }
+  if (value instanceof Uint8Array) {
+    return value
+  }
+  if (Array.isArray(value)) {
+    return Uint8Array.from(value)
+  }
+  if (value.startsWith('0x') || /^[0-9a-f]+$/i.test(value)) {
+    return hexToBytes(value)
+  }
+  return base64ToBytes(value)
+}
+
+function toBigInt(value: string | number | bigint | undefined | null): bigint {
+  if (value === undefined || value === null) {
+    return 0n
+  }
+  if (typeof value === 'bigint') {
+    return value
+  }
+  if (typeof value === 'string') {
+    return BigInt(value)
+  }
+  // `value` is already a float64 at this point — any u64 > 2^53 has already lost
+  // precision before reaching here. String(n) round-trips the truncated float64,
+  // not the original integer. Callers should pass string timestamps from the API
+  // to avoid this loss.
+  return BigInt(String(value))
+}
+
+function parseV(value: string | number): number {
+  if (typeof value === 'number') {
+    return value
+  }
+  const bytes = toBytes(value, 'v')
+  if (bytes.length > 0) {
+    return bytes[0]!
+  }
+  if (value.startsWith('0x')) {
+    return Number.parseInt(value, 16)
+  }
+  return Number.parseInt(value, 10)
+}
+
+export function parseStorkUpdateDataRaw(raw: IStorkUpdateDataRaw): IStorkUpdateData {
+  const id = toBytes(raw.id, 'id')
+  if (id.length !== 32) {
+    throw new Error(`Stork update id must be 32 bytes, got ${id.length}`)
+  }
+
+  return {
+    id,
+    temporalNumericValueTimestampNs: toBigInt(raw.temporal_numeric_value_timestamp_ns),
+    temporalNumericValueMagnitude: toBigInt(raw.temporal_numeric_value_magnitude),
+    temporalNumericValueNegative: raw.temporal_numeric_value_negative ?? false,
+    publisherMerkleRoot: toBytes(raw.publisher_merkle_root, 'publisher_merkle_root'),
+    valueComputeAlgHash: toBytes(raw.value_compute_alg_hash, 'value_compute_alg_hash'),
+    r: toBytes(raw.r, 'r'),
+    s: toBytes(raw.s, 's'),
+    v: parseV(raw.v ?? 0),
+  }
+}
+
+function parseQuantizedPrice(value: string): { magnitude: bigint, negative: boolean } {
+  let price = BigInt(value)
+  const negative = price < 0n
+  if (negative) {
+    price = -price
+  }
+  return { magnitude: price, negative }
+}
+
+/** Build on-chain update data from kronos / Stork REST signed price payload. */
+export function buildStorkUpdateDataFromSignedPrice(
+  entry: IStorkKronosPriceEntry,
+  /** Fallback 32-byte feeder id when `encoded_asset_id` is absent. */
+  feederId?: Uint8Array,
+): IStorkUpdateData | null {
+  const signed = entry.stork_signed_price
+  if (signed?.timestamped_signature?.signature) {
+    const checksum = signed.calculation_alg?.checksum
+    if (!checksum) {
+      return null
+    }
+
+    const quantizedPrice = signed.quantized_price ?? signed.price ?? entry.price
+    if (!quantizedPrice) {
+      return null
+    }
+
+    const assetId = signed.encoded_asset_id
+    if (!assetId && !feederId) {
+      return null
+    }
+
+    const { magnitude, negative } = parseQuantizedPrice(String(quantizedPrice))
+
+    // Nanosecond timestamps for dates in 2026+ (~1.78e18 ns) exceed float64 safe-integer
+    // range (2^53 ≈ 9e15). JSON.parse silently truncates them by up to ±127 ns (precision
+    // step = 256 at this scale), causing get_stork_message_hash to produce the wrong value
+    // and ecrecover to fail → EInvalidSignature (error code 0).
+    // Prefer string sources; fall back to update_data.temporal_numeric_value_timestamp_ns
+    // (a string in kronos pre-parsed payloads) when stork_signed_price only has a number.
+    const rawTimestampNs = signed.timestamped_signature.timestamp_nano
+      ?? signed.timestamped_signature.timestamp
+      ?? entry.timestamp
+    const timestampNs = (
+      typeof rawTimestampNs === 'number'
+      && typeof entry.update_data?.temporal_numeric_value_timestamp_ns === 'string'
+    )
+      ? entry.update_data.temporal_numeric_value_timestamp_ns
+      : rawTimestampNs
+
+    const id = assetId
+      ? toBytes(assetId, 'encoded_asset_id')
+      : feederId!
+
+    return {
+      id,
+      temporalNumericValueTimestampNs: toBigInt(timestampNs),
+      temporalNumericValueMagnitude: magnitude,
+      temporalNumericValueNegative: negative,
+      publisherMerkleRoot: toBytes(signed.publisher_merkle_root, 'publisher_merkle_root'),
+      valueComputeAlgHash: toBytes(checksum, 'value_compute_alg_hash'),
+      r: toBytes(signed.timestamped_signature.signature.r, 'r'),
+      s: toBytes(signed.timestamped_signature.signature.s, 's'),
+      v: parseV(signed.timestamped_signature.signature.v),
+    }
+  }
+
+  if (entry.update_data) {
+    return parseStorkUpdateDataRaw(entry.update_data)
+  }
+
+  return null
+}
+
+export function parseStorkUpdateDataList(
+  data: IStorkLatestPriceData,
+  /** Stork asset symbol → 32-byte on-chain feeder id from zo-oracle config. */
+  assetIdByAsset?: Map<string, Uint8Array>,
+): IStorkUpdateData[] {
+  const updates: IStorkUpdateData[] = []
+  for (const entry of Object.values(data.prices)) {
+    const feederId = assetIdByAsset?.get(entry.asset_id)
+    const update = buildStorkUpdateDataFromSignedPrice(entry, feederId)
+    if (update) {
+      if (update.id.length !== 32) {
+        throw new Error(
+          `Stork asset ${entry.asset_id}: id must be 32 bytes (got ${update.id.length}); `
+          + 'pass assetIdByAsset from buildStorkAssetIdMap()',
+        )
+      }
+      updates.push(update)
+    }
+  }
+  return updates
+}
+
+/**
+ * Fetch latest Stork prices from kronos REST (`GET` or `POST /stork/latest-price`).
+ */
+export async function getLatestStorkPrices(
+  baseUrl: string,
+  options: IGetLatestStorkPricesOptions,
+): Promise<IStorkLatestPriceData> {
+  const { assets } = options
+  if (assets.length === 0) {
+    throw new Error('assets is required')
+  }
+
+  const root = normalizeBaseUrl(baseUrl)
+
+  if (assets.length <= 20) {
+    const params = new URLSearchParams()
+    params.set('assets', assets.join(','))
+    const res = await fetch(`${root}/stork/latest-price?${params}`)
+    const json = await res.json() as IStorkLatestPriceResponse
+    if (!res.ok && json.message) {
+      throw new Error(json.message)
+    }
+    return parseLatestStorkResponse(json)
+  }
+
+  const res = await fetch(`${root}/stork/latest-price`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ assets }),
+  })
+  const json = await res.json() as IStorkLatestPriceResponse
+  if (!res.ok && json.message) {
+    throw new Error(json.message)
+  }
+  return parseLatestStorkResponse(json)
+}
+
+export async function fetchStorkUpdateDataFromKronos(
+  baseUrl: string,
+  assets: string[],
+  assetIdByAsset?: Map<string, Uint8Array>,
+): Promise<IStorkUpdateData[]> {
+  const data = await getLatestStorkPrices(baseUrl, { assets })
+  const updates = parseStorkUpdateDataList(data, assetIdByAsset)
+  if (updates.length === 0) {
+    throw new Error(`No Stork update data returned for assets: ${assets.join(',')}`)
+  }
+  return updates
+}

package/src/storkOracle.ts

@@ -0,0 +1,82 @@
+import type { TransactionObjectArgument } from '@mysten/sui/transactions'
+import { Transaction } from '@mysten/sui/transactions'
+
+import type { IOracleProConfig } from './consts'
+import type { IStorkUpdateData } from './storkClient'
+
+/** 1 MIST per Stork feed update (matches zo-go-executor). */
+export const STORK_UPDATE_FEE_MIST = 1n
+
+export interface IAppendStorkUpdatesOptions {
+  /** Coin to split update fees from. Defaults to `tx.gas`. */
+  feeSource?: TransactionObjectArgument
+  /** MIST per update. Defaults to 1. */
+  feePerUpdate?: bigint
+}
+
+function bytesToPureVector(bytesList: Uint8Array[]): number[][] {
+  return bytesList.map(bytes => Array.from(bytes))
+}
+
+/**
+ * Append Stork on-chain price updates to an open PTB (before Pyth Pro verify + market op).
+ *
+ * 1. `update_temporal_numeric_value_evm_input_vec::new`
+ * 2. `stork::update_multiple_temporal_numeric_values_evm`
+ */
+export function appendStorkUpdatesToTransaction(
+  tx: Transaction,
+  config: Pick<IOracleProConfig, 'storkPackage' | 'storkState'>,
+  updates: IStorkUpdateData[],
+  options?: IAppendStorkUpdatesOptions,
+): void {
+  if (updates.length === 0) {
+    return
+  }
+
+  const feePerUpdate = options?.feePerUpdate ?? STORK_UPDATE_FEE_MIST
+  const totalFee = feePerUpdate * BigInt(updates.length)
+  const feeSource = options?.feeSource ?? tx.gas
+  const [feeCoin] = tx.splitCoins(feeSource, [tx.pure.u64(totalFee)])
+
+  const ids = bytesToPureVector(updates.map(u => u.id))
+  const timestampNss = updates.map(u => u.temporalNumericValueTimestampNs)
+  const magnitudes = updates.map(u => u.temporalNumericValueMagnitude)
+  const negatives = updates.map(u => u.temporalNumericValueNegative)
+  const publisherMerkleRoots = bytesToPureVector(updates.map(u => u.publisherMerkleRoot))
+  const valueComputeAlgHashes = bytesToPureVector(updates.map(u => u.valueComputeAlgHash))
+  const rs = bytesToPureVector(updates.map(u => u.r))
+  const ss = bytesToPureVector(updates.map(u => u.s))
+  const vs = updates.map(u => u.v)
+
+  const [updateInputVec] = tx.moveCall({
+    target: `${config.storkPackage}::update_temporal_numeric_value_evm_input_vec::new`,
+    arguments: [
+      tx.pure.vector('vector<u8>', ids),
+      tx.pure.vector('u64', timestampNss),
+      tx.pure.vector('u128', magnitudes),
+      tx.pure.vector('bool', negatives),
+      tx.pure.vector('vector<u8>', publisherMerkleRoots),
+      tx.pure.vector('vector<u8>', valueComputeAlgHashes),
+      tx.pure.vector('vector<u8>', rs),
+      tx.pure.vector('vector<u8>', ss),
+      tx.pure.vector('u8', vs),
+    ],
+  })
+
+  tx.moveCall({
+    target: `${config.storkPackage}::stork::update_multiple_temporal_numeric_values_evm`,
+    arguments: [
+      tx.object(config.storkState),
+      updateInputVec,
+      feeCoin,
+    ],
+  })
+}
+
+export function estimateStorkUpdateFeeMist(
+  updateCount: number,
+  feePerUpdate: bigint = STORK_UPDATE_FEE_MIST,
+): bigint {
+  return feePerUpdate * BigInt(updateCount)
+}

package/tests/pythProClient.test.ts

@@ -0,0 +1,155 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import {
+  apiBaseUrlToPythProWsUrl,
+  fetchPythProUpdateBytesFromKronos,
+  getLatestPythProPrices,
+  hexToBytes,
+  PythProStreamClient,
+} from '../src/pythProClient'
+
+describe('pythProClient REST', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('apiBaseUrlToPythProWsUrl converts http to ws', () => {
+    expect(apiBaseUrlToPythProWsUrl('http://localhost:8080/')).toBe('ws://localhost:8080/pyth-pro/stream')
+    expect(apiBaseUrlToPythProWsUrl('https://kronos.example.com/api')).toBe(
+      'wss://kronos.example.com/pyth-pro/stream',
+    )
+  })
+
+  it('getLatestPythProPrices uses GET with comma-separated feed ids', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        success: true,
+        data: {
+          timestampUs: '1',
+          priceFeeds: [{ priceFeedId: 1, price: '100', exponent: -8, confidence: '1', feedUpdateTimestamp: '1', priceUsd: 1 }],
+          leEcdsaHex: null,
+        },
+      }),
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const data = await getLatestPythProPrices('http://localhost:8080', {
+      priceFeedIds: [1, 2],
+      includeEmaPrice: true,
+    })
+
+    expect(data.priceFeeds).toHaveLength(1)
+    expect(fetchMock).toHaveBeenCalledWith(
+      'http://localhost:8080/pyth-pro/latest-price?priceFeedIds=1%2C2&includeEmaPrice=true',
+    )
+  })
+
+  it('fetchPythProUpdateBytesFromKronos decodes leEcdsaHex', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        success: true,
+        data: {
+          timestampUs: '1',
+          priceFeeds: [],
+          leEcdsaHex: '0102ab',
+        },
+      }),
+    }))
+
+    const bytes = await fetchPythProUpdateBytesFromKronos('http://localhost:8080', [1])
+    expect(Array.from(bytes)).toEqual([1, 2, 171])
+    expect(hexToBytes('0x0102ab')).toEqual(bytes)
+  })
+
+  it('throws on kronos error response', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: false,
+      json: async () => ({ success: false, message: 'PYTH_LAZER_ACCESS_TOKEN not configured' }),
+    }))
+
+    await expect(
+      getLatestPythProPrices('http://localhost:8080', { priceFeedIds: [1] }),
+    ).rejects.toThrow('PYTH_LAZER_ACCESS_TOKEN not configured')
+  })
+})
+
+describe('PythProStreamClient', () => {
+  class MockWebSocket {
+    static OPEN = 1
+    readyState = MockWebSocket.OPEN
+    sent: string[] = []
+    private listeners: Record<string, Array<(event: { data?: string }) => void>> = {}
+
+    constructor(public url: string) {
+      queueMicrotask(() => {
+        this.listeners.open?.forEach(cb => cb({}))
+        this.emit({ data: JSON.stringify({ type: 'connected' }) })
+      })
+    }
+
+    addEventListener(event: string, cb: (event: { data?: string }) => void, opts?: { once?: boolean }) {
+      if (!this.listeners[event]) {
+        this.listeners[event] = []
+      }
+      if (opts?.once) {
+        const onceWrapper = (ev: { data?: string }) => {
+          this.listeners[event] = this.listeners[event].filter(h => h !== onceWrapper)
+          cb(ev)
+        }
+        this.listeners[event].push(onceWrapper)
+        return
+      }
+      this.listeners[event].push(cb)
+    }
+
+    send(data: string) {
+      this.sent.push(data)
+    }
+
+    close() {
+      this.readyState = 3
+      this.listeners.close?.forEach(cb => cb({}))
+    }
+
+    emit(event: { data?: string }) {
+      this.listeners.message?.forEach(cb => cb(event))
+    }
+  }
+
+  it('subscribes and forwards streamUpdated', async () => {
+    vi.stubGlobal('WebSocket', MockWebSocket)
+
+    const client = new PythProStreamClient('http://localhost:8080', {
+      WebSocketImpl: MockWebSocket as unknown as typeof WebSocket,
+      pingIntervalMs: 0,
+    })
+
+    const updates: number[] = []
+    client.subscribe(
+      { subscriptionId: 1, priceFeedIds: [1, 2], channel: 'real_time' },
+      (update) => {
+        updates.push(update.priceFeeds[0]?.priceFeedId ?? 0)
+      },
+    )
+
+    await client.connect()
+    await new Promise<void>(resolve => setTimeout(resolve, 0))
+
+    expect((client as any).ws.sent.length).toBeGreaterThan(0)
+    expect(JSON.parse((client as any).ws.sent[0]).type).toBe('subscribe')
+
+    ;(client as any).ws.emit({
+      data: JSON.stringify({
+        type: 'streamUpdated',
+        subscriptionId: 1,
+        timestampUs: '99',
+        priceFeeds: [{ priceFeedId: 42, price: '1', exponent: -8, confidence: '1', feedUpdateTimestamp: '1', priceUsd: 1 }],
+      }),
+    })
+
+    expect(updates).toEqual([42])
+    client.disconnect()
+  })
+})