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