Pyth Solidity SDK

This package provides utilities for consuming prices from the Pyth Network Oracle using Solidity. Also, it contains the Pyth Interface ABI that you can use in your libraries to communicate with the contract.

It is strongly recommended to follow the consumer best practices when consuming Pyth data.

Installation

npm install @pythnetwork/pyth-sdk-solidity

Example Usage

To consume prices you should use the IPyth interface. Please make sure to read the documentation of this interface in order to use the prices safely.

For example, to read the latest price, call getCurrentPrice with the Price ID of the price feed you're interested in. The price feeds available on each chain are listed below.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "@pythnetwork/pyth-sdk-solidity/IPyth.sol";
import "@pythnetwork/pyth-sdk-solidity/PythStructs.sol";

contract ExampleContract {
    IPyth pyth;

    constructor(address pythContract) {
        pyth = IPyth(pythContract);
    }

    function getBTCUSDPrice(bytes[] memory priceUpdateData) public returns (PythStructs.Price memory) {
        // Update the prices to be set to the latest values. The `priceUpdateData` data should be
        // retrieved from our off-chain Price Service API using the `pyth-evm-js` package.
        // See section "How Pyth Works on EVM Chains" below for more information.
        pyth.updatePriceFeeds(priceUpdateData);

        bytes32 priceID = 0xf9c0172ba10dfa4d19088d94f5bf61d3b54d5bd7483a322a982e1373ee8ea31b;
        return pyth.getCurrentPrice(priceID);
    }
}

How Pyth Works on EVM Chains

Pyth prices are published on Solana, and relayed to EVM chains using the Wormhole Network as a cross-chain message passing bridge. The Wormhole Network observes when Pyth prices on Solana have changed and publishes an off-chain signed message attesting to this fact. This is explained in more detail here.

This signed message can then be submitted to the Pyth contract on the EVM networks, which will verify the Wormhole message and update the Pyth contract with the new price.

On-demand price updates

Price updates are not submitted on the EVM networks automatically: rather, when a consumer needs to use the value of a price they should first submit the latest Wormhole update for that price to the Pyth contract on the EVM network they are working on. This will make the most recent price update available on-chain for EVM contracts to use. Updating the price needs to be done in an off-chain program, using the pyth-evm-js package.

Solidity Target Chains

This document contains list of the EVM networks that Pyth is available on.

You can find a list of available price feeds here.

Mocking Pyth

MockPyth is a mock contract that you can use and deploy locally to mock Pyth contract behaviour. To set and update price feeds you should call updatePriceFeeds and provide an array of encoded price feeds (the struct defined in PythStructs) as its argument. You can create encoded price feeds either by using web3.js or ethers ABI utilities or calling createPriceFeedUpdateData function in the mock contract.

Development

When making changes to the contract, please make sure to update the ABI. You can update it using npm run generate-abi and it will update IPythAbi.json file.

Releases

We use Semantic Versioning for our releases. In order to release a new version of this package and publish it to npm, follow these steps:

1. Run npm version <new version number> --no-git-tag-version. This command will update the version of the package. Then push your changes to github.
2. Once your change is merged into main, create a release with tag v<new version number> like v1.5.2, and a github action will automatically publish the new version of this package to npm.

pre-commit hooks

pre-commit is a tool that checks and fixes simple issues (formatting, ...) before each commit. You can install it by following their website. In order to enable checks for this repo run pre-commit install from command-line in the root of this repo.

The checks are also performed in the CI to ensure the code follows consistent formatting.