a6099ef319
Based on the proposal, update the help message of rpc methods - strings arguments are in double quotes rather than square brackets - numeric arguments have no quotes (and no default value) - optional parameters are surrounded by round brackets - json arguments are strings but don't use double quotes Added 3 sections for the details - Arguments: lists each argument, it's type, required or not, a default, and a description - Result: The method result, with json format if applicable, type, and a description - Examples: examples calls using bitcoin-cli and curl for json rpc call Problems - maybe this is too verbose - lines might be too long - description are not good or complete - examples may be too much
406 lines
15 KiB
C++
406 lines
15 KiB
C++
// Copyright (c) 2010 Satoshi Nakamoto
|
|
// Copyright (c) 2009-2013 The Bitcoin developers
|
|
// Distributed under the MIT/X11 software license, see the accompanying
|
|
// file COPYING or http://www.opensource.org/licenses/mit-license.php.
|
|
|
|
|
|
|
|
#include "bitcoinrpc.h"
|
|
#include "main.h"
|
|
#include "sync.h"
|
|
|
|
#include <stdint.h>
|
|
|
|
#include "json/json_spirit_value.h"
|
|
|
|
using namespace json_spirit;
|
|
using namespace std;
|
|
|
|
void ScriptPubKeyToJSON(const CScript& scriptPubKey, Object& out, bool fIncludeHex);
|
|
|
|
double GetDifficulty(const CBlockIndex* blockindex)
|
|
{
|
|
// Floating point number that is a multiple of the minimum difficulty,
|
|
// minimum difficulty = 1.0.
|
|
if (blockindex == NULL)
|
|
{
|
|
if (chainActive.Tip() == NULL)
|
|
return 1.0;
|
|
else
|
|
blockindex = chainActive.Tip();
|
|
}
|
|
|
|
int nShift = (blockindex->nBits >> 24) & 0xff;
|
|
|
|
double dDiff =
|
|
(double)0x0000ffff / (double)(blockindex->nBits & 0x00ffffff);
|
|
|
|
while (nShift < 29)
|
|
{
|
|
dDiff *= 256.0;
|
|
nShift++;
|
|
}
|
|
while (nShift > 29)
|
|
{
|
|
dDiff /= 256.0;
|
|
nShift--;
|
|
}
|
|
|
|
return dDiff;
|
|
}
|
|
|
|
|
|
Object blockToJSON(const CBlock& block, const CBlockIndex* blockindex)
|
|
{
|
|
Object result;
|
|
result.push_back(Pair("hash", block.GetHash().GetHex()));
|
|
CMerkleTx txGen(block.vtx[0]);
|
|
txGen.SetMerkleBranch(&block);
|
|
result.push_back(Pair("confirmations", (int)txGen.GetDepthInMainChain()));
|
|
result.push_back(Pair("size", (int)::GetSerializeSize(block, SER_NETWORK, PROTOCOL_VERSION)));
|
|
result.push_back(Pair("height", blockindex->nHeight));
|
|
result.push_back(Pair("version", block.nVersion));
|
|
result.push_back(Pair("merkleroot", block.hashMerkleRoot.GetHex()));
|
|
Array txs;
|
|
BOOST_FOREACH(const CTransaction&tx, block.vtx)
|
|
txs.push_back(tx.GetHash().GetHex());
|
|
result.push_back(Pair("tx", txs));
|
|
result.push_back(Pair("time", (boost::int64_t)block.GetBlockTime()));
|
|
result.push_back(Pair("nonce", (boost::uint64_t)block.nNonce));
|
|
result.push_back(Pair("bits", HexBits(block.nBits)));
|
|
result.push_back(Pair("difficulty", GetDifficulty(blockindex)));
|
|
result.push_back(Pair("chainwork", blockindex->nChainWork.GetHex()));
|
|
|
|
if (blockindex->pprev)
|
|
result.push_back(Pair("previousblockhash", blockindex->pprev->GetBlockHash().GetHex()));
|
|
CBlockIndex *pnext = chainActive.Next(blockindex);
|
|
if (pnext)
|
|
result.push_back(Pair("nextblockhash", pnext->GetBlockHash().GetHex()));
|
|
return result;
|
|
}
|
|
|
|
|
|
Value getblockcount(const Array& params, bool fHelp)
|
|
{
|
|
if (fHelp || params.size() != 0)
|
|
throw runtime_error(
|
|
"getblockcount\n"
|
|
"\nReturns the number of blocks in the longest block chain.\n"
|
|
"\nResult:\n"
|
|
"n (numeric) The current block count\n"
|
|
"\nExamples:\n"
|
|
+ HelpExampleCli("getblockcount", "")
|
|
+ HelpExampleRpc("getblockcount", "")
|
|
);
|
|
|
|
return chainActive.Height();
|
|
}
|
|
|
|
Value getbestblockhash(const Array& params, bool fHelp)
|
|
{
|
|
if (fHelp || params.size() != 0)
|
|
throw runtime_error(
|
|
"getbestblockhash\n"
|
|
"\nReturns the hash of the best (tip) block in the longest block chain.\n"
|
|
"\nResult\n"
|
|
"\"hex\" (string) the block hash hex encoded\n"
|
|
"\nExamples\n"
|
|
+ HelpExampleCli("getbestblockhash", "")
|
|
+ HelpExampleRpc("getbestblockhash", "")
|
|
);
|
|
|
|
return chainActive.Tip()->GetBlockHash().GetHex();
|
|
}
|
|
|
|
Value getdifficulty(const Array& params, bool fHelp)
|
|
{
|
|
if (fHelp || params.size() != 0)
|
|
throw runtime_error(
|
|
"getdifficulty\n"
|
|
"\nReturns the proof-of-work difficulty as a multiple of the minimum difficulty.\n"
|
|
"\nResult:\n"
|
|
"n.nnn (numeric) the proof-of-work difficulty as a multiple of the minimum difficulty.\n"
|
|
"\nExamples:\n"
|
|
+ HelpExampleCli("getdifficulty", "")
|
|
+ HelpExampleRpc("getdifficulty", "")
|
|
);
|
|
|
|
return GetDifficulty();
|
|
}
|
|
|
|
|
|
Value settxfee(const Array& params, bool fHelp)
|
|
{
|
|
if (fHelp || params.size() < 1 || params.size() > 1)
|
|
throw runtime_error(
|
|
"settxfee amount\n"
|
|
"\nSet the transaction fee. 'amount' is a real and is rounded to the nearest 0.00000001\n"
|
|
"\nArguments:\n"
|
|
"1. amount (numeric, required) The transaction fee in btc rounded to the nearest 0.00000001\n"
|
|
"\nResult\n"
|
|
"true|false (boolean) Returns true if successful\n"
|
|
"\nExamples:\n"
|
|
+ HelpExampleCli("settxfee", "0.00001")
|
|
+ HelpExampleRpc("settxfee", "0.00001")
|
|
);
|
|
|
|
// Amount
|
|
int64_t nAmount = 0;
|
|
if (params[0].get_real() != 0.0)
|
|
nAmount = AmountFromValue(params[0]); // rejects 0.0 amounts
|
|
|
|
nTransactionFee = nAmount;
|
|
return true;
|
|
}
|
|
|
|
Value getrawmempool(const Array& params, bool fHelp)
|
|
{
|
|
if (fHelp || params.size() != 0)
|
|
throw runtime_error(
|
|
"getrawmempool\n"
|
|
"\nReturns all transaction ids in memory pool as a json array of string transaction ids.\n"
|
|
"\nResult:\n"
|
|
"[ (json array of string)\n"
|
|
" \"transactionid\" (string) The transaction id\n"
|
|
" ,...\n"
|
|
"]\n"
|
|
"\nExamples\n"
|
|
+ HelpExampleCli("getrawmempool", "")
|
|
+ HelpExampleRpc("getrawmempool", "")
|
|
);
|
|
|
|
vector<uint256> vtxid;
|
|
mempool.queryHashes(vtxid);
|
|
|
|
Array a;
|
|
BOOST_FOREACH(const uint256& hash, vtxid)
|
|
a.push_back(hash.ToString());
|
|
|
|
return a;
|
|
}
|
|
|
|
Value getblockhash(const Array& params, bool fHelp)
|
|
{
|
|
if (fHelp || params.size() != 1)
|
|
throw runtime_error(
|
|
"getblockhash index\n"
|
|
"\nReturns hash of block in best-block-chain at index provided.\n"
|
|
"\nArguments:\n"
|
|
"1. index (numeric, required) The block index\n"
|
|
"\nResult:\n"
|
|
"\"hash\" (string) The block hash\n"
|
|
"\nExamples:\n"
|
|
+ HelpExampleCli("getblockhash", "1000")
|
|
+ HelpExampleRpc("getblockhash", "1000")
|
|
);
|
|
|
|
int nHeight = params[0].get_int();
|
|
if (nHeight < 0 || nHeight > chainActive.Height())
|
|
throw runtime_error("Block number out of range.");
|
|
|
|
CBlockIndex* pblockindex = chainActive[nHeight];
|
|
return pblockindex->GetBlockHash().GetHex();
|
|
}
|
|
|
|
Value getblock(const Array& params, bool fHelp)
|
|
{
|
|
if (fHelp || params.size() < 1 || params.size() > 2)
|
|
throw runtime_error(
|
|
"getblock \"hash\" ( verbose )\n"
|
|
"\nIf verbose is false, returns a string that is serialized, hex-encoded data for block 'hash'.\n"
|
|
"If verbose is true, returns an Object with information about block <hash>.\n"
|
|
"\nArguments:\n"
|
|
"1. \"hash\" (string, required) The block hash\n"
|
|
"2. verbose (boolean, optional, default=true) true for a json object, false for the hex encoded data\n"
|
|
"\nResult (for verbose = true):\n"
|
|
"{\n"
|
|
" \"hash\" : \"hash\", (string) the block hash (same as provided)\n"
|
|
" \"confirmations\" : n, (numeric) The number of confirmations\n"
|
|
" \"size\" : n, (numeric) The block size\n"
|
|
" \"height\" : n, (numeric) The block height or index\n"
|
|
" \"version\" : n, (numeric) The block version\n"
|
|
" \"merkleroot\" : \"xxxx\", (string) The merkle root\n"
|
|
" \"tx\" : [ (array of string) The transaction ids\n"
|
|
" \"transactionid\" (string) The transaction id\n"
|
|
" ,...\n"
|
|
" ],\n"
|
|
" \"time\" : ttt, (numeric) The block time in seconds since epoch (Jan 1 1970 GMT)\n"
|
|
" \"nonce\" : n, (numeric) The nonce\n"
|
|
" \"bits\" : \"1d00ffff\", (string) The bits\n"
|
|
" \"difficulty\" : x.xxx, (numeric) The difficulty\n"
|
|
" \"previousblockhash\" : \"hash\", (string) The hash of the previous block\n"
|
|
" \"nextblockhash\" : \"hash\" (string) The hash of the next block\n"
|
|
"}\n"
|
|
"\nResult (for verbose=false):\n"
|
|
"\"data\" (string) A string that is serialized, hex-encoded data for block 'hash'.\n"
|
|
"\nExamples:\n"
|
|
+ HelpExampleCli("getblock", "\"00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09\"")
|
|
+ HelpExampleRpc("getblock", "\"00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09\"")
|
|
);
|
|
|
|
std::string strHash = params[0].get_str();
|
|
uint256 hash(strHash);
|
|
|
|
bool fVerbose = true;
|
|
if (params.size() > 1)
|
|
fVerbose = params[1].get_bool();
|
|
|
|
if (mapBlockIndex.count(hash) == 0)
|
|
throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Block not found");
|
|
|
|
CBlock block;
|
|
CBlockIndex* pblockindex = mapBlockIndex[hash];
|
|
ReadBlockFromDisk(block, pblockindex);
|
|
|
|
if (!fVerbose)
|
|
{
|
|
CDataStream ssBlock(SER_NETWORK, PROTOCOL_VERSION);
|
|
ssBlock << block;
|
|
std::string strHex = HexStr(ssBlock.begin(), ssBlock.end());
|
|
return strHex;
|
|
}
|
|
|
|
return blockToJSON(block, pblockindex);
|
|
}
|
|
|
|
Value gettxoutsetinfo(const Array& params, bool fHelp)
|
|
{
|
|
if (fHelp || params.size() != 0)
|
|
throw runtime_error(
|
|
"gettxoutsetinfo\n"
|
|
"\nReturns statistics about the unspent transaction output set.\n"
|
|
"Note this call may take some time.\n"
|
|
"\nResult:\n"
|
|
"{\n"
|
|
" \"height\":n, (numeric) The current block height (index)\n"
|
|
" \"bestblock\": \"hex\", (string) the best block hash hex\n"
|
|
" \"transactions\": n, (numeric) The number of transactions\n"
|
|
" \"txouts\": n, (numeric) The number of output transactions\n"
|
|
" \"bytes_serialized\": n, (numeric) The serialized size\n"
|
|
" \"hash_serialized\": \"hash\", (string) The serialized hash\n"
|
|
" \"total_amount\": x.xxx (numeric) The total amount\n"
|
|
"}\n"
|
|
"\nExamples:\n"
|
|
+ HelpExampleCli("gettxoutsetinfo", "")
|
|
+ HelpExampleRpc("gettxoutsetinfo", "")
|
|
);
|
|
|
|
Object ret;
|
|
|
|
CCoinsStats stats;
|
|
if (pcoinsTip->GetStats(stats)) {
|
|
ret.push_back(Pair("height", (boost::int64_t)stats.nHeight));
|
|
ret.push_back(Pair("bestblock", stats.hashBlock.GetHex()));
|
|
ret.push_back(Pair("transactions", (boost::int64_t)stats.nTransactions));
|
|
ret.push_back(Pair("txouts", (boost::int64_t)stats.nTransactionOutputs));
|
|
ret.push_back(Pair("bytes_serialized", (boost::int64_t)stats.nSerializedSize));
|
|
ret.push_back(Pair("hash_serialized", stats.hashSerialized.GetHex()));
|
|
ret.push_back(Pair("total_amount", ValueFromAmount(stats.nTotalAmount)));
|
|
}
|
|
return ret;
|
|
}
|
|
|
|
Value gettxout(const Array& params, bool fHelp)
|
|
{
|
|
if (fHelp || params.size() < 2 || params.size() > 3)
|
|
throw runtime_error(
|
|
"gettxout \"txid\" n ( includemempool )\n"
|
|
"\nReturns details about an unspent transaction output.\n"
|
|
"\nArguments:\n"
|
|
"1. \"txid\" (string, required) The transaction id\n"
|
|
"2. n (numeric, required) vout value\n"
|
|
"3. includemempool (boolean, optional) Whether to included the mem pool\n"
|
|
"\nResult:\n"
|
|
"{\n"
|
|
" \"bestblock\" : \"hash\", (string) the block hash\n"
|
|
" \"confirmations\" : n, (numeric) The number of confirmations\n"
|
|
" \"value\" : x.xxx, (numeric) The transaction value in btc\n"
|
|
" \"scriptPubKey\" : { (json object)\n"
|
|
" \"asm\" : \"code\", (string) \n"
|
|
" \"hex\" : \"hex\", (string) \n"
|
|
" \"reqSigs\" : n, (numeric) Number of required signatures\n"
|
|
" \"type\" : \"pubkeyhash\", (string) The type, eg pubkeyhash\n"
|
|
" \"addresses\" : [ (array of string) array of bitcoin addresses\n"
|
|
" \"bitcoinaddress\" (string) bitcoin address\n"
|
|
" ,...\n"
|
|
" ]\n"
|
|
" },\n"
|
|
" \"version\" : n, (numeric) The version\n"
|
|
" \"coinbase\" : true|false (boolean) Coinbase or not\n"
|
|
"}\n"
|
|
|
|
"\nExamples:\n"
|
|
"\nGet unspent transactions\n"
|
|
+ HelpExampleCli("listunspent", "") +
|
|
"\nView the details\n"
|
|
+ HelpExampleCli("gettxout", "\"txid\" 1") +
|
|
"\nAs a json rpc call\n"
|
|
+ HelpExampleRpc("gettxout", "\"txid\", 1")
|
|
);
|
|
|
|
Object ret;
|
|
|
|
std::string strHash = params[0].get_str();
|
|
uint256 hash(strHash);
|
|
int n = params[1].get_int();
|
|
bool fMempool = true;
|
|
if (params.size() > 2)
|
|
fMempool = params[2].get_bool();
|
|
|
|
CCoins coins;
|
|
if (fMempool) {
|
|
LOCK(mempool.cs);
|
|
CCoinsViewMemPool view(*pcoinsTip, mempool);
|
|
if (!view.GetCoins(hash, coins))
|
|
return Value::null;
|
|
mempool.pruneSpent(hash, coins); // TODO: this should be done by the CCoinsViewMemPool
|
|
} else {
|
|
if (!pcoinsTip->GetCoins(hash, coins))
|
|
return Value::null;
|
|
}
|
|
if (n<0 || (unsigned int)n>=coins.vout.size() || coins.vout[n].IsNull())
|
|
return Value::null;
|
|
|
|
std::map<uint256, CBlockIndex*>::iterator it = mapBlockIndex.find(pcoinsTip->GetBestBlock());
|
|
CBlockIndex *pindex = it->second;
|
|
ret.push_back(Pair("bestblock", pindex->GetBlockHash().GetHex()));
|
|
if ((unsigned int)coins.nHeight == MEMPOOL_HEIGHT)
|
|
ret.push_back(Pair("confirmations", 0));
|
|
else
|
|
ret.push_back(Pair("confirmations", pindex->nHeight - coins.nHeight + 1));
|
|
ret.push_back(Pair("value", ValueFromAmount(coins.vout[n].nValue)));
|
|
Object o;
|
|
ScriptPubKeyToJSON(coins.vout[n].scriptPubKey, o, true);
|
|
ret.push_back(Pair("scriptPubKey", o));
|
|
ret.push_back(Pair("version", coins.nVersion));
|
|
ret.push_back(Pair("coinbase", coins.fCoinBase));
|
|
|
|
return ret;
|
|
}
|
|
|
|
Value verifychain(const Array& params, bool fHelp)
|
|
{
|
|
if (fHelp || params.size() > 2)
|
|
throw runtime_error(
|
|
"verifychain ( checklevel numblocks )\n"
|
|
"\nVerifies blockchain database.\n"
|
|
"\nArguments:\n"
|
|
"1. checklevel (numeric, optional, default=3) The level\n"
|
|
"2. numblocks (numeric, optional, 288) The number of blocks\n"
|
|
"\nResult:\n"
|
|
"true|false (boolean) Verified or not\n"
|
|
"\nExamples:\n"
|
|
+ HelpExampleCli("verifychain", "")
|
|
+ HelpExampleRpc("verifychain", "")
|
|
);
|
|
|
|
int nCheckLevel = GetArg("-checklevel", 3);
|
|
int nCheckDepth = GetArg("-checkblocks", 288);
|
|
if (params.size() > 0)
|
|
nCheckLevel = params[0].get_int();
|
|
if (params.size() > 1)
|
|
nCheckDepth = params[1].get_int();
|
|
|
|
return VerifyDB(nCheckLevel, nCheckDepth);
|
|
}
|
|
|