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