IPyth.sol
1 // SPDX-License-Identifier: Apache-2.0 2 pragma solidity >=0.6.0; 3 pragma experimental ABIEncoderV2; 4 5 /// @title Consume prices from the Pyth Network (https://pyth.network/). 6 /// @dev Please refer to the guidance at https://docs.pyth.network/consumers/best-practices for how to consume prices safely. 7 /// @author Pyth Data Association 8 interface IPyth { 9 // A price with a degree of uncertainty, represented as a price +- a confidence interval. 10 // 11 // The confidence interval roughly corresponds to the standard error of a normal distribution. 12 // Both the price and confidence are stored in a fixed-point numeric representation, 13 // `x * (10^expo)`, where `expo` is the exponent. 14 // 15 // Please refer to the documentation at https://docs.pyth.network/consumers/best-practices for how 16 // to how this price safely. 17 struct Price { 18 // Price 19 int64 price; 20 // Confidence interval around the price 21 uint64 conf; 22 // Price exponent 23 int32 expo; 24 // Unix timestamp describing when the price was published 25 uint publishTime; 26 } 27 28 // PriceFeed represents a current aggregate price from pyth publisher feeds. 29 struct PriceFeed { 30 // The price ID. 31 bytes32 id; 32 // Latest available price 33 Price price; 34 // Latest available exponentially-weighted moving average price 35 Price emaPrice; 36 } 37 38 /// @dev Emitted when the price feed with `id` has received a fresh update. 39 /// @param id The Pyth Price Feed ID. 40 /// @param publishTime Publish time of the given price update. 41 /// @param price Price of the given price update. 42 /// @param conf Confidence interval of the given price update. 43 event PriceFeedUpdate( 44 bytes32 indexed id, 45 uint64 publishTime, 46 int64 price, 47 uint64 conf 48 ); 49 50 /// @dev Emitted when a batch price update is processed successfully. 51 /// @param chainId ID of the source chain that the batch price update comes from. 52 /// @param sequenceNumber Sequence number of the batch price update. 53 event BatchPriceFeedUpdate(uint16 chainId, uint64 sequenceNumber); 54 55 /// @notice Returns the period (in seconds) that a price feed is considered valid since its publish time 56 function getValidTimePeriod() external view returns (uint validTimePeriod); 57 58 /// @notice Returns the price and confidence interval. 59 /// @dev Reverts if the price has not been updated within the last `getValidTimePeriod()` seconds. 60 /// @param id The Pyth Price Feed ID of which to fetch the price and confidence interval. 61 /// @return price - please read the documentation of Price to understand how to use this safely. 62 function getPrice( 63 bytes32 id 64 ) external view returns (Price memory price); 65 66 /// @notice Returns the exponentially-weighted moving average price and confidence interval. 67 /// @dev Reverts if the EMA price is not available. 68 /// @param id The Pyth Price Feed ID of which to fetch the EMA price and confidence interval. 69 /// @return price - please read the documentation of Price to understand how to use this safely. 70 function getEmaPrice( 71 bytes32 id 72 ) external view returns (Price memory price); 73 74 /// @notice Returns the price of a price feed without any sanity checks. 75 /// @dev This function returns the most recent price update in this contract without any recency checks. 76 /// This function is unsafe as the returned price update may be arbitrarily far in the past. 77 /// 78 /// Users of this function should check the `publishTime` in the price to ensure that the returned price is 79 /// sufficiently recent for their application. If you are considering using this function, it may be 80 /// safer / easier to use either `getPrice` or `getPriceNoOlderThan`. 81 /// @return price - please read the documentation of Price to understand how to use this safely. 82 function getPriceUnsafe( 83 bytes32 id 84 ) external view returns (Price memory price); 85 86 /// @notice Returns the price that is no older than `age` seconds of the current time. 87 /// @dev This function is a sanity-checked version of `getPriceUnsafe` which is useful in 88 /// applications that require a sufficiently-recent price. Reverts if the price wasn't updated sufficiently 89 /// recently. 90 /// @return price - please read the documentation of Price to understand how to use this safely. 91 function getPriceNoOlderThan( 92 bytes32 id, 93 uint age 94 ) external view returns (Price memory price); 95 96 /// @notice Returns the exponentially-weighted moving average price of a price feed without any sanity checks. 97 /// @dev This function returns the same price as `getEmaPrice` in the case where the price is available. 98 /// However, if the price is not recent this function returns the latest available price. 99 /// 100 /// The returned price can be from arbitrarily far in the past; this function makes no guarantees that 101 /// the returned price is recent or useful for any particular application. 102 /// 103 /// Users of this function should check the `publishTime` in the price to ensure that the returned price is 104 /// sufficiently recent for their application. If you are considering using this function, it may be 105 /// safer / easier to use either `getEmaPrice` or `getEmaPriceNoOlderThan`. 106 /// @return price - please read the documentation of Price to understand how to use this safely. 107 function getEmaPriceUnsafe( 108 bytes32 id 109 ) external view returns (Price memory price); 110 111 /// @notice Returns the exponentially-weighted moving average price that is no older than `age` seconds 112 /// of the current time. 113 /// @dev This function is a sanity-checked version of `getEmaPriceUnsafe` which is useful in 114 /// applications that require a sufficiently-recent price. Reverts if the price wasn't updated sufficiently 115 /// recently. 116 /// @return price - please read the documentation of Price to understand how to use this safely. 117 function getEmaPriceNoOlderThan( 118 bytes32 id, 119 uint age 120 ) external view returns (Price memory price); 121 122 /// @notice Update price feeds with given update messages. 123 /// This method requires the caller to pay a fee in wei; the required fee can be computed by calling 124 /// `getUpdateFee` with the length of the `updateData` array. 125 /// Prices will be updated if they are more recent than the current stored prices. 126 /// The call will succeed even if the update is not the most recent. 127 /// @dev Reverts if the transferred fee is not sufficient or the updateData is invalid. 128 /// @param updateData Array of price update data. 129 function updatePriceFeeds(bytes[] calldata updateData) external payable; 130 131 /// @notice Wrapper around updatePriceFeeds that rejects fast if a price update is not necessary. A price update is 132 /// necessary if the current on-chain publishTime is older than the given publishTime. It relies solely on the 133 /// given `publishTimes` for the price feeds and does not read the actual price update publish time within `updateData`. 134 /// 135 /// This method requires the caller to pay a fee in wei; the required fee can be computed by calling 136 /// `getUpdateFee` with the length of the `updateData` array. 137 /// 138 /// `priceIds` and `publishTimes` are two arrays with the same size that correspond to senders known publishTime 139 /// of each priceId when calling this method. If all of price feeds within `priceIds` have updated and have 140 /// a newer or equal publish time than the given publish time, it will reject the transaction to save gas. 141 /// Otherwise, it calls updatePriceFeeds method to update the prices. 142 /// 143 /// @dev Reverts if update is not needed or the transferred fee is not sufficient or the updateData is invalid. 144 /// @param updateData Array of price update data. 145 /// @param priceIds Array of price ids. 146 /// @param publishTimes Array of publishTimes. `publishTimes[i]` corresponds to known `publishTime` of `priceIds[i]` 147 function updatePriceFeedsIfNecessary( 148 bytes[] calldata updateData, 149 bytes32[] calldata priceIds, 150 uint64[] calldata publishTimes 151 ) external payable; 152 153 /// @notice Returns the required fee to update an array of price updates. 154 /// @param updateData Array of price update data. 155 /// @return feeAmount The required fee in Wei. 156 function getUpdateFee( 157 bytes[] calldata updateData 158 ) external view returns (uint feeAmount); 159 160 /// @notice Parse `updateData` and return price feeds of the given `priceIds` if they are all published 161 /// within `minPublishTime` and `maxPublishTime`. 162 /// 163 /// You can use this method if you want to use a Pyth price at a fixed time and not the most recent price; 164 /// otherwise, please consider using `updatePriceFeeds`. This method does not store the price updates on-chain. 165 /// 166 /// This method requires the caller to pay a fee in wei; the required fee can be computed by calling 167 /// `getUpdateFee` with the length of the `updateData` array. 168 /// 169 /// 170 /// @dev Reverts if the transferred fee is not sufficient or the updateData is invalid or there is 171 /// no update for any of the given `priceIds` within the given time range. 172 /// @param updateData Array of price update data. 173 /// @param priceIds Array of price ids. 174 /// @param minPublishTime minimum acceptable publishTime for the given `priceIds`. 175 /// @param maxPublishTime maximum acceptable publishTime for the given `priceIds`. 176 /// @return priceFeeds Array of the price feeds corresponding to the given `priceIds` (with the same order). 177 function parsePriceFeedUpdates( 178 bytes[] calldata updateData, 179 bytes32[] calldata priceIds, 180 uint64 minPublishTime, 181 uint64 maxPublishTime 182 ) external payable returns (PriceFeed[] memory priceFeeds); 183 }