diff --git a/src/currency_core/blockchain_storage_basic.h b/src/currency_core/blockchain_storage_basic.h index 27908fbf..65c6862b 100644 --- a/src/currency_core/blockchain_storage_basic.h +++ b/src/currency_core/blockchain_storage_basic.h @@ -1,4 +1,4 @@ -// Copyright (c) 2014-2023 Zano Project +// Copyright (c) 2014-2024 Zano Project // Copyright (c) 2014-2018 The Louisdor Project // Copyright (c) 2012-2013 The Cryptonote developers // Copyright (c) 2012-2013 The Boolberry developers @@ -167,9 +167,9 @@ namespace currency uint64_t no; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(proposal_id) - KV_SERIALIZE(yes) - KV_SERIALIZE(no) + KV_SERIALIZE(proposal_id) DOC_DSCR("ID of the proposal.") DOC_EXMP("ZAP999") DOC_END + KV_SERIALIZE(yes) DOC_DSCR("Nubmer of positve votes.") DOC_EXMP(42) DOC_END + KV_SERIALIZE(no) DOC_DSCR("Number of negative votes.") DOC_EXMP(37) DOC_END END_KV_SERIALIZE_MAP() }; @@ -179,8 +179,8 @@ namespace currency std::list votes; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(total_pos_blocks) - KV_SERIALIZE(votes) + KV_SERIALIZE(total_pos_blocks) DOC_DSCR("Number of blocks in a given range.") DOC_EXMP(87482) DOC_END + KV_SERIALIZE(votes) DOC_DSCR("Result of votes in a given range.") DOC_END END_KV_SERIALIZE_MAP() }; diff --git a/src/currency_core/currency_format_utils.cpp b/src/currency_core/currency_format_utils.cpp index 1124d625..20d43d9f 100644 --- a/src/currency_core/currency_format_utils.cpp +++ b/src/currency_core/currency_format_utils.cpp @@ -2814,6 +2814,7 @@ namespace currency return CURRENT_TRANSACTION_VERSION; } //--------------------------------------------------------------- + // TODO @#@# this function is obsolete and needs to be re-written uint64_t get_reward_from_miner_tx(const transaction& tx) { uint64_t income = 0; diff --git a/src/rpc/core_rpc_server_commands_defs.h b/src/rpc/core_rpc_server_commands_defs.h index 431cfd20..6ccd37ba 100644 --- a/src/rpc/core_rpc_server_commands_defs.h +++ b/src/rpc/core_rpc_server_commands_defs.h @@ -1,20 +1,30 @@ -// Copyright (c) 2014-2018 Zano Project +// Copyright (c) 2014-2024 Zano Project // Copyright (c) 2014-2018 The Louisdor Project // Copyright (c) 2012-2013 The Cryptonote developers // Distributed under the MIT/X11 software license, see the accompanying // file COPYING or http://www.opensource.org/licenses/mit-license.php. - #pragma once #include "serialization/keyvalue_hexemizer.h" #include "currency_protocol/currency_protocol_defs.h" #include "currency_core/currency_basic.h" -#include "currency_core/difficulty.h" +//#include "currency_core/difficulty.h" #include "crypto/hash.h" #include "p2p/p2p_protocol_defs.h" -#include "storages/portable_storage_base.h" +//#include "storages/portable_storage_base.h" #include "currency_core/offers_service_basics.h" -#include "currency_core/basic_api_response_codes.h" +#include +#include +#include +#include +#include +#include #include "common/error_codes.h" +#include +#include +#include +#include +//#include "currency_core/basic_api_response_codes.h" + namespace currency { //----------------------------------------------- @@ -26,9 +36,9 @@ namespace currency std::string comment; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(address) - KV_SERIALIZE(tracking_key) - KV_SERIALIZE(comment) + KV_SERIALIZE(address) DOC_DSCR("Address of the alias.") DOC_EXMP("ZxCSpsGGeJsS8fwvQ4HktDU3qBeauoJTR6j73jAWWZxFXdF7XTbGm4YfS2kXJmAP4Rf5BVsSQ9iZ45XANXEYsrLN2L2W77dH7") DOC_END + KV_SERIALIZE(tracking_key) DOC_DSCR("View secret key of the corresponding address (optional).") DOC_EXMP("18bb94f69ed61b47b6556f3871b89dff8f9a6f4f798f706fd199b05ccf8ef20c") DOC_END + KV_SERIALIZE(comment) DOC_DSCR("Arbitrary comment (optional).") DOC_EXMP("Society is never gonna make any progress until we all learn to pretend to like each other.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -38,8 +48,8 @@ namespace currency alias_rpc_details_base details; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(alias) - KV_CHAIN_MAP(details) + KV_SERIALIZE(alias) DOC_DSCR("Alias itself, a brief shortcut for an address.") DOC_EXMP("zxdya6q6whzwqjkmtcsjpc3ku") DOC_END + KV_CHAIN_MAP(details) //DOC_DSCR("Object of alias_rpc_details_base struct.") DOC_EXMP_AUTO() DOC_END END_KV_SERIALIZE_MAP() }; @@ -51,9 +61,9 @@ namespace currency alias_rpc_details_base details; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(old_address) - KV_SERIALIZE(alias) - KV_SERIALIZE(details) + KV_SERIALIZE(old_address) DOC_DSCR("Previous address of the alias.") DOC_EXMP("ZxCSpsGGeJsS8fwvQ4HktDU3qBeauoJTR6j73jAWWZxFXdF7XTbGm4YfS2kXJmAP4Rf5BVsSQ9iZ45XANXEYsrLN2L2W77dH7") DOC_END + KV_SERIALIZE(alias) DOC_DSCR("Alias itself, a brief shortcut for an address.") DOC_EXMP("zxdya6q6whzwqjkmtcsjpc3ku") DOC_END + KV_SERIALIZE(details) DOC_DSCR("Object of alias_rpc_details_base struct.") DOC_EXMP_AUTO() DOC_END END_KV_SERIALIZE_MAP() }; @@ -62,6 +72,8 @@ namespace currency struct COMMAND_RPC_GET_POOL_INFO { + DOC_COMMAND("Obtain basic information about the transaction pool."); + struct request { BEGIN_KV_SERIALIZE_MAP() @@ -75,23 +87,25 @@ namespace currency std::list aliases_que; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) - KV_SERIALIZE(error_code) - KV_SERIALIZE(aliases_que) + KV_SERIALIZE(status) DOC_DSCR("Status code, OK if succeeded.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END + KV_SERIALIZE(error_code) DOC_DSCR("Error code, if there's any error (optional).") DOC_EXMP_AUTO() DOC_END + KV_SERIALIZE(aliases_que) DOC_DSCR("List of aliases from txs that are currently in the tx pool.") DOC_EXMP_AUTO() DOC_END END_KV_SERIALIZE_MAP() }; }; struct COMMAND_RPC_GET_VOTES { + DOC_COMMAND("Get votes' results from the given block range."); + struct request { uint64_t h_start; uint64_t h_end; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(h_start) - KV_SERIALIZE(h_end) + KV_SERIALIZE(h_start) DOC_DSCR("Start of the block range to search in (including).") DOC_EXMP(0) DOC_END + KV_SERIALIZE(h_end) DOC_DSCR("End of the block range to serach in (excluding).") DOC_EXMP(40000) DOC_END END_KV_SERIALIZE_MAP() }; @@ -102,9 +116,9 @@ namespace currency vote_results votes; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) - KV_SERIALIZE(error_code) - KV_SERIALIZE(votes) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END + KV_SERIALIZE(error_code) DOC_DSCR("Error code, if any.") DOC_END + KV_SERIALIZE(votes) DOC_DSCR("Found votes in the given range.") DOC_END END_KV_SERIALIZE_MAP() }; }; @@ -114,13 +128,15 @@ namespace currency crypto::public_key asset_id; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE_POD_AS_HEX_STRING(asset_id) + KV_SERIALIZE_POD_AS_HEX_STRING(asset_id) DOC_DSCR("ID of an asset.") DOC_EXMP("cc4e69455e63f4a581257382191de6856c2156630b3fba0db4bdd73ffcfb36b6") DOC_END END_KV_SERIALIZE_MAP() }; struct COMMAND_RPC_GET_ASSET_INFO { + DOC_COMMAND("Obtain information for the given asset by its ID."); + typedef asset_id_kv request; struct response @@ -129,8 +145,8 @@ namespace currency asset_descriptor_base asset_descriptor; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) - KV_SERIALIZE(asset_descriptor) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END + KV_SERIALIZE(asset_descriptor) DOC_DSCR("Descriptor of the given asset.") DOC_END END_KV_SERIALIZE_MAP() }; }; @@ -165,7 +181,6 @@ namespace currency struct COMMAND_RPC_GET_HEIGHT { DOC_COMMAND("Return current blockchain height"); - struct request { @@ -179,8 +194,8 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(height) DOC_DSCR("Some height of the block") DOC_EXMP(11111) DOC_END - KV_SERIALIZE(status) DOC_DSCR("Status of the operation") DOC_EXMP("OK") DOC_END + KV_SERIALIZE(height) DOC_DSCR("Height of the blockchain (equals to top block's height + 1).") DOC_EXMP(11111) DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; @@ -193,11 +208,11 @@ namespace currency struct request { uint64_t minimum_height; - std::list block_ids; //*first 10 blocks id goes sequential, next goes in pow(2,n) offset, like 2, 4, 8, 16, 32, 64 and so on, and the last one is always genesis block */ + std::list block_ids; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(minimum_height) - KV_SERIALIZE_CONTAINER_POD_AS_BLOB(block_ids) + KV_SERIALIZE(minimum_height) DOC_DSCR("The minimum height of the returning buch of blocks.") DOC_EXMP(0) DOC_END + KV_SERIALIZE_CONTAINER_POD_AS_BLOB(block_ids) /* TODO !!! DOC_DSCR("Current state of the local blockchain. Hashes of the most recent 10 blocks goes first, then each 2nd, then 4th, 8, 16, 32, 64 and so on, and the last one is always hash of the genesis block.") DOC_END */ END_KV_SERIALIZE_MAP() }; @@ -209,10 +224,10 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(blocks) - KV_SERIALIZE(start_height) - KV_SERIALIZE(current_height) - KV_SERIALIZE(status) + KV_SERIALIZE(blocks) DOC_DSCR("Bunch of blocks") DOC_END + KV_SERIALIZE(start_height) DOC_DSCR("Starting height of the resulting bunch of blocks.") DOC_END + KV_SERIALIZE(current_height) DOC_DSCR("Current height of the blockchain.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; @@ -223,12 +238,14 @@ namespace currency //----------------------------------------------- struct COMMAND_RPC_GET_TRANSACTIONS { + DOC_COMMAND("Retreive transactions by their IDs.") + struct request { std::list txs_hashes; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(txs_hashes) + KV_SERIALIZE(txs_hashes) DOC_DSCR("List of transactions' IDs.") DOC_EXMP_AUTO() DOC_END // "146791c4f5ca94bcf423557e5eb859a3a69991bd33960d52f709d88bf5d1ac6d","ec4d913a40a9ac1fbd9d33b71ef507b5c85d1f503b89096618a18b08991b5171") DOC_END END_KV_SERIALIZE_MAP() }; @@ -239,9 +256,9 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(txs_as_hex) DOC_DSCR("Transactions stored as blobs") DOC_EXMP_AUTO(1, "7d914497d91442f8f3c2268397d914497d91442f8f3c22683585eaa60b53757d49bf046a96269cef45c1bc9ff7300cc2f8f3c22683585eaa60b53757d49bf046a96269cef45c1bc9ff7300cc") DOC_END - KV_SERIALIZE(missed_tx) DOC_DSCR("Missed transactions hashes") DOC_EXMP_AUTO(1, "97d91442f8f3c22683585eaa60b53757d49bf046a96269cef45c1bc9ff7300cc") DOC_END - KV_SERIALIZE(status) DOC_DSCR("Command response status") DOC_EXMP_AUTO("OK") DOC_END + KV_SERIALIZE(txs_as_hex) DOC_DSCR("Transactions stored as blobs") DOC_EXMP_AUTO(1, "7d914497d91442f8f3c2268397d914497d91442f8f3c22683585eaa60b53757d49bf046a96269cef45c1bc9ff7300cc2f8f3c22683585eaa60b53757d49bf046a96269cef45c1bc9ff7300cc") DOC_END + KV_SERIALIZE(missed_tx) DOC_DSCR("Missed transactions hashes") DOC_EXMP_AUTO(1, "97d91442f8f3c22683585eaa60b53757d49bf046a96269cef45c1bc9ff7300cc") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; @@ -249,12 +266,14 @@ namespace currency //----------------------------------------------- struct COMMAND_RPC_GET_EST_HEIGHT_FROM_DATE { + DOC_COMMAND("Give an estimation of block height by the given date.") + struct request { uint64_t timestamp; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(timestamp) + KV_SERIALIZE(timestamp) DOC_DSCR("Linux timestamp for the required date.") DOC_EXMP(1711021795) DOC_END END_KV_SERIALIZE_MAP() }; @@ -264,14 +283,16 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(h) - KV_SERIALIZE(status) + KV_SERIALIZE(h) DOC_DSCR("Estimated height of a block.") DOC_EXMP(2555000) DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; //----------------------------------------------- struct COMMAND_RPC_GET_TX_POOL { + DOC_COMMAND("Retreives transactions from tx pool (and other information).") + struct request { BEGIN_KV_SERIALIZE_MAP() @@ -285,20 +306,22 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(txs) - KV_SERIALIZE(tx_expiration_ts_median) - KV_SERIALIZE(status) + KV_SERIALIZE(txs) DOC_DSCR("Transactions as blobs.") DOC_EXMP_AUTO(1, "7d914497d91442f8f3c2268397d914497d91442f8f3c22683585eaa60b53757d49bf046a96269cef45c1bc9ff7300cc2f8f3c22683585eaa60b53757d49bf046a96269cef45c1bc9ff7300cc") DOC_END + KV_SERIALIZE(tx_expiration_ts_median) DOC_DSCR("Timestamp median value of last TX_EXPIRATION_TIMESTAMP_CHECK_WINDOW blocks.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; //----------------------------------------------- struct COMMAND_RPC_CHECK_KEYIMAGES { + DOC_COMMAND("Check spent status of given key images.") + struct request { std::list images; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE_CONTAINER_POD_AS_BLOB(images) + KV_SERIALIZE_CONTAINER_POD_AS_BLOB(images) //DOC_DSCR("List of key images.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -308,20 +331,22 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(images_stat) - KV_SERIALIZE(status) + KV_SERIALIZE(images_stat) DOC_DSCR("List of spent states, where 1 means unspent and 0 means spent.") DOC_EXMP_AUTO(1, 0) DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; //----------------------------------------------- struct COMMAND_RPC_GET_TX_GLOBAL_OUTPUTS_INDEXES { + DOC_COMMAND("Obtain global outputs' indexes for the given txs.") + struct request { std::list txids; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE_CONTAINER_POD_AS_BLOB(txids) + KV_SERIALIZE_CONTAINER_POD_AS_BLOB(txids)// DOC_DSCR("List of transaction hashes.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -332,8 +357,8 @@ namespace currency //std::vector o_indexes; std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(tx_global_outs) - KV_SERIALIZE(status) + KV_SERIALIZE(tx_global_outs) DOC_DSCR("List of global indexies for each output for each transaction.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; @@ -341,18 +366,19 @@ namespace currency struct COMMAND_RPC_GET_TX_GLOBAL_OUTPUTS_INDEXES_BY_AMOUNT { + DOC_COMMAND("Returns transaction ID and local output index for a given output amount and its global index.") + struct request { uint64_t amount; uint64_t i; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(amount) - KV_SERIALIZE(i) + KV_SERIALIZE(amount) DOC_DSCR("The specific amount of output to query.") DOC_END + KV_SERIALIZE(i) DOC_DSCR("The global index of the output amount to be queried.") DOC_END END_KV_SERIALIZE_MAP() }; - struct response { std::string status; @@ -360,9 +386,9 @@ namespace currency uint64_t out_no; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE_POD_AS_HEX_STRING(tx_id) - KV_SERIALIZE(out_no) - KV_SERIALIZE(status) + KV_SERIALIZE_POD_AS_HEX_STRING(tx_id) DOC_DSCR("Transaction ID where the queried output is present, if found.") DOC_END + KV_SERIALIZE(out_no) DOC_DSCR("Local output index within the transaction.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; @@ -370,16 +396,17 @@ namespace currency struct COMMAND_RPC_GET_MULTISIG_INFO { + DOC_COMMAND("Retrieve basic information about a multisig output using its unique identifier (hash)."); + struct request { crypto::hash ms_id; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE_POD_AS_HEX_STRING(ms_id) + KV_SERIALIZE_POD_AS_HEX_STRING(ms_id) DOC_DSCR("The multisig output's unique identifier (hash).") DOC_END END_KV_SERIALIZE_MAP() }; - struct response { std::string status; @@ -387,15 +414,17 @@ namespace currency uint64_t out_no; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE_POD_AS_HEX_STRING(tx_id) - KV_SERIALIZE(out_no) - KV_SERIALIZE(status) + KV_SERIALIZE_POD_AS_HEX_STRING(tx_id) DOC_DSCR("Transaction ID where the multisig output is present, if found.")DOC_END + KV_SERIALIZE(out_no) DOC_DSCR("Local output index within the transaction.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; //----------------------------------------------- struct COMMAND_RPC_GET_RANDOM_OUTPUTS_FOR_AMOUNTS { + DOC_COMMAND("Retrieve random decoy outputs for specified amounts, to be used for mixing in transactions."); + struct request { std::list amounts; @@ -403,10 +432,10 @@ namespace currency uint64_t height_upper_limit; // if nonzero, all the decoy outputs must be either older than, or the same age as this height bool use_forced_mix_outs; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(amounts) - KV_SERIALIZE(decoys_count) - KV_SERIALIZE(height_upper_limit) - KV_SERIALIZE(use_forced_mix_outs) + KV_SERIALIZE(amounts) DOC_DSCR("List of amounts for which decoy outputs are requested.") DOC_END + KV_SERIALIZE(decoys_count) DOC_DSCR("Number of decoy outputs required for each amount specified.") DOC_END + KV_SERIALIZE(height_upper_limit) DOC_DSCR("Maximum blockchain height from which decoys can be taken. If nonzero, decoys must be at this height or older.") DOC_END + KV_SERIALIZE(use_forced_mix_outs) DOC_DSCR("If true, only outputs with a 'mix_attr' greater than 0 are used as decoys.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -440,8 +469,8 @@ namespace currency std::list outs; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(amount) - KV_SERIALIZE_CONTAINER_POD_AS_BLOB(outs) + KV_SERIALIZE(amount) DOC_DSCR("The amount for which decoys are returned.") DOC_END + KV_SERIALIZE_CONTAINER_POD_AS_BLOB(outs) //DOC_DSCR("List of 'out_entry' structures, serialized as a blob.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -450,22 +479,24 @@ namespace currency std::vector outs; std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(outs) - KV_SERIALIZE(status) + KV_SERIALIZE(outs) DOC_DSCR("List of 'outs_for_amount' structures, each containing decoys for a specific amount.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; //----------------------------------------------- struct COMMAND_RPC_GET_RANDOM_OUTPUTS_FOR_AMOUNTS3 { + DOC_COMMAND("Version 3 of the command to retrieve random decoy outputs for specified amounts, focusing on either pre-zarcanum or post-zarcanum zones based on the amount value."); + struct offsets_distribution { uint64_t amount; //if amount is 0 then lookup in post-zarcanum zone only, if not 0 then pre-zarcanum only std::vector global_offsets; //[i] = global_index to pick up BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(amount) - KV_SERIALIZE(global_offsets) + KV_SERIALIZE(amount) DOC_DSCR("If set to 0, only ZC outputs are considered. If nonzero, only old bare outputs are considered.") DOC_END + KV_SERIALIZE(global_offsets) DOC_DSCR("List of global indices for picking decoys. Each index corresponds to a potential decoy output.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -477,27 +508,30 @@ namespace currency bool use_forced_mix_outs; uint64_t coinbase_percents; //from 0 to 100, estimate percents of coinbase outputs included in decoy sets BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(amounts) - KV_SERIALIZE(height_upper_limit) - KV_SERIALIZE(use_forced_mix_outs) - KV_SERIALIZE(coinbase_percents) + KV_SERIALIZE(amounts) DOC_DSCR("List of amount distributions specifying where to look for decoys, based on old bare outputs or ZC outputs.") DOC_END + KV_SERIALIZE(height_upper_limit) DOC_DSCR("Maximum blockchain height from which decoys can be taken. If nonzero, decoys must be at this height or older.") DOC_END + KV_SERIALIZE(use_forced_mix_outs) DOC_DSCR("If true, only outputs with a 'mix_attr' greater than 0 are used as decoys.") DOC_END + KV_SERIALIZE(coinbase_percents) DOC_DSCR("Specifies the estimated percentage of coinbase outputs to be included in the decoy sets, ranging from 0 to 100.") DOC_END END_KV_SERIALIZE_MAP() }; typedef COMMAND_RPC_GET_RANDOM_OUTPUTS_FOR_AMOUNTS::response response; }; - - struct COMMAND_RPC_GET_RANDOM_OUTPUTS_FOR_AMOUNTS_LEGACY + //----------------------------------------------- + struct COMMAND_RPC_GET_RANDOM_OUTPUTS_FOR_AMOUNTS_LEGACY { + DOC_COMMAND("Retrieve random decoy outputs for specified amounts (legacy format)."); + struct request { std::list amounts; uint64_t outs_count; bool use_forced_mix_outs; + BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(amounts) - KV_SERIALIZE(outs_count) - KV_SERIALIZE(use_forced_mix_outs) + KV_SERIALIZE(amounts) DOC_DSCR("List of amounts for which decoy outputs are requested.") DOC_END + KV_SERIALIZE(outs_count) DOC_DSCR("Number of decoy outputs requested for each amount.") DOC_END + KV_SERIALIZE(use_forced_mix_outs) DOC_DSCR("If true, only outputs with a 'mix_attr' greater than 0 are used as decoys.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -515,8 +549,8 @@ namespace currency std::list outs; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(amount) - KV_SERIALIZE_CONTAINER_POD_AS_BLOB(outs) + KV_SERIALIZE(amount) DOC_DSCR("The amount for which decoys are returned.") DOC_END + KV_SERIALIZE_CONTAINER_POD_AS_BLOB(outs) //DOC_DSCR("List of 'out_entry' structures serialized as a blob, representing the decoy outputs for the specified amount.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -524,9 +558,10 @@ namespace currency { std::vector outs; std::string status; + BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(outs) - KV_SERIALIZE(status) + KV_SERIALIZE(outs) DOC_DSCR("List of 'outs_for_amount' structures, each containing decoys for a specific amount.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; @@ -542,7 +577,7 @@ namespace currency { std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; @@ -550,7 +585,9 @@ namespace currency //----------------------------------------------- struct COMMAND_RPC_SEND_RAW_TX { - struct request + DOC_COMMAND("Broadcasts a raw transaction encoded in hexadecimal format to the network."); + + struct request { std::string tx_as_hex; @@ -558,8 +595,8 @@ namespace currency explicit request(const transaction &); BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(tx_as_hex) - END_KV_SERIALIZE_MAP() + KV_SERIALIZE(tx_as_hex) DOC_DSCR("The transaction data as a hexadecimal string, ready for network broadcast.") DOC_END + END_KV_SERIALIZE_MAP() }; @@ -568,11 +605,12 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- struct COMMAND_RPC_FORCE_RELAY_RAW_TXS { @@ -581,7 +619,7 @@ namespace currency std::vector txs_as_hex; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(txs_as_hex) + KV_SERIALIZE(txs_as_hex) DOC_DSCR("List of transactions as a hexadecimal strings.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -591,21 +629,23 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; //----------------------------------------------- struct COMMAND_RPC_START_MINING { + DOC_COMMAND("Initiates PoW mining process on a node using the specified miner address and the number of CPU threads."); + struct request { std::string miner_address; uint64_t threads_count; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(miner_address) - KV_SERIALIZE(threads_count) + KV_SERIALIZE(miner_address) DOC_DSCR("The address where the mining rewards will be deposited.") DOC_END + KV_SERIALIZE(threads_count) DOC_DSCR("The number of CPU threads to use for mining.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -614,7 +654,7 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; @@ -801,11 +841,14 @@ namespace currency struct COMMAND_RPC_GET_INFO { + DOC_COMMAND("Retrieves various information about the blockchain node. The user must specify their needs via a 'flags' field in the request by combining necessary flags using binary OR. Some values are always calculated and provided, others only if the corresponding flag is specified."); + struct request { uint64_t flags; + BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(flags) + KV_SERIALIZE(flags) DOC_DSCR("Combination of flags to request specific data elements that are computationally expensive to calculate.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -873,83 +916,92 @@ namespace currency uint64_t offers_count; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) - KV_SERIALIZE(height) - KV_SERIALIZE(pos_difficulty) - KV_SERIALIZE(pow_difficulty) - KV_SERIALIZE(tx_count) - KV_SERIALIZE(tx_pool_size) - KV_SERIALIZE(alt_blocks_count) - KV_SERIALIZE(outgoing_connections_count) - KV_SERIALIZE(incoming_connections_count) - KV_SERIALIZE(synchronized_connections_count) - KV_SERIALIZE(net_time_delta_median) - KV_SERIALIZE(white_peerlist_size) - KV_SERIALIZE(grey_peerlist_size) - KV_SERIALIZE(current_blocks_median) - KV_SERIALIZE(current_network_hashrate_50) - KV_SERIALIZE(current_network_hashrate_350) - KV_SERIALIZE(alias_count) - KV_SERIALIZE(daemon_network_state) - KV_SERIALIZE(synchronization_start_height) - KV_SERIALIZE(max_net_seen_height) - KV_SERIALIZE(transactions_cnt_per_day) - KV_SERIALIZE(transactions_volume_per_day) - KV_SERIALIZE(mi) - KV_SERIALIZE(pos_sequence_factor) - KV_SERIALIZE(pow_sequence_factor) - KV_SERIALIZE(last_pow_timestamp) - KV_SERIALIZE(last_pos_timestamp) - KV_SERIALIZE(seconds_for_10_blocks) - KV_SERIALIZE(seconds_for_30_blocks) - KV_SERIALIZE(total_coins) - KV_SERIALIZE(block_reward) - KV_SERIALIZE(last_block_total_reward) - KV_SERIALIZE(pos_diff_total_coins_rate) - KV_SERIALIZE(pos_block_ts_shift_vs_actual) - KV_SERIALIZE(expiration_median_timestamp) - KV_SERIALIZE(pos_allowed) - KV_SERIALIZE(outs_stat) - KV_SERIALIZE(performance_data) - KV_SERIALIZE(tx_pool_performance_data) - KV_SERIALIZE(last_block_size) - KV_SERIALIZE(current_max_allowed_block_size) - KV_SERIALIZE(tx_count_in_last_block) - KV_SERIALIZE(default_fee) - KV_SERIALIZE(minimum_fee) - KV_SERIALIZE(last_block_timestamp) - KV_SERIALIZE(last_block_hash) - KV_SERIALIZE(is_hardfok_active) - KV_SERIALIZE(offers_count) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END + // Always calculated and provided fields + KV_SERIALIZE(height) DOC_DSCR("The current size of the blockchain, equal to the height of the top block plus one.") DOC_END + KV_SERIALIZE(pos_allowed) DOC_DSCR("Boolean value indicating whether PoS mining is currently allowed based on network rules and state.") DOC_END + KV_SERIALIZE(pos_difficulty) DOC_DSCR("Current difficulty for Proof of Stake mining.") DOC_END + KV_SERIALIZE(pow_difficulty) DOC_DSCR("Current difficulty for Proof of Work mining.") DOC_END + KV_SERIALIZE(tx_count) DOC_DSCR("Total number of transactions in the blockchain.") DOC_END + KV_SERIALIZE(tx_pool_size) DOC_DSCR("Number of transactions currently in the pool.") DOC_END + KV_SERIALIZE(alt_blocks_count) DOC_DSCR("Number of alternative blocks on the blockchain.") DOC_END + KV_SERIALIZE(outgoing_connections_count) DOC_DSCR("Number of outgoing P2P connections to other nodes.") DOC_END + KV_SERIALIZE(incoming_connections_count) DOC_DSCR("Number of incoming P2P connections established by other nodes.") DOC_END + KV_SERIALIZE(synchronized_connections_count) DOC_DSCR("Number of P2P connections to nodes that have a fully synchronized blockchain.") DOC_END + KV_SERIALIZE(white_peerlist_size) DOC_DSCR("Size of the white peer list, which includes addresses of reliable nodes.") DOC_END + KV_SERIALIZE(grey_peerlist_size) DOC_DSCR("Size of the grey peer list, which includes addresses of nodes with less consistent availability.") DOC_END + KV_SERIALIZE(current_blocks_median) // TODO + KV_SERIALIZE(alias_count) DOC_DSCR("The total number of unique aliases registered on the blockchain. Aliases are alternate, human-readable names associated with addresses.") DOC_END + KV_SERIALIZE(current_max_allowed_block_size) DOC_DSCR("Current maximum allowed cummulative block size in bytes.") DOC_END + KV_SERIALIZE(is_hardfok_active) DOC_DSCR("A list of boolean values indicating whether each corresponding hardfork is active. For example, a list 'true, true, false' indicates that the first hardfork is activated, while the second is not. Hardfork #0 is always active as it is a stub.") DOC_END + KV_SERIALIZE(daemon_network_state) DOC_DSCR("Current network state of the daemon, which could be connecting, synchronizing, online, loading core, internal error, unloading core, or downloading database.") DOC_END + KV_SERIALIZE(synchronization_start_height) DOC_DSCR("Blockchain height at which the current synchronization process started. Indicates the starting point for catching up to the network's latest state.") DOC_END + KV_SERIALIZE(max_net_seen_height) DOC_DSCR("Maximum blockchain height observed in the network by this node.") DOC_END + KV_SERIALIZE(default_fee) DOC_DSCR("Default fee for transactions.") DOC_END + KV_SERIALIZE(minimum_fee) DOC_DSCR("Minimum fee for transactions.") DOC_END + KV_SERIALIZE(mi) DOC_DSCR("The most recent mainterner's info.") DOC_END + + // Fields dependent on flags for their inclusion + KV_SERIALIZE(net_time_delta_median) DOC_DSCR("A value of 0 indicates no time synchronization issues, while a value of 1 indicates the presence of time sync issues. Only available if the COMMAND_RPC_GET_INFO_FLAG_NET_TIME_DELTA_MEDIAN flag is set.") DOC_END + KV_SERIALIZE(current_network_hashrate_50)DOC_DSCR("The PoW hash rate calculated over the last 50 blocks of any type. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_CURRENT_NETWORK_HASHRATE_50 flag is set.") DOC_END + KV_SERIALIZE(current_network_hashrate_350) DOC_DSCR("The PoW hash rate calculated over the last 350 blocks of any type. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_CURRENT_NETWORK_HASHRATE_350 flag is set.") DOC_END + KV_SERIALIZE(seconds_for_10_blocks) DOC_DSCR("The time period in seconds between the most recent block and the 10th block older. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_SECONDS_FOR_10_BLOCKS flag is set.") DOC_END + KV_SERIALIZE(seconds_for_30_blocks) DOC_DSCR("The time period in seconds between the most recent block and the 30th block older. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_SECONDS_FOR_30_BLOCKS flag is set.") DOC_END + KV_SERIALIZE(transactions_cnt_per_day) DOC_DSCR("The number of non-mining transactions recorded over the last 24 hours. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_TRANSACTIONS_DAILY_STAT flag is set.") DOC_END + KV_SERIALIZE(transactions_volume_per_day)DOC_DSCR("The total sum of input amounts from all non-mining transactions over the last 24 hours. Only old bare inputs with explicit amounts are considered. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_TRANSACTIONS_DAILY_STAT flag is set.") DOC_END + KV_SERIALIZE(last_pos_timestamp) DOC_DSCR("The timestamp of the most recent PoS block. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_LAST_POS_TIMESTAMP flag is set.") DOC_END + KV_SERIALIZE(last_pow_timestamp) DOC_DSCR("The timestamp of the most recent PoW block. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_LAST_POW_TIMESTAMP flag is set.") DOC_END + KV_SERIALIZE(total_coins) DOC_DSCR("The total amount of all emitted coins in the system. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_TOTAL_COINS flag is set.") DOC_END + KV_SERIALIZE(last_block_size) DOC_DSCR("The size of the last block in bytes. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_LAST_BLOCK_SIZE flag is set.") DOC_END + KV_SERIALIZE(tx_count_in_last_block) DOC_DSCR("The number of non-mining transactions in the last block. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_TX_COUNT_IN_LAST_BLOCK flag is set.") DOC_END + KV_SERIALIZE(pos_sequence_factor) DOC_DSCR("The current PoS sequence factor, representing the number of consecutive PoS blocks. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_POS_SEQUENCE_FACTOR flag is set.") DOC_END + KV_SERIALIZE(pow_sequence_factor) DOC_DSCR("The current PoW sequence factor, representing the number of consecutive PoW blocks. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_POW_SEQUENCE_FACTOR flag is set.") DOC_END + KV_SERIALIZE(block_reward) DOC_DSCR("The base block reward that is effective for the next block. Calculated only if either COMMAND_RPC_GET_INFO_FLAG_POS_DIFFICULTY or COMMAND_RPC_GET_INFO_FLAG_TOTAL_COINS flag is set.") DOC_END + KV_SERIALIZE(last_block_total_reward) DOC_DSCR("Reward for the last block, including base reward and transaction fees. Calculated only if either COMMAND_RPC_GET_INFO_FLAG_POS_DIFFICULTY or COMMAND_RPC_GET_INFO_FLAG_TOTAL_COINS flag is set.") DOC_END + KV_SERIALIZE(pos_diff_total_coins_rate) DOC_DSCR("PoS difficulty divided by the total amount of all coins in the system minus a premined amount (17,517,203). Calculated only if either COMMAND_RPC_GET_INFO_FLAG_POS_DIFFICULTY or COMMAND_RPC_GET_INFO_FLAG_TOTAL_COINS flag is set.") DOC_END + KV_SERIALIZE(last_block_timestamp) DOC_DSCR("Timestamp of the last block. Calculated only if either COMMAND_RPC_GET_INFO_FLAG_POS_DIFFICULTY or COMMAND_RPC_GET_INFO_FLAG_TOTAL_COINS flag is set.") DOC_END + KV_SERIALIZE(last_block_hash) DOC_DSCR("Hash of the last block. Calculated only if either COMMAND_RPC_GET_INFO_FLAG_POS_DIFFICULTY or COMMAND_RPC_GET_INFO_FLAG_TOTAL_COINS flag is set.") DOC_END + KV_SERIALIZE(pos_block_ts_shift_vs_actual) DOC_DSCR("The difference between the timestamp used in the last PoS block for mining purposes and its actual timestamp as stored in the miner's transaction extra data. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_POS_BLOCK_TS_SHIFT_VS_ACTUAL flag is set.") DOC_END + KV_SERIALIZE(outs_stat) DOC_DSCR("Statistics for the number of outputs that have a specific amount. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_OUTS_STAT flag is set.") DOC_END + KV_SERIALIZE(performance_data) DOC_DSCR("Detailed technical performance data intended for developers. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_PERFORMANCE flag is set.") DOC_END + KV_SERIALIZE(tx_pool_performance_data) DOC_DSCR("Detailed technical performance data intended for developers. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_PERFORMANCE flag is set.") DOC_END + KV_SERIALIZE(offers_count) DOC_DSCR("Current number of offers in the offers service. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_PERFORMANCE flag is set.") DOC_END + KV_SERIALIZE(expiration_median_timestamp)DOC_DSCR("Median of timestamps of the last N blocks, used to determine the expiration status of transactions. This information is only provided if the COMMAND_RPC_GET_INFO_FLAG_EXPIRATIONS_MEDIAN flag is set.") DOC_END END_KV_SERIALIZE_MAP() }; }; //----------------------------------------------- struct COMMAND_RPC_STOP_MINING { + DOC_COMMAND("Stop PoW mining process on CPU.") + struct request { - BEGIN_KV_SERIALIZE_MAP() END_KV_SERIALIZE_MAP() }; - struct response { std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- - // struct COMMAND_RPC_GETBLOCKCOUNT { - typedef std::list request; + DOC_COMMAND("Returns the total number of blocks in the blockchain (the height of the top block plus one)."); + + struct request + { + BEGIN_KV_SERIALIZE_MAP() + END_KV_SERIALIZE_MAP() + }; struct response { @@ -957,39 +1009,45 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(count) - KV_SERIALIZE(status) + KV_SERIALIZE(count) DOC_DSCR("The total number of blocks in the blockchain, equivalent to the top block's height plus one.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; - }; + //----------------------------------------------- + struct COMMAND_RPC_GETBLOCKHASH { + DOC_COMMAND("Returns block hash by the given height."); + typedef std::vector request; typedef std::string response; }; + //----------------------------------------------- struct COMMAND_RPC_GETBLOCKTEMPLATE { + DOC_COMMAND("Generates a block template for mining, intended for both PoW and PoS types of blocks based on the provided parameters."); + struct request { blobdata explicit_transaction; std::string extra_text; std::string wallet_address; - std::string stakeholder_address; // address for stake return (PoS blocks) - pos_entry pe; // for PoS blocks - bool pos_block; // is pos block + std::string stakeholder_address; // address for stake return (PoS blocks) + pos_entry pe; // for PoS blocks + bool pos_block; // is pos block BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE_BLOB_AS_HEX_STRING(explicit_transaction) - KV_SERIALIZE(extra_text) - KV_SERIALIZE(wallet_address) - KV_SERIALIZE(stakeholder_address); - KV_SERIALIZE(pe) - KV_SERIALIZE(pos_block) + KV_SERIALIZE_BLOB_AS_HEX_STRING(explicit_transaction) DOC_DSCR("A transaction blob that must be explicitly included in the block.") DOC_END + KV_SERIALIZE(extra_text) DOC_DSCR("Arbitrary data added to the extra field of the miner transaction.") DOC_END + KV_SERIALIZE(wallet_address) DOC_DSCR("Address where mining rewards will be deposited.") DOC_END + KV_SERIALIZE(stakeholder_address) DOC_DSCR("Address where the stake is returned for PoS blocks (usually the same as 'wallet_address').") DOC_END + KV_SERIALIZE(pe) DOC_DSCR("PoS entry details, relevant only for PoS block generation.") DOC_END + KV_SERIALIZE(pos_block) DOC_DSCR("Flag indicating whether the block is a PoS block.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1007,22 +1065,26 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(difficulty) - KV_SERIALIZE(height) - KV_SERIALIZE_POD_AS_HEX_STRING(seed) - KV_SERIALIZE(blocktemplate_blob) - KV_SERIALIZE(prev_hash) - KV_SERIALIZE(miner_tx_tgc) - KV_SERIALIZE(block_reward_without_fee) - KV_SERIALIZE(block_reward) - KV_SERIALIZE(txs_fee) - KV_SERIALIZE(status) + KV_SERIALIZE(difficulty) DOC_DSCR("The mining difficulty targeted by the block template.") DOC_END + KV_SERIALIZE(height) DOC_DSCR("The height of the block template in the blockchain.") DOC_END + KV_SERIALIZE_POD_AS_HEX_STRING(seed) DOC_DSCR("Seed value for the ProgPoWZ mining algorithm's epoch.") DOC_END + KV_SERIALIZE(blocktemplate_blob) DOC_DSCR("Serialized block template blob.") DOC_END + KV_SERIALIZE(prev_hash) DOC_DSCR("Hash of the previous block in the chain.") DOC_END + KV_SERIALIZE(miner_tx_tgc) DOC_DSCR("Miner transaction generation context. Intended for PoS blocks and Zarcanum.") DOC_END + KV_SERIALIZE(block_reward_without_fee) DOC_DSCR("Base block reward excluding any transaction fees.") DOC_END + KV_SERIALIZE(block_reward) DOC_DSCR("Total block reward, including transaction fees if they are given to the miner (legacy), or the base reward if fees are burnt (current state).") DOC_END + KV_SERIALIZE(txs_fee) DOC_DSCR("Total fees from transactions included in the block.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- + struct COMMAND_RPC_SUBMITBLOCK { + DOC_COMMAND("Adds new block to the blockchain. Request should contain one string with hex-encoded block blob."); + typedef std::vector request; struct response @@ -1030,21 +1092,25 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- + struct COMMAND_RPC_SUBMITBLOCK2 { + DOC_COMMAND("Adds new block to the blockchain."); + struct request { std::string b; //hex encoded block blob std::list explicit_txs; //hex encoded tx blobs BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE_BLOB_AS_HEX_STRING(b) - KV_SERIALIZE(explicit_txs) + KV_SERIALIZE_BLOB_AS_HEX_STRING(b) DOC_DSCR("Hex-encoded serialized block.") DOC_END + KV_SERIALIZE(explicit_txs) DOC_DSCR("List of hex-encoded transactions to be explicitly included in the block.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1053,11 +1119,13 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- + struct block_header_response { uint8_t major_version; @@ -1073,23 +1141,24 @@ namespace currency uint64_t reward; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(major_version) - KV_SERIALIZE(minor_version) - KV_SERIALIZE(timestamp) - KV_SERIALIZE(prev_hash) - KV_SERIALIZE(nonce) - KV_SERIALIZE(orphan_status) - KV_SERIALIZE(height) - KV_SERIALIZE(depth) - KV_SERIALIZE(hash) - KV_SERIALIZE(difficulty) - KV_SERIALIZE(reward) + KV_SERIALIZE(major_version) DOC_DSCR("Major version of the block.") DOC_END + KV_SERIALIZE(minor_version) DOC_DSCR("Minor version of the block.") DOC_END + KV_SERIALIZE(timestamp) DOC_DSCR("Timestamp of the block creation.") DOC_END + KV_SERIALIZE(prev_hash) DOC_DSCR("Hash of the previous block in the chain.") DOC_END + KV_SERIALIZE(nonce) DOC_DSCR("Nonce used for generating the block to meet the network difficulty.") DOC_END + KV_SERIALIZE(orphan_status) DOC_DSCR("Indicates if the block is an orphan (true) or a normal block (false).") DOC_END + KV_SERIALIZE(height) DOC_DSCR("Height of the block in the blockchain.") DOC_END + KV_SERIALIZE(depth) DOC_DSCR("Depth of the block in the blockchain. Depth 0 indicates the most recent block.") DOC_END + KV_SERIALIZE(hash) DOC_DSCR("Hash of the block.") DOC_END + KV_SERIALIZE(difficulty) DOC_DSCR("Network difficulty target that the block met.") DOC_END + KV_SERIALIZE(reward) DOC_DSCR("Total mining reward of the block including transaction fees (if applicable).") DOC_END END_KV_SERIALIZE_MAP() }; struct COMMAND_RPC_GET_LAST_BLOCK_HEADER { - typedef std::list request; + DOC_COMMAND("Returns the block header information of the most recent block."); + typedef std::list request; // TODO @#@# fix this struct response { @@ -1098,20 +1167,24 @@ namespace currency BEGIN_KV_SERIALIZE_MAP() KV_SERIALIZE(block_header) - KV_SERIALIZE(status) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- + struct COMMAND_RPC_GET_BLOCK_HEADER_BY_HASH { + DOC_COMMAND("Retrieves the block header information for a given block hash."); + struct request { std::string hash; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(hash) + KV_SERIALIZE(hash) DOC_DSCR("The hash of the block for which the header information is being requested.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1121,21 +1194,24 @@ namespace currency block_header_response block_header; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(block_header) - KV_SERIALIZE(status) + KV_SERIALIZE(block_header) DOC_DSCR("Detailed header information of the block.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; - }; + //----------------------------------------------- + struct COMMAND_RPC_GET_BLOCK_HEADER_BY_HEIGHT { + DOC_COMMAND("Retrieves the block header information for a given block height."); + struct request { uint64_t height; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(height) + KV_SERIALIZE(height) DOC_DSCR("The height of the block for which the header information is being requested.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1145,20 +1221,23 @@ namespace currency block_header_response block_header; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(block_header) - KV_SERIALIZE(status) + KV_SERIALIZE(block_header) DOC_DSCR("Detailed header information of the block.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; - }; + //----------------------------------------------- + struct COMMAND_RPC_GET_ALIAS_DETAILS { + DOC_COMMAND("Retrieves information about a specific address alias."); + struct request { std::string alias; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(alias) + KV_SERIALIZE(alias) DOC_DSCR("The alias name for which details are being requested.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1168,19 +1247,23 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(alias_details) - KV_SERIALIZE(status) + KV_SERIALIZE(alias_details) DOC_DSCR("Contains the detailed information about the specified alias, including the associated wallet address, tracking key, comment etc..") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- + struct COMMAND_RPC_GET_ALIAS_REWARD { + DOC_COMMAND("Retrieves the cost of registering an alias on the blockchain."); + struct request { std::string alias; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(alias) + KV_SERIALIZE(alias) DOC_DSCR("The alias name for which the registration cost is being queried.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1190,15 +1273,18 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(reward) - KV_SERIALIZE(status) + KV_SERIALIZE(reward) DOC_DSCR("The registration cost for the specified alias.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- struct COMMAND_RPC_GET_ALL_ALIASES { + DOC_COMMAND("Retrieves all registered aliases along with associated information."); + struct request { BEGIN_KV_SERIALIZE_MAP() @@ -1211,22 +1297,26 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(aliases) - KV_SERIALIZE(status) + KV_SERIALIZE(aliases) DOC_DSCR("List of alias_rpc_details objects, each containing information about an individual alias.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- + struct COMMAND_RPC_GET_ALIASES { + DOC_COMMAND("Retrieves a specified portion of all registered aliases, allowing pagination through large sets of aliases."); + struct request { - uint64_t offset; - uint64_t count; + uint64_t offset; // The starting point from which aliases are to be retrieved. + uint64_t count; // The number of aliases to retrieve. BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(offset) - KV_SERIALIZE(count) + KV_SERIALIZE(offset) DOC_DSCR("The offset in the list of all aliases from which to start retrieving.") DOC_END + KV_SERIALIZE(count) DOC_DSCR("The number of aliases to retrieve from the specified offset.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1236,33 +1326,37 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(aliases) - KV_SERIALIZE(status) + KV_SERIALIZE(aliases) DOC_DSCR("List of alias_rpc_details objects, each containing information about an individual alias retrieved based on the request parameters.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- + struct COMMAND_RPC_GET_ALIASES_BY_ADDRESS { + DOC_COMMAND("Retrieves all aliases registered for a given address."); typedef std::string request; struct response { - //std::string alias; std::vector alias_info_list; std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(alias_info_list) - KV_SERIALIZE(status) + KV_SERIALIZE(alias_info_list) DOC_DSCR("List of alias_rpc_details objects, each containing detailed information about each alias registered to the specified address.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- struct COMMAND_RPC_RESET_TX_POOL { + DOC_COMMAND("Clears transaction pool."); struct request { @@ -1275,20 +1369,23 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- + struct COMMAND_RPC_REMOVE_TX_FROM_POOL { + DOC_COMMAND("Removes specified transactions from the transaction pool, typically to clear out transactions that are no longer valid or needed."); struct request { std::list tx_to_remove; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(tx_to_remove) + KV_SERIALIZE(tx_to_remove) DOC_DSCR("List of transaction IDs that are to be removed from the transaction pool.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1297,13 +1394,17 @@ namespace currency std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- + struct COMMAND_RPC_GET_POS_MINING_DETAILS - { + { + DOC_COMMAND("Retrieves basic information regarding PoS mining, including current PoS conditions and constraints."); + struct request { BEGIN_KV_SERIALIZE_MAP() @@ -1321,17 +1422,19 @@ namespace currency bool pos_sequence_factor_is_good; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE_VAL_POD_AS_BLOB(sm) - KV_SERIALIZE(pos_basic_difficulty) - KV_SERIALIZE(starter_timestamp) - KV_SERIALIZE(pos_mining_allowed) - KV_SERIALIZE(pos_sequence_factor_is_good) - KV_SERIALIZE(status) - KV_SERIALIZE_VAL_POD_AS_BLOB(last_block_hash) + KV_SERIALIZE_VAL_POD_AS_BLOB(sm) //DOC_DSCR("Stake modifier object used in PoS mining calculations.") DOC_END + KV_SERIALIZE(pos_basic_difficulty) DOC_DSCR("Current PoS difficulty.") DOC_END + KV_SERIALIZE(starter_timestamp) DOC_DSCR("Timestamp from which timestamps are evaluated for meeting PoS win condition.") DOC_END + KV_SERIALIZE(pos_mining_allowed) DOC_DSCR("Indicates whether PoS mining is currently allowed, which may be restricted under certain blockchain conditions or in testnets.") DOC_END + KV_SERIALIZE(pos_sequence_factor_is_good) DOC_DSCR("Indicates whether the PoS sequence factor is at a level that allows for continued PoS mining, requiring a PoW block to reset if too high.") DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END + KV_SERIALIZE_VAL_POD_AS_BLOB(last_block_hash) //DOC_DSCR("Hash of the most recent block in the blockchain.") DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- + struct tx_out_rpc_entry { uint64_t amount; @@ -1340,11 +1443,11 @@ namespace currency bool is_spent; uint64_t global_index; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(amount) - KV_SERIALIZE(pub_keys) - KV_SERIALIZE(minimum_sigs) - KV_SERIALIZE(is_spent) - KV_SERIALIZE(global_index) + KV_SERIALIZE(amount) DOC_DSCR("The output's amount, 0 for ZC outputs.") DOC_END + KV_SERIALIZE(pub_keys) DOC_DSCR("List of public keys associated with the output.") DOC_END + KV_SERIALIZE(minimum_sigs) DOC_DSCR("Minimum number of signatures required to spend the output, for multisig outputs only.") DOC_END + KV_SERIALIZE(is_spent) DOC_DSCR("Indicates whether the output has been spent.") DOC_END + KV_SERIALIZE(global_index) DOC_DSCR("Global index of the output for this specific amount.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1357,12 +1460,12 @@ namespace currency std::vector global_indexes; std::vector etc_options; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(amount) - KV_SERIALIZE(htlc_origin) - KV_SERIALIZE(kimage_or_ms_id) - KV_SERIALIZE(global_indexes) - KV_SERIALIZE(multisig_count) - KV_SERIALIZE(etc_options) + KV_SERIALIZE(amount) DOC_DSCR("The amount of coins being transacted.") DOC_END + KV_SERIALIZE(htlc_origin) DOC_DSCR("Origin hash for HTLC (Hash Time Locked Contract).") DOC_END + KV_SERIALIZE(kimage_or_ms_id) DOC_DSCR("Contains either the key image for the input or the multisig output ID, depending on the input type.") DOC_END + KV_SERIALIZE(global_indexes) DOC_DSCR("List of global indexes indicating the outputs referenced by this input, where only one is actually being spent.") DOC_END + KV_SERIALIZE(multisig_count) DOC_DSCR("Number of multisig signatures used, relevant only for multisig outputs.") DOC_END + KV_SERIALIZE(etc_options) DOC_DSCR("Auxiliary options associated with the input, containing additional configuration or data.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1372,9 +1475,9 @@ namespace currency std::string short_view; std::string details_view; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(type) - KV_SERIALIZE(short_view) - KV_SERIALIZE(details_view) + KV_SERIALIZE(type) DOC_DSCR("Type of the extra entry in the transaction.") DOC_END + KV_SERIALIZE(short_view) DOC_DSCR("A concise representation of the extra entry.") DOC_END + KV_SERIALIZE(details_view) DOC_DSCR("A detailed representation of the extra entry.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1396,19 +1499,19 @@ namespace currency std::string object_in_json; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE_BLOB_AS_BASE64_STRING(blob) - KV_SERIALIZE(blob_size) - KV_SERIALIZE(timestamp) - KV_SERIALIZE(keeper_block) - KV_SERIALIZE(fee) - KV_SERIALIZE(amount) - KV_SERIALIZE(id) - KV_SERIALIZE(pub_key) - KV_SERIALIZE(outs) - KV_SERIALIZE(ins) - KV_SERIALIZE(extra) - KV_SERIALIZE(attachments) - KV_SERIALIZE_BLOB_AS_BASE64_STRING(object_in_json) + KV_SERIALIZE_BLOB_AS_BASE64_STRING(blob) DOC_DSCR("Serialized form of the transaction, encoded in Base64.") DOC_END + KV_SERIALIZE(blob_size) DOC_DSCR("Size of the serialized transaction in bytes.") DOC_END + KV_SERIALIZE(timestamp) DOC_DSCR("Timestamp when the transaction was created.") DOC_END + KV_SERIALIZE(keeper_block) DOC_DSCR("Block height where the transaction is confirmed, or -1 if it is unconfirmed.") DOC_END + KV_SERIALIZE(fee) DOC_DSCR("Transaction fee in the smallest currency unit.") DOC_END + KV_SERIALIZE(amount) DOC_DSCR("Total output amount of the transaction (legacy, for pre-Zarcanum txs).") DOC_END + KV_SERIALIZE(id) DOC_DSCR("Hash of the transaction.") DOC_END + KV_SERIALIZE(pub_key) DOC_DSCR("Public key associated with the transaction.") DOC_END + KV_SERIALIZE(outs) DOC_DSCR("Outputs of the transaction.") DOC_END + KV_SERIALIZE(ins) DOC_DSCR("Inputs of the transaction.") DOC_END + KV_SERIALIZE(extra) DOC_DSCR("Extra data associated with the transaction.") DOC_END + KV_SERIALIZE(attachments) DOC_DSCR("Additional attachments to the transaction.") DOC_END + KV_SERIALIZE_BLOB_AS_BASE64_STRING(object_in_json) DOC_DSCR("Serialized transaction represented in JSON, encoded in Base64.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1420,10 +1523,10 @@ namespace currency uint64_t sz; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(id) - KV_SERIALIZE(fee) - KV_SERIALIZE(total_amount) - KV_SERIALIZE(sz) + KV_SERIALIZE(id) DOC_DSCR("Hash of the transaction.") DOC_END + KV_SERIALIZE(fee) DOC_DSCR("Transaction fee in the smallest currency unit.") DOC_END + KV_SERIALIZE(total_amount) DOC_DSCR("Total amount transferred in the transaction (legacy, for pre-Zarcanum txs).") DOC_END + KV_SERIALIZE(sz) DOC_DSCR("Size of the transaction in bytes.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1454,41 +1557,43 @@ namespace currency std::list transactions_details; std::string miner_text_info; std::string object_in_json; - BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(blob) - KV_SERIALIZE(height) - KV_SERIALIZE(timestamp) - KV_SERIALIZE(actual_timestamp) - KV_SERIALIZE(block_cumulative_size) - KV_SERIALIZE(total_txs_size) - KV_SERIALIZE(block_tself_size) - KV_SERIALIZE(base_reward) - KV_SERIALIZE(summary_reward) - KV_SERIALIZE(total_fee) - KV_SERIALIZE(penalty) - KV_SERIALIZE(id) - KV_SERIALIZE(prev_id) - KV_SERIALIZE(pow_seed) - KV_SERIALIZE(cumulative_diff_adjusted) - KV_SERIALIZE(cumulative_diff_precise) - KV_SERIALIZE(difficulty) - KV_SERIALIZE(already_generated_coins) - KV_SERIALIZE(this_block_fee_median) - KV_SERIALIZE(effective_fee_median) - KV_SERIALIZE(transactions_details) - KV_SERIALIZE(type) - KV_SERIALIZE(is_orphan) - KV_SERIALIZE(miner_text_info) - KV_SERIALIZE(object_in_json) + KV_SERIALIZE(blob) DOC_DSCR("Serialized form of the block.") DOC_END + KV_SERIALIZE(height) DOC_DSCR("Height of the block in the blockchain.") DOC_END + KV_SERIALIZE(timestamp) DOC_DSCR("Timestamp when the block was created, in PoS blocks used for mining.") DOC_END + KV_SERIALIZE(actual_timestamp) DOC_DSCR("Actual timestamp encoded in the block's extra data for PoS blocks.") DOC_END + KV_SERIALIZE(block_cumulative_size) DOC_DSCR("Cumulative size of the block including all transactions.") DOC_END + KV_SERIALIZE(total_txs_size) DOC_DSCR("Total size of all transactions included in the block.") DOC_END + KV_SERIALIZE(block_tself_size) // TODO ? + KV_SERIALIZE(base_reward) DOC_DSCR("Base mining reward for the block.") DOC_END + KV_SERIALIZE(summary_reward) DOC_DSCR("Total reward for the block, including base reward and transaction fees (legacy).") DOC_END + KV_SERIALIZE(total_fee) DOC_DSCR("Total transaction fees included in the block.") DOC_END + KV_SERIALIZE(penalty) DOC_DSCR("Penalty applied to the reward if the block is larger than median but not large enough to be rejected.") DOC_END + KV_SERIALIZE(id) DOC_DSCR("Unique identifier of the block.") DOC_END + KV_SERIALIZE(prev_id) DOC_DSCR("Hash of the previous block in the chain.") DOC_END + KV_SERIALIZE(pow_seed) // TODO + KV_SERIALIZE(cumulative_diff_adjusted) DOC_DSCR("Adjusted cumulative difficulty of the blockchain up to this block.") DOC_END + KV_SERIALIZE(cumulative_diff_precise) DOC_DSCR("Precise cumulative difficulty of the blockchain up to this block.") DOC_END + KV_SERIALIZE(difficulty) DOC_DSCR("Mining difficulty of the block.") DOC_END + KV_SERIALIZE(already_generated_coins) DOC_DSCR("Total amount of coins generated in the blockchain up to this block.") DOC_END + KV_SERIALIZE(this_block_fee_median) DOC_DSCR("Median transaction fee of the transactions within this block.") DOC_END + KV_SERIALIZE(effective_fee_median) // TODO + KV_SERIALIZE(transactions_details) DOC_DSCR("Detailed information about each transaction included in the block.") DOC_END + KV_SERIALIZE(type) DOC_DSCR("Type of the block.") DOC_END + KV_SERIALIZE(is_orphan) DOC_DSCR("Indicates whether the block is an orphan.") DOC_END + KV_SERIALIZE(miner_text_info) DOC_DSCR("Additional textual information provided by the miner of the block.") DOC_END + KV_SERIALIZE(object_in_json) DOC_DSCR("Serialized representation of the block in JSON format.") DOC_END END_KV_SERIALIZE_MAP() }; - + //----------------------------------------------- + struct COMMAND_RPC_GET_BLOCKS_DETAILS { + DOC_COMMAND("Retrieves detailed information about a sequence of blocks starting from a specific height."); + struct request { uint64_t height_start; @@ -1496,9 +1601,9 @@ namespace currency bool ignore_transactions; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(height_start) - KV_SERIALIZE(count) - KV_SERIALIZE(ignore_transactions) + KV_SERIALIZE(height_start) DOC_DSCR("The starting block height from which block details are retrieved.") DOC_END + KV_SERIALIZE(count) DOC_DSCR("The number of blocks to retrieve from the starting height.") DOC_END + KV_SERIALIZE(ignore_transactions) // TODO END_KV_SERIALIZE_MAP() }; @@ -1508,22 +1613,26 @@ namespace currency std::list blocks; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) - KV_SERIALIZE(blocks) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END + KV_SERIALIZE(blocks) DOC_DSCR("List of blocks with detailed information, starting from the specified height.") DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- + struct COMMAND_RPC_GET_ALT_BLOCKS_DETAILS { + DOC_COMMAND("Retrieves details of alternative blocks in the blockchain, allowing for pagination through large datasets."); + struct request { uint64_t offset; uint64_t count; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(offset) - KV_SERIALIZE(count) + KV_SERIALIZE(offset) DOC_DSCR("The offset in the list of alternative blocks from which to start retrieval.") DOC_END + KV_SERIALIZE(count) DOC_DSCR("The number of alternative blocks to retrieve from the specified offset.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1533,21 +1642,24 @@ namespace currency std::vector blocks; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) - KV_SERIALIZE(blocks) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END + KV_SERIALIZE(blocks) DOC_DSCR("List of alternative blocks with detailed information, retrieved based on the specified parameters.") DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- struct COMMAND_RPC_GET_BLOCK_DETAILS { + DOC_COMMAND("Retrieves detailed information about a specific block identified by its hash."); + struct request { crypto::hash id; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE_POD_AS_HEX_STRING(id) + KV_SERIALIZE_POD_AS_HEX_STRING(id) DOC_DSCR("The hash ID of the block for which detailed information is being requested.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1557,21 +1669,24 @@ namespace currency block_rpc_extended_info block_details; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) - KV_SERIALIZE(block_details) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END + KV_SERIALIZE(block_details) DOC_DSCR("Detailed information about the block retrieved based on the provided hash ID.") DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- struct COMMAND_RPC_GET_POOL_TXS_DETAILS { + DOC_COMMAND("Retrieves detailed information about specific transactions in the transaction pool, identified by their IDs."); + struct request { std::list ids; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(ids) + KV_SERIALIZE(ids) DOC_DSCR("List of transaction IDs.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1581,21 +1696,24 @@ namespace currency std::list txs; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) - KV_SERIALIZE(txs) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END + KV_SERIALIZE(txs) DOC_DSCR("List of transactions with detailed information.") DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- struct COMMAND_RPC_GET_POOL_TXS_BRIEF_DETAILS { + DOC_COMMAND("Retrieves brief details about specific transactions in the transaction pool, identified by their IDs."); + struct request { std::list ids; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(ids) + KV_SERIALIZE(ids) DOC_DSCR("List of transaction IDs.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1605,14 +1723,18 @@ namespace currency std::list txs; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) - KV_SERIALIZE(txs) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END + KV_SERIALIZE(txs) DOC_DSCR("List of transactions with detailed information.") DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- + struct COMMAND_RPC_GET_ALL_POOL_TX_LIST { + DOC_COMMAND("Retrieves a list of all transaction IDs currently in the transaction pool."); + struct request { BEGIN_KV_SERIALIZE_MAP() @@ -1625,13 +1747,15 @@ namespace currency std::list ids; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) - KV_SERIALIZE(ids) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END + KV_SERIALIZE(ids) DOC_DSCR("List of all transaction IDs currently in the transaction pool.") DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- + // TODO looks like it is never used, a typo? struct COMMAND_RPC_GET_GLOBAL_INDEX_INFO { struct request @@ -1659,14 +1783,18 @@ namespace currency }; }; + //----------------------------------------------- + struct COMMAND_RPC_GET_TX_DETAILS { + DOC_COMMAND("Retrieves detailed information about a specific transaction."); + struct request { std::string tx_hash; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(tx_hash) + KV_SERIALIZE(tx_hash) DOC_DSCR("The hash of the transaction for which detailed information is being requested.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1676,12 +1804,13 @@ namespace currency tx_rpc_extended_info tx_info; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) - KV_SERIALIZE(tx_info) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END + KV_SERIALIZE(tx_info) DOC_DSCR("Detailed information about the transaction.") DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- struct search_entry { @@ -1690,12 +1819,14 @@ namespace currency struct COMMAND_RPC_SERARCH_BY_ID { + DOC_COMMAND("Searches for a given ID across various entity types such as blocks, transactions, key images, multisig outputs, and alternative blocks, useful when the entity type is unknown or unspecified."); + struct request { std::string id; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(id) + KV_SERIALIZE(id) DOC_DSCR("The identifier used to search across various types of entities.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1705,12 +1836,13 @@ namespace currency std::list types_found; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) - KV_SERIALIZE(types_found) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END + KV_SERIALIZE(types_found) DOC_DSCR("List of entity types where the identifier was found.") DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- struct COMMAND_RPC_GET_OFFERS_EX { @@ -1720,7 +1852,7 @@ namespace currency { bc_services::core_offers_filter filter; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(filter) DOC_DSCR("Filter options.") DOC_END + KV_SERIALIZE(filter) DOC_DSCR("Filter options.") DOC_END END_KV_SERIALIZE_MAP() }; @@ -1731,15 +1863,19 @@ namespace currency uint64_t total_offers; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) DOC_DSCR("Status of the operation") DOC_EXMP("OK") DOC_END - KV_SERIALIZE(offers) DOC_DSCR("List of offers related to the operation") DOC_EXMP_AUTO(1) DOC_END - KV_SERIALIZE(total_offers) DOC_DSCR("Total number of offers") DOC_EXMP(1) DOC_END + KV_SERIALIZE(status) DOC_DSCR("Status of the operation.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END + KV_SERIALIZE(offers) DOC_DSCR("List of offers related to the operation.") DOC_EXMP_AUTO(1) DOC_END + KV_SERIALIZE(total_offers) DOC_DSCR("Total number of offers.") DOC_EXMP(1) DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- + struct COMMAND_RPC_GET_CURRENT_CORE_TX_EXPIRATION_MEDIAN { + DOC_COMMAND("Retrieves the current core transaction expiration median."); + struct request { BEGIN_KV_SERIALIZE_MAP() @@ -1752,15 +1888,18 @@ namespace currency uint64_t expiration_median; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) - KV_SERIALIZE(expiration_median) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END + KV_SERIALIZE(expiration_median) DOC_DSCR("The median timestamp from the last N blocks, used to determine if transactions are expired based on their timestamp.") DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- struct COMMAND_VALIDATE_SIGNATURE { + DOC_COMMAND("Validates a Schnorr signature for arbitrary data. The public key for verification is provided directly or retrieved using an associated alias."); + struct request { std::string buff; //base64 encoded data @@ -1769,23 +1908,24 @@ namespace currency std::string alias; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(buff) - KV_SERIALIZE_POD_AS_HEX_STRING(sig) - KV_SERIALIZE_POD_AS_HEX_STRING(pkey) - KV_SERIALIZE(alias) + KV_SERIALIZE(buff) DOC_DSCR("Base64 encoded data for which the signature is to be validated.") DOC_END + KV_SERIALIZE_POD_AS_HEX_STRING(sig) DOC_DSCR("Schnorr signature to validate, encoded as a hexadecimal string.") DOC_END + KV_SERIALIZE_POD_AS_HEX_STRING(pkey) DOC_DSCR("Public key used for signature verification, encoded as a hexadecimal string. If null or not set, the public key is retrieved using the provided alias.") DOC_END + KV_SERIALIZE(alias) DOC_DSCR("Alias to retrieve the associated public spend key if no explicit public key is provided for verification.") DOC_END END_KV_SERIALIZE_MAP() }; - struct response { std::string status; BEGIN_KV_SERIALIZE_MAP() - KV_SERIALIZE(status) + KV_SERIALIZE(status) DOC_DSCR("Status of the call.") DOC_EXMP(API_RETURN_CODE_OK) DOC_END END_KV_SERIALIZE_MAP() }; }; + //----------------------------------------------- + struct void_struct { BEGIN_KV_SERIALIZE_MAP() diff --git a/tests/core_tests/multisig_wallet_tests.cpp b/tests/core_tests/multisig_wallet_tests.cpp index 4fdbcc7f..2801b1fc 100644 --- a/tests/core_tests/multisig_wallet_tests.cpp +++ b/tests/core_tests/multisig_wallet_tests.cpp @@ -23,7 +23,7 @@ using namespace currency; #define TMP_LOG_RESTORE #endif -void exception_handler(){} +static void exception_handler(){} //============================================================================================================================== // helper routine: creates multisig-spending tx using a wallet and keys of other ms-participants, then sends it to the core proxy