Oracle API standardizations

[rowgraus]

What is the Problem Being Solved?

The oracle aggregator contract should present a standard API for querying aggregated prices without exposing the individual oracle identities or query parameters.

Description of the Design

Type declarations for the current design:

/**
 * @typedef {Object} PriceQuote
 * @property {Amount} quoteAmount Amount whose value is a PriceQuoteValue
 * @property {Payment} quotePayment The `quoteAmount` wrapped as a payment
 */

/**
 * @typedef {Array<PriceDescription>} PriceQuoteValue A set of PriceDescriptions
 */

/**
 * @typedef {Object} PriceDescription A description of a single quote
 * @property {Amount} amountIn The amount supplied to a trade
 * @property {Amount} amountOut The quoted result of trading `amountIn`
 * @property {TimerService} timer The service that gave the `timestamp`
 * @property {Timestamp} timestamp A timestamp according to `timer` for the
 * quote
 * @property {any=} conditions Additional conditions for the quote
 */

/**
 * @typedef {Object} PriceAuthority An object that mints PriceQuotes and handles
 * triggers and notifiers for changes in the price
 * @property {(brandIn: Brand, brandOut: Brand) => ERef<Issuer>} getQuoteIssuer
 * Get the ERTP issuer of PriceQuotes for a given brandIn/brandOut pair
 * @property {(brandIn: Brand, brandOut: Brand) => ERef<TimerService>}
 * getTimerService get the timer used in PriceQuotes for a given
 * brandIn/brandOut pair
 * @property {(brandIn: Brand, brandOut: Brand) => ERef<Notifier<PriceQuote>>}
 * getPriceNotifier
 * @property {(deadline: Timestamp, amountIn: Amount, brandOut: Brand) =>
 * Promise<PriceQuote>} quoteAtTime Resolves after `deadline` passes on the
 * priceAuthority's timerService with the price quote of `amountIn` at that time
 * @property {(amountIn: Amount, brandOut: Brand) => Promise<PriceQuote>}
 * quoteGiven get a quote corresponding to the specified amountIn
 * @property {(brandIn: Brand, amountOut: Amount) => Promise<PriceQuote>}
 * quoteWanted get a quote corresponding to the specified amountOut
 * @property {(amountIn: Amount, amountOutLimit: Amount) => Promise<PriceQuote>}
 * quoteWhenGT Resolve when a price quote of `amountIn` exceeds `amountOutLimit`
 * @property {(amountIn: Amount, amountOutLimit: Amount) => Promise<PriceQuote>}
 * quoteWhenGTE Resolve when a price quote of `amountIn` reaches or exceeds
 * `amountOutLimit`
 * @property {(amountIn: Amount, amountOutLimit: Amount) => Promise<PriceQuote>}
 * quoteWhenLTE Resolve when a price quote of `amountIn` reaches or drops below
 * `amountOutLimit`
 * @property {(amountIn: Amount, amountOutLimit: Amount) => Promise<PriceQuote>}
 * quoteWhenLT Resolve when the price quote of `amountIn` drops below
 * `amountOutLimit`
 */

Security Considerations

Test Plan

[katelynsills]

I copied in what was in the doc that we worked on. Happy to add more if needed. @Chris-Hibbert does this match what you have implemented in the call spread?

[Chris-Hibbert]

does this match what you have implemented in the call spread?

I didn't have a timer in the call, and my result doesn't include a timeStamp in the PriceQuote. Those are easy enough to add. Otherwise, compatible.

assetAmount can't default to 1 unit unless we have other mechanism for specifying the brand.

[katelynsills]

For the priceQuote, the properties shouldn't be capitalized because they aren't keywords: { asset, price, timer, timestamp }

[katelynsills]

assetAmount can't default to 1 unit unless we have other mechanism for specifying the brand.

Agreed. Let's not make it optional

[katelynsills]

A PriceQuote is a payment for which: quoteMath.getValue(priceQuote) => { asset, price, timer, timestamp }

Also, the value must be an array if it's MathKind.SET

[michaelfig]

I've updated the above API with the type definitions I understood from our conversation. Please update the issue description if you have changes, with a new comment to draw attention to them.

[michaelfig]

Pivot the naming from 'asset' and 'price' to be more general ('amountIn', 'amountOut' and 'Quote').

[michaelfig]

Remove timer argument from quoteAtTime and add getTimerService(brandIn, brandOut) to retrieve the authority's timer for brandIn/brandOut.

[michaelfig]

Update for quoteGiven and quoteWanted.

[katelynsills]

Closed by #1952