Skip to content

Commit faecb2e

Browse files
fanquakefanquake
committed
Merge bitcoin/bitcoin#22798: doc: Fix RPC result documentation
fa10fbc doc: Fix RPC result documentation (MarcoFalke) Pull request description: Fix: * Incorrectly named fields * Add missing ones * Add missing optional flag ACKs for top commit: fanquake: ACK fa10fbc Tree-SHA512: 2b302e6f7ac8253a55882bc032ddda1932b728abddd12b0adb5fba814b12fb998a67b91e6dd124ebbe0ac16dccdace01332ade01c1dc00a3768647118dd3a2d2
2 parents 971cad4 + fa10fbc commit faecb2e

File tree

7 files changed

+145
-124
lines changed

7 files changed

+145
-124
lines changed

‎src/rpc/blockchain.cpp

Lines changed: 42 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1115,11 +1115,11 @@ static RPCHelpMan gettxoutsetinfo()
11151115
{RPCResult::Type::NUM, "bogosize", "Database-independent, meaningless metric indicating the UTXO set size"},
11161116
{RPCResult::Type::STR_HEX, "hash_serialized_2", /* optional */ true, "The serialized hash (only present if 'hash_serialized_2' hash_type is chosen)"},
11171117
{RPCResult::Type::STR_HEX, "muhash", /* optional */ true, "The serialized hash (only present if 'muhash' hash_type is chosen)"},
1118-
{RPCResult::Type::NUM, "transactions", "The number of transactions with unspent outputs (not available when coinstatsindex is used)"},
1119-
{RPCResult::Type::NUM, "disk_size", "The estimated size of the chainstate on disk (not available when coinstatsindex is used)"},
1118+
{RPCResult::Type::NUM, "transactions", /* optional */ true, "The number of transactions with unspent outputs (not available when coinstatsindex is used)"},
1119+
{RPCResult::Type::NUM, "disk_size", /* optional */ true, "The estimated size of the chainstate on disk (not available when coinstatsindex is used)"},
11201120
{RPCResult::Type::STR_AMOUNT, "total_amount", "The total amount of coins in the UTXO set"},
1121-
{RPCResult::Type::STR_AMOUNT, "total_unspendable_amount", "The total amount of coins permanently excluded from the UTXO set (only available if coinstatsindex is used)"},
1122-
{RPCResult::Type::OBJ, "block_info", "Info on amounts in the block at this block height (only available if coinstatsindex is used)",
1121+
{RPCResult::Type::STR_AMOUNT, "total_unspendable_amount", /* optional */ true, "The total amount of coins permanently excluded from the UTXO set (only available if coinstatsindex is used)"},
1122+
{RPCResult::Type::OBJ, "block_info", /* optional */ true, "Info on amounts in the block at this block height (only available if coinstatsindex is used)",
11231123
{
11241124
{RPCResult::Type::STR_AMOUNT, "prevout_spent", "Total amount of all prevouts spent in this block"},
11251125
{RPCResult::Type::STR_AMOUNT, "coinbase", "Coinbase subsidy amount of this block"},
@@ -1436,32 +1436,32 @@ RPCHelpMan getblockchaininfo()
14361436
{RPCResult::Type::STR_HEX, "chainwork", "total amount of work in active chain, in hexadecimal"},
14371437
{RPCResult::Type::NUM, "size_on_disk", "the estimated size of the block and undo files on disk"},
14381438
{RPCResult::Type::BOOL, "pruned", "if the blocks are subject to pruning"},
1439-
{RPCResult::Type::NUM, "pruneheight", "lowest-height complete block stored (only present if pruning is enabled)"},
1440-
{RPCResult::Type::BOOL, "automatic_pruning", "whether automatic pruning is enabled (only present if pruning is enabled)"},
1441-
{RPCResult::Type::NUM, "prune_target_size", "the target size used by pruning (only present if automatic pruning is enabled)"},
1439+
{RPCResult::Type::NUM, "pruneheight", /* optional */ true, "lowest-height complete block stored (only present if pruning is enabled)"},
1440+
{RPCResult::Type::BOOL, "automatic_pruning", /* optional */ true, "whether automatic pruning is enabled (only present if pruning is enabled)"},
1441+
{RPCResult::Type::NUM, "prune_target_size", /* optional */ true, "the target size used by pruning (only present if automatic pruning is enabled)"},
14421442
{RPCResult::Type::OBJ_DYN, "softforks", "status of softforks",
14431443
{
14441444
{RPCResult::Type::OBJ, "xxxx", "name of the softfork",
14451445
{
14461446
{RPCResult::Type::STR, "type", "one of \"buried\", \"bip9\""},
1447-
{RPCResult::Type::OBJ, "bip9", "status of bip9 softforks (only for \"bip9\" type)",
1447+
{RPCResult::Type::OBJ, "bip9", /* optional */ true, "status of bip9 softforks (only for \"bip9\" type)",
14481448
{
14491449
{RPCResult::Type::STR, "status", "one of \"defined\", \"started\", \"locked_in\", \"active\", \"failed\""},
1450-
{RPCResult::Type::NUM, "bit", "the bit (0-28) in the block version field used to signal this softfork (only for \"started\" and \"locked_in\" status)"},
1450+
{RPCResult::Type::NUM, "bit", /* optional */ true, "the bit (0-28) in the block version field used to signal this softfork (only for \"started\" and \"locked_in\" status)"},
14511451
{RPCResult::Type::NUM_TIME, "start_time", "the minimum median time past of a block at which the bit gains its meaning"},
14521452
{RPCResult::Type::NUM_TIME, "timeout", "the median time past of a block at which the deployment is considered failed if not yet locked in"},
14531453
{RPCResult::Type::NUM, "since", "height of the first block to which the status applies"},
14541454
{RPCResult::Type::NUM, "min_activation_height", "minimum height of blocks for which the rules may be enforced"},
1455-
{RPCResult::Type::OBJ, "statistics", "numeric statistics about signalling for a softfork (only for \"started\" and \"locked_in\" status)",
1455+
{RPCResult::Type::OBJ, "statistics", /* optional */ true, "numeric statistics about signalling for a softfork (only for \"started\" and \"locked_in\" status)",
14561456
{
14571457
{RPCResult::Type::NUM, "period", "the length in blocks of the signalling period"},
1458-
{RPCResult::Type::NUM, "threshold", "the number of blocks with the version bit set required to activate the feature (only for \"started\" status)"},
1458+
{RPCResult::Type::NUM, "threshold", /* optional */ true, "the number of blocks with the version bit set required to activate the feature (only for \"started\" status)"},
14591459
{RPCResult::Type::NUM, "elapsed", "the number of blocks elapsed since the beginning of the current period"},
14601460
{RPCResult::Type::NUM, "count", "the number of blocks with the version bit set in the current period"},
1461-
{RPCResult::Type::BOOL, "possible", "returns false if there are not enough blocks left in this period to pass activation threshold (only for \"started\" status)"},
1461+
{RPCResult::Type::BOOL, "possible", /* optional */ true, "returns false if there are not enough blocks left in this period to pass activation threshold (only for \"started\" status)"},
14621462
}},
14631463
}},
1464-
{RPCResult::Type::NUM, "height", "height of the first block which the rules are or will be enforced (only for \"buried\" type, or \"bip9\" type with \"active\" status)"},
1464+
{RPCResult::Type::NUM, "height", /* optional */ true, "height of the first block which the rules are or will be enforced (only for \"buried\" type, or \"bip9\" type with \"active\" status)"},
14651465
{RPCResult::Type::BOOL, "active", "true if the rules are enforced for the mempool and the next block"},
14661466
}},
14671467
}},
@@ -1971,42 +1971,42 @@ static RPCHelpMan getblockstats()
19711971
RPCResult{
19721972
RPCResult::Type::OBJ, "", "",
19731973
{
1974-
{RPCResult::Type::NUM, "avgfee", "Average fee in the block"},
1975-
{RPCResult::Type::NUM, "avgfeerate", "Average feerate (in satoshis per virtual byte)"},
1976-
{RPCResult::Type::NUM, "avgtxsize", "Average transaction size"},
1977-
{RPCResult::Type::STR_HEX, "blockhash", "The block hash (to check for potential reorgs)"},
1978-
{RPCResult::Type::ARR_FIXED, "feerate_percentiles", "Feerates at the 10th, 25th, 50th, 75th, and 90th percentile weight unit (in satoshis per virtual byte)",
1974+
{RPCResult::Type::NUM, "avgfee", /* optional */ true, "Average fee in the block"},
1975+
{RPCResult::Type::NUM, "avgfeerate", /* optional */ true, "Average feerate (in satoshis per virtual byte)"},
1976+
{RPCResult::Type::NUM, "avgtxsize", /* optional */ true, "Average transaction size"},
1977+
{RPCResult::Type::STR_HEX, "blockhash", /* optional */ true, "The block hash (to check for potential reorgs)"},
1978+
{RPCResult::Type::ARR_FIXED, "feerate_percentiles", /* optional */ true, "Feerates at the 10th, 25th, 50th, 75th, and 90th percentile weight unit (in satoshis per virtual byte)",
19791979
{
19801980
{RPCResult::Type::NUM, "10th_percentile_feerate", "The 10th percentile feerate"},
19811981
{RPCResult::Type::NUM, "25th_percentile_feerate", "The 25th percentile feerate"},
19821982
{RPCResult::Type::NUM, "50th_percentile_feerate", "The 50th percentile feerate"},
19831983
{RPCResult::Type::NUM, "75th_percentile_feerate", "The 75th percentile feerate"},
19841984
{RPCResult::Type::NUM, "90th_percentile_feerate", "The 90th percentile feerate"},
19851985
}},
1986-
{RPCResult::Type::NUM, "height", "The height of the block"},
1987-
{RPCResult::Type::NUM, "ins", "The number of inputs (excluding coinbase)"},
1988-
{RPCResult::Type::NUM, "maxfee", "Maximum fee in the block"},
1989-
{RPCResult::Type::NUM, "maxfeerate", "Maximum feerate (in satoshis per virtual byte)"},
1990-
{RPCResult::Type::NUM, "maxtxsize", "Maximum transaction size"},
1991-
{RPCResult::Type::NUM, "medianfee", "Truncated median fee in the block"},
1992-
{RPCResult::Type::NUM, "mediantime", "The block median time past"},
1993-
{RPCResult::Type::NUM, "mediantxsize", "Truncated median transaction size"},
1994-
{RPCResult::Type::NUM, "minfee", "Minimum fee in the block"},
1995-
{RPCResult::Type::NUM, "minfeerate", "Minimum feerate (in satoshis per virtual byte)"},
1996-
{RPCResult::Type::NUM, "mintxsize", "Minimum transaction size"},
1997-
{RPCResult::Type::NUM, "outs", "The number of outputs"},
1998-
{RPCResult::Type::NUM, "subsidy", "The block subsidy"},
1999-
{RPCResult::Type::NUM, "swtotal_size", "Total size of all segwit transactions"},
2000-
{RPCResult::Type::NUM, "swtotal_weight", "Total weight of all segwit transactions"},
2001-
{RPCResult::Type::NUM, "swtxs", "The number of segwit transactions"},
2002-
{RPCResult::Type::NUM, "time", "The block time"},
2003-
{RPCResult::Type::NUM, "total_out", "Total amount in all outputs (excluding coinbase and thus reward [ie subsidy + totalfee])"},
2004-
{RPCResult::Type::NUM, "total_size", "Total size of all non-coinbase transactions"},
2005-
{RPCResult::Type::NUM, "total_weight", "Total weight of all non-coinbase transactions"},
2006-
{RPCResult::Type::NUM, "totalfee", "The fee total"},
2007-
{RPCResult::Type::NUM, "txs", "The number of transactions (including coinbase)"},
2008-
{RPCResult::Type::NUM, "utxo_increase", "The increase/decrease in the number of unspent outputs"},
2009-
{RPCResult::Type::NUM, "utxo_size_inc", "The increase/decrease in size for the utxo index (not discounting op_return and similar)"},
1986+
{RPCResult::Type::NUM, "height", /* optional */ true, "The height of the block"},
1987+
{RPCResult::Type::NUM, "ins", /* optional */ true, "The number of inputs (excluding coinbase)"},
1988+
{RPCResult::Type::NUM, "maxfee", /* optional */ true, "Maximum fee in the block"},
1989+
{RPCResult::Type::NUM, "maxfeerate", /* optional */ true, "Maximum feerate (in satoshis per virtual byte)"},
1990+
{RPCResult::Type::NUM, "maxtxsize", /* optional */ true, "Maximum transaction size"},
1991+
{RPCResult::Type::NUM, "medianfee", /* optional */ true, "Truncated median fee in the block"},
1992+
{RPCResult::Type::NUM, "mediantime", /* optional */ true, "The block median time past"},
1993+
{RPCResult::Type::NUM, "mediantxsize", /* optional */ true, "Truncated median transaction size"},
1994+
{RPCResult::Type::NUM, "minfee", /* optional */ true, "Minimum fee in the block"},
1995+
{RPCResult::Type::NUM, "minfeerate", /* optional */ true, "Minimum feerate (in satoshis per virtual byte)"},
1996+
{RPCResult::Type::NUM, "mintxsize", /* optional */ true, "Minimum transaction size"},
1997+
{RPCResult::Type::NUM, "outs", /* optional */ true, "The number of outputs"},
1998+
{RPCResult::Type::NUM, "subsidy", /* optional */ true, "The block subsidy"},
1999+
{RPCResult::Type::NUM, "swtotal_size", /* optional */ true, "Total size of all segwit transactions"},
2000+
{RPCResult::Type::NUM, "swtotal_weight", /* optional */ true, "Total weight of all segwit transactions"},
2001+
{RPCResult::Type::NUM, "swtxs", /* optional */ true, "The number of segwit transactions"},
2002+
{RPCResult::Type::NUM, "time", /* optional */ true, "The block time"},
2003+
{RPCResult::Type::NUM, "total_out", /* optional */ true, "Total amount in all outputs (excluding coinbase and thus reward [ie subsidy + totalfee])"},
2004+
{RPCResult::Type::NUM, "total_size", /* optional */ true, "Total size of all non-coinbase transactions"},
2005+
{RPCResult::Type::NUM, "total_weight", /* optional */ true, "Total weight of all non-coinbase transactions"},
2006+
{RPCResult::Type::NUM, "totalfee", /* optional */ true, "The fee total"},
2007+
{RPCResult::Type::NUM, "txs", /* optional */ true, "The number of transactions (including coinbase)"},
2008+
{RPCResult::Type::NUM, "utxo_increase", /* optional */ true, "The increase/decrease in the number of unspent outputs"},
2009+
{RPCResult::Type::NUM, "utxo_size_inc", /* optional */ true, "The increase/decrease in size for the utxo index (not discounting op_return and similar)"},
20102010
}},
20112011
RPCExamples{
20122012
HelpExampleCli("getblockstats", R"('"00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09"' '["minfeerate","avgfeerate"]')") +

‎src/rpc/external_signer.cpp

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,11 @@ static RPCHelpMan enumeratesigners()
2424
{
2525
{RPCResult::Type::ARR, "signers", /* optional */ false, "",
2626
{
27-
{RPCResult::Type::STR_HEX, "masterkeyfingerprint", "Master key fingerprint"},
28-
{RPCResult::Type::STR, "name", "Device name"},
27+
{RPCResult::Type::OBJ, "", "",
28+
{
29+
{RPCResult::Type::STR_HEX, "fingerprint", "Master key fingerprint"},
30+
{RPCResult::Type::STR, "name", "Device name"},
31+
}},
2932
},
3033
}
3134
}

‎src/rpc/mining.cpp

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -553,6 +553,10 @@ static RPCHelpMan getblocktemplate()
553553
{
554554
{RPCResult::Type::NUM, "rulename", "identifies the bit number as indicating acceptance and readiness for the named softfork rule"},
555555
}},
556+
{RPCResult::Type::ARR, "capabilities", "",
557+
{
558+
{RPCResult::Type::STR, "value", "A supported feature, for example 'proposal'"},
559+
}},
556560
{RPCResult::Type::NUM, "vbrequired", "bit mask of versionbits the server requires set in submissions"},
557561
{RPCResult::Type::STR, "previousblockhash", "The hash of current highest block"},
558562
{RPCResult::Type::ARR, "transactions", "contents of non-coinbase transactions that should be included in the next block",
@@ -586,11 +590,12 @@ static RPCHelpMan getblocktemplate()
586590
{RPCResult::Type::STR_HEX, "noncerange", "A range of valid nonces"},
587591
{RPCResult::Type::NUM, "sigoplimit", "limit of sigops in blocks"},
588592
{RPCResult::Type::NUM, "sizelimit", "limit of block size"},
589-
{RPCResult::Type::NUM, "weightlimit", "limit of block weight"},
593+
{RPCResult::Type::NUM, "weightlimit", /* optional */ true, "limit of block weight"},
590594
{RPCResult::Type::NUM_TIME, "curtime", "current timestamp in " + UNIX_EPOCH_TIME},
591595
{RPCResult::Type::STR, "bits", "compressed target of next block"},
592596
{RPCResult::Type::NUM, "height", "The height of the next block"},
593-
{RPCResult::Type::STR, "default_witness_commitment", /* optional */ true, "a valid witness commitment for the unmodified block template"},
597+
{RPCResult::Type::STR_HEX, "signet_challenge", /* optional */ true, "Only on signet"},
598+
{RPCResult::Type::STR_HEX, "default_witness_commitment", /* optional */ true, "a valid witness commitment for the unmodified block template"},
594599
}},
595600
},
596601
RPCExamples{

‎src/rpc/misc.cpp

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,10 @@ static RPCHelpMan validateaddress()
4444
RPCResult::Type::OBJ, "", "",
4545
{
4646
{RPCResult::Type::BOOL, "isvalid", "If the address is valid or not"},
47-
{RPCResult::Type::STR, "address", "The bitcoin address validated"},
48-
{RPCResult::Type::STR_HEX, "scriptPubKey", "The hex-encoded scriptPubKey generated by the address"},
49-
{RPCResult::Type::BOOL, "isscript", "If the key is a script"},
50-
{RPCResult::Type::BOOL, "iswitness", "If the address is a witness address"},
47+
{RPCResult::Type::STR, "address", /* optional */ true, "The bitcoin address validated"},
48+
{RPCResult::Type::STR_HEX, "scriptPubKey", /* optional */ true, "The hex-encoded scriptPubKey generated by the address"},
49+
{RPCResult::Type::BOOL, "isscript", /* optional */ true, "If the key is a script"},
50+
{RPCResult::Type::BOOL, "iswitness", /* optional */ true, "If the address is a witness address"},
5151
{RPCResult::Type::NUM, "witness_version", /* optional */ true, "The version number of the witness program"},
5252
{RPCResult::Type::STR_HEX, "witness_program", /* optional */ true, "The hex value of the witness program"},
5353
{RPCResult::Type::STR, "error", /* optional */ true, "Error message, if any"},
@@ -717,7 +717,7 @@ static RPCHelpMan getindexinfo()
717717
{"index_name", RPCArg::Type::STR, RPCArg::Optional::OMITTED_NAMED_ARG, "Filter results for an index with a specific name."},
718718
},
719719
RPCResult{
720-
RPCResult::Type::OBJ, "", "", {
720+
RPCResult::Type::OBJ_DYN, "", "", {
721721
{
722722
RPCResult::Type::OBJ, "name", "The name of the index",
723723
{

0 commit comments

Comments
 (0)