Documentation of new market API

[theoreticalbts]

According to @xeroc comment in #500 the API implemented in #500 #503 needs to be better documented. Discussion of that documentation effort should take place in this ticket.

[mvandeberg]

With regard to #500, the API is simply to open up methods from the fc crypto suite, which themselves are not documented. This was at the request of @bytemaster

With regard to #503, @xeroc, in what ways does the documentation need to be better? None of the methods are ground breaking from a market perspective, and the parameterization is consistent with the rest of the API with the exception of referencing assets by string instead of id, which was a primary motivation behind the new API calls.

[abitmore]

Maybe just copy Polo's docs to docs.bitshares.org?

[abitmore]

And what are the blog_post APIs? Why are they here?

[svk31]

While these are a good start it's a shame none of the "all markets" methods were implemented. We desperately need a way to poll for active markets and obtain some stats about them. Approximate equivalents of these two would have been great:

returnTicker: Returns the ticker for all markets
return24Volume: Returns the 24-hour volume for all markets, plus totals for primary currencies

[abitmore]

@mvandeberg In regards to in-code documents, by a simple comparation of crypto api code to other APIs' code, anyone can see there are big differences.

[abitmore]

@svk31 We simply have much much more markets than other exchanges, so a "all market" API is not practicable imo. However a "top X volume markets" API would be better.

[svk31]

Yea that's why I said approximate equivalent. Even just the top 10 by volume would be amazing, but of course the more the better...

[mvandeberg]

@svk31 The market volume is being calculated every call. We are currently not saving that information in the database, so there is no quick way for sort on it and look up top 10 markets. That would require modification of how we store markets and orders and is beyond the scope of what I was asked to do.

[mvandeberg]

@abitmore I am not sure what specific differences you are referring to. Of course the APIs are different, they are different APIs. The point of the crypto API was to expose cryptographic utility methods through the network layer for utilization by the web client. All of the implementation is in fc elliptic. Unfortunately there is no documentation on those methods and I was only given a list of methods to expose. I assumed they were commonly understood methods to anyone familiar with elliptic curve cryptography.

[abitmore]

@mvandeberg thanks anyway.. I have no idea about these functions at all. Maybe it need to be done by others. @bytemaster @pmconrad? Thanks.

[pmconrad]

Sorry, I didn't follow this discussion - can you provide a list? Which methods do you want to expose, which need documentation?

[abitmore]

@pmconrad Please see

graphene/libraries/app/include/graphene/app/api.hpp

Lines 199 to 235 in fd09669

	class crypto_api
	{
	public:
	crypto_api();
	fc::ecc::blind_signature blind_sign( const extended_private_key_type& key, const fc::ecc::blinded_hash& hash, int i );
	signature_type unblind_signature( const extended_private_key_type& key,
	const extended_public_key_type& bob,
	const fc::ecc::blind_signature& sig,
	const fc::sha256& hash,
	int i );
	fc::ecc::commitment_type blind( const fc::ecc::blind_factor_type& blind, uint64_t value );
	fc::ecc::blind_factor_type blind_sum( const std::vector<blind_factor_type>& blinds_in, uint32_t non_neg );
	bool verify_sum( const std::vector<commitment_type>& commits_in, const std::vector<commitment_type>& neg_commits_in, int64_t excess );
	verify_range_result verify_range( const fc::ecc::commitment_type& commit, const std::vector<char>& proof );
	std::vector<char> range_proof_sign( uint64_t min_value,
	const commitment_type& commit,
	const blind_factor_type& commit_blind,
	const blind_factor_type& nonce,
	int8_t base10_exp,
	uint8_t min_bits,
	uint64_t actual_value );
	verify_range_proof_rewind_result verify_range_proof_rewind( const blind_factor_type& nonce,
	const fc::ecc::commitment_type& commit,
	const std::vector<char>& proof );
	range_proof_info range_get_info( const std::vector<char>& proof );
	};

these are new added APIs without any document. Thanks for help.

[pmconrad]

blind_sign and unblind_signature belong to this: https://bitsharestalk.org/index.php/topic,17315.msg220421.html#msg220421
I suppose these two shouldn't even be there - AFAIK they're not used anywhere in graphene currently, and if they are the API should include the blind_hash function as well.

I don't know anything about the range stuff nor the blind_factor stuff.

[vikramrajkumar]

This issue was moved to bitshares/bitshares-core#171