ERC-7726 Common quote oracle interface (Common Quote Oracle)
Draft · Other · created 2024-06-20
A standard that lets a data feed (oracle) reporting the relative value of assets be queried through one common function. It defines a getQuote function that returns values as actual token quantities rather than price ratios.
Why it is needed
For a smart contract to determine an asset's value, it must rely on an external data provider (oracle), but this information is scattered across many large and small sources, each with different integration methods and security considerations. As a result, many protocols have each built their own adapter layer to hide this complexity, creating wasteful duplication of the same work across teams. Also, handling prices as decimal ratios makes it easy to make mistakes in handling the differing decimals of different tokens. This standard aims to define a common API that can handle the majority of use cases, making integration easier and allowing product teams with less knowledge and fewer resources to use it safely. The source explains that using explicit token quantities instead of ratios has led to better outcomes in terms of security and speed to market.
In depth
Definitions of base, quote, and value
The base asset is the asset whose value the user wants to know, and the quote asset is the reference asset in which that value is expressed. For example, in "how much is 1e6 USDC in ETH," USDC is the base and ETH is the quote. value is the quantity of base expressed as a quantity of quote. In the source's example, the value of 1000e6 USDC in terms of ETH is 283,969,794,427,307,000 ETH units, and the value of 1000e18 ETH in terms of USDC is 3,521,501,299,000 USDC units. The key point of this standard is that this value is an asset quantity, not a decimal factor.
Behavior rules of getQuote
getQuote(baseAmount, base, quote) is a view function that returns the value of baseAmount of the base asset in terms of quote. The result MUST round down toward zero, and it MUST revert if the result overflows the uint256 range. There are three inputs, baseAmount (uint256), base (address), and quote (address), and one output, quoteAmount (uint256).
Special addresses for assets without an address
Assets without a contract address, such as ETH, BTC, and national fiat currencies, are also within the scope of this standard. ETH uses 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE per ERC-7528, and BTC uses 0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB. For assets without an address but with an ISO 4217 currency code, that code is used as the address. For example, the US dollar (USD) is address(840).
Why there is no getPrice
This specification does not include a getPrice function that returns a price ratio. This is because a price ratio is rarely needed on-chain and becomes a fraction that is hard to represent. getQuote should be preferred for most data handling because it removes the need for consumers to know the decimals defined on base or quote. Still, the source explains that if a commonly used price representation is needed, it can be implemented for an ERC-20 with decimals by calling oracle.getQuote(base, quote, 10**base.decimals()) to get the value of one unit of base in terms of quote.
Compatibility with existing data feeds
The source states that most existing data feeds about the relative value of asset pairs can be expressed with this standard. In other words, it is not a call to create new data sources, but a direction of layering a common interface on top of feeds that already exist.
Proposal in Draft status
This ERC is in Draft status, created on June 20, 2024. Since this is a proposal stage whose content may change going forward, the latest source should be checked before implementing or integrating. It requires ERC-7528 (special address for ETH) as a prior standard.
Things to watch out for
- Does not provide a means of data validity verification: This specification deliberately does not provide a way for consumers to evaluate the validity of the data they receive. Each implementer of this standard is expected to define and disclose, on its own, the quality of the data it provides and the conditions under which it will stop providing that data.
- Deciding whether to integrate based on the provider's guarantees: Consumers must review the guarantees disclosed by a data provider and decide, on that basis, whether to integrate with that provider.