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 <key_io.h>
  7  #include <outputtype.h>
  8  #include <pubkey.h>
  9  #include <rpc/protocol.h>
 10  #include <rpc/request.h>
 11  #include <rpc/server.h>
 12  #include <rpc/util.h>
 13  #include <script/descriptor.h>
 14  #include <script/script.h>
 15  #include <script/signingprovider.h>
 16  #include <tinyformat.h>
 17  #include <univalue.h>
 18  #include <util/check.h>
 19  #include <util/strencodings.h>
 20  
 21  #include <cstdint>
 22  #include <memory>
 23  #include <optional>
 24  #include <string>
 25  #include <tuple>
 26  #include <vector>
 27  
 28  static RPCHelpMan validateaddress()
 29  {
 30      return RPCHelpMan{
 31          "validateaddress",
 32          "\nReturn information about the given bitcoin address.\n",
 33          {
 34              {"address", RPCArg::Type::STR, RPCArg::Optional::NO, "The bitcoin address to validate"},
 35          },
 36          RPCResult{
 37              RPCResult::Type::OBJ, "", "",
 38              {
 39                  {RPCResult::Type::BOOL, "isvalid", "If the address is valid or not"},
 40                  {RPCResult::Type::STR, "address", /*optional=*/true, "The bitcoin address validated"},
 41                  {RPCResult::Type::STR_HEX, "scriptPubKey", /*optional=*/true, "The hex-encoded scriptPubKey generated by the address"},
 42                  {RPCResult::Type::BOOL, "isscript", /*optional=*/true, "If the key is a script"},
 43                  {RPCResult::Type::BOOL, "iswitness", /*optional=*/true, "If the address is a witness address"},
 44                  {RPCResult::Type::NUM, "witness_version", /*optional=*/true, "The version number of the witness program"},
 45                  {RPCResult::Type::STR_HEX, "witness_program", /*optional=*/true, "The hex value of the witness program"},
 46                  {RPCResult::Type::STR, "error", /*optional=*/true, "Error message, if any"},
 47                  {RPCResult::Type::ARR, "error_locations", /*optional=*/true, "Indices of likely error locations in address, if known (e.g. Bech32 errors)",
 48                      {
 49                          {RPCResult::Type::NUM, "index", "index of a potential error"},
 50                      }},
 51              }
 52          },
 53          RPCExamples{
 54              HelpExampleCli("validateaddress", "\"" + EXAMPLE_ADDRESS[0] + "\"") +
 55              HelpExampleRpc("validateaddress", "\"" + EXAMPLE_ADDRESS[0] + "\"")
 56          },
 57          [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
 58          {
 59              std::string error_msg;
 60              std::vector<int> error_locations;
 61              CTxDestination dest = DecodeDestination(request.params[0].get_str(), error_msg, &error_locations);
 62              const bool isValid = IsValidDestination(dest);
 63              CHECK_NONFATAL(isValid == error_msg.empty());
 64  
 65              UniValue ret(UniValue::VOBJ);
 66              ret.pushKV("isvalid", isValid);
 67              if (isValid) {
 68                  std::string currentAddress = EncodeDestination(dest);
 69                  ret.pushKV("address", currentAddress);
 70  
 71                  CScript scriptPubKey = GetScriptForDestination(dest);
 72                  ret.pushKV("scriptPubKey", HexStr(scriptPubKey));
 73  
 74                  UniValue detail = DescribeAddress(dest);
 75                  ret.pushKVs(detail);
 76              } else {
 77                  UniValue error_indices(UniValue::VARR);
 78                  for (int i : error_locations) error_indices.push_back(i);
 79                  ret.pushKV("error_locations", error_indices);
 80                  ret.pushKV("error", error_msg);
 81              }
 82  
 83              return ret;
 84          },
 85      };
 86  }
 87  
 88  static RPCHelpMan createmultisig()
 89  {
 90      return RPCHelpMan{"createmultisig",
 91          "\nCreates a multi-signature address with n signature of m keys required.\n"
 92          "It returns a json object with the address and redeemScript.\n",
 93          {
 94              {"nrequired", RPCArg::Type::NUM, RPCArg::Optional::NO, "The number of required signatures out of the n keys."},
 95              {"keys", RPCArg::Type::ARR, RPCArg::Optional::NO, "The hex-encoded public keys.",
 96                  {
 97                      {"key", RPCArg::Type::STR_HEX, RPCArg::Optional::OMITTED, "The hex-encoded public key"},
 98                  }},
 99              {"address_type", RPCArg::Type::STR, RPCArg::Default{"legacy"}, "The address type to use. Options are \"legacy\", \"p2sh-segwit\", and \"bech32\"."},
100          },
101          RPCResult{
102              RPCResult::Type::OBJ, "", "",
103              {
104                  {RPCResult::Type::STR, "address", "The value of the new multisig address."},
105                  {RPCResult::Type::STR_HEX, "redeemScript", "The string value of the hex-encoded redemption script."},
106                  {RPCResult::Type::STR, "descriptor", "The descriptor for this multisig"},
107                  {RPCResult::Type::ARR, "warnings", /*optional=*/true, "Any warnings resulting from the creation of this multisig",
108                  {
109                      {RPCResult::Type::STR, "", ""},
110                  }},
111              }
112          },
113          RPCExamples{
114              "\nCreate a multisig address from 2 public keys\n"
115              + HelpExampleCli("createmultisig", "2 \"[\\\"03789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd\\\",\\\"03dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a61626\\\"]\"") +
116              "\nAs a JSON-RPC call\n"
117              + HelpExampleRpc("createmultisig", "2, [\"03789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd\",\"03dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a61626\"]")
118                  },
119          [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
120          {
121              int required = request.params[0].getInt<int>();
122  
123              // Get the public keys
124              const UniValue& keys = request.params[1].get_array();
125              std::vector<CPubKey> pubkeys;
126              for (unsigned int i = 0; i < keys.size(); ++i) {
127                  if (IsHex(keys[i].get_str()) && (keys[i].get_str().length() == 66 || keys[i].get_str().length() == 130)) {
128                      pubkeys.push_back(HexToPubKey(keys[i].get_str()));
129                  } else {
130                      throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, strprintf("Invalid public key: %s\n.", keys[i].get_str()));
131                  }
132              }
133  
134              // Get the output type
135              OutputType output_type = OutputType::LEGACY;
136              if (!request.params[2].isNull()) {
137                  std::optional<OutputType> parsed = ParseOutputType(request.params[2].get_str());
138                  if (!parsed) {
139                      throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, strprintf("Unknown address type '%s'", request.params[2].get_str()));
140                  } else if (parsed.value() == OutputType::BECH32M) {
141                      throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "createmultisig cannot create bech32m multisig addresses");
142                  }
143                  output_type = parsed.value();
144              }
145  
146              // Construct using pay-to-script-hash:
147              FillableSigningProvider keystore;
148              CScript inner;
149              const CTxDestination dest = AddAndGetMultisigDestination(required, pubkeys, output_type, keystore, inner);
150  
151              // Make the descriptor
152              std::unique_ptr<Descriptor> descriptor = InferDescriptor(GetScriptForDestination(dest), keystore);
153  
154              UniValue result(UniValue::VOBJ);
155              result.pushKV("address", EncodeDestination(dest));
156              result.pushKV("redeemScript", HexStr(inner));
157              result.pushKV("descriptor", descriptor->ToString());
158  
159              UniValue warnings(UniValue::VARR);
160              if (descriptor->GetOutputType() != output_type) {
161                  // Only warns if the user has explicitly chosen an address type we cannot generate
162                  warnings.push_back("Unable to make chosen address type, please ensure no uncompressed public keys are present.");
163              }
164              PushWarnings(warnings, result);
165  
166              return result;
167          },
168      };
169  }
170  
171  static RPCHelpMan getdescriptorinfo()
172  {
173      const std::string EXAMPLE_DESCRIPTOR = "wpkh([d34db33f/84h/0h/0h]0279be667ef9dcbbac55a06295Ce870b07029Bfcdb2dce28d959f2815b16f81798)";
174  
175      return RPCHelpMan{"getdescriptorinfo",
176          {"\nAnalyses a descriptor.\n"},
177          {
178              {"descriptor", RPCArg::Type::STR, RPCArg::Optional::NO, "The descriptor."},
179          },
180          RPCResult{
181              RPCResult::Type::OBJ, "", "",
182              {
183                  {RPCResult::Type::STR, "descriptor", "The descriptor in canonical form, without private keys"},
184                  {RPCResult::Type::STR, "checksum", "The checksum for the input descriptor"},
185                  {RPCResult::Type::BOOL, "isrange", "Whether the descriptor is ranged"},
186                  {RPCResult::Type::BOOL, "issolvable", "Whether the descriptor is solvable"},
187                  {RPCResult::Type::BOOL, "hasprivatekeys", "Whether the input descriptor contained at least one private key"},
188              }
189          },
190          RPCExamples{
191              "Analyse a descriptor\n" +
192              HelpExampleCli("getdescriptorinfo", "\"" + EXAMPLE_DESCRIPTOR + "\"") +
193              HelpExampleRpc("getdescriptorinfo", "\"" + EXAMPLE_DESCRIPTOR + "\"")
194          },
195          [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
196          {
197              FlatSigningProvider provider;
198              std::string error;
199              auto desc = Parse(request.params[0].get_str(), provider, error);
200              if (!desc) {
201                  throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, error);
202              }
203  
204              UniValue result(UniValue::VOBJ);
205              result.pushKV("descriptor", desc->ToString());
206              result.pushKV("checksum", GetDescriptorChecksum(request.params[0].get_str()));
207              result.pushKV("isrange", desc->IsRange());
208              result.pushKV("issolvable", desc->IsSolvable());
209              result.pushKV("hasprivatekeys", provider.keys.size() > 0);
210              return result;
211          },
212      };
213  }
214  
215  static RPCHelpMan deriveaddresses()
216  {
217      const std::string EXAMPLE_DESCRIPTOR = "wpkh([d34db33f/84h/0h/0h]xpub6DJ2dNUysrn5Vt36jH2KLBT2i1auw1tTSSomg8PhqNiUtx8QX2SvC9nrHu81fT41fvDUnhMjEzQgXnQjKEu3oaqMSzhSrHMxyyoEAmUHQbY/0/*)#cjjspncu";
218  
219      return RPCHelpMan{"deriveaddresses",
220          {"\nDerives one or more addresses corresponding to an output descriptor.\n"
221           "Examples of output descriptors are:\n"
222           "    pkh(<pubkey>)                                     P2PKH outputs for the given pubkey\n"
223           "    wpkh(<pubkey>)                                    Native segwit P2PKH outputs for the given pubkey\n"
224           "    sh(multi(<n>,<pubkey>,<pubkey>,...))              P2SH-multisig outputs for the given threshold and pubkeys\n"
225           "    raw(<hex script>)                                 Outputs whose scriptPubKey equals the specified hex scripts\n"
226           "    tr(<pubkey>,multi_a(<n>,<pubkey>,<pubkey>,...))   P2TR-multisig outputs for the given threshold and pubkeys\n"
227           "\nIn the above, <pubkey> either refers to a fixed public key in hexadecimal notation, or to an xpub/xprv optionally followed by one\n"
228           "or more path elements separated by \"/\", where \"h\" represents a hardened child key.\n"
229           "For more information on output descriptors, see the documentation in the doc/descriptors.md file.\n"},
230          {
231              {"descriptor", RPCArg::Type::STR, RPCArg::Optional::NO, "The descriptor."},
232              {"range", RPCArg::Type::RANGE, RPCArg::Optional::OMITTED, "If a ranged descriptor is used, this specifies the end or the range (in [begin,end] notation) to derive."},
233          },
234          RPCResult{
235              RPCResult::Type::ARR, "", "",
236              {
237                  {RPCResult::Type::STR, "address", "the derived addresses"},
238              }
239          },
240          RPCExamples{
241              "First three native segwit receive addresses\n" +
242              HelpExampleCli("deriveaddresses", "\"" + EXAMPLE_DESCRIPTOR + "\" \"[0,2]\"") +
243              HelpExampleRpc("deriveaddresses", "\"" + EXAMPLE_DESCRIPTOR + "\", \"[0,2]\"")
244          },
245          [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
246          {
247              const std::string desc_str = request.params[0].get_str();
248  
249              int64_t range_begin = 0;
250              int64_t range_end = 0;
251  
252              if (request.params.size() >= 2 && !request.params[1].isNull()) {
253                  std::tie(range_begin, range_end) = ParseDescriptorRange(request.params[1]);
254              }
255  
256              FlatSigningProvider key_provider;
257              std::string error;
258              auto desc = Parse(desc_str, key_provider, error, /* require_checksum = */ true);
259              if (!desc) {
260                  throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, error);
261              }
262  
263              if (!desc->IsRange() && request.params.size() > 1) {
264                  throw JSONRPCError(RPC_INVALID_PARAMETER, "Range should not be specified for an un-ranged descriptor");
265              }
266  
267              if (desc->IsRange() && request.params.size() == 1) {
268                  throw JSONRPCError(RPC_INVALID_PARAMETER, "Range must be specified for a ranged descriptor");
269              }
270  
271              UniValue addresses(UniValue::VARR);
272  
273              for (int64_t i = range_begin; i <= range_end; ++i) {
274                  FlatSigningProvider provider;
275                  std::vector<CScript> scripts;
276                  if (!desc->Expand(i, key_provider, scripts, provider)) {
277                      throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Cannot derive script without private keys");
278                  }
279  
280                  for (const CScript& script : scripts) {
281                      CTxDestination dest;
282                      if (!ExtractDestination(script, dest)) {
283                          // ExtractDestination no longer returns true for P2PK since it doesn't have a corresponding address
284                          // However combo will output P2PK and should just ignore that script
285                          if (scripts.size() > 1 && std::get_if<PubKeyDestination>(&dest)) {
286                              continue;
287                          }
288                          throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Descriptor does not have a corresponding address");
289                      }
290  
291                      addresses.push_back(EncodeDestination(dest));
292                  }
293              }
294  
295              // This should not be possible, but an assert seems overkill:
296              if (addresses.empty()) {
297                  throw JSONRPCError(RPC_MISC_ERROR, "Unexpected empty result");
298              }
299  
300              return addresses;
301          },
302      };
303  }
304  
305  void RegisterOutputScriptRPCCommands(CRPCTable& t)
306  {
307      static const CRPCCommand commands[]{
308          {"util", &validateaddress},
309          {"util", &createmultisig},
310          {"util", &deriveaddresses},
311          {"util", &getdescriptorinfo},
312      };
313      for (const auto& c : commands) {
314          t.appendCommand(c.name, &c);
315      }
316  }