Skip to content

Commit d556da5

Browse files
jayantkjayantk
authored
Merge pull request #38 from pyth-network/doc_update2
Update READMEs
2 parents f097f46 + d514a0e commit d556da5

File tree

4 files changed

+158
-156
lines changed

4 files changed

+158
-156
lines changed

‎README.md

Lines changed: 27 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,38 @@
1-
# Pyth SDK
1+
# Pyth Network SDK
22

3-
This repo contains multiple crates for using Pyth Oracle.
4-
1. Pyth SDK: This crate contains general Pyth structures and interfaces which are consistent across different blockchains.
5-
2. Pyth SDK Solana: This crate contains methods for reading and parsing Pyth structures from Pyth Solana accounts.
3+
The Pyth Network Rust SDK provides utilities for reading price feeds from the [pyth.network](https://pyth.network/) oracle in on- and off-chain applications.
4+
5+
Key features of this SDK include:
6+
7+
* Get the current price of over [50 products](https://pyth.network/markets/), including cryptocurrencies,
8+
US equities, forex and more.
9+
* Combine listed products to create new price feeds, e.g., for baskets of tokens or non-USD quote currencies.
10+
* Consume prices in Solana programs, Terra smart contracts, or off-chain applications.
11+
12+
Please see the [pyth.network documentation](https://docs.pyth.network/) for more information about pyth.network.
13+
14+
## Usage
15+
16+
This repository is divided into several crates focused on specific use cases:
17+
18+
1. [Pyth SDK](pyth-sdk) provides common data types and interfaces for that are shared across different blockchains.
19+
2. [Pyth SDK Solana](pyth-sdk-solana) provides an interface for reading Pyth price feeds in Solana programs.
20+
This crate may also be used in off-chain applications that read prices from the Solana blockchain.
21+
3. [Pyth SDK Terra](pyth-sdk-terra) provides an interface for reading Pyth price feeds in on-chain Terra contracts.
22+
23+
Please see the documentation for the relevant crate to get started using Pyth Network.
624

725
## Development
826

9-
These crates can be built for either your native platform or other platforms for specific blockchains.
10-
- Use `cargo build` / `cargo test` to build and test natively.
27+
All crates in this repository can be built for either your native platform or blockchain-specific platforms.
28+
Use `cargo build` / `cargo test` to build and test natively.
1129

12-
### Releases
30+
### Creating a Release
1331

14-
To release new versions of these packages, perform the following steps within the crate being released:
32+
To release a new version of any of these crates, perform the following steps within the crate being released:
1533

1634
1. Increment the version number in `Cargo.toml`.
1735
You may use a version number with a `-beta.x` suffix such as `0.0.1-beta.0` to create opt-in test versions.
1836
2. Merge your change into `main` on github.
1937
3. Create and publish a new github release.
38+
We currently don't have a Github Action to automatically push releases to [crates.io](https://crates.io), but should set one up.

‎pyth-sdk-solana/README.md

Lines changed: 26 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,7 @@
1-
# Pyth SDK Solana
1+
# Pyth Network Solana SDK
22

33
This crate provides utilities for reading price feeds from the [pyth.network](https://pyth.network/) oracle on the Solana network.
4-
The crate includes a library for reading and using Pyth data feeds in Solana both on-chain (Solana programs) and off-chain (clients interacting with Solana blockchain). It also includes multiple off-chain example programs.
5-
6-
Key features of this library include:
7-
8-
* Get the current price of over [50 products](https://pyth.network/markets/), including cryptocurrencies,
9-
US equities, forex and more.
10-
* Combine listed products to create new price feeds, e.g., for baskets of tokens or non-USD quote currencies.
11-
* Consume prices in on-chain Solana programs or off-chain applications.
12-
13-
Please see the [pyth.network documentation](https://docs.pyth.network/) for more information about pyth.network.
4+
It also includes several [off-chain example programs](examples/).
145

156
## Installation
167

@@ -30,96 +21,51 @@ Pyth Network stores its price feeds in a collection of Solana accounts of variou
3021
* Product accounts store metadata about a product, such as its symbol (e.g., "BTC/USD").
3122
* Mapping accounts store a listing of all Pyth accounts
3223

33-
> :warning: This structure is designed for Pyth Oracle internal program. In most of the use cases only Price account is needed.
34-
35-
For more information on the different types of Pyth accounts, see the [account structure documentation](https://docs.pyth.network/how-pyth-works/account-structure).
36-
The pyth.network website also lists the public keys of the accounts (e.g., [Crypto.BTC/USD accounts](https://pyth.network/markets/#Crypto.BTC/USD)).
37-
38-
This crate provides utilities for interpreting and manipulating the content of these accounts.
24+
Most users of this SDK only need to access the content of price accounts; the other two account types are implementation details of the oracle.
3925
Applications can obtain the content of these accounts in two different ways:
4026
* On-chain programs should pass these accounts to the instructions that require price feeds.
4127
* Off-chain programs can access these accounts using the Solana RPC client (as in the [eth price example program](examples/eth_price.rs)).
4228

43-
In both cases, the content of the account will be provided to the application as a binary blob (`Vec<u8>`).
44-
The examples below assume that the user has already obtained this account data.
45-
46-
### Parse price data
47-
Each price feed (e.g: `Crypto.BTC/USD`) is stored in a Solana price account.
48-
You can find price accounts in the pyth.network website (e.g.: [Crypto.BTC/USD accounts](https://pyth.network/markets/#Crypto.BTC/USD)).
49-
50-
The `Price` struct contains several useful functions for working with the price.
51-
Some of these functions are described below.
52-
For more detailed information, please see the crate documentation.
29+
The pyth.network website can be used to identify the public keys of the various Pyth Network accounts (e.g., [Crypto.BTC/USD accounts](https://pyth.network/markets/#Crypto.BTC/USD)).
5330

54-
#### On-chain
31+
### On-chain
5532

56-
To read the price from a price account on-chain, this library provides a `load_price_from_account_info` method that constructs `Price` struct from AccountInfo:
33+
On-chain applications should pass the relevant Pyth Network price account to the Solana instruction that consumes it.
34+
This price account will be represented as an `AccountInfo` in the code for the Solana instruction.
35+
The `load_price_feed_from_account_info` function will construct a `PriceFeed` struct from `AccountInfo`:
5736

5837
```rust
5938
use pyth_sdk_solana::{load_price_feed_from_account_info, PriceFeed};
6039

6140
let price_account_info: AccountInfo = ...;
62-
let price: PriceFeed = load_price_feed_from_account_info( &price_account_info ).unwrap();
41+
let price_feed: PriceFeed = load_price_feed_from_account_info( &price_account_info ).unwrap();
42+
let current_price: Price = price_feed.get_current_price().unwrap();
43+
println!("price: ({} +- {}) x 10^{}", current_price.price, current_price.conf, current_price.expo);
6344
```
6445

65-
#### Off-chain
66-
To read the price from a price account off-chain in clients, this library provides a `load_price_from_account` method that constructs `Price` struct from Account:
46+
The `PriceFeed` object returned by `load_price_feed_from_account_info` contains all currently-available pricing information about the product.
47+
This struct also has some useful functions for manipulating and combining prices; see the [common SDK documentation](../pyth-sdk) for more details.
48+
49+
Note that your application should also validate the address of the passed-in price account before using it.
50+
Otherwise, an attacker could pass in a different account and set the price to an arbitrary value.
51+
52+
### Off-chain
53+
54+
Off-chain applications can read the current value of a Pyth Network price account using the Solana RPC client.
55+
This client will return the content of the account as an `Account` struct.
56+
The `load_price_feed_from_account` function will construct a `PriceFeed` struct from `Account`:
6757

6858
```rust
6959
use pyth_sdk_solana::{load_price_feed_from_account, PriceFeed};
7060

7161
let price_key: Pubkey = ...;
7262
let mut price_account: Account = ...;
73-
let price: PriceFeed = load_price_feed_from_account( &price_key, &mut price_account ).unwrap();
74-
```
75-
76-
### Get the current price
77-
78-
Read the current price from a `PriceFeed`:
79-
80-
```rust
63+
let price_feed: PriceFeed = load_price_feed_from_account( &price_key, &mut price_account ).unwrap();
8164
let current_price: Price = price_feed.get_current_price().unwrap();
8265
println!("price: ({} +- {}) x 10^{}", current_price.price, current_price.conf, current_price.expo);
8366
```
8467

85-
The price is returned along with a confidence interval that represents the degree of uncertainty in the price.
86-
Both values are represented as fixed-point numbers, `a * 10^e`.
87-
The method will return `None` if the price is not currently available.
88-
89-
### Non-USD prices
90-
91-
Most assets in Pyth are priced in USD.
92-
Applications can combine two USD prices to price an asset in a different quote currency:
93-
94-
```rust
95-
let btc_usd: Price = ...;
96-
let eth_usd: Price = ...;
97-
// -8 is the desired exponent for the result
98-
let btc_eth: Price = btc_usd.get_price_in_quote(&eth_usd, -8);
99-
println!("BTC/ETH price: ({} +- {}) x 10^{}", price.price, price.conf, price.expo);
100-
```
101-
102-
### Price a basket of assets
103-
104-
Applications can also compute the value of a basket of multiple assets:
105-
106-
```rust
107-
let btc_usd: Price = ...;
108-
let eth_usd: Price = ...;
109-
// Quantity of each asset in fixed-point a * 10^e.
110-
// This represents 0.1 BTC and .05 ETH.
111-
// -8 is desired exponent for result
112-
let basket_price: Price = Price::price_basket(&[
113-
(btc_usd, 10, -2),
114-
(eth_usd, 5, -2)
115-
], -8);
116-
println!("0.1 BTC and 0.05 ETH are worth: ({} +- {}) x 10^{} USD",
117-
basket_price.price, basket_price.conf, basket_price.expo);
118-
```
119-
120-
This function additionally propagates any uncertainty in the price into uncertainty in the value of the basket.
121-
122-
### Solana Account Structure
68+
## Low-Level Solana Account Structure
12369

12470
> :warning: The Solana account structure is an internal API that is subject to change. Prefer to use `load_price_feed_*` when possible.
12571
@@ -139,8 +85,9 @@ let mapping_account_data: Vec<u8> = ...;
13985
let mapping_account: &MappingAccount = load_mapping_account( &mapping_account_data ).unwrap();
14086
```
14187

88+
For more information on the different types of Pyth accounts, see the [account structure documentation](https://docs.pyth.network/how-pyth-works/account-structure).
14289

143-
### Off-chain example program
90+
## Off-chain Example Programs
14491

14592
The example [eth_price](examples/eth_price.rs) program prints the product reference data and current price information for Pyth on Solana devnet.
14693
Run the following commands to try this example program:

‎pyth-sdk-terra/README.md

Lines changed: 29 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,44 @@
1-
# Pyth SDK Terra
1+
# Pyth Network Terra SDK
22

33
This crate provides utilities for reading price feeds from the [pyth.network](https://pyth.network/) oracle on the Terra network.
4-
The crate includes a library for reading and using Pyth data feeds in Terra.
4+
It also includes an [example contract](../examples/terra-contract/) demonstrating how to read price feeds from on-chain Terra applications.
55

6-
## Usage
7-
8-
> :grey_exclamation: Please follow [consumer best practices](https://docs.pyth.network/consumers/best-practices) when consuming Pyth data.
9-
10-
### Read price
6+
## Installation
117

12-
For reading the price you just need to call `query_price_feed` function within your contract with the id of the price feed.
8+
Add this crate to the dependencies section of your Terra contract's `Cargo.toml` file:
139

14-
You can find the contract address and price feed ids in the section [Contracts and Price Feeds](#contracts-and-price-feeds) below.
15-
16-
```rust
17-
let price_feed: PriceFeed = query_price_feed(deps.querier, contract_addr, id)?.price_feed;
1810
```
19-
20-
### Example contract
21-
22-
Checkout [Example Terra Contract](../examples/terra-contract/) as an example which uses Pyth Terra contract to fetch a price.
23-
24-
## Price Feed and Price API
25-
26-
The `PriceFeed` struct contains several useful functions for working with the price.
27-
Some of these functions are described below.
28-
For more detailed information, please see the crate documentation.
29-
30-
### Get the current price
31-
32-
Read the current price from a `PriceFeed`:
33-
34-
```rust
35-
let current_price: Price = price_feed.get_current_price().ok_or(StdError::not_found("Current Price is not available"))?;
36-
println!("price: ({} +- {}) x 10^{}", current_price.price, current_price.conf, current_price.expo);
11+
[dependencies]
12+
pyth-sdk-terra = { version = "<current version>" }
3713
```
3814

39-
The price is returned along with a confidence interval that represents the degree of uncertainty in the price.
40-
Both values are represented as fixed-point numbers, `a * 10^e`.
41-
The method will return `None` if the price is not currently available.
42-
43-
### Non-USD prices
44-
45-
Most assets in Pyth are priced in USD.
46-
Applications can combine two USD prices to price an asset in a different quote currency:
47-
48-
```rust
49-
let btc_usd: Price = ...;
50-
let eth_usd: Price = ...;
51-
// -8 is the desired exponent for the result
52-
let btc_eth: Price = btc_usd.get_price_in_quote(&eth_usd, -8);
53-
println!("BTC/ETH price: ({} +- {}) x 10^{}", price.price, price.conf, price.expo);
54-
```
15+
See [pyth-sdk-terra on crates.io](https://crates.io/crates/pyth-sdk-terra) to get the most recent version.
5516

56-
### Price a basket of assets
17+
## Usage
5718

58-
Applications can also compute the value of a basket of multiple assets:
19+
Simply call the `query_price_feed` function in your Terra contract with a price feed id:
5920

6021
```rust
61-
let btc_usd: Price = ...;
62-
let eth_usd: Price = ...;
63-
// Quantity of each asset in fixed-point a * 10^e.
64-
// This represents 0.1 BTC and .05 ETH.
65-
// -8 is desired exponent for result
66-
let basket_price: Price = Price::price_basket(&[
67-
(btc_usd, 10, -2),
68-
(eth_usd, 5, -2)
69-
], -8);
70-
println!("0.1 BTC and 0.05 ETH are worth: ({} +- {}) x 10^{} USD",
71-
basket_price.price, basket_price.conf, basket_price.expo);
22+
// Pyth network testnet contract address
23+
pyth_contract_addr: string = "terra1hdc8q4ejy82kd9w7wj389dlul9z5zz9a36jflh";
24+
// Price feed id for BTC/USD on testnet
25+
price_feed_id: string = "0xf9c0172ba10dfa4d19088d94f5bf61d3b54d5bd7483a322a982e1373ee8ea31b";
26+
27+
let price_feed: PriceFeed = query_price_feed(deps.querier, pyth_contract_addr, price_feed_id)?.price_feed;
28+
let current_price: Price = price_feed.get_current_price().ok_or(StdError::not_found("price is not currently available"))?;
29+
println!("current BTC/USD price: ({} +- {}) x 10^{}", current_price.price, current_price.conf, current_price.expo);
7230
```
7331

74-
This function additionally propagates any uncertainty in the price into uncertainty in the value of the basket.
32+
`query_price_feed` makes a query to the Pyth Network Terra contract
33+
This query requires a price feed id that indicates the product whose price should be returned.
34+
Each product listed on Pyth Network (e.g., BTC/USD) has its own price feed id; see the [Contracts and Price Feeds](#contracts-and-price-feeds) section below for the possible products and their price feed ids.
35+
The result of the query is a `PriceFeed` struct which contains the current price of the product along with additional metadata.
36+
This struct also has some useful functions for manipulating and combining prices; see the [common SDK documentation](../pyth-sdk) for more details.
7537

76-
## Client-side Usage
38+
## Off-Chain Queries
7739

78-
You can use the provided schemas in the `schema` directory to query the terra contract client side.
79-
80-
The query should look like:
40+
You can use the provided schemas in the `schema` directory to directly query the terra contract from off-chain applications.
41+
A typical query will look like:
8142

8243
```
8344
{
@@ -91,7 +52,7 @@ By going to the contract address in [Terra Finder](https://finder.terra.money/)
9152

9253
## Contracts and Price Feeds
9354

94-
Currently Pyth is only available in testnet network.
55+
Pyth is currently only available in Terra testnet.
9556

9657
### Testnet
9758

@@ -107,5 +68,7 @@ List of available Price Feeds and their ids:
10768
| Crypto.UST/USD | `0x026d1f1cf9f1c0ee92eb55696d3bd2393075b611c4f468ae5b967175edc4c25c` |
10869
| Crypto.ALGO/USD | `0x08f781a893bc9340140c5f89c8a96f438bcfae4d1474cc0f688e3a52892c7318` |
10970

71+
Testnet price feeds update once per minute.
72+
11073
#### Notes
111-
- :warning: `num_publishers` and `max_num_publishers` in `PriceFeed` are currrently unavailable and set to 0.
74+
- :warning: `num_publishers` and `max_num_publishers` in `PriceFeed` are currently unavailable and set to 0.

0 commit comments

Comments
 (0)