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

Original ERC · ← ERCs