# Price Oracle Policy

The following describes our policy as the operator of one or more price oracles. Please refer to the [Price Oracle Specification](https://gitlab.com/GeneralProtocols/priceoracle/specification) for a complete explanation of what a price oracle is and how it works.


## Relevant Public Key(s)

Multiple price oracles operate under this policy. Each price oracle is identified uniquely by its cryptographic public key, and publicly publishes metadata identifying its policy.


## Data Source

The oracle attests to prices provided by [General Protocols Price Source](https://generalprotocols.com/price-source-policy).


## Metadata

Metadata can change over time. You can get the latest metadata in several ways.

1. Oracle information provider such as [oracles.cash](https://oracles.cash). [Example metadata page for CNY](https://oracles.cash/oracles/030654b9598186fe4bc9e1b0490c6b85b13991cdb9a7afa34af1bbeee22a35487a).

2. Directly from a public oracle relay such as `oracles.generalprotocols.com`. [Example metadata lookup for CNY](https://oracles.generalprotocols.com/api/v1/oracleMetadata?publicKey=030654b9598186fe4bc9e1b0490c6b85b13991cdb9a7afa34af1bbeee22a35487a). This method requires tools such as [Price Oracle Library](https://www.npmjs.com/package/@generalprotocols/price-oracle) to parse the metadata messages. Please refer to the specification above for full details about price oracle metadata.


### Example metadata for the CNY oracle as of 2023-04-08:

Note that this example data should not be depended on for any decisions whatsoever. Always use latest metadata.

Asset Pair

- numerator unit name: `Chinese Yuan`
- numerator unit code: `CNY`
- denominator unit name: `Bitcoin Cash`
- denominator unit code: `BCH`

Source

- name: `General Protocols`
- website: `https://generalprotocols.com/price-source-policy`
- policy hash: `7082ec78581daf67f1c21fa58201fc3de95016885394b98e16ec18af2c4acbca`

Attestation

- attestation period in milliseconds: `60000`
- attestation units per standard asset unit: `100`
- starting timestamp: `1680523200` (2023-04-03T12:00:00+00:00)
- ending timestamp: `1704067199` (2023-12-31T23:59:59+00:00)

Operator

- operator name: `General Protocols`
- operator website: `https://generalprotocols.com/price-oracle-policy`
- policy hash: `(sha256 hash of this policy)`

Availability

- relay server: `oracles.generalprotocols.com`


## Validations and Contingencies

While a price oracle fundamentally only attests to prices provided by its source, our price oracles perform a set of validations and have contingency plans for handling problems.

- Recency of source price: The oracle ensures that current price is recent before publishing or else tries again after a delay.
- Completeness of message schedule: In the case that the oracle detects a significant gap between the last price message and the current time, it gets the current price from the data source, and then linearly interpolate prices between the last price message and the current price. If any problem is detected during the recovery process, it terminates the process and tries again after a delay.
- Reasonability of price changes: The oracle checks that the next price from the source is within a wide, reasonable change threshold before publishing. In the case that the change is larger than the threshold, the oracle delays publication of the price and tries again after a delay.

In the case of an existential problem with a price oracle such as leak of its private signing key, the oracle will announce the issue and mitigations both in metadata as per Price Oracle Specification, and also in separate public channels.


## Changes

Changes to this policy will be indicated in the change of its cryptographic hash and a metadata announcement of the new hash. For strictest safety, users of price messages are advised to observe the cryptographic hash of this policy, regularly or even programatically before usage of a given price message.

Changes to the underlying source data policy, will be indicated in a metadata announcement of the new source policy hash.


## History

v1.0.1, 2023-09-14

- Update example data to represent numerator / denominator unit specification

v1.0.0, 2023-04-08

- Initial publication