In order to promote a consistent and minimally ambiguous vocabulary to simplify the experience of users of both the SDK and the whole platform, I am proposing to make a major overhaul of the function and variable names used in the SDK and CLI, in line with the (Glossary)[https://docs.zeitgeist.pm/glossary] and the more specific Google Doc proposal on it.
Broadly speaking, any deprecated terminology will be only at the lowest possible level (ie usually the substrate code) until changed there too.
There may be some cases where this is not desirable, however, as the substrate function names are accessible through Apps, which could cause users confusion if they differ from the SDK namings doing substantially the same thing.
Classes:
rename the whole Swaps
class to SwapPool
, and instances of it to swapPool
or pool
.
rename classes to the singular (affects only Models
-> Model
) and their and their filenames consistently either to the singular or plural (affects either market.ts
or swaps.ts
)
Methods:
getXxx
and fetchXxx
are used synonymously. Use getXxx
as it is shorter.
Retain use of 'get' where retrieval involves an asynchronous request.
Remove redundant words from names.
Models
getAllMarketIds
(keep 'All' to imply analogy with getAllMarkets
)
getAllMarkets
(keep 'All' as a simple plural may be too short to be an intuitive differentiator)
createNewMarket
-> createMarket
(keep 'create' not 'new', as 'new' alone could imply that the new market will be returned. Keep 'market', as the class deals with more than just markets)
createNewCategoricalMarket
-> createCategoricalMarket
createNewScalarMarket
-> createScalarMarket
fetchMarketData
-> getMarketData
(keep 'data' as it is data being returned, not the instance of the market)
fetchDisputes
-> getDisputes
fetchPoolData
-> getPool
(same name for Market.getPool
as for SwapPool.getPool
makes clear they do the same thing (although the method on Market
requires a parameter, in order to specify the swap pool)
assetSpotPricesInZtg
->getAllPricesInZtg
(use all to differentiate from Market.getPricesInZtg
/ Market.assetSpotPricesInZtg
indexTransferRecipients
(keep name - this function does more than this, but the function will nt be relied upoj in it's current form and can be renamed later to better reflect the functionality of its future purpose)
Market
filterMarketData
(Keep 'market' as it is marketData
that is being filtered.
deploySwapPool
-> deployPool
for consistency with getPool
etc.
assetSpotPricesInZtg
-> getPricesInZtg
buyCompleteSet
(keep name to match sellCompleteSet
even though other verbs could be more appropriate)
sellCompleteSet
(keep name since there is no more intuitive verb which is accurate)
reportOutcome
-> report
('report' is unambiguous and matches dispute
. This will clash with the class field report
, which is an ambiguous name and should be renamed (see below))
redeemShares
-> redeemOutcomeAssets
(I would welcome a better phrase which makes clear both that only outcome assets are affected, and also implies finality. 'redeem' alone feels unituitive)
cancelAdvised
-> cancelCreateMarket
(makes clear the relation to createMarket
. An alternative would be -> cancel
. Unclarity about the circumstances in which a market can be cancelled could be resolved with an error message, or param name)
Swaps
/ swapPool
getSpotPrice
consider -> getPrice
('price' is no more ambiguous than 'spot price' in this context)
assetSpotPricesInZtg
-> getPricesInZtg
fetchPoolSpotPricesFromBlockNumbers
-> getPricesFromBlockNumbers
('pool' is redundant as the method is on the SwapPool
class. I cannot think of a shorter way to convey 'from block numbers')
fetchPoolSpotPrices
-> getPriceMany
(don't pluralise price
- 'prices' has been to used to mean prices of multiple assets at the same block. Otherwise, retain name as similar as possible to getPrice
. In future these should be wrapped by a function which calls the correct method whether a single block, an array or none at all is passed.
sharesId
-> getAssetTypeName
('shares' is deprecated; 'Id' is deprecated for this purpose. 'asset type' would be misleading since no type is returned, only the type's name.
accountId
-> getAddress
('Id' is redundant. I would welcome suggestions on how to concisely convey that the Address
returned is that of the swap pool rather than anything associated)
joinPool
-> join
'join' is in the glossary and so should be unabmiguous in its meaning. The method will usually be called as something like pool.join(...
. Confusion with Array.join
seems unlikely.
poolJoinWithExactPoolAmount
-> joinToReceiveExactLPTokenAmount
('pool' is inaccurate. 'receive' is more specific than 'with')
poolJoinWithExactAssetAmount
-> joinToSpendExactAssetAmount
exitPool
-> exit
(confusion with other exit
s is unlikely, but the word 'leave' may be clearer, if we were to start using 'leave' over 'exit' when speaking in other contexts - needs discussion!)
poolExitWithExactAssetAmount
-> exitToReceiveExactAssetAmount
poolExitWithExactPoolAmount
->exitToSpendExactLPTokenAmount
('remove', or even 'with' would be more accurate, but 'spend' makes clear analogy with joinToSpendExactAssetAmount
. Improvements welcome)
swapExactAmountIn
-> swapToSpendExactAmount
('exact amount' is ambiguous, since the natural reading would be for it to refer to both sides of the swap. 'In' and 'out' help only indirectly with that as they only indirectly specify which of the assets will be exact.
swapExactAmountOut
-> swapToReceiveExactAmount
Class fields
Market
report
-> reportedOutcome
(clearer, does not clash with proposed method report
. Analogous with resolved_outcome
. Could also use outcome
, though that could cause confusion as 'outcome' is sometimes used to maen 'outcome asset' or 'outcome token'.
Swaps
/ swapPool
weights
/ totalWeight
...are confusing here, as weight is used as a parameter to mean relative weights, but here they appear to be absolute. Any suggestions for a more intuiuitve word? (alternatively, since substrate uses 'weight' as an absolute, maybe the weights param should be more explicitly relative?)