Skip to content

Refactor Sui guide #316

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
May 29, 2024
Merged

Refactor Sui guide #316

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
12c721e
initial commit
aditya520 May 27, 2024
c7a0153
tiny improvements
aditya520 May 29, 2024
86db063
updated addresses
aditya520 May 29, 2024
6a88532
requested changes
aditya520 May 29, 2024
f8d7d79
requested changes
aditya520 May 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
284 changes: 108 additions & 176 deletions pages/price-feeds/use-real-time-data/sui.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,82 +1,124 @@
# Pyth on Sui
import { Callout, Tabs } from "nextra/components";

Pyth price feeds on Sui are uniquely represented in the global store as `PriceInfoObjects`. These objects have the `key` ability and serve as wrappers around the `PriceInfo` object, which in turn contains the price info: namely the `PriceFeed`, the arrival time of the latest price update, and the attestation time of the latest update.
# How to Use Real-Time Data in Sui Contracts

`PriceInfoObject`s are central to Pyth on Sui, since they are in unique correspondence with each Pyth price feed and must be passed in to functions that update price feeds or which query info about price feeds, e.g.
This guide explains how to use real-time Pyth data in Sui applications.

- `update_single_price_feed`
- `update_single_price_feeds_if_fresh`
- `get_price`
## Install Pyth SDK

## How to Update and Consume Price Feeds
Use the following dependency in your `Move.toml` file to use the latest Pyth Sui package and its dependencies:

We provide a javascript sdk to use for constructing transaction blocks which updates price feeds.
<Tabs items={['Sui Mainnet', 'Sui Testnet','Movement M2 devnet']}>
<Tabs.Tab>
```sh copy
[dependencies.Pyth]
git = "https://github.com/pyth-network/pyth-crosschain.git"
subdir = "target_chains/sui/contracts"
rev = "sui-contract-mainnet"

[dependencies.Wormhole]
git = "https://github.com/wormhole-foundation/wormhole.git"
subdir = "sui/wormhole"
rev = "sui-upgrade-mainnet"

### Installation
# Pyth is locked into this specific `rev` because our package depends on Wormhole and is pinned to this version.

If you are using npm run:
[dependencies.Sui]
git = "https://github.com/MystenLabs/sui.git"
subdir = "crates/sui-framework/packages/sui-framework"
rev = "041c5f2bae2fe52079e44b70514333532d69f4e6"

````
</Tabs.Tab>
<Tabs.Tab>
```sh copy
npm install --save @pythnetwork/pyth-sui-js
```
[dependencies.Pyth]
git = "https://github.com/pyth-network/pyth-crosschain.git"
subdir = "target_chains/sui/contracts"
rev = "sui-contract-testnet"

[dependencies.Wormhole]
git = "https://github.com/wormhole-foundation/wormhole.git"
subdir = "sui/wormhole"
rev = "sui-upgrade-testnet"

If you are using yarn run:
# Pyth is locked into this specific `rev` because our package depends on Wormhole and is pinned to this version.
[dependencies.Sui]
git = "https://github.com/MystenLabs/sui.git"
subdir = "crates/sui-framework/packages/sui-framework"
rev = "041c5f2bae2fe52079e44b70514333532d69f4e6"
````

</Tabs.Tab>

<Tabs.Tab>
```sh copy
yarn add @pythnetwork/pyth-sui-js
```
[dependencies.Pyth]
git = "https://github.com/pyth-network/pyth-crosschain.git"
subdir = "target_chains/sui/contracts"
rev = "sui-contract-movement-m2-devnet"

## Quickstart
[dependencies.Wormhole]
git = "https://github.com/pyth-network/pyth-crosschain.git"
subdir = "target_chains/sui/vendor/wormhole_movement_devnet/wormhole"
rev = "sui-contract-movement-m2-devnet"

Pyth stores prices off-chain to minimize gas fees, which allows us to offer a wider selection of products and faster update times.
See [Pull Updates](../pythnet-price-feeds/pull-updates) for more information about this approach.
Typically, to use Pyth prices on chain,
they must be fetched from the [Hermes API](https://hermes.pyth.network/docs). The `SuiPriceServiceConnection` class can be used to interact with these services,
providing a way to fetch these prices directly in your code. The following example wraps an existing RPC provider and shows how to obtain
Pyth prices and submit them to the network:
# Pyth is locked into this specific `rev` because our package depends on Wormhole and is pinned to this version.

```typescript copy
import { SuiPriceServiceConnection } from "@pythnetwork/pyth-sui-js";
[dependencies.Sui]
git = "https://github.com/MystenLabs/sui.git"
subdir = "crates/sui-framework/packages/sui-framework"
rev = "041c5f2bae2fe52079e44b70514333532d69f4e6"

const connection = new SuiPriceServiceConnection(
"https://hermes-beta.pyth.network"
); // See Hermes endpoints section below for other endpoints
````

const priceIds = [
// You can find the ids of prices at https://pyth.network/developers/price-feed-ids
"0xf9c0172ba10dfa4d19088d94f5bf61d3b54d5bd7483a322a982e1373ee8ea31b", // BTC/USD price id in testnet
"0xca80ba6dc32e08d06f1aa886011eed1d77c77be9eb761cc10d72b7d0a2fd57a6", // ETH/USD price id in testnet
];
</Tabs.Tab>
</Tabs>

// In order to use Pyth prices in your protocol you need to submit the price update data to Pyth contract in your target
// chain. `getPriceUpdateData` creates the update data which can be submitted to your contract.
Pyth also provides a javascript SDK to construct transaction blocks that update price feeds:

const priceUpdateData = await connection.getPriceFeedsUpdateData(priceIds);
```
<Tabs items={["npm", "yarn"]}>
<Tabs.Tab>
```sh copy npm install --save @pythnetwork/pyth-sui-js ```
</Tabs.Tab>
<Tabs.Tab>```sh copy yarn add @pythnetwork/pyth-sui-js ```</Tabs.Tab>
</Tabs>

## On-chain prices
## Write Contract Code

### ⚠️ **_Important Note for Integrators_**
<Callout type="warning" emoji="⚠️">

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this callout should come after the code snippet.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is pretty important piece of information, so I believe the callout should be before the code snippet.

Your Sui Move module **should NOT** have a hard-coded call to `pyth::update_single_price_feed`. In other words, the Sui Pyth `pyth::update_single_price_feed` entry point should never be called by a contract, instead it should be called directly from client code (e.g. Typescript or Rust).
Your Sui Move module **should NOT** have a hard-coded call to `pyth::update_single_price_feed.` In other words, a contract should **never call** the Sui Pyth `pyth::update_single_price_feed` entry point. Instead, it should be called directly from client code (e.g., Typescript or Rust).

This is because when a Sui contract is [upgraded](https://docs.sui.io/build/package-upgrades), the new address is different from the original. If your module has a hard-coded call to `pyth::update_single_price_feed` living at a fixed call-site, it may eventually get bricked due to the way Pyth upgrades are implemented. (We only allows users to interact with the most recent package version for security reasons).
When Sui contracts are [upgraded](<(https://docs.sui.io/build/package-upgrades)>), the address changes, which makes the old address no longer valid. If your module has a hard-coded call to `pyth::update_single_price_feed` living at a fixed call-site, it may eventually get bricked due to how Pyth upgrades are implemented. (We only allow users to interact with the most recent package version for security reasons).

Therefore, you should build a [Sui programmable transaction](https://docs.sui.io/build/prog-trans-ts-sdk) that first updates the price by calling `pyth::update_single_price_feed` at the latest call-site from the client-side and then call a function in your contract that invokes `pyth::get_price` on the `PriceInfoObject` to get the recently updated price.
You can use `SuiPythClient` to build such transactions and handles all the complexity of updating the price feeds.
You can use `SuiPythClient` to build such transactions and handle all the complexity of updating the price feeds.

Consult [Fetch Price Updates](../fetch-price-updates) for more information on how to fetch the `pyth_price_update`.

</Callout>

### Update Example
The code snippet below provides an example of how to update the Pyth price feeds:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the organization of these code snippets is confusing. Most of our guides have the contract code first, then they don't have the client code at all. In this case, maybe the contract code first, then the client code as a separate section (sort of how we used to have it before?)

Copy link
Member Author

@aditya520 aditya520 May 29, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, but especially for sui, it is recommended not to update the price from the contract, I believe we keep this flow.

```ts copy
import { SuiPythClient } from "@pythnetwork/pyth-sui-js";
import { SuiPriceServiceConnection, SuiPythClient } from "@pythnetwork/pyth-sui-js";
import { TransactionBlock } from "@mysten/sui.js";

const priceUpdateData = await connection.getPriceFeedsUpdateData(priceIds); // see quickstart section
// Get the Stable Hermes service URL from https://docs.pyth.network/price-feeds/api-instances-and-providers/hermes
const connection = new SuiPriceServiceConnection("https://hermes-beta.pyth.network");

const priceIds = [
// You can find the IDs of prices at https://pyth.network/developers/price-feed-ids
"0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43", // BTC/USD price ID
"0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace", // ETH/USD price ID
];

const priceUpdateData = await connection.getPriceFeedsUpdateData(priceIds);

// It is either injected from browser or instantiated in backend via some private key
// It is either injected from the browser or instantiated in the backend via some private key
const wallet: SignerWithProvider = getWallet();
// Get the state ids of the Pyth and Wormhole contracts from
// Get the state IDs of the Pyth and Wormhole contracts from
// https://docs.pyth.network/price-feeds/contract-addresses/sui
const wormholeStateId = " 0xFILL_ME";
const pythStateId = "0xFILL_ME";
Expand All @@ -103,12 +145,12 @@ const txBlock = {
};

const result = await wallet.signAndExecuteTransactionBlock(txBlock);
```
````

By calling the `updatePriceFeeds` function, the `SuiPythClient` adds the necessary transactions to the transaction block to update the price feeds.
Now in your contract you can consume the price by calling `pyth::get_price` or other utility functions on the `PriceInfoObject`:
Now, one can consume the price by calling `pyth::get_price` or other utility functions on the `PriceInfoObject` in the Move module:

```rust copy
```rust {20} copy
module pyth_example::main {
use sui::clock::Clock;
use pyth::price_info;
Expand All @@ -121,98 +163,40 @@ module pyth_example::main {
const E_INVALID_ID: u64 = 1;

public fun use_pyth_price(
// other arguments
// Other arguments
clock: &Clock,
pyth_state: &PythState,
price_info_object: &PriceInfoObject,
){
let max_age = 60;
// make sure the price is not older than max_age seconds
// Make sure the price is not older than max_age seconds
let price_struct = pyth::get_price(pyth_state,price_info_object, clock);

// check the price feed id
// Check the price feed ID
let price_info = price_info::get_price_info_from_price_info_object(price_info_object);
let price_id = price_identifier::get_bytes(&price_info::get_price_identifier(&price_info));
// ETH/USD price feed id

// ETH/USD price feed ID
// The complete list of feed IDs is available at https://pyth.network/developers/price-feed-ids
// Note: Sui uses the Pyth price feed ID without the `0x` prefix.
assert!(price_id!=x"ff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace", E_INVALID_ID);

// extract the price, decimal, and timestamp from the price struct and use them
// Extract the price, decimal, and timestamp from the price struct and use them
let decimal_i64 = price::get_expo(&price_struct);
let price_i64 = price::get_price(&price_struct);
let timestamp_sec = price::get_timestamp(&price_struct);
}
}
```

### Pyth Dependency

Use the following dependency in your `Move.toml` file to use the latest Pyth Sui package and its dependencies.

Sui Mainnet:

```sh copy
[dependencies.Pyth]
git = "https://github.com/pyth-network/pyth-crosschain.git"
subdir = "target_chains/sui/contracts"
rev = "sui-contract-mainnet"

[dependencies.Wormhole]
git = "https://github.com/wormhole-foundation/wormhole.git"
subdir = "sui/wormhole"
rev = "sui-upgrade-mainnet"

[dependencies.Sui]
git = "https://github.com/MystenLabs/sui.git"
subdir = "crates/sui-framework/packages/sui-framework"
rev = "041c5f2bae2fe52079e44b70514333532d69f4e6"
```

Sui Testnet:

```sh copy
[dependencies.Pyth]
git = "https://github.com/pyth-network/pyth-crosschain.git"
subdir = "target_chains/sui/contracts"
rev = "sui-contract-testnet"

[dependencies.Wormhole]
git = "https://github.com/wormhole-foundation/wormhole.git"
subdir = "sui/wormhole"
rev = "sui-upgrade-testnet"

[dependencies.Sui]
git = "https://github.com/MystenLabs/sui.git"
subdir = "crates/sui-framework/packages/sui-framework"
rev = "041c5f2bae2fe52079e44b70514333532d69f4e6"
```

Movement M2 devnet:

```sh copy
[dependencies.Pyth]
git = "https://github.com/pyth-network/pyth-crosschain.git"
subdir = "target_chains/sui/contracts"
rev = "sui-contract-movement-m2-devnet"

[dependencies.Wormhole]
git = "https://github.com/pyth-network/pyth-crosschain.git"
subdir = "target_chains/sui/vendor/wormhole_movement_devnet/wormhole"
rev = "sui-contract-movement-m2-devnet"

[dependencies.Sui]
git = "https://github.com/MystenLabs/sui.git"
subdir = "crates/sui-framework/packages/sui-framework"
rev = "041c5f2bae2fe52079e44b70514333532d69f4e6"
```

### CLI Example

[This example](./src/examples/SuiRelay.ts) shows how to update prices on an Sui network. It does the following:
[This example](https://github.com/pyth-network/pyth-crosschain/tree/main/target_chains/sui/cli) shows how to update prices on a Sui network. It does the following:

1. Fetches update data from Hermes for the given price feeds.
2. Calls the Pyth Sui contract with the update data.
1. Call the Pyth Sui contract with a price update.

You can run this example with `npm run example-relay`. A full command that updates prices on Sui testnet looks like:
You can run this example with `npm run example-relay`. A full command that updates prices on the Sui testnet looks like this:

```bash
export SUI_KEY=YOUR_PRIV_KEY;
Expand All @@ -223,66 +207,14 @@ npm run example-relay -- --feed-id "5a035d5440f5c163069af66062bac6c79377bf88396f
--wormhole-state-id "0x31358d198147da50db32eda2562951d53973a0c0ad5ed738e9b17d88b213d790"
```

## Off-chain prices

Many applications additionally need to display Pyth prices off-chain, for example, in their frontend application.
The `SuiPriceServiceConnection` provides two different ways to fetch the current Pyth price.
The code blocks below assume that the `connection` and `priceIds` objects have been initialized as shown above.
The first method is a single-shot query:

```typescript
// `getLatestPriceFeeds` returns a `PriceFeed` for each price id. It contains all information about a price and has
// utility functions to get the current and exponentially-weighted moving average price, and other functionality.
const priceFeeds = await connection.getLatestPriceFeeds(priceIds);
// Get the price if it is not older than 60 seconds from the current time.
console.log(priceFeeds[0].getPriceNoOlderThan(60)); // Price { conf: '1234', expo: -8, price: '12345678' }
// Get the exponentially-weighted moving average price if it is not older than 60 seconds from the current time.
console.log(priceFeeds[1].getEmaPriceNoOlderThan(60));
```
## Additional Resources

The object also supports a streaming websocket connection that allows you to subscribe to every new price update for a given feed.
This method is useful if you want to show continuously updating real-time prices in your frontend:
You may find these additional resources helpful for developing your Sui application.

```typescript
// Subscribe to the price feeds given by `priceId`. The callback will be invoked every time the requested feed
// gets a price update.
connection.subscribePriceFeedUpdates(priceIds, (priceFeed) => {
console.log(
`Received update for ${priceFeed.id}: ${priceFeed.getPriceNoOlderThan(60)}`
);
});

// When using the subscription, make sure to close the websocket upon termination to finish the process gracefully.
setTimeout(() => {
connection.closeWebSocket();
}, 60000);
```

## [Hermes endpoints](hermes#public-endpoints)

## Contract Addresses

Developers will need the Pyth package IDs in order to use Pyth.
Please consult [Sui Contract Addresses](../contract-addresses/sui) to find the package IDs for your blockchain.

## Common Questions on How to Integrate with Pyth on Sui

### What is up with the "sui rev"? Why does it point to a specific commit hash instead of "main" or "devnet"?

Our Pyth `Move.toml` depends on specific versions of the [Sui Framework](https://github.com/MystenLabs/sui) as well as [Wormhole](https://github.com/wormhole-foundation/wormhole).
To make your Sui package compatible, you must also specify the following dependencies verbatim in your `Move.toml` file. We are locked in to this specific `rev` because our package depends on Wormhole and it is pinned to this
version.

```sh copy
[dependencies.Sui]
git = "https://github.com/MystenLabs/sui.git"
subdir = "crates/sui-framework/packages/sui-framework"
rev = "041c5f2bae2fe52079e44b70514333532d69f4e6"
```
### Contract Addresses

### How do I find the Sui Object ID of a PriceInfoObject for a Pyth Price Feed?
Consult [Sui Contract Addresses](../contract-addresses/sui) to find the package IDs.

You can use the `getPriceFeedObjectId` function in the js sdk to fetch the object ids.
This mapping is also stored on-chain, and can be queried on-chain using the getter function `pyth::state::get_price_info_object_id` defined in the Pyth package.
### Pyth Price Feed IDs

Also recall that the list of Pyth price feed IDs can be found [here](https://pyth.network/developers/price-feed-ids).
Consult [Pyth Price Feed IDs](https://pyth.network/developers/price-feed-ids) to find Pyth price feed IDs for various assets.
Loading