Add APIs to query for general asset info
PR for #1867. @sschiessl-bcp
Added APIs:
- get_assets_general_info
( vector asset_symbols_or_ids ) - list_assets_general_info
( optional lower_bound, optional limit, optional asset_type )
General asset info is:
struct general_asset_info
{
asset_id_type id; ///< ID of this asset, i.e. "1.3.1"
string symbol; ///< Ticker symbol for this asset, i.e. "USD"
uint8_t precision = 0; ///< Maximum number of digits after the decimal point
account_id_type issuer; ///< ID of the account which created this asset
asset_type type; ///< Type of the asset
optional<asset_id_type> backing_asset_id; ///< ID of backing asset if this asset is a MPA or PM
};
asset_type is
enum asset_type
{
CORE, ///< Core asset
UIA, ///< User-issued asset
MPA, ///< Market-pegged asset
PM, ///< Predition market
CORE_OR_UIA, ///< CORE or UIA, to be used as query parameter
MPA_OR_PM, ///< MPA or PM, to be used as query parameter
ALL ///< ALL, to be used as query parameter
};
Implementation details:
- Add a
symbolfield in asset_bitasset_data_object - Add indices related to asset symbol
Other fields I thought that would be a bit frequently requested by clients are
- when listing assets to be used to pay fees:
CER,fee pool balance - when showing in dashboard:
is_globally_settled(for whether can borrow) - when trying to transact with:
info about white-listing
@sschiessl-bcp @startailcoon please comment.
Currently we have list_assets which returns the full asset object.
Suggestion:
- Name of the new operation
get_assets_general_info: Current method for getting list of assets islist_assets, thus I suggest same naming pattern. For example:list_assets_with_filter - Add additional optional argument to
get_assets_general_info, namelyquery_type. Ifquery_typeis set tofull, then return the full asset object just likelist_assetswould. Ifquery_typeis set toinfo, return thegeneral_asset_infolike you suggested, including the information from your last comment, add current supply. - Necessity of
list_assets_general_info: Is this much more lightweight compared toget_assets? - Structure of
general_asset_info: Would it make sense to do compatibility format? i.e. it looks exactly like normalasset_objectbut only has the values mentioned filled in?
@sschiessl-bcp I fixed typos about API names in OP. The idea was to return only minimum required fields but not the full asset objects when querying for many assets, in order to reduce network traffic and improve UI loading speed. The returned fields are listed in OP. These fields should meet the needs of common use cases -- when showing a list in UI, we can get all needed data with one API call. For example, to show balance sheet or account activities, we only need the symbols and precision of related assets. Then, when need details of one asset or multiple assets, call get_assets API.
Since asset_type and supply weren't in asset_object, the result will never really be compatible. A possible solution is to change return type of get_assets and list_assets and perhaps list_assets_by_issuer API (we already made a step in https://github.com/bitshares/bitshares-core/pull/1836), and add more optional parameters including a type filter and a return_type indicator (we also already added one in https://github.com/bitshares/bitshares-core/pull/1868), so we don't need to add the 2 new APIs thus would reduce confusion. This would complex the implementation of related APIs, but I think it's worthwhile since the outcome could be very good.
For the return_type parameter, it seems that it's best if the client can always define what fields to retrieve, right? However, the API could be too complicated if it's too flexible, E.G. it would need a big request to get a bit more results. Please think about common use cases and proper workflows, then make suggestions. For example. CER is a big structure for clients (3-layer nested), there are at least 5 fields related to whitelisting, so I thought these aren't minimum required info when searching for assets. Anyway, in the worst case scenario, you can still use the old get_assets API.