feat(wallet): derive masternode operator keys from the wallet mnemonic

doc/release-notes-8002.md

@@ -0,0 +1,14 @@
+Wallet
+------
+
+- New wallet RPC `bls operatorkey` issues masternode operator keys derived from
+  the wallet mnemonic at `m/9'/coin'/3'/3'/index`, the keys the DashPay mobile
+  wallets derive from the same recovery phrase, so that phrase is the only
+  backup an operator needs. Each call issues the next key; `bls operatorkey
+  <index>` returns a key issued earlier. A wallet restored from the phrase
+  skips indexes whose key is in the masternode list at the chain tip, and a
+  rescan moves past every key it sees assigned by a ProRegTx or ProUpRegTx,
+  so keys rotated away earlier are not issued again. Rescans driven by block
+  filters cannot see operator keys, and a pruned node cannot rescan at all,
+  so issuing on a pruned node returns a warning. Requires an unlocked
+  descriptor wallet with a mnemonic. (#8002)

src/rpc/client.cpp

@@ -276,6 +276,7 @@ static const CRPCConvertParam vRPCConvertParams[] =
     // Compound RPCs (note: index position is offset by one to account for subcommand)
     { "bls generate", 1, "legacy" },
     { "bls fromsecret", 2, "legacy" },
+    { "bls operatorkey", 1, "index" },
     { "coinjoinsalt generate", 1, "overwrite" },
     { "coinjoinsalt set", 2, "overwrite" },
     { "gobject list-prepared", 1, "count" },

src/rpc/evo.cpp

@@ -54,6 +54,7 @@ using wallet::DEFAULT_DISABLE_WALLET;
 using wallet::GetWalletForJSONRPCRequest;
 using wallet::HELP_REQUIRING_PASSPHRASE;
 using wallet::isminetype;
+using wallet::PlatformKeyStatus;
 #endif // ENABLE_WALLET
 
 // Defined here rather than with the other ToJson() in evo/core_write.cpp: dash-tx never prints
@@ -2462,13 +2463,125 @@ static RPCHelpMan bls_fromsecret()
     };
 }
 
+#ifdef ENABLE_WALLET
+[[noreturn]] static void ThrowOperatorKeyError(PlatformKeyStatus status, uint32_t index)
+{
+    switch (status) {
+    case PlatformKeyStatus::WALLET_LOCKED:
+        throw JSONRPCError(RPC_WALLET_UNLOCK_NEEDED,
+                           "Error: Please enter the wallet passphrase with walletpassphrase first.");
+    case PlatformKeyStatus::NOT_SUPPORTED:
+        throw JSONRPCError(RPC_WALLET_ERROR, "Operator keys need a descriptor wallet with private keys and a mnemonic");
+    case PlatformKeyStatus::AMBIGUOUS_SOURCE:
+        throw JSONRPCError(RPC_WALLET_ERROR, "Active descriptors of this wallet come from different root keys");
+    case PlatformKeyStatus::INVALID_SOURCE:
+        throw JSONRPCError(RPC_WALLET_ERROR, "Wallet mnemonic does not match the descriptor root key");
+    case PlatformKeyStatus::INVALID_ARGUMENT:
+        throw JSONRPCError(RPC_INVALID_PARAMETER, strprintf("operator key %d has not been issued by this wallet", index));
+    case PlatformKeyStatus::DATABASE_ERROR:
+        throw JSONRPCError(RPC_WALLET_ERROR, "Operator key records could not be read or written");
+    case PlatformKeyStatus::DERIVATION_ERROR:
+        throw JSONRPCError(RPC_WALLET_ERROR, "Operator key derivation failed");
+    case PlatformKeyStatus::SUCCESS:
+    case PlatformKeyStatus::IMPORT_ERROR:
+        break;
+    }
+    NONFATAL_UNREACHABLE();
+}
+
+static RPCHelpMan bls_operatorkey()
+{
+    return RPCHelpMan{
+        "bls operatorkey",
+        "\nIssues the next masternode operator key derived from the wallet mnemonic, or returns a key issued earlier.\n"
+        "Keys follow m/9'/coin'/3'/3'/index with the BLS HD scheme of the DashPay mobile wallets, so restoring\n"
+        "the mnemonic anywhere reproduces the same keys in the same order. Indexes whose key is in the masternode\n"
+        "list at the chain tip are skipped.\n" +
+            HELP_REQUIRING_PASSPHRASE,
+        {
+            {"index", RPCArg::Type::NUM, RPCArg::Optional::OMITTED,
+             "Return the key issued earlier at this index instead of issuing a new one"},
+        },
+        RPCResult{RPCResult::Type::OBJ,
+                  "",
+                  "",
+                  {
+                      {RPCResult::Type::NUM, "index", "Derivation index of the key"},
+                      {RPCResult::Type::STR_HEX, "secret", "BLS secret key"},
+                      {RPCResult::Type::STR_HEX, "public", "BLS public key"},
+                      {RPCResult::Type::STR, "scheme", "BLS scheme, always basic (use bls fromsecret for legacy)"},
+                      {RPCResult::Type::ARR,
+                       "warnings",
+                       /*optional=*/true,
+                       "Why the key may have been used before",
+                       {
+                           {RPCResult::Type::STR, "", ""},
+                       }},
+                  }},
+        RPCExamples{HelpExampleCli("bls operatorkey", "") + HelpExampleCli("bls operatorkey", "0")},
+        [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue {
+            std::shared_ptr<CWallet> const wallet{GetWalletForJSONRPCRequest(request)};
+            if (!wallet) return UniValue::VNULL;
+            // Make sure the results are valid at least up to the most recent block
+            // the user could have gotten from another RPC command prior to now
+            wallet->BlockUntilSyncedToCurrentChain();
+            EnsureWalletIsUnlocked(*wallet);
+
+            uint32_t index{0};
+            CBLSSecretKey secret;
+            PlatformKeyStatus status;
+            if (request.params[0].isNull()) {
+                const NodeContext& node{EnsureAnyNodeContext(request.context)};
+                std::set<std::vector<uint8_t>> operator_keys;
+                CHECK_NONFATAL(node.dmnman)->GetListAtChainTip().ForEachMN(/*onlyValid=*/false, [&](const auto& dmn) {
+                    operator_keys.insert(dmn.pdmnState->pubKeyOperator.Get().ToByteVector(/*specificLegacyScheme=*/false));
+                });
+                LOCK(wallet->cs_wallet);
+                status = wallet->IssueOperatorKey(
+                    [&operator_keys](const CBLSPublicKey& pubkey) {
+                        return operator_keys.count(pubkey.ToByteVector(/*specificLegacyScheme=*/false)) != 0;
+                    },
+                    index, secret);
+            } else {
+                const int64_t requested{request.params[0].getInt<int64_t>()};
+                if (requested < 0 || requested >> 31) {
+                    throw JSONRPCError(RPC_INVALID_PARAMETER, "Operator key index out of range");
+                }
+                index = requested;
+                LOCK(wallet->cs_wallet);
+                status = wallet->GetOperatorKey(index, secret);
+            }
+            if (status != PlatformKeyStatus::SUCCESS) ThrowOperatorKeyError(status, index);
+
+            UniValue ret(UniValue::VOBJ);
+            ret.pushKV("index", index);
+            ret.pushKV("secret", secret.ToString());
+            ret.pushKV("public", secret.GetPublicKey().ToString(/*specificLegacyScheme=*/false));
+            ret.pushKV("scheme", "basic");
+            if (request.params[0].isNull() && wallet->chain().havePruned()) {
+                UniValue warnings(UniValue::VARR);
+                warnings.push_back(
+                    "This node is pruned, so provider transactions in pruned blocks were not scanned: a key "
+                    "rotated away before this wallet was restored may be issued again. Issue the key on a "
+                    "node with full blocks or rotate the operator key after registering.");
+                PushWarnings(warnings, ret);
+            }
+            return ret;
+        },
+    };
+}
+#endif // ENABLE_WALLET
+
 static RPCHelpMan bls_help()
 {
     return RPCHelpMan{"bls",
         "Set of commands to execute BLS related actions.\n"
         "To get help on individual commands, use \"help bls command\".\n"
         "\nAvailable commands:\n"
         "  generate          - Create a BLS secret/public key pair\n"
+#ifdef ENABLE_WALLET
+        "  operatorkey       - Issue or return a masternode operator key derived from the wallet mnemonic\n"
+#endif
         "  fromsecret        - Parse a BLS secret key and return the secret/public key pair\n",
         {
             {"command", RPCArg::Type::STR, RPCArg::Optional::NO, "The command to execute"},
@@ -2507,6 +2620,7 @@ Span<const CRPCCommand> GetWalletEvoRPCCommands()
         {"evo", &protx_shared_dissolve_prepare},
         {"evo", &protx_shared_update_share},
         {"evo", &protx_shared_update_registrar_prepare},
+        {"evo", &bls_operatorkey},
         {"hidden", &protx_register_legacy},
         {"hidden", &protx_register_fund_legacy},
         {"hidden", &protx_register_prepare_legacy},

src/test/rpc_tests.cpp

@@ -590,6 +590,10 @@ BOOST_AUTO_TEST_CASE(rpc_convert_composite_commands)
     BOOST_CHECK_EQUAL(result[3][1].get_str(), "1.0.0.1:19999");
     BOOST_CHECK_EQUAL(result[4].get_str(), "yhq7ifNCtTKEpY4Yu5XPCcztQco6Fh6JsZ");
 
+    BOOST_CHECK_NO_THROW(result = RPCConvertValues("bls", {"operatorkey", "0"}));
+    BOOST_CHECK_EQUAL(result[0].get_str(), "operatorkey");
+    BOOST_CHECK_EQUAL(result[1].getInt<int>(), 0);
+
     // Validate that array syntax is not interpreted as string literal (named parameter)
     BOOST_CHECK_NO_THROW(result = RPCConvertNamedValues("protx", {
         "register_prepare",

src/wallet/platformkeys.cpp

@@ -4,10 +4,12 @@
 
 #include <wallet/platformkeys.h>
 
+#include <bls/bls.h>
 #include <crypto/common.h>
 #include <crypto/hmac_sha256.h>
 #include <secp256k1.h>
 #include <secp256k1_ecdh.h>
+#include <support/cleanse.h>
 
 #include <algorithm>
 #include <cassert>
@@ -83,6 +85,51 @@ Path FriendshipPath(uint32_t coin_type, uint32_t account, Span<const uint8_t> us
     };
 }
 
+//! m/9'/coin'/3'/3'. Soft derivation below it hashes the parent public key,
+//! and only its legacy serialization reproduces the keys DashSync and dashj
+//! derive.
+static bls::ExtendedPrivateKey OperatorKeyParent(Span<const uint8_t> seed, uint32_t coin_type)
+{
+    constexpr uint32_t HARDENED{0x80000000u};
+    return bls::ExtendedPrivateKey::FromSeed(bls::Bytes(seed.data(), seed.size()))
+        .PrivateChild(FEATURE_PURPOSE | HARDENED, /*fLegacy=*/true)
+        .PrivateChild(coin_type | HARDENED, /*fLegacy=*/true)
+        .PrivateChild(FEATURE_MASTERNODE | HARDENED, /*fLegacy=*/true)
+        .PrivateChild(MASTERNODE_KEY_OPERATOR | HARDENED, /*fLegacy=*/true);
+}
+
+CBLSSecretKey DeriveOperatorKey(Span<const uint8_t> seed, uint32_t coin_type, uint32_t index)
+{
+    if (index >> 31) return {};
+    const auto leaf{OperatorKeyParent(seed, coin_type).PrivateChild(index, /*fLegacy=*/true)};
+    std::array<uint8_t, CBLSSecretKey::SerSize> bytes;
+    leaf.GetPrivateKey().Serialize(bytes.data());
+    const CBLSSecretKey secret(bytes);
+    memory_cleanse(bytes.data(), bytes.size());
+    return secret;
+}
+
+std::vector<uint8_t> OperatorKeyChain(Span<const uint8_t> seed, uint32_t coin_type)
+{
+    return OperatorKeyParent(seed, coin_type).GetExtendedPublicKey(/*fLegacy=*/true).Serialize(/*fLegacy=*/true);
+}
+
+CBLSPublicKey OperatorPubKey(Span<const uint8_t> chain, uint32_t index)
+{
+    CBLSPublicKey pubkey;
+    if (index >> 31 || chain.size() != bls::ExtendedPublicKey::SIZE) return pubkey;
+    try {
+        const auto child{bls::ExtendedPublicKey::FromBytes(bls::Bytes(chain.data(), chain.size()), /*fLegacy=*/true)
+                             .PublicChild(index, /*fLegacy=*/true)
+                             .GetPublicKey()
+                             .Serialize(/*fLegacy=*/false)};
+        pubkey.SetBytes(child, /*specificLegacyScheme=*/false);
+    } catch (const std::exception&) {
+        // Bytes that do not decode as an extended public key yield no key.
+    }
+    return pubkey;
+}
+
 bool DeriveExtKey(const CExtKey& parent, const Path& path, ExtKey256& out)
 {
     out = {};

src/wallet/platformkeys.h

@@ -16,6 +16,9 @@
 #include <variant>
 #include <vector>
 
+class CBLSPublicKey;
+class CBLSSecretKey;
+
 /**
  * Dash Platform (DIP-9/13/14/15) key derivation for the wallet.
  *
@@ -28,7 +31,9 @@
  *  - DIP-13 identity keys (m/9'/coin'/5'/...)
  *  - DIP-14 256-bit child indexes (CKey::Derive256)
  *  - DIP-15 DashPay friendship keychains (m/9'/coin'/15'/account'/idA/idB)
- *  - dashj DerivationPathFactory.java / FriendKeyChain.java (reference impl)
+ *  - DIP-3 masternode operator keys (m/9'/coin'/3'/3'/index, BLS HD scheme)
+ *  - dashj DerivationPathFactory.java / FriendKeyChain.java /
+ *    BLSDeterministicKey.java (reference impl)
  */
 namespace wallet::platformkeys {
 
@@ -44,11 +49,15 @@ struct PathElement {
 };
 using Path = std::vector<PathElement>;
 
-// DIP-9 feature purpose, and DIP-13/DIP-15 feature types under it.
+// DIP-9 feature purpose, and DIP-3/DIP-13/DIP-15 feature types under it.
 inline constexpr uint32_t FEATURE_PURPOSE{9};
+inline constexpr uint32_t FEATURE_MASTERNODE{3}; // DIP-3
 inline constexpr uint32_t FEATURE_IDENTITIES{5}; // DIP-13
 inline constexpr uint32_t FEATURE_DASHPAY{15};   // DIP-15
 
+// DIP-3 masternode key sub-features: m/9'/coin'/3'/<subfeature>'
+inline constexpr uint32_t MASTERNODE_KEY_OPERATOR{3};
+
 // DIP-13 sub-features: m/9'/coin'/5'/<subfeature>'
 inline constexpr uint32_t IDENTITY_AUTHENTICATION{0};
 inline constexpr uint32_t IDENTITY_REGISTRATION_FUNDING{1};
@@ -91,6 +100,21 @@ Path PlatformKeyPath(uint32_t coin_type, const PlatformKeyRequest& request);
 //! (userA = my id, userB = their id), the sending chain is the reverse.
 Path FriendshipPath(uint32_t coin_type, uint32_t account, Span<const uint8_t> user_a_id, Span<const uint8_t> user_b_id);
 
+//! m/9'/coin'/3'/3'/<index> — DIP-3 masternode operator key, derived the way
+//! DashSync and dashj do it: bls::ExtendedPrivateKey from the 64-byte BIP39
+//! seed with legacy child derivation at every step. The leaf index is soft
+//! and must be below 2^31; an invalid key is returned otherwise.
+CBLSSecretKey DeriveOperatorKey(Span<const uint8_t> seed, uint32_t coin_type, uint32_t index);
+
+//! Serialized bls::ExtendedPublicKey at m/9'/coin'/3'/3', the parent of every
+//! operator key. Its soft children are the operator public keys, so it stands
+//! in for the seed wherever only public keys are needed.
+std::vector<uint8_t> OperatorKeyChain(Span<const uint8_t> seed, uint32_t coin_type);
+
+//! Operator public key at `index` under a chain from OperatorKeyChain; invalid
+//! for a malformed chain or an index of 2^31 or above.
+CBLSPublicKey OperatorPubKey(Span<const uint8_t> chain, uint32_t index);
+
 //! Derive the extended key at `path` from a BIP32 extended private key.
 //! Returns false if the parent key or any derivation step is invalid.
 [[nodiscard]] bool DeriveExtKey(const CExtKey& parent, const Path& path, ExtKey256& out);

src/wallet/platformtypes.h

@@ -26,6 +26,7 @@ enum class PlatformKeyStatus : uint8_t {
     INVALID_ARGUMENT,
     IMPORT_ERROR,
     DERIVATION_ERROR,
+    DATABASE_ERROR,
 };
 
 template <typename T>

src/wallet/rpc/wallet.cpp

@@ -431,6 +431,12 @@ static RPCHelpMan upgradetohd()
 
         if (pwallet->IsWalletFlagSet(WALLET_FLAG_DESCRIPTORS)) {
             pwallet->SetupDescriptorScriptPubKeyMans(mnemonic, mnemonic_passphrase);
+            // A supplied mnemonic may already have operator keys on-chain; the
+            // chain record lets the rescan below recognise them and must exist
+            // before encryption locks the seed away.
+            if (!generate_mnemonic && pwallet->SetupOperatorKeyChain() != PlatformKeyStatus::SUCCESS) {
+                throw JSONRPCError(RPC_WALLET_ERROR, "Failed to store the operator key chain");
+            }
         } else {
             auto spk_man = pwallet->GetLegacyScriptPubKeyMan();
             if (!spk_man) {

src/wallet/scriptpubkeyman.cpp

@@ -2,6 +2,7 @@
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
+#include <bls/bls.h>
 #include <chainparams.h>
 #include <key_io.h>
 #include <logging.h>
@@ -2781,6 +2782,58 @@ PlatformKeyStatus DescriptorScriptPubKeyMan::DerivePlatformKey(const platformkey
     return platformkeys::DeriveExtKey(root, path, out) ? PlatformKeyStatus::SUCCESS : PlatformKeyStatus::DERIVATION_ERROR;
 }
 
+PlatformKeyStatus DescriptorScriptPubKeyMan::OperatorKeySeed(SecureVector& seed) const
+{
+    std::vector<unsigned char> identifier;
+    if (const auto status{GetPlatformKeySource(identifier)}; status != PlatformKeyStatus::SUCCESS) return status;
+    if (m_storage.IsLocked(false)) return PlatformKeyStatus::WALLET_LOCKED;
+
+    // Only the mnemonic reproduces the BLS tree the mobile wallets derive
+    // from; a wallet built from an imported extended key has no BIP39 seed.
+    // The encrypted path of GetMnemonicString appends one decrypted character
+    // at a time; reserving keeps them out of the small-string buffer, which
+    // the secure allocator does not cover.
+    SecureString mnemonic;
+    SecureString passphrase;
+    mnemonic.reserve(256);
+    passphrase.reserve(256);
+    if (!GetMnemonicString(mnemonic, passphrase) || mnemonic.empty()) return PlatformKeyStatus::NOT_SUPPORTED;
+    CMnemonic::ToSeed(mnemonic, passphrase, seed);
+
+    // The mnemonic is stored beside the descriptor root key; one that does not
+    // reproduce it would hand out keys no backup of this wallet recovers.
+    CExtKey master;
+    master.SetSeed(MakeByteSpan(seed));
+    CExtPubKey root;
+    {
+        LOCK(cs_desc_man);
+        if (!m_wallet_descriptor.descriptor->GetRootExtPubKey(root)) return PlatformKeyStatus::INVALID_SOURCE;
+    }
+    return master.Neuter() == root ? PlatformKeyStatus::SUCCESS : PlatformKeyStatus::INVALID_SOURCE;
+}
+
+PlatformKeyStatus DescriptorScriptPubKeyMan::DeriveOperatorKeys(uint32_t coin_type, uint32_t first, uint32_t count,
+                                                                std::vector<CBLSSecretKey>& out) const
+{
+    out.clear();
+    SecureVector seed;
+    if (const auto status{OperatorKeySeed(seed)}; status != PlatformKeyStatus::SUCCESS) return status;
+    for (uint32_t i{0}; i < count; ++i) {
+        out.push_back(platformkeys::DeriveOperatorKey(seed, coin_type, first + i));
+        if (!out.back().IsValid()) return PlatformKeyStatus::DERIVATION_ERROR;
+    }
+    return PlatformKeyStatus::SUCCESS;
+}
+
+PlatformKeyStatus DescriptorScriptPubKeyMan::OperatorKeyChain(uint32_t coin_type, std::vector<unsigned char>& out) const
+{
+    out.clear();
+    SecureVector seed;
+    if (const auto status{OperatorKeySeed(seed)}; status != PlatformKeyStatus::SUCCESS) return status;
+    out = platformkeys::OperatorKeyChain(seed, coin_type);
+    return out.empty() ? PlatformKeyStatus::DERIVATION_ERROR : PlatformKeyStatus::SUCCESS;
+}
+
 TransactionError DescriptorScriptPubKeyMan::FillPSBT(PartiallySignedTransaction& psbtx, const PrecomputedTransactionData& txdata, int sighash_type, bool sign, bool bip32derivs, int* n_signed, bool finalize) const
 {
     if (n_signed) {