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

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

Related Skills

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