zecfoundation
/
zcashd
mirror of https://github.com/ZcashFoundation/zcashd.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update release notes to include all RPC changes since 4.6.0 

This also corrects some minor errors in the help text for
a few of the RPC methods.
This commit is contained in:
Kris Nuttycombe 2022-03-28 21:21:26 -06:00
parent d4b2ec6359
commit db315fd693
3 changed files with 121 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
doc/release-notes.md
View File

@ -31,55 +31,104 @@ 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.7.0 UPGRADE.
Wallet Updates
--------------
The zcashd wallet has been modified to alter the way that change is handled. In the case
that funds are being spent from a unified account, change is sent to a wallet-internal
change address for that account instead of sending change amounts back to the original
address where a note being spent was received. The rationale for this change is that it
improves the security that is provided to the user of the wallet when supplying incoming
viewing keys to third parties; previously, an incoming viewing key could effectively be
used to detect when a note was spent (hence violating the "incoming" restriction) by
observing change outputs that were sent back to the address where the spent note was
originally received.
New RPC Methods
---------------
- 'walletconfirmbackup' This newly created API checks a provided emergency
- `walletconfirmbackup` This newly created API 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
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
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.
- 'z_getbalanceforviewingkey' This newly created API allows a user to obtain
balance information for funds visible to a Sapling or Unified full
viewing key; if a Sprout viewing key is provided, this method allows
retrieval of the balance only in the case that the wallet controls the
corresponding spending key.
- `z_getnewaccount` This API allows for creation of new BIP 44 / ZIP 32
accounts using HD derivation from the wallet's mnemonic seed. Each account represents a
separate spending authority and source of funds. A single account may contain funds in
the Sapling and Orchard shielded pools, as well as funds held in transparent addresses.
- `z_getaddressforaccount` This API allows for creation of diversified unified
addresses under a single account. Each call to this API will, by default, create
a new diversified unified address containing p2pkh, Sapling, and Orchard receivers.
Additional arguments to this API may be provided to request the address to be created
with a user-specified set of receiver types and diversifier index.
- `z_getbalanceforaccount` This API makes it possible to obtain balance information
on a per-account basis.
- `z_getbalanceforviewingkey` This newly created API allows a user to obtain
balance information for funds visible to a Sapling or Unified full viewing key; if a
Sprout viewing key is provided, this method allows retrieval of the balance only in the
case that the wallet controls the corresponding spending key. This API has been added
to supplement (and largely supplant) `z_getbalance`. Querying for balance by a single
address returns only the amount received by that address, and omits value sent to other
diversified addresses derived from the same full viewing key; by using
`z_getbalanceforviewingkey` it is possible to obtain a correct balance that includes all
amounts controlled by a single spending key, including both those sent to external
diversified addresses and to wallet-internal change addresses.
- `z_listunifiedreceivers` This API allows the caller to extract the individual
component receivers from a unified address. This is useful if one needs to
provide a bare Sapling or p2pkh address to a service that does not yet
support unified addresses.
RPC Changes
-----------
- The result type for the `listaddresses` endpoint has been modified:
- The `keypool` source type has been removed; it was reserved but not used.
- In the `sapling` address results, the `zip32AccountId` attribute has been
removed in favor of `zip32KeyPath`. This is to allow distinct key paths to
be reported for addresses derived from the legacy account under different
child spending authorities, as are produced by `z_getnewaddress`.
- 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:
- 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`.
Wallet
------
was previously named `seedfp`.
- A new `pool` attribute has been added to each element returned by `z_listunspent`
to indicate which value pool the unspent note controls funds in.
- `z_listreceivedbyaddress` a `pool` attribute has been added to each result to indicate
what pool the received funds are held in.
- `z_viewtransaction` has been updated to include attributes that provide
information about Orchard components of the transaction. Also, the `type`
attribute for spend and output values has been deprecated and replaced
by the `pool` attribute.
- `z_getnotescount` now also returns information for Orchard notes.
- The output format of `z_exportwallet` has been changed. The exported file now
includes the mnemonic seed for the wallet, and HD keypaths are now exported for
transparent addresses when available.
- The result value for `z_importviewingkey` now includes an `address_type` field
that replaces the now-deprecated `type` key.
'z_sendmany'
------------
- The 'z_sendmany' RPC call no longer permits Sprout recipients in the
- The `z_sendmany` RPC call no longer permits Sprout recipients in the
list of recipient addresses. Transactions spending Sprout funds will
still result in change being sent back into the Sprout pool, but no
other `Sprout->Sprout` transactions will be constructed by the Zcashd
wallet.
wallet.
- The restriction that prohibited `Sprout->Sapling` transactions has been
lifted; however, since such transactions reveal the amount crossing
- The restriction that prohibited `Sprout->Sapling` transactions has been
lifted; however, since such transactions reveal the amount crossing
pool boundaries, they must be explicitly enabled via a parameter to
the 'z_sendmany' call.
the `z_sendmany` call.
- A new string parameter, `privacyPolicy`, has been added to the list of
arguments accepted by `z_sendmany`. This parameter enables the caller to
@ -92,6 +141,19 @@ Wallet
corresponds to the `AllowFullyTransparent` policy).
- Since Sprout outputs are no longer created (with the exception of change)
'z_sendmany' no longer generates payment disclosures (which were only
`z_sendmany` no longer generates payment disclosures (which were only
available for Sprout outputs) when the `-paymentdisclosure` experimental
feature flag is set.
Deprecated
----------
- `z_getnewaddress` has been deprecated in favor of `z_getnewaccount` and
`z_getaddressforaccount`.
- `z_listaddresses` has been deprecated. Use `listaddresses` instead.
- `z_getbalance` has been deprecated. Use `z_getbalanceforviewingkey` instead.
See the discussion of how change is now handled under the `Wallet` heading for
additional background.
- `z_gettotalbalance` has been deprecated. Use `z_getbalanceforaccount` instead.
- `dumpwallet` has been deprecated. Use `z_exportwallet` instead.

12
qa/rpc-tests/wallet_listnotes.py
View File

@ -46,7 +46,7 @@ class WalletListNotes(BitcoinTestFramework):
assert_equal(1, len(unspent_cb))
assert_equal(False, unspent_cb[0]['change'])
assert_equal(txid_1, unspent_cb[0]['txid'])
assert_equal('sprout', unspent_cb[0]['type'])
assert_equal('sprout', unspent_cb[0]['pool'])
assert_equal(True, unspent_cb[0]['spendable'])
assert_equal(sproutzaddr, unspent_cb[0]['address'])
assert_equal(receive_amount_1, unspent_cb[0]['amount'])
@ -79,14 +79,14 @@ class WalletListNotes(BitcoinTestFramework):
unspent_tx = sorted(unspent_tx, key=lambda k: k['amount'])
assert_equal(False, unspent_tx[0]['change'])
assert_equal(txid_2, unspent_tx[0]['txid'])
assert_equal('sapling', unspent_tx[0]['type'])
assert_equal('sapling', unspent_tx[0]['pool'])
assert_equal(True, unspent_tx[0]['spendable'])
assert_equal(saplingzaddr, unspent_tx[0]['address'])
assert_equal(receive_amount_2, unspent_tx[0]['amount'])
assert_equal(True, unspent_tx[1]['change'])
assert_equal(txid_2, unspent_tx[1]['txid'])
assert_equal('sprout', unspent_tx[1]['type'])
assert_equal('sprout', unspent_tx[1]['pool'])
assert_equal(True, unspent_tx[1]['spendable'])
assert_equal(sproutzaddr, unspent_tx[1]['address'])
assert_equal(change_amount_2, unspent_tx[1]['amount'])
@ -118,21 +118,21 @@ class WalletListNotes(BitcoinTestFramework):
assert_equal(False, unspent_tx[0]['change'])
assert_equal(txid_2, unspent_tx[0]['txid'])
assert_equal('sapling', unspent_tx[0]['type'])
assert_equal('sapling', unspent_tx[0]['pool'])
assert_equal(True, unspent_tx[0]['spendable'])
assert_equal(saplingzaddr, unspent_tx[0]['address'])
assert_equal(receive_amount_2, unspent_tx[0]['amount'])
assert_equal(False, unspent_tx[1]['change'])
assert_equal(txid_3, unspent_tx[1]['txid'])
assert_equal('sapling', unspent_tx[1]['type'])
assert_equal('sapling', unspent_tx[1]['pool'])
assert_equal(True, unspent_tx[1]['spendable'])
assert_equal(saplingzaddr2, unspent_tx[1]['address'])
assert_equal(receive_amount_3, unspent_tx[1]['amount'])
assert_equal(True, unspent_tx[2]['change'])
assert_equal(txid_3, unspent_tx[2]['txid'])
assert_equal('sprout', unspent_tx[2]['type'])
assert_equal('sprout', unspent_tx[2]['pool'])
assert_equal(True, unspent_tx[2]['spendable'])
assert_equal(sproutzaddr, unspent_tx[2]['address'])
assert_equal(change_amount_3, unspent_tx[2]['amount'])

59
src/wallet/rpcwallet.cpp
View File

@ -340,7 +340,7 @@ UniValue listaddresses(const UniValue& params, bool fHelp)
"generated from the legacy HD seed, imported watchonly transparent \n"
"addresses, shielded addresses tracked using imported viewing keys, \n"
"and addresses derived from the wallet's mnemonic seed for releases \n"
"version 4.5.2 and above. \n"
"version 4.7.0 and above. \n"
"\nREMINDER: It is recommended that you back up your wallet.dat file \n"
"regularly!\n"
"\nResult:\n"
@ -2448,18 +2448,17 @@ UniValue z_listunspent(const UniValue& params, bool fHelp)
"\nResult (output indices for only one value pool will be present):\n"
"[ (array of json object)\n"
" {\n"
" \"txid\" : \"txid\", (string) the transaction id \n"
" \"pool\" : \"sprout|sapling|orchard\", (string) The shielded value pool\n"
" \"type\" : \"sprout|sapling|orchard\", (string) The shielded value pool (DEPRECATED legacy attribute)\n"
" \"jsindex\" (sprout) : n, (numeric) the joinsplit index\n"
" \"jsoutindex\" (sprout) : n, (numeric) the output index of the joinsplit\n"
" \"outindex\" (transparent, sapling, orchard) : n, (numeric) the Output or Action index\n"
" \"confirmations\" : n, (numeric) the number of confirmations\n"
" \"spendable\" : true|false, (boolean) true if note can be spent by wallet, false if address is watchonly\n"
" \"address\" : \"address\", (string) the shielded address\n"
" \"amount\": xxxxx, (numeric) the amount of value in the note\n"
" \"memo\": xxxxx, (string) hexadecimal string representation of memo field\n"
" \"change\": true|false, (boolean) true if the address that received the note is also one of the sending addresses\n"
" \"txid\" : \"txid\", (string) the transaction id \n"
" \"pool\" : \"sprout|sapling|orchard\", (string) The shielded value pool\n"
" \"jsindex\" (sprout) : n, (numeric) the joinsplit index\n"
" \"jsoutindex\" (sprout) : n, (numeric) the output index of the joinsplit\n"
" \"outindex\" (sapling, orchard) : n, (numeric) the Sapling output or Orchard action index\n"
" \"confirmations\" : n, (numeric) the number of confirmations\n"
" \"spendable\" : true|false, (boolean) true if note can be spent by wallet, false if address is watchonly\n"
" \"address\" : \"address\", (string) the shielded address\n"
" \"amount\": xxxxx, (numeric) the amount of value in the note\n"
" \"memo\": xxxxx, (string) hexadecimal string representation of memo field\n"
" \"change\": true|false, (boolean) true if the address that received the note is also one of the sending addresses\n"
" }\n"
" ,...\n"
"]\n"
@ -2554,7 +2553,6 @@ UniValue z_listunspent(const UniValue& params, bool fHelp)
UniValue obj(UniValue::VOBJ);
obj.pushKV("txid", entry.jsop.hash.ToString());
obj.pushKV("pool", ADDR_TYPE_SPROUT);
obj.pushKV("type", ADDR_TYPE_SPROUT); //deprecated
obj.pushKV("jsindex", (int)entry.jsop.js );
obj.pushKV("jsoutindex", (int)entry.jsop.n);
obj.pushKV("confirmations", entry.confirmations);
@ -3628,21 +3626,24 @@ UniValue z_listreceivedbyaddress(const UniValue& params, bool fHelp)
"1. \"address\" (string) The shielded address.\n"
"2. minconf (numeric, optional, default=1) Only include transactions confirmed at least this many times.\n"
"\nResult (output indices for only one value pool will be present):\n"
"{\n"
" \"pool\": \"pool\" (string) one of (\"transparent\", \"sprout\", \"sapling\", \"orchard\")\n"
" \"txid\": \"txid\", (string) the transaction id\n"
" \"amount\": xxxxx, (numeric) the amount of value in the note\n"
" \"amountZat\" : xxxx (numeric) The amount in " + MINOR_CURRENCY_UNIT + "\n"
" \"memo\": xxxxx, (string) hexadecimal string representation of memo field\n"
" \"confirmations\" : n, (numeric) the number of confirmations\n"
" \"blockheight\": n, (numeric) The block height containing the transaction\n"
" \"blockindex\": n, (numeric) The block index containing the transaction.\n"
" \"blocktime\": xxx, (numeric) The transaction time in seconds since epoch (midnight Jan 1 1970 GMT).\n"
" \"jsindex\" (sprout) : n, (numeric) the joinsplit index\n"
" \"jsoutindex\" (sprout) : n, (numeric) the output index of the joinsplit\n"
" \"outindex\" (transparent, sapling, orchard) : n, (numeric) the output index for transparent and Sapling outputs, or the action index for Orchard\n"
" \"change\": true|false, (boolean) true if the output was received to a change address\n"
"}\n"
"[\n"
" {\n"
" \"pool\": \"pool\" (string) one of (\"transparent\", \"sprout\", \"sapling\", \"orchard\")\n"
" \"txid\": \"txid\", (string) the transaction id\n"
" \"amount\": xxxxx, (numeric) the amount of value in the note\n"
" \"amountZat\" : xxxx (numeric) The amount in " + MINOR_CURRENCY_UNIT + "\n"
" \"memo\": xxxxx, (string) hexadecimal string representation of memo field\n"
" \"confirmations\" : n, (numeric) the number of confirmations\n"
" \"blockheight\": n, (numeric) The block height containing the transaction\n"
" \"blockindex\": n, (numeric) The block index containing the transaction.\n"
" \"blocktime\": xxx, (numeric) The transaction time in seconds since epoch (midnight Jan 1 1970 GMT).\n"
" \"jsindex\" (sprout) : n, (numeric) the joinsplit index\n"
" \"jsoutindex\" (sprout) : n, (numeric) the output index of the joinsplit\n"
" \"outindex\" (sapling, orchard) : n, (numeric) the Sapling output index, or the Orchard action index\n"
" \"change\": true|false, (boolean) true if the output was received to a change address\n"
" },\n"
"...\n"
"]\n"
"\nExamples:\n"
+ HelpExampleCli("z_listreceivedbyaddress", "\"ztfaW34Gj9FrnGUEf833ywDVL62NWXBM81u6EQnM6VR45eYnXhwztecW1SjxA7JrmAXKJhxhj3vDNEpVCQoSvVoSpmbhtjf\"")
+ HelpExampleRpc("z_listreceivedbyaddress", "\"ztfaW34Gj9FrnGUEf833ywDVL62NWXBM81u6EQnM6VR45eYnXhwztecW1SjxA7JrmAXKJhxhj3vDNEpVCQoSvVoSpmbhtjf\"")