Contradicting terminology
MarkoPaasila opened this issue · comments
Order['base'] refers to the asset to be sold and the unit-of-measure in Order['price']
Order['quote'] refers to the asset to be bought, and the asset-of-interest in Order['price']
Market['base'] refers to the unit-of-measure Asset(), in which prices are measured
Market['quote'] refers to the asset-of-interest, the price of which is measured in the other asset.
Problem
Now if I make sell order in Market('BTS:USD'), Order['base'] = 'BTS' and Market['base'] = 'USD'. Confusion here.
Then if I make a buy order in Market('BTS:USD'), Order['base'] = 'USD' and Market['base'] = 'USD'
As you can see, base matches between Market() and Order() if the order is a sell order, but if it is a buy order, they are opposite. When designing strategies you then always need to keep in mind what means what in which case so you don't mess up badly, and reading code is equally difficult.
An additional source of confusion is that the terms are used bitshares-ui in the exact opposite sense. I don't know about bitshares-core.
Suggestion1
Depricate the terms base and quote from Order(). Instead, use sell and buy, or alternatively for_sale and to_buy. These terms don't carry any meaning with regards to which way the market is looked at, which is good, because the order itself doesn't carry that information. The result will be less ambiguity and confusion (yes the current situation is confusing).
Suggestion2
Depricate the terms base and quote from Market(), Instead, use unit_of_measure and asset_of_interest. Those aren't the best terms ever, and shorter but equally descriptive and unambiguous ones would be great. This will result in a representation of the market that aligns with the way we naturally think of markets. We always measure and report the price of one and the same asset measured in the other asset - consistently, regardless if we are buying or selling.
Challenge
This suggests a breaking change. A solution would be to introduce the new terms (and dict pairs) alongside the old, so users could opt to use the new ones for less confusion.
python-bitshares just wraps bitshares-core terms and structures here. So the confusion should be addressed to the bitshares-core first.
Then I suggest adding the keys "to_buy", "unit_of_measure" and "asset_of_interest". The key "for_sale" already exists, and the meaning is clear. That would leave base/quote terms intact but improve code clarity significantly.
There is a big fat note here:
http://docs.pybitshares.com/en/latest/bitshares.market.html
It says:
Throughout this library, the quote symbol will be presented first (e.g. USD:BTS with USD being the quote), while the base only refers to a secondary asset for a trade. This means, if you call bitshares.market.Market.sell() or bitshares.market.Market.buy(), you will sell/buy only quote and obtain/pay only base.
There is another note here:
http://docs.pybitshares.com/en/latest/bitshares.price.html#bitshares.price.Price
that says:
The price (floating) is derived as base/quote
Everything else is a limitation of the backend caused (mostly) by the fact that the blockchain onky knows a sell operation.