Exchange::convert fails on a pair it could derive #47
Labels
No labels
kind
bug
kind
enhancement
kind
refactor
workflow
needs-info
workflow
needs-triage
workflow
ready-for-agent
workflow
ready-for-human
workflow
wontfix
No milestone
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
rosa/lucre#47
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Problem
Exchange::convertlooks up one pair and stops. A table holding USD/EUR andEUR/JPY cannot convert USD to JPY, even though
ExchangeRate::cross_withalready combines two rates that share a currency and
ExchangeRate::invertalready turns a rate around. The table has the parts and does not use them.
Proposal
When the direct pair is missing,
convertderives the rate from the ones thetable does hold.
Open questions
predictable. Searching for any shared currency makes the answer depend on
the search order whenever two paths exist and disagree.
ratederive as well, or onlyconvert?ratetoday answers what thetable was told, and deriving there changes what a quote means.
invert, or must every hop be quoted in thedirection of travel? A desk that charges a spread quotes the two directions
differently, so inverting invents a rate it never offered.
ExchangeRatelike any other, with norecord of how it was reached?
Out of scope
Dated rates, the provider trait, and two-sided quotes. Each is its own issue.
#50 answers part of this issue's third open question
#50 has been designed out and moved to
ready-for-agent. Its outcome changeswhat triangulation is routing over, so this issue should be read against it
rather than against the table as it stands today.
"May a hop run backwards through
invert?" — the answer splits by whatkind of quotation the hop holds.
Exchangewill store aQuotationper pair: either one-way, which prices asingle direction, or two-way, which holds a
Marketand prices both. A hopmay run backwards through a two-way quotation, because both directions were
genuinely offered. A hop may never run backwards through a one-way one, since
inverting it invents a price nobody quoted. #50 also adds an
ExchangeErrorvariant for exactly this case — a pair that is quoted, but not in the
direction asked — which gives the path search a precise thing to catch and
tells it apart from a pair that is absent entirely.
"Does a derived rate come back with no record of how it was reached?" —
#50 settled the same question for crossed markets and landed on no
provenance.
Market::cross_withcompounds spreads and returns an ordinaryMarket. Provenance was ruled out on the grounds that it belongs to thedated-rate (#48) and provider (#49) work, and that half a provenance system
built early would sit in the wrong place. Answering this issue differently
would leave the crate with two conventions.
What this issue now routes over. The path search operates on quotations
rather than bare rates, and
len()counts quotations, so a two-way pair isone entry rather than two. A crossed path through two two-way quotations has
a defined result: the spreads compound, low times low and high times high.
The remaining open questions here — which paths count, whether
ratederivesor only
convert, and how many hops — are untouched by #50 and still needsettling.
See
CONTEXT.mdfor the settled vocabulary anddocs/adr/0001-a-market-is-ordered-not-checked.mdfor why a market isordered rather than checked.
Agent Brief
Category: enhancement
Summary: Add
Exchange::rate_crossedandExchange::convert_crossed, whichprice a pair the table does not quote directly by combining the quotations it
does hold.
Current behavior:
Exchange::ratereads one entry and prices one direction from it.Exchange::convertdoes the same and fails withExchangeError::Unquotedwhenno entry covers the two currencies, even where the table holds quotations that
lead from one to the other.
Quotation::cross_withcombines two quotations thatshare a currency, and
Quotation::invertturns one around, so the parts exist —the table's own documentation tells callers to do the crossing themselves.
Desired behavior:
Two new methods on
Exchange. Neither changesget,rateorconvert, whichkeep their current behavior exactly.
rate_crossedtakes a pair — as aPairor as the two currencies, base first,like every other lookup — and returns
Option<Quotation>. It searches for aroute from the base currency to the quote through currencies the table quotes,
under these rules:
the fewest quotations in it. There is no cap on route length; the search stops
at the first length that yields any route at all.
there is, so whenever the table prices the direction asked,
rate_crossedreturns exactly what
ratereturns. Crossing never overrules a stated price.rateorients a lookup: a two-way quotation prices both directions, a one-wayquotation prices only the direction it was quoted in. A one-way quotation asked
backwards blocks that step. It is never inverted, because inverting it would
invent a price nobody quoted.
route never returns to the currency it started from. A pair of one currency is
answered by a stored quotation —
Quotation::identityfor par, a one-currencyquotation for a fee — or not at all.
wins. Exact ties break by the intermediate currencies, compared in order by
currency code, so the answer depends on what the table holds and not on how it
was searched.
Quotation::cross_withfailswhen a combined price is too large for a
Decimal, or too small to be quoted.Such a route is not a route; the search passes over it and carries on.
cross_withyields a two-way quotation,
rate_crossedreturns a one-way quotation for thepair asked. The route was chosen by its price in one direction, so the result
states that direction and no other. A caller wanting the way back asks for the
reverse pair, which may well be priced by a different route.
Nonewhen no route survives.convert_crossedtakes an amount and a currency, likeconvert, and returnsResult<Money, ExchangeError>. It prices the amount at whatrate_crossedgives for the two currencies. Its errors reuse the existing variants with their
current meanings:
Unpricedwhen the table quotes the two currencies directly but not in thedirection asked, and no route replaced it.
Unquotedwhen no route prices the two currencies at all. This still includesa currency against itself with no quotation set.
Convertforwarding aConvertErrorfrom the conversion itself.Historygains nothing. A caller crossing at a moment reads the exchange ineffect and crosses on that, so the search exists in one place.
Key interfaces:
Exchange::rate_crossed<P: Into<Pair>>(&self, pair: P) -> Option<Quotation>—new. Mirrors
rate's signature.Exchange::convert_crossed(&self, money: Money, into: Currency) -> Result<Money, ExchangeError>—new. Mirrors
convert's signature. A thin call overrate_crossed.ExchangeError— no new variants.#[non_exhaustive]leaves room todistinguish "connected but every route blocked" later, if a caller ever needs
it.
Quotation::cross_with,Quotation::rate,Quotation::invert— unchanged,and the pieces the search is built from.
Exchange's own documentation currently tells callers that crossing a pair thetable does not quote is work the table does not do. That claim is now wrong and
needs rewriting.
Acceptance criteria:
USD/EURandEUR/JPYconverts USD to JPY, at theprice
cross_withgives for the two.rate_crossedon a directly quoted pair returns the same quotationratedoes, even where a longer route would price it lower.
rate_crossedreturns a one-way quotation when every step is two-way.quotation is inverted to unblock it.
the direction asked wins. Reversing the order the quotations were added
does not change the answer.
whichever order the quotations were added in.
rate_crossedfor a currency against itself returnsNoneunless the pairis quoted, and does not route out and back through another currency.
convert_crossedreturnsUnpricedfor a pair quoted only the other waywith no route, and
Unquotedfor two currencies nothing connects.rate,convertandgetreturn exactly what they return today for everyexisting test and doctest.
mise run cipasses.Out of scope:
rate,convertorget. Crossing is opt-in and lives behindits own name.
History. Delegating to the exchange in effectwould be a method that only forwards.
Exchangestaysa set of quotations and serializes as one.
carries no record of how it was reached; a crossed rate here follows.
Vocabulary for the brief above
CONTEXT.mdnow defines route and hop, so the brief's wording resolvesagainst the glossary rather than against itself.
currency to another, in order. A route names two or more currencies, and no
currency twice. A directly quoted pair is a route of two currencies.
travels. A route of three currencies has two hops. This is the meaning
Quotation::cross_withalready documents.than by combining exactly two quotations.
Two consequences for the brief:
CODING_STANDARDS.mdtreats a name that contradicts the glossary as wrong, sothe implementation and its docs should say hop.
an extra rule the search applies. The search cannot produce a repeat, because
a sequence with one is not a route.
No behavior in the brief changes.
Closing this as out of scope, recorded in
.out-of-scope/crossing-a-route.md.Choosing a route is policy. Which of two routes wins, whether a hop may run
backwards through
invert, how many hops are too many, and whether the answersays which currencies it passed through are all questions about a desk, not
about the crate. The open questions on this issue were never gaps in a design —
they were the caller's facts, and the crate would have had to guess at them.
The parts stay public:
Exchange::getreads a quotation,Quotation::cross_withcombines two that share a currency, andQuotation::invertturns one around. A caller who knows their own rules writesthe search over those.
A route the caller names — cross along
[USD, EUR, JPY], fail on the first hopthat cannot be priced — makes no such choices, and the note says so. That is a
separate issue if it is ever wanted.