From de57da38cebe6c228f8698bd8ba6ef96c59b03ef Mon Sep 17 00:00:00 2001 From: Kris Nuttycombe Date: Thu, 4 Nov 2021 20:15:35 -0500 Subject: [PATCH] Document mnemonic-seed-related RPC method changes & update changelog. --- doc/release-notes.md | 54 ++++++++++++++++++++++++++++++++++++++++ src/wallet/rpcwallet.cpp | 5 +++- 2 files changed, 58 insertions(+), 1 deletion(-) diff --git a/doc/release-notes.md b/doc/release-notes.md index a29094b51..7daf66f30 100644 --- a/doc/release-notes.md +++ b/doc/release-notes.md @@ -4,3 +4,57 @@ release-notes at release time) Notable changes =============== +Mnemonic Recovery Phrases +------------------------- + +The zcashd wallet has been modified to support ZIP 339 (derived from BIP 39) +which describes how to derive the wallet's HD seed from a mnemonic phrase. +The mnemonic phrase will be generated on load of the wallet, or the first time +the wallet is unlocked, and is available via the `z_exportwallet` RPC call. All +new addresses produced by the wallet are now derived from this seed using the +HD wallet functionality described in ZIP 32 and ZIP 316. For users upgrading an +existing Zcashd wallet, it is recommended that the wallet be backed up prior to +upgrading to the 4.5.2 Zcashd release. + +Following the upgrade to 4.5.2, Zcashd will require that the user confirm that +they have backed up their new emergency recovery phrase, which may be obtained +from the output of the `z_exportwallet` RPC call. This confirmation be can be +performed manually using the `zcashd-wallet-tool` utility that is supplied with +this release. The wallet will not allow the generation of new addresses until +this confirmation has been performed. It is recommended that after this +upgrade, that funds tied to preexisting addresses be migrated to newly +generated addresses so that all wallet funds are recoverable using the +emergency recovery phrase going forward. If you choose not to migrate funds in +this fashion, you will continue to need to securely back up the entire +`wallet.dat` file to ensure that you do not lose access to existing funds; +EXISTING FUNDS WILL NOT BE RECOVERABLE USING THE EMERGENCY RECOVERY PHRASE +UNLESS THEY HAVE BEEN MOVED TO A NEWLY GENERATED ADDRESS FOLLOWING THE 4.5.2 +UPGRADE. + +New RPC Methods +--------------- + +- 'walletconfirmbackup' This newly created API is checks a provided emergency + recovery phrase against the wallet's emergency recovery phrase; if the phrases + match then it updates the wallet state to allow the generation of new addresses. + This backup confirmation workflow can be disabled by starting zcashd with + `-requirewalletbackup=false` but this is not recommended unless you know what + you're doing (and have otherwise backed up the wallet's recovery phrase anyway.) + For security reasons, this RPC method is not intended for use via zcash-cli + but is provided to enable `zcashd-wallet-tool` and other third-party wallet + interfaces to satisfy the backup confirmation requirement. Use of the + `walletconfirmbackup` API via zcash-cli would risk that the recovery phrase + being confirmed might be leaked via the user's shell history or the system + process table; `zcashd-wallet-tool` is specifically provided to avoid this + problem. + +RPC Changes +----------- + +- The results of the 'dumpwallet' and 'z_exportwallet' RPC methods have been modified + to now include the wallet's newly generated emergency recovery phrase as part of the + exported data. + +- The results of the 'getwalletinfo' RPC have been modified to return two new fields: + `mnemonic_seedfp` and `legacy_seedfp`, the latter of which replaces the field that + was previously named `seedfp`. diff --git a/src/wallet/rpcwallet.cpp b/src/wallet/rpcwallet.cpp index 090459fc2..74938c8c3 100644 --- a/src/wallet/rpcwallet.cpp +++ b/src/wallet/rpcwallet.cpp @@ -2062,7 +2062,10 @@ UniValue getwalletinfo(const UniValue& params, bool fHelp) " \"keypoolsize\": xxxx, (numeric) how many new keys are pre-generated\n" " \"unlocked_until\": ttt, (numeric) the timestamp in seconds since epoch (midnight Jan 1 1970 GMT) that the wallet is unlocked for transfers, or 0 if the wallet is locked\n" " \"paytxfee\": x.xxxx, (numeric) the transaction fee configuration, set in " + CURRENCY_UNIT + "/kB\n" - " \"seedfp\": \"uint256\", (string) the BLAKE2b-256 hash of the HD seed\n" + " \"mnemonic_seedfp\": \"uint256\", (string) the BLAKE2b-256 hash of the HD seed derived from the wallet's emergency recovery phrase\n" + " \"legacy_seedfp\": \"uint256\", (string, optional) if this wallet was created prior to release 4.5.2, this will contain the BLAKE2b-256\n" + " hash of the legacy HD seed that was used to derive Sapling addresses prior to the 4.5.2 upgrade to mnemonic\n" + " emergency recovery phrases. This field was previously named \"seedfp\".\n" "}\n" "\nExamples:\n" + HelpExampleCli("getwalletinfo", "")