Bitcoin Core  27.99.0
P2P Digital Currency
node.cpp
Go to the documentation of this file.
1 // Copyright (c) 2010 Satoshi Nakamoto
2 // Copyright (c) 2009-2022 The Bitcoin Core developers
3 // Distributed under the MIT software license, see the accompanying
4 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
5 
6 #include <config/bitcoin-config.h> // IWYU pragma: keep
7 
8 #include <chainparams.h>
9 #include <httpserver.h>
10 #include <index/blockfilterindex.h>
11 #include <index/coinstatsindex.h>
12 #include <index/txindex.h>
13 #include <interfaces/chain.h>
14 #include <interfaces/echo.h>
15 #include <interfaces/init.h>
16 #include <interfaces/ipc.h>
17 #include <kernel/cs_main.h>
18 #include <logging.h>
19 #include <node/context.h>
20 #include <rpc/server.h>
21 #include <rpc/server_util.h>
22 #include <rpc/util.h>
23 #include <scheduler.h>
24 #include <univalue.h>
25 #include <util/any.h>
26 #include <util/check.h>
27 #include <util/time.h>
28 
29 #include <stdint.h>
30 #ifdef HAVE_MALLOC_INFO
31 #include <malloc.h>
32 #endif
33 
34 using node::NodeContext;
35 
37 {
38  return RPCHelpMan{"setmocktime",
39  "\nSet the local time to given timestamp (-regtest only)\n",
40  {
42  "Pass 0 to go back to using the system time."},
43  },
45  RPCExamples{""},
46  [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
47 {
48  if (!Params().IsMockableChain()) {
49  throw std::runtime_error("setmocktime is for regression testing (-regtest mode) only");
50  }
51 
52  // For now, don't change mocktime if we're in the middle of validation, as
53  // this could have an effect on mempool time-based eviction, as well as
54  // IsCurrentForFeeEstimation() and IsInitialBlockDownload().
55  // TODO: figure out the right way to synchronize around mocktime, and
56  // ensure all call sites of GetTime() are accessing this safely.
57  LOCK(cs_main);
58 
59  const int64_t time{request.params[0].getInt<int64_t>()};
60  constexpr int64_t max_time{Ticks<std::chrono::seconds>(std::chrono::nanoseconds::max())};
61  if (time < 0 || time > max_time) {
62  throw JSONRPCError(RPC_INVALID_PARAMETER, strprintf("Mocktime must be in the range [0, %s], not %s.", max_time, time));
63  }
64 
65  SetMockTime(time);
66  const NodeContext& node_context{EnsureAnyNodeContext(request.context)};
67  for (const auto& chain_client : node_context.chain_clients) {
68  chain_client->setMockTime(time);
69  }
70 
71  return UniValue::VNULL;
72 },
73  };
74 }
75 
77 {
78  return RPCHelpMan{"mockscheduler",
79  "\nBump the scheduler into the future (-regtest only)\n",
80  {
81  {"delta_time", RPCArg::Type::NUM, RPCArg::Optional::NO, "Number of seconds to forward the scheduler into the future." },
82  },
84  RPCExamples{""},
85  [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
86 {
87  if (!Params().IsMockableChain()) {
88  throw std::runtime_error("mockscheduler is for regression testing (-regtest mode) only");
89  }
90 
91  int64_t delta_seconds = request.params[0].getInt<int64_t>();
92  if (delta_seconds <= 0 || delta_seconds > 3600) {
93  throw std::runtime_error("delta_time must be between 1 and 3600 seconds (1 hr)");
94  }
95 
96  const NodeContext& node_context{EnsureAnyNodeContext(request.context)};
97  CHECK_NONFATAL(node_context.scheduler)->MockForward(std::chrono::seconds{delta_seconds});
98  CHECK_NONFATAL(node_context.validation_signals)->SyncWithValidationInterfaceQueue();
99  for (const auto& chain_client : node_context.chain_clients) {
100  chain_client->schedulerMockForward(std::chrono::seconds(delta_seconds));
101  }
102 
103  return UniValue::VNULL;
104 },
105  };
106 }
107 
109 {
112  obj.pushKV("used", uint64_t(stats.used));
113  obj.pushKV("free", uint64_t(stats.free));
114  obj.pushKV("total", uint64_t(stats.total));
115  obj.pushKV("locked", uint64_t(stats.locked));
116  obj.pushKV("chunks_used", uint64_t(stats.chunks_used));
117  obj.pushKV("chunks_free", uint64_t(stats.chunks_free));
118  return obj;
119 }
120 
121 #ifdef HAVE_MALLOC_INFO
122 static std::string RPCMallocInfo()
123 {
124  char *ptr = nullptr;
125  size_t size = 0;
126  FILE *f = open_memstream(&ptr, &size);
127  if (f) {
128  malloc_info(0, f);
129  fclose(f);
130  if (ptr) {
131  std::string rv(ptr, size);
132  free(ptr);
133  return rv;
134  }
135  }
136  return "";
137 }
138 #endif
139 
141 {
142  /* Please, avoid using the word "pool" here in the RPC interface or help,
143  * as users will undoubtedly confuse it with the other "memory pool"
144  */
145  return RPCHelpMan{"getmemoryinfo",
146  "Returns an object containing information about memory usage.\n",
147  {
148  {"mode", RPCArg::Type::STR, RPCArg::Default{"stats"}, "determines what kind of information is returned.\n"
149  " - \"stats\" returns general statistics about memory usage in the daemon.\n"
150  " - \"mallocinfo\" returns an XML string describing low-level heap state (only available if compiled with glibc)."},
151  },
152  {
153  RPCResult{"mode \"stats\"",
154  RPCResult::Type::OBJ, "", "",
155  {
156  {RPCResult::Type::OBJ, "locked", "Information about locked memory manager",
157  {
158  {RPCResult::Type::NUM, "used", "Number of bytes used"},
159  {RPCResult::Type::NUM, "free", "Number of bytes available in current arenas"},
160  {RPCResult::Type::NUM, "total", "Total number of bytes managed"},
161  {RPCResult::Type::NUM, "locked", "Amount of bytes that succeeded locking. If this number is smaller than total, locking pages failed at some point and key data could be swapped to disk."},
162  {RPCResult::Type::NUM, "chunks_used", "Number allocated chunks"},
163  {RPCResult::Type::NUM, "chunks_free", "Number unused chunks"},
164  }},
165  }
166  },
167  RPCResult{"mode \"mallocinfo\"",
168  RPCResult::Type::STR, "", "\"<malloc version=\"1\">...\""
169  },
170  },
171  RPCExamples{
172  HelpExampleCli("getmemoryinfo", "")
173  + HelpExampleRpc("getmemoryinfo", "")
174  },
175  [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
176 {
177  std::string mode = request.params[0].isNull() ? "stats" : request.params[0].get_str();
178  if (mode == "stats") {
180  obj.pushKV("locked", RPCLockedMemoryInfo());
181  return obj;
182  } else if (mode == "mallocinfo") {
183 #ifdef HAVE_MALLOC_INFO
184  return RPCMallocInfo();
185 #else
186  throw JSONRPCError(RPC_INVALID_PARAMETER, "mallocinfo mode not available");
187 #endif
188  } else {
189  throw JSONRPCError(RPC_INVALID_PARAMETER, "unknown mode " + mode);
190  }
191 },
192  };
193 }
194 
195 static void EnableOrDisableLogCategories(UniValue cats, bool enable) {
196  cats = cats.get_array();
197  for (unsigned int i = 0; i < cats.size(); ++i) {
198  std::string cat = cats[i].get_str();
199 
200  bool success;
201  if (enable) {
202  success = LogInstance().EnableCategory(cat);
203  } else {
204  success = LogInstance().DisableCategory(cat);
205  }
206 
207  if (!success) {
208  throw JSONRPCError(RPC_INVALID_PARAMETER, "unknown logging category " + cat);
209  }
210  }
211 }
212 
214 {
215  return RPCHelpMan{"logging",
216  "Gets and sets the logging configuration.\n"
217  "When called without an argument, returns the list of categories with status that are currently being debug logged or not.\n"
218  "When called with arguments, adds or removes categories from debug logging and return the lists above.\n"
219  "The arguments are evaluated in order \"include\", \"exclude\".\n"
220  "If an item is both included and excluded, it will thus end up being excluded.\n"
221  "The valid logging categories are: " + LogInstance().LogCategoriesString() + "\n"
222  "In addition, the following are available as category names with special meanings:\n"
223  " - \"all\", \"1\" : represent all logging categories.\n"
224  " - \"none\", \"0\" : even if other logging categories are specified, ignore all of them.\n"
225  ,
226  {
227  {"include", RPCArg::Type::ARR, RPCArg::Optional::OMITTED, "The categories to add to debug logging",
228  {
229  {"include_category", RPCArg::Type::STR, RPCArg::Optional::OMITTED, "the valid logging category"},
230  }},
231  {"exclude", RPCArg::Type::ARR, RPCArg::Optional::OMITTED, "The categories to remove from debug logging",
232  {
233  {"exclude_category", RPCArg::Type::STR, RPCArg::Optional::OMITTED, "the valid logging category"},
234  }},
235  },
236  RPCResult{
237  RPCResult::Type::OBJ_DYN, "", "keys are the logging categories, and values indicates its status",
238  {
239  {RPCResult::Type::BOOL, "category", "if being debug logged or not. false:inactive, true:active"},
240  }
241  },
242  RPCExamples{
243  HelpExampleCli("logging", "\"[\\\"all\\\"]\" \"[\\\"http\\\"]\"")
244  + HelpExampleRpc("logging", "[\"all\"], [\"libevent\"]")
245  },
246  [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
247 {
248  uint32_t original_log_categories = LogInstance().GetCategoryMask();
249  if (request.params[0].isArray()) {
250  EnableOrDisableLogCategories(request.params[0], true);
251  }
252  if (request.params[1].isArray()) {
253  EnableOrDisableLogCategories(request.params[1], false);
254  }
255  uint32_t updated_log_categories = LogInstance().GetCategoryMask();
256  uint32_t changed_log_categories = original_log_categories ^ updated_log_categories;
257 
258  // Update libevent logging if BCLog::LIBEVENT has changed.
259  if (changed_log_categories & BCLog::LIBEVENT) {
261  }
262 
263  UniValue result(UniValue::VOBJ);
264  for (const auto& logCatActive : LogInstance().LogCategoriesList()) {
265  result.pushKV(logCatActive.category, logCatActive.active);
266  }
267 
268  return result;
269 },
270  };
271 }
272 
273 static RPCHelpMan echo(const std::string& name)
274 {
275  return RPCHelpMan{name,
276  "\nSimply echo back the input arguments. This command is for testing.\n"
277  "\nIt will return an internal bug report when arg9='trigger_internal_bug' is passed.\n"
278  "\nThe difference between echo and echojson is that echojson has argument conversion enabled in the client-side table in "
279  "bitcoin-cli and the GUI. There is no server-side difference.",
280  {
291  },
292  RPCResult{RPCResult::Type::ANY, "", "Returns whatever was passed in"},
293  RPCExamples{""},
294  [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
295 {
296  if (request.params[9].isStr()) {
297  CHECK_NONFATAL(request.params[9].get_str() != "trigger_internal_bug");
298  }
299 
300  return request.params;
301 },
302  };
303 }
304 
305 static RPCHelpMan echo() { return echo("echo"); }
306 static RPCHelpMan echojson() { return echo("echojson"); }
307 
309 {
310  return RPCHelpMan{
311  "echoipc",
312  "\nEcho back the input argument, passing it through a spawned process in a multiprocess build.\n"
313  "This command is for testing.\n",
314  {{"arg", RPCArg::Type::STR, RPCArg::Optional::NO, "The string to echo",}},
315  RPCResult{RPCResult::Type::STR, "echo", "The echoed string."},
316  RPCExamples{HelpExampleCli("echo", "\"Hello world\"") +
317  HelpExampleRpc("echo", "\"Hello world\"")},
318  [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue {
319  interfaces::Init& local_init = *EnsureAnyNodeContext(request.context).init;
320  std::unique_ptr<interfaces::Echo> echo;
321  if (interfaces::Ipc* ipc = local_init.ipc()) {
322  // Spawn a new bitcoin-node process and call makeEcho to get a
323  // client pointer to a interfaces::Echo instance running in
324  // that process. This is just for testing. A slightly more
325  // realistic test spawning a different executable instead of
326  // the same executable would add a new bitcoin-echo executable,
327  // and spawn bitcoin-echo below instead of bitcoin-node. But
328  // using bitcoin-node avoids the need to build and install a
329  // new executable just for this one test.
330  auto init = ipc->spawnProcess("bitcoin-node");
331  echo = init->makeEcho();
332  ipc->addCleanup(*echo, [init = init.release()] { delete init; });
333  } else {
334  // IPC support is not available because this is a bitcoind
335  // process not a bitcoind-node process, so just create a local
336  // interfaces::Echo object and return it so the `echoipc` RPC
337  // method will work, and the python test calling `echoipc`
338  // can expect the same result.
339  echo = local_init.makeEcho();
340  }
341  return echo->echo(request.params[0].get_str());
342  },
343  };
344 }
345 
346 static UniValue SummaryToJSON(const IndexSummary&& summary, std::string index_name)
347 {
348  UniValue ret_summary(UniValue::VOBJ);
349  if (!index_name.empty() && index_name != summary.name) return ret_summary;
350 
351  UniValue entry(UniValue::VOBJ);
352  entry.pushKV("synced", summary.synced);
353  entry.pushKV("best_block_height", summary.best_block_height);
354  ret_summary.pushKV(summary.name, std::move(entry));
355  return ret_summary;
356 }
357 
359 {
360  return RPCHelpMan{"getindexinfo",
361  "\nReturns the status of one or all available indices currently running in the node.\n",
362  {
363  {"index_name", RPCArg::Type::STR, RPCArg::Optional::OMITTED, "Filter results for an index with a specific name."},
364  },
365  RPCResult{
366  RPCResult::Type::OBJ_DYN, "", "", {
367  {
368  RPCResult::Type::OBJ, "name", "The name of the index",
369  {
370  {RPCResult::Type::BOOL, "synced", "Whether the index is synced or not"},
371  {RPCResult::Type::NUM, "best_block_height", "The block height to which the index is synced"},
372  }
373  },
374  },
375  },
376  RPCExamples{
377  HelpExampleCli("getindexinfo", "")
378  + HelpExampleRpc("getindexinfo", "")
379  + HelpExampleCli("getindexinfo", "txindex")
380  + HelpExampleRpc("getindexinfo", "txindex")
381  },
382  [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
383 {
384  UniValue result(UniValue::VOBJ);
385  const std::string index_name = request.params[0].isNull() ? "" : request.params[0].get_str();
386 
387  if (g_txindex) {
388  result.pushKVs(SummaryToJSON(g_txindex->GetSummary(), index_name));
389  }
390 
391  if (g_coin_stats_index) {
392  result.pushKVs(SummaryToJSON(g_coin_stats_index->GetSummary(), index_name));
393  }
394 
395  ForEachBlockFilterIndex([&result, &index_name](const BlockFilterIndex& index) {
396  result.pushKVs(SummaryToJSON(index.GetSummary(), index_name));
397  });
398 
399  return result;
400 },
401  };
402 }
403 
405 {
406  static const CRPCCommand commands[]{
407  {"control", &getmemoryinfo},
408  {"control", &logging},
409  {"util", &getindexinfo},
410  {"hidden", &setmocktime},
411  {"hidden", &mockscheduler},
412  {"hidden", &echo},
413  {"hidden", &echojson},
414  {"hidden", &echoipc},
415  };
416  for (const auto& c : commands) {
417  t.appendCommand(c.name, &c);
418  }
419 }
void ForEachBlockFilterIndex(std::function< void(BlockFilterIndex &)> fn)
Iterate over all running block filter indexes, invoking fn on each.
const CChainParams & Params()
Return the currently selected parameters.
#define CHECK_NONFATAL(condition)
Identity function.
Definition: check.h:73
void EnableCategory(LogFlags flag)
Definition: logging.cpp:99
uint32_t GetCategoryMask() const
Definition: logging.h:177
std::string LogCategoriesString() const
Returns a string with the log categories in alphabetical order.
Definition: logging.h:190
void DisableCategory(LogFlags flag)
Definition: logging.cpp:112
IndexSummary GetSummary() const
Get a summary of the index and its state.
Definition: base.cpp:421
BlockFilterIndex is used to store and retrieve block filters, hashes, and headers for a range of bloc...
bool IsMockableChain() const
If this chain allows time to be mocked.
Definition: chainparams.h:104
RPC command dispatcher.
Definition: server.h:133
Stats stats() const
Get pool usage statistics.
Definition: lockedpool.cpp:323
static LockedPoolManager & Instance()
Return the current instance, or create it once.
Definition: lockedpool.h:222
const std::string & get_str() const
@ VNULL
Definition: univalue.h:24
@ VOBJ
Definition: univalue.h:24
bool isNull() const
Definition: univalue.h:79
size_t size() const
Definition: univalue.h:71
void pushKVs(UniValue obj)
Definition: univalue.cpp:137
const UniValue & get_array() const
void pushKV(std::string key, UniValue val)
Definition: univalue.cpp:126
Initial interface created when a process is first started, and used to give and get access to other i...
Definition: init.h:30
virtual std::unique_ptr< Echo > makeEcho()
Definition: init.h:36
virtual Ipc * ipc()
Definition: init.h:37
Interface providing access to interprocess-communication (IPC) functionality.
Definition: ipc.h:45
std::unique_ptr< CoinStatsIndex > g_coin_stats_index
The global UTXO set hash object.
RecursiveMutex cs_main
Mutex to guard access to validation specific variables, such as reading or changing the chainstate.
Definition: cs_main.cpp:8
void UpdateHTTPServerLogging(bool enable)
Change logging level for libevent.
Definition: httpserver.cpp:473
BCLog::Logger & LogInstance()
Definition: logging.cpp:23
@ LIBEVENT
Definition: logging.h:58
Definition: ipc.h:12
static RPCHelpMan logging()
Definition: node.cpp:213
static RPCHelpMan setmocktime()
Definition: node.cpp:36
void RegisterNodeRPCCommands(CRPCTable &t)
Definition: node.cpp:404
static void EnableOrDisableLogCategories(UniValue cats, bool enable)
Definition: node.cpp:195
static UniValue RPCLockedMemoryInfo()
Definition: node.cpp:108
static RPCHelpMan mockscheduler()
Definition: node.cpp:76
static RPCHelpMan getmemoryinfo()
Definition: node.cpp:140
static RPCHelpMan echo(const std::string &name)
Definition: node.cpp:273
static UniValue SummaryToJSON(const IndexSummary &&summary, std::string index_name)
Definition: node.cpp:346
static RPCHelpMan echojson()
Definition: node.cpp:306
static RPCHelpMan echoipc()
Definition: node.cpp:308
static RPCHelpMan getindexinfo()
Definition: node.cpp:358
UniValue JSONRPCError(int code, const std::string &message)
Definition: request.cpp:71
const char * name
Definition: rest.cpp:49
@ RPC_INVALID_PARAMETER
Invalid, missing or duplicate parameter.
Definition: protocol.h:44
std::string HelpExampleCli(const std::string &methodname, const std::string &args)
Definition: util.cpp:169
std::string HelpExampleRpc(const std::string &methodname, const std::string &args)
Definition: util.cpp:187
const std::string UNIX_EPOCH_TIME
String used to describe UNIX epoch time in documentation, factored out to a constant for consistency.
Definition: util.cpp:44
NodeContext & EnsureAnyNodeContext(const std::any &context)
Definition: server_util.cpp:21
Memory statistics.
Definition: lockedpool.h:146
@ OMITTED
Optional argument for which the default value is omitted from help text for one of two reasons:
@ NO
Required arg.
bool skip_type_check
Definition: util.h:156
@ ANY
Special type to disable type checks (for testing only)
@ OBJ_DYN
Special dictionary with keys that are not literals.
NodeContext struct containing references to chain state and connection state.
Definition: context.h:53
interfaces::Init * init
Init interface for initializing current process and connecting to other processes.
Definition: context.h:58
#define LOCK(cs)
Definition: sync.h:257
void SetMockTime(int64_t nMockTimeIn)
DEPRECATED Use SetMockTime with chrono type.
Definition: time.cpp:32
#define strprintf
Format arguments and return the string or write to given std::ostream (see tinyformat::format doc for...
Definition: tinyformat.h:1162
std::unique_ptr< TxIndex > g_txindex
The global transaction index, used in GetTransaction. May be null.
Definition: txindex.cpp:16