pyth

name	pyth
description	This skill should be used when the user asks about Pyth Network, Pyth oracle, price feeds on Sui, or wants to integrate Pyth price data into their Move contracts. Covers price feed updates, price queries, governance, and data source management.

Pyth Network on Sui

Pyth Network is a decentralized price oracle that provides real-time price data for crypto assets, equities, forex, and commodities. On Sui, Pyth delivers price feeds via Wormhole-verified VAA (Verifiable Action Approval) messages.

Package Information

• Original Package ID: 0x00b53b0f4174108627fbee72e2498b58d6a2714cded53fac537034c220d26302
• Wormhole dependency: 0x5306f64e312b581766351c07af79c72fcb1cd25147157fdc2f8ad76de9a3fb6a
• Pyth State object: shared state::State object (holds configuration, fee info, data sources)

Architecture Overview

Pyth on Sui uses a pull-based oracle model:

1. Off-chain: A relayer fetches signed price updates (VAAs) from the Pyth network.
2. On-chain: The user submits VAAs in a transaction to create a HotPotatoVector<PriceInfo> (must be consumed in the same transaction).
3. Update: Each price feed is updated individually via update_single_price_feed, which requires paying a fee in SUI.
4. Read: After updating, call get_price, get_price_no_older_than, or get_price_unsafe to read the price.

The hot-potato pattern ensures that price updates are paid for and consumed atomically.

Key Shared Objects

• State -- the singleton Pyth state; passed as &State for reads or &mut State for governance.
• PriceInfoObject -- one per price feed; each is a shared object containing the cached PriceInfo for a specific asset.

Source Files

Decompiled source at: packages/mainnet/0x00/b53b0f4174108627fbee72e2498b58d6a2714cded53fac537034c220d26302/decompiled_modules/

21 modules: pyth, price, price_feed, price_info, price_identifier, price_status, i64, state, hot_potato_vector, data_source, batch_price_attestation, governance, governance_action, governance_instruction, governance_witness, event, contract_upgrade, migrate, setup, deserialize, set, version_control

Module Summary

Module	Purpose
pyth	Main entry points: price queries, feed creation, feed updates
price	Price struct with price value (I64), confidence, exponent, timestamp
price_feed	PriceFeed struct bundling price identifier with current and EMA prices
price_info	PriceInfo and PriceInfoObject -- on-chain cached price data
price_identifier	32-byte identifier for each price feed
price_status	Trading (1) vs Unknown (0) status
i64	Signed 64-bit integer (magnitude + negative flag)
state	Pyth global state: fees, staleness threshold, data sources
hot_potato_vector	Non-storable vector wrapper enforcing consumption in same tx
data_source	Wormhole emitter chain + address pairs for valid data sources

Typical Integration Pattern (PTB)

// 1. Parse Wormhole VAAs
let vaa = wormhole::vaa::parse_and_verify(wormhole_state, raw_vaa, clock);

// 2. Create hot potato with price infos
let hot_potato = pyth::create_price_infos_hot_potato(pyth_state, vector[vaa], clock);

// 3. Update each price feed (pays SUI fee)
let hot_potato = pyth::update_single_price_feed(
    pyth_state, hot_potato, price_info_object, fee_coin, clock
);

// 4. Destroy remaining hot potato
hot_potato_vector::destroy(hot_potato);

// 5. Read the price
let price = pyth::get_price(pyth_state, price_info_object, clock);
// Or with custom staleness check:
let price = pyth::get_price_no_older_than(price_info_object, clock, max_age_secs);

Reading a Price

The Price struct uses I64 for the price value and exponent:

actual_price = price_value * 10^exponent

• price::get_price(&price) returns I64 -- the raw price value
• price::get_expo(&price) returns I64 -- typically negative (e.g., -8 means 8 decimal places)
• price::get_conf(&price) returns u64 -- the confidence interval
• price::get_timestamp(&price) returns u64 -- Unix timestamp in seconds

To interpret I64:

• i64::get_is_negative(&val) returns bool
• i64::get_magnitude_if_positive(&val) returns u64 (aborts if negative)
• i64::get_magnitude_if_negative(&val) returns u64 (aborts if positive)

Error Codes

Code	Meaning
0	Data source chain/address count mismatch
1	Invalid data source for VAA
2	Insufficient fee
3	Price is stale
4	Price identifier mismatch during cache update
5	Price identifier not found in hot potato vector

Related Skills

• sui-framework -- Core Coin, Balance, Clock types
• suilend / navi / scallop -- Lending protocols that consume Pyth prices
• kriya -- Oracle-driven pools using Pyth