From 827839911db0cd259182f294063a6543ae15283f Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Tue, 26 Apr 2022 21:58:55 +0100 Subject: [PATCH 01/21] ZIP 315: Initial work in progress. Co-authored-by: Kris Nuttycombe Signed-off-by: Daira Hopwood --- zip-0315.rst | 221 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 220 insertions(+), 1 deletion(-) diff --git a/zip-0315.rst b/zip-0315.rst index 141cac40..a958326c 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -4,6 +4,225 @@ Title: Best Practices for Wallet Handling of Multiple Pools Owners: Daira Emma Hopwood Jack Grigg - Status: Reserved + Status: Proposed Category: Wallet Discussions-To: + Pull-Request: + + +Terminology +=========== + +The key words "MUST", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be +interpreted as described in RFC 2119. [#RFC2119]_ + +The terms below are to be interpreted as follows: + +Auto-shielding + The process of automatically transferring transparent funds to the most recent + shielded pool on receipt. + +Auto-migration + The process of automatically transferring shielded funds from older pools to the + most preferred (usually the most recent) pool on receipt. + +TODO: add definitions of opportunistic shielding and migration. + +TODO: "confirmed", "partially confirmed" + + +Motivation +========== + +The aim of this ZIP is to provide wallet developers with a set of best practices by +which they can minimize the leakage of information when constructing transactions. + +This includes best practices for: + +* how to handle interactions between the ZIP 32 key tree and Unified Addresses; +* when to use external or internal keys/addresses; +* sharing addresses and viewing keys; +* sending and receiving funds; +* migrating funds between pools. + + +Requirements +============ + +User consent +------------ + +The guiding principle of these requirements is that users must explicitly consent +to each instance of information being revealed by the wallet. + +As is true for consent in general, a user may give blanket consent to reveal a +particular kind of information, and must always be able to revoke consent to +reveal such information in the future. The specifications below describe some +situations in which blanket consent may be inappropriate. + + +Reporting of balances +--------------------- + +Wallets MUST report at least separate shielded and transparent balance. + +If auto-shielding or auto-migration is off, then wallets SHOULD report separate +balances for each shielded pool and for transparent balance. + +If the wallet never supports a given pool, it can obviously omit balances for that +pool. + +If auto-shielding is on, transparent funds should be reported in "balance unavailable +to spend". + +Wallets SHOULD separately report the balances of funds that are immediately +spendable, and any remaining funds that are expected from unconfirmed or +partially confirmed transfers. + +TODO: make this more precise in terms of the following categories: + +* Funds at rest (not involved in any not-fully-confirmed transfer) +* Outgoing funds to an external source (might come back if the tx doesn't go through) +* Incoming funds from an external source +* Funds we are sending to ourself. + + +Linkability of transactions or addresses +---------------------------------------- + + + +Network-layer privacy +--------------------- + + +Viewing keys +------------ + +What they are supposed to reveal; see ZIP 310 for Sapling (needs updating for +Orchard). https://github.com/zcash/zips/issues/606 + + + +Allowed transfers +----------------- + +* Sprout -> transparent or Sapling +* Sapling -> transparent or Sapling or Orchard +* Orchard -> transparent or Sapling or Orchard +* if auto-shielding is off: + * transparent -> transparent or Sapling or Orchard +* if auto-shielding is on: + * transparent -> internal Orchard or Sapling + +Note: wallets MAY further restrict the set of transfers they perform. + + +Auto-shielding +-------------- + +Wallets SHOULD NOT spend funds from a transparent address to an external address, +unless the user gives explicit consent for this on a per-transaction basis. + +In order to support this policy, wallets SHOULD implement a system of auto-shielding +with the following characteristics. + + +If auto-shielding functionality is available in a wallet, then users MUST be able +to explicitly consent to one of the following possibilities: + +* auto-shielding is always on; +* auto-shielding is always off; +* the user specifies a policy... + +Auto-shielding MUST be one of: + +* "must opt in or out" (zcashd will do this -- i.e. refuse to start unless the option + is configured), or +* always on. + + +Auto-migration +-------------- + + +Information leakage for transfers between pools +----------------------------------------------- + + +If no auto-migration, if you can satisfy a transfer request to Sapling from your +Sapling funds, do so. + +The user's consent is needed to reveal amounts. Therefore, there should be +per-transaction opt-in for any amount-revealing transfer. + +* there may be a compatibility issue for amount-revealing cross-pool txns that were + previously allowed without opt-in + +Don't automatically combine funds across pools to satisfy a transfer (since that +could reveal the total funds in some pool). + +In order to maintain the integrity of IVK guarantees, wallets should not generate +unified addresses that contain internal receivers, nor expose internal receivers +(such as those used for auto-shielding and change outputs) in any way. + +Open questions: + +* should there be an auto-migration option from Sapling to Orchard? + +# str4d notes + +If we want to have both automatic and opportunistic shielding, and keep the two +indistinguishable, then we can't auto-shield when the transparent balance reaches +some threshold (otherwise opportunistic would either never be used, or would be +identifiable when it uses the balance below the threshold). + +Instead, a proposition: we define a distribution of "time since last payment to the +address" from which we sample the time at which the auto-shielding transaction will +be created. This distribution is weighted by the balance in the address, so as more +funds accrue, the auto-shielding transaction is more likely to be created. + +- It ensures that all funds will eventually be auto-shielded, while preventing + fee-dusting attacks (where dust is sent in order to repeatedly consume fees from + the wallet), as the auto-shielding transaction is not directly triggered by payment + receipt. + +- If the user makes a shielding transaction in the meantime, we opportunistically + shield, without it being clearly not an auto-shielding transaction. + +- If a wallet is offline for a long time, then it would likely auto-shield as soon as + it finishes syncing. This maybe isn't enough to reveal that the wallet came online, + except that it _might_ result in auto-shielding transactions for multiple + transparent addresses being created at the same time. So we might want to + special-case this? + +Properties we want from auto-shielding: + +- Auto-shielding transactions MUST NOT shield from multiple transparent receivers in + the same transaction. + - Doing so would trivially link diversified UAs containing transparent receivers. + +Properties we want from auto-migration: + +- Receipt of a shielded payment MUST NOT trigger any on-chain behaviour (as that + reveals transaction linkability). + +Both auto-shielding and auto-migration are time-triggered actions, not +receipt-triggered actions. An auto-shielding or auto-migration transaction MUST NOT +be created as a direct result of a payment being received. + +Both of these are opportunistic: if the user's wallet is making a transaction in +which one of these actions would occur anyway, then the wallet takes the opportunity +to migrate as much as it would do if it were generating an autoshielding transaction. +This both saves on a transaction, and removes the need for any kind of transparent +change address within UAs. + +TODO: what pool should change go to? + +* Proposal: the most recent pool already involved in the transaction. + + +References +========== + +.. [#RFC2119] `RFC 2119: Key words for use in RFCs to Indicate Requirement Levels `_ From ae001dcc91adb9454c47e4a44e9d54211fe20073 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Wed, 27 Apr 2022 16:36:25 +0100 Subject: [PATCH 02/21] ZIP 315: WIP from meeting. Signed-off-by: Daira Hopwood --- zip-0315.rst | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 91 insertions(+), 1 deletion(-) diff --git a/zip-0315.rst b/zip-0315.rst index a958326c..25d9d5b4 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -61,12 +61,92 @@ reveal such information in the future. The specifications below describe some situations in which blanket consent may be inappropriate. +Long-term storage of funds +-------------------------- + +It is RECOMMENDED that wallets only hold funds as shielded in the long-term; +that is, they automatically shield incoming transparent funds. + +The remainder of this specification assumes a wallet that follows this +recommendation, except where explicitly noted. + + +Trusted and untrusted notes +--------------------------- + +Wallets need to take account of two concerns: + +* enabling funds to be spent as quickly as possible to reduce latency; +* waiting for long enough before spending notes to ensure that the spendable + balance is not overestimated, and so can be trusted by the user. + +To enable this we define two kinds of notes: + +* An untrusted note is a note received from a party that may try to double-spend. +* A trusted note is a note received from a party where the wallet trusts a + double-spend not to occur, e.g. notes created by the wallet's internal note + handling. + +Wallets can then require that untrusted notes need more confirmations before +they become spendable than trusted notes. This provides an improved trade-off +between latency on the one hand, and reliability and safety on the other. + +Wallets MAY enable users to mark specific external transactions as trusted, +allowing their received notes to be spent more quickly. + +A wallet SHOULD have a policy that is clearly communicated to the user for +the number of confirmations needed to spend untrusted and trusted notes +respectively. The following confirmation policy is RECOMMENDED: + +* 10 confirmations, for untrusted notes; +* 3 confirmations, for trusted notes. + +A note is *confirmed spendable* if and only if the wallet has its spending +key, and: + +* it is a trusted note that has at least the required confirmations for trusted + notes; or +* it is an untrusted note that has at least the required confirmations for + untrusted notes. + +A note is *unconfirmed spendable* if and only if the wallet has its spending +key, and it is not confirmed spendable. + +A note is *watch-only* if and only if the wallet has its full viewing key +but not its spending key. + + Reporting of balances --------------------- +Wallets SHOULD report: + +* Spendable balance. +* Pending funds, *or* total (spendable + pending) balance. + +These are calculated as follows: + +* The spendable balance is the sum of values of confirmed spendable notes. +* The pending ... + +Incoming transactions (each with # confirmations, amount) + +Sent transactions (each with # confirmations, how long until expiry, amount) + + +If they use auto-shielding, then any transparent balance should be treated as +pending. + +For wallets that allow long-term storage of transparent funds, they SHOULD also +show spendable transparent and pending (or total) transparent according to the +same policy. + +Unedited +-------- + Wallets MUST report at least separate shielded and transparent balance. -If auto-shielding or auto-migration is off, then wallets SHOULD report separate +If auto-shielding or auto-migration is off, then wallets MAY report separate balances for each shielded pool and for transparent balance. If the wallet never supports a given pool, it can obviously omit balances for that @@ -87,6 +167,16 @@ TODO: make this more precise in terms of the following categories: * Funds we are sending to ourself. + + +Rationale +''''''''' + +The specification of balance reporting is intended to give the user visibility +into the operation of auto-shielding, opportunistic shielding, and pool migration/usage. + + + Linkability of transactions or addresses ---------------------------------------- From 3eee14d8f57544e1d259cfc359836e771ad4490d Mon Sep 17 00:00:00 2001 From: Kris Nuttycombe Date: Tue, 3 May 2022 15:40:50 -0600 Subject: [PATCH 03/21] ZIP 315: WIP draft wallet recovery policy. --- zip-0315.rst | 50 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/zip-0315.rst b/zip-0315.rst index 25d9d5b4..11e07476 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -167,8 +167,6 @@ TODO: make this more precise in terms of the following categories: * Funds we are sending to ourself. - - Rationale ''''''''' @@ -311,6 +309,54 @@ TODO: what pool should change go to? * Proposal: the most recent pool already involved in the transaction. +Wallet Recovery +--------------- + +In the case where we are recovering a wallet from a backed-up mnemonic phrase, +and not from a wallet.dat, we don't have enough information to figure out what +receiver types the user originally used when deriving each UA under an account. +We have a similar issue if someone exports a UFVK, derives an address from it, +and has a payment sent to the address: zcashd will detect the payment, but has +no way to figure out what address it should display in the UI. A wallet could +store this information in the memo field of change outputs, but that adds a +bunch of coordination to the problem, and assumes ongoing on-chain state +storage. + +- If the receiver matches an address that the wallet knows was derived via + z_getaddressforaccount, show that UA as expected (matching the receiver + types the user selected). +- If the receiver matches a UFVK in the wallet, and we are looking it up + because we detected a received note in some block, show the UA with the + default receiver types that zcashd was using as of that block height + (ideally the earliest block height we detect), and cache this for future + usage. +- For zcashd's current policy of "best and second-best shielded pools, plus + transparent pool", that would mean Orchard, Sapling, and transparent for + current block heights. +- For each release of a wallet, the wallet should specify a set of receiver + types and an associated range of block heights during which the wallet + will, by default, generate unified addresses using that set of receiver + types. +- For zcashd we know how the policy evolves because each zcashd release has + an approximate relase height and EoS height that defines the window. +- Subsequent releases of a wallet should not retroactively change their + policies for previously defined block height ranges. +- If the receiver type for a note received at a given type is not a member + of the set of receiver types expected for the range of block heights, the + policy corresponding to the nearest block height range that includes that + receiver type should be used. +- If the receiver matches a UFVK in the wallet, and we have no information + about when this receiver may have been first used, show the UA + corresponding to the most recent receiver types policy that includes the + receiver's type. +- As part of this, we're also going to change the "Sapling receiver to + UfvkId" logic to trial-decrypt after trying internal map, so that we will + detect all receivers linked to UFVKs in the wallet, not just receivers in + addresses generated via z_getaddressforaccount. The internal map lookup + is then just an optimisation (and a future refactor to have Orchard do + the same is possible, but for now we will only trial-decrypt so we don't + need to refactor to access the Rust wallet). + References ========== From 09443c7d25b146183919ebe2b5ea7cca93b29b35 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Tue, 28 Jun 2022 21:53:42 +0100 Subject: [PATCH 04/21] ZIP 315: WIP. Co-authored-by: Kris Nuttycombe Signed-off-by: Daira Hopwood --- zip-0315.rst | 146 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 102 insertions(+), 44 deletions(-) diff --git a/zip-0315.rst b/zip-0315.rst index 11e07476..7abd7800 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -26,9 +26,21 @@ Auto-migration The process of automatically transferring shielded funds from older pools to the most preferred (usually the most recent) pool on receipt. -TODO: add definitions of opportunistic shielding and migration. +Opportunistic shielding + TODO -TODO: "confirmed", "partially confirmed" +Opportunistic migration + TODO + +Confirmed + TODO + +Partially confirmed + TODO + +Transaction output (TXO) + An output (transparent TXO or note) of a transaction on the consensus block chain + or in the mempool visible to a wallet. Motivation @@ -55,11 +67,42 @@ User consent The guiding principle of these requirements is that users must explicitly consent to each instance of information being revealed by the wallet. -As is true for consent in general, a user may give blanket consent to reveal a -particular kind of information, and must always be able to revoke consent to -reveal such information in the future. The specifications below describe some -situations in which blanket consent may be inappropriate. +A wallet typically reveals some information in the process of creating a transaction. +Which information is revealed depends on the configured wallet privacy policy. +A user may give blanket consent to reveal a particular kind of information, and +must also be able to change the configured wallet privacy policy to avoid the +wallet creating new privacy leaks of a given type. +The specifications below describe some situations in which blanket consent may be +inappropriate. + +Some varieties of consent may not be revocable, for example if a user chooses to +share some of their keys. + + +Prompt accessibility of funds +----------------------------- + +Wallets need to take account of two concerns: + +* enabling funds to be spent as quickly as possible to reduce latency; +* waiting for long enough before spending TXOs to ensure that the spendable + balance is not overestimated, and so can be trusted by the user. + +To enable this we define two kinds of TXOs: + +* An untrusted TXO is a TXO received from a party that may try to double-spend. +* A trusted TXO is a TXO received from a party where the wallet trusts a + double-spend not to occur, e.g. TXOs created by the wallet's internal TXO + handling. + +Wallets can then require that untrusted TXOs need more confirmations before +they become spendable than trusted TXOs. This provides an improved trade-off +between latency on the one hand, and reliability and safety on the other. + + +Specification +============= Long-term storage of funds -------------------------- @@ -71,49 +114,37 @@ The remainder of this specification assumes a wallet that follows this recommendation, except where explicitly noted. -Trusted and untrusted notes ---------------------------- - -Wallets need to take account of two concerns: - -* enabling funds to be spent as quickly as possible to reduce latency; -* waiting for long enough before spending notes to ensure that the spendable - balance is not overestimated, and so can be trusted by the user. - -To enable this we define two kinds of notes: - -* An untrusted note is a note received from a party that may try to double-spend. -* A trusted note is a note received from a party where the wallet trusts a - double-spend not to occur, e.g. notes created by the wallet's internal note - handling. - -Wallets can then require that untrusted notes need more confirmations before -they become spendable than trusted notes. This provides an improved trade-off -between latency on the one hand, and reliability and safety on the other. - -Wallets MAY enable users to mark specific external transactions as trusted, -allowing their received notes to be spent more quickly. +Trusted and untrusted TXOs +-------------------------- A wallet SHOULD have a policy that is clearly communicated to the user for -the number of confirmations needed to spend untrusted and trusted notes +the number of confirmations needed to spend untrusted and trusted TXOs respectively. The following confirmation policy is RECOMMENDED: -* 10 confirmations, for untrusted notes; -* 3 confirmations, for trusted notes. +* 10 confirmations, for untrusted TXOs; +* 3 confirmations, for trusted TXOs. -A note is *confirmed spendable* if and only if the wallet has its spending +Wallets MAY enable users to mark specific external transactions as trusted, +allowing their received TXOs to be treated as trusted TXOs even if they +do not have the required number of confirmations. + + +Categories of TXOs according to spendability +-------------------------------------------- + +A TXO is *confirmed spendable* if and only if the wallet has its spending key, and: -* it is a trusted note that has at least the required confirmations for trusted - notes; or -* it is an untrusted note that has at least the required confirmations for - untrusted notes. +* it is a trusted TXO that has at least the required confirmations for trusted + TXOs; or +* it is an untrusted TXO that has at least the required confirmations for + untrusted TXOs. -A note is *unconfirmed spendable* if and only if the wallet has its spending +A TXO is *unconfirmed spendable* if and only if the wallet has its spending key, and it is not confirmed spendable. -A note is *watch-only* if and only if the wallet has its full viewing key -but not its spending key. +A TXO is *watch-only* if and only if the wallet has its full viewing key +(or address in the case of a transparent TXO) but not its spending key. Reporting of balances @@ -122,17 +153,43 @@ Reporting of balances Wallets SHOULD report: * Spendable balance. -* Pending funds, *or* total (spendable + pending) balance. +* Pending balance, *or* total balance. These are calculated as follows: -* The spendable balance is the sum of values of confirmed spendable notes. -* The pending ... +* The spendable balance is the sum of values of confirmed spendable TXOs. +* The pending balance is the sum of values of unconfirmed spendable TXOs. +* The total balance is the spendable balance plus the pending balance. -Incoming transactions (each with # confirmations, amount) -Sent transactions (each with # confirmations, how long until expiry, amount) +Reporting of transactions +------------------------- +If a transaction contains both spendable and watch-only TXOs, its spendable +and watch-only incoming balances MUST be reported separately. + +Incoming transactions +''''''''''''''''''''' + +A transaction is incoming if it contains unconfirmed TXOs. Incoming +transactions SHOULD be reported with their number of confirmations and +their balances as described in `Reporting of balances`_. + +Sent transactions +''''''''''''''''' + +A transaction is sent if it was either: +* created by the wallet, or +* detected using the wallet's outgoing viewing keys, or +* detected as having been sent from one of the wallet's watch-only addresses. + +Sent transactions SHOULD be reported with their number of confirmations, +how long until they expire, and their balances as described in `Reporting of balances`_. + + + +Auto-shielding +-------------- If they use auto-shielding, then any transparent balance should be treated as pending. @@ -141,6 +198,7 @@ For wallets that allow long-term storage of transparent funds, they SHOULD also show spendable transparent and pending (or total) transparent according to the same policy. + Unedited -------- From f4dd8a5fdd7794d14be6487cd563e37c6f20e986 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Wed, 29 Jun 2022 09:46:14 +0100 Subject: [PATCH 05/21] ZIP 315: Address review comments or add them as TODOs. Co-authored-by: Deirdre Connolly Signed-off-by: Daira Hopwood --- zip-0315.rst | 90 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 60 insertions(+), 30 deletions(-) diff --git a/zip-0315.rst b/zip-0315.rst index 7abd7800..de0431e4 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -22,21 +22,18 @@ Auto-shielding The process of automatically transferring transparent funds to the most recent shielded pool on receipt. +Opportunistic shielding + The process of transferring previously received transparent funds to the most + recent shielded pool as part of a user-initiated transaction. + Auto-migration The process of automatically transferring shielded funds from older pools to the most preferred (usually the most recent) pool on receipt. -Opportunistic shielding - TODO - Opportunistic migration - TODO - -Confirmed - TODO - -Partially confirmed - TODO + The process of transferring previously received shielded funds from older pools + to the most preferred (usually the most recent) pool as part of a user-initiated + transaction. Transaction output (TXO) An output (transparent TXO or note) of a transaction on the consensus block chain @@ -46,11 +43,20 @@ Transaction output (TXO) Motivation ========== -The aim of this ZIP is to provide wallet developers with a set of best practices by -which they can minimize the leakage of information when constructing transactions. +Zcash wallets have to serve two purposes as a user agent: -This includes best practices for: +* to manage the economic actions dictated by the user; +* to manage the privacy implications of these actions. +The goal of this ZIP is to document security and privacy best practices when handling +funds and transactions as the user's agent. These best practices are intended to +provide as much privacy as is feasible by default, while still enabling the user's +desired transactions to occur, and exposing any privacy implications to the user so +that they have enough information to assess the consequences of their economic actions. + +This ZIP covers best practices for: + +* what information to display to the user about transactions and balances; * how to handle interactions between the ZIP 32 key tree and Unified Addresses; * when to use external or internal keys/addresses; * sharing addresses and viewing keys; @@ -64,14 +70,14 @@ Requirements User consent ------------ -The guiding principle of these requirements is that users must explicitly consent -to each instance of information being revealed by the wallet. - A wallet typically reveals some information in the process of creating a transaction. Which information is revealed depends on the configured wallet privacy policy. +The guiding principle of these requirements is that users must explicitly consent +to each instance of information being revealed by the wallet in a transaction. + A user may give blanket consent to reveal a particular kind of information, and must also be able to change the configured wallet privacy policy to avoid the -wallet creating new privacy leaks of a given type. +wallet creating new information leaks of a given type. The specifications below describe some situations in which blanket consent may be inappropriate. @@ -108,15 +114,24 @@ Long-term storage of funds -------------------------- It is RECOMMENDED that wallets only hold funds as shielded in the long-term; -that is, they automatically shield incoming transparent funds. +that is, if a wallet supports receiving transparent funds (or supports +importing a seed from another wallet that may have done so), then it SHOULD +either auto-shield or opportunistically shield such funds. -The remainder of this specification assumes a wallet that follows this +Following this recommendation improves both collective privacy and the user's +individual privacy, by maximizing the size of the note anonymity set over time. +The remainder of this specification assumes a wallet that follows the above recommendation, except where explicitly noted. Trusted and untrusted TXOs -------------------------- +A wallet SHOULD treat received TXOs that are outputs of transactions created +by the same wallet, as trusted TXOs. Wallets MAY enable users to mark specific +external transactions as trusted, allowing their received TXOs also to be +classified as trusted TXOs. + A wallet SHOULD have a policy that is clearly communicated to the user for the number of confirmations needed to spend untrusted and trusted TXOs respectively. The following confirmation policy is RECOMMENDED: @@ -124,10 +139,6 @@ respectively. The following confirmation policy is RECOMMENDED: * 10 confirmations, for untrusted TXOs; * 3 confirmations, for trusted TXOs. -Wallets MAY enable users to mark specific external transactions as trusted, -allowing their received TXOs to be treated as trusted TXOs even if they -do not have the required number of confirmations. - Categories of TXOs according to spendability -------------------------------------------- @@ -161,6 +172,8 @@ These are calculated as follows: * The pending balance is the sum of values of unconfirmed spendable TXOs. * The total balance is the spendable balance plus the pending balance. +TODO: report separate shielded and transparent balance? + Reporting of transactions ------------------------- @@ -199,11 +212,19 @@ show spendable transparent and pending (or total) transparent according to the same policy. +Transaction creation +-------------------- + +Anchor selection +'''''''''''''''' + +TODO: choose anchors at the trusted confirmation depth. This avoids leaking information +about whether or not we spent trusted notes. + + Unedited -------- -Wallets MUST report at least separate shielded and transparent balance. - If auto-shielding or auto-migration is off, then wallets MAY report separate balances for each shielded pool and for transparent balance. @@ -236,6 +257,7 @@ into the operation of auto-shielding, opportunistic shielding, and pool migratio Linkability of transactions or addresses ---------------------------------------- +TODO: dusting attack mitigation Network-layer privacy @@ -396,13 +418,13 @@ storage. will, by default, generate unified addresses using that set of receiver types. - For zcashd we know how the policy evolves because each zcashd release has - an approximate relase height and EoS height that defines the window. -- Subsequent releases of a wallet should not retroactively change their + an approximate release height and End-of-Service height that defines the window. +- Subsequent releases of a wallet SHOULD NOT retroactively change their policies for previously defined block height ranges. -- If the receiver type for a note received at a given type is not a member +- If the receiver type for a note received at a given time is not a member of the set of receiver types expected for the range of block heights, the policy corresponding to the nearest block height range that includes that - receiver type should be used. + receiver type SHOULD be used. - If the receiver matches a UFVK in the wallet, and we have no information about when this receiver may have been first used, show the UA corresponding to the most recent receiver types policy that includes the @@ -413,8 +435,16 @@ storage. addresses generated via z_getaddressforaccount. The internal map lookup is then just an optimisation (and a future refactor to have Orchard do the same is possible, but for now we will only trial-decrypt so we don't - need to refactor to access the Rust wallet). + need to refactor to access the Rust wallet). TODO: express this in a less + zcashd-specific way. +TODO: Mention recommendations (not requirements) of receiver types based on +settled ('accepted') network upgrades, as defined in §3.3 of the +Zcash Protocol Specification, at the time of the release of the wallet. + +TODO: Rationale subsection explaining why earliest block height at detection +and the rules/recommendations in place at that block height are preferred +over showing different UAs at different heights References ========== From ce836df9538246cd17ae402dce72b13f22652646 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Wed, 20 Jul 2022 13:28:20 +0100 Subject: [PATCH 06/21] ZIP 315: Fix the definition of confirmed spendable. Previously it did not correctly handle unsynced wallets, or transparent TXOs when auto-shielding is enabled. Also, move some unedited text into the relevant sections. Signed-off-by: Daira Hopwood --- zip-0315.rst | 106 ++++++++++++++++++++++++++------------------------- 1 file changed, 54 insertions(+), 52 deletions(-) diff --git a/zip-0315.rst b/zip-0315.rst index de0431e4..b7f21ace 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -116,13 +116,16 @@ Long-term storage of funds It is RECOMMENDED that wallets only hold funds as shielded in the long-term; that is, if a wallet supports receiving transparent funds (or supports importing a seed from another wallet that may have done so), then it SHOULD -either auto-shield or opportunistically shield such funds. +either auto-shield or opportunistically shield such funds by default. Following this recommendation improves both collective privacy and the user's individual privacy, by maximizing the size of the note anonymity set over time. + The remainder of this specification assumes a wallet that follows the above recommendation, except where explicitly noted. +A wallet MAY allow users to disable auto-shielding. + Trusted and untrusted TXOs -------------------------- @@ -143,20 +146,26 @@ respectively. The following confirmation policy is RECOMMENDED: Categories of TXOs according to spendability -------------------------------------------- -A TXO is *confirmed spendable* if and only if the wallet has its spending -key, and: +A TXO is *confirmed spendable*, relative to a given block chain state, +if and only if all of the following are true in that state: -* it is a trusted TXO that has at least the required confirmations for trusted - TXOs; or -* it is an untrusted TXO that has at least the required confirmations for - untrusted TXOs. +* the wallet is synchronized; and +* the TXO is unspent; and +* the wallet has the TXO's spending key; and +* either auto-shielding is disabled or the TXO is shielded; and +* the TXO is trusted and has at least the required confirmations for + trusted TXOs, or it is untrusted and has at least the required + confirmations for untrusted TXOs. -A TXO is *unconfirmed spendable* if and only if the wallet has its spending -key, and it is not confirmed spendable. +A TXO is *unconfirmed spendable*, relative to a given block chain state, +if and only if it is unspent, the wallet has its spending key, and it is +not confirmed spendable. A TXO is *watch-only* if and only if the wallet has its full viewing key (or address in the case of a transparent TXO) but not its spending key. +A wallet MUST NOT attempt to spend a TXO that is not confirmed spendable. + Reporting of balances --------------------- @@ -172,8 +181,39 @@ These are calculated as follows: * The pending balance is the sum of values of unconfirmed spendable TXOs. * The total balance is the spendable balance plus the pending balance. -TODO: report separate shielded and transparent balance? +Note: the definition of "confirmed spendable" above ensures that: +* if auto-shielding is enabled, transparent funds will be reported in + the pending or total balance, but not in the spendable balance; +* if the wallet is not synchronized, the spendable balance will be + zero. + +If auto-shielding is disabled, the wallet MAY report shielded and +transparent balances separately. If it does so, it MUST make clear +whether each reported balance corresponds to a spendable, pending, or +total subset of funds. + +TODO: refine this in terms of the following categories: + +* Funds at rest (not involved in any not-fully-confirmed transfer). +* Outgoing funds to an external source (might come back if the tx + doesn't go through). +* Incoming funds from an external source. +* Funds we are sending to ourself. + +Rationale for reporting of balances +''''''''''''''''''''''''''''''''''' + +If auto-shielding is disabled, then separate shielded and transparent +balances (and potentially, for expert users, separate shielded balances +per pool) can constitute useful information. If auto-shielding is enabled +then the wallet can and will automatically spend transparent TXOs in +order to shield them, and so transparent TXOs need to be presented as +pending, not as part of the balance spendable by the user. + +TODO: The specification of balance reporting is intended to give the user +visibility into the operation of auto-shielding, opportunistic shielding, +and pool migration/usage. (Does the spec satisfy this?) Reporting of transactions ------------------------- @@ -200,18 +240,6 @@ Sent transactions SHOULD be reported with their number of confirmations, how long until they expire, and their balances as described in `Reporting of balances`_. - -Auto-shielding --------------- - -If they use auto-shielding, then any transparent balance should be treated as -pending. - -For wallets that allow long-term storage of transparent funds, they SHOULD also -show spendable transparent and pending (or total) transparent according to the -same policy. - - Transaction creation -------------------- @@ -222,36 +250,10 @@ TODO: choose anchors at the trusted confirmation depth. This avoids leaking info about whether or not we spent trusted notes. -Unedited --------- - -If auto-shielding or auto-migration is off, then wallets MAY report separate -balances for each shielded pool and for transparent balance. - -If the wallet never supports a given pool, it can obviously omit balances for that -pool. - -If auto-shielding is on, transparent funds should be reported in "balance unavailable -to spend". - -Wallets SHOULD separately report the balances of funds that are immediately -spendable, and any remaining funds that are expected from unconfirmed or -partially confirmed transfers. - -TODO: make this more precise in terms of the following categories: - -* Funds at rest (not involved in any not-fully-confirmed transfer) -* Outgoing funds to an external source (might come back if the tx doesn't go through) -* Incoming funds from an external source -* Funds we are sending to ourself. - - -Rationale -''''''''' - -The specification of balance reporting is intended to give the user visibility -into the operation of auto-shielding, opportunistic shielding, and pool migration/usage. +Rationale for anchor selection +'''''''''''''''''''''''''''''' +TODO Linkability of transactions or addresses @@ -403,7 +405,7 @@ bunch of coordination to the problem, and assumes ongoing on-chain state storage. - If the receiver matches an address that the wallet knows was derived via - z_getaddressforaccount, show that UA as expected (matching the receiver + ``z_getaddressforaccount``, show that UA as expected (matching the receiver types the user selected). - If the receiver matches a UFVK in the wallet, and we are looking it up because we detected a received note in some block, show the UA with the From ff99ddc449f87e12e8bc943989df42d6ee84671a Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Tue, 6 Sep 2022 22:01:44 +0100 Subject: [PATCH 07/21] ZIP 315: Clarify TXO categories and other editing. Co-authored-by: Kris Nuttycombe Signed-off-by: Daira Hopwood --- zip-0315.rst | 114 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 80 insertions(+), 34 deletions(-) diff --git a/zip-0315.rst b/zip-0315.rst index b7f21ace..fe8872f7 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -92,8 +92,9 @@ Prompt accessibility of funds Wallets need to take account of two concerns: * enabling funds to be spent as quickly as possible to reduce latency; -* waiting for long enough before spending TXOs to ensure that the spendable - balance is not overestimated, and so can be trusted by the user. +* waiting for long enough before spending TXOs to ensure that the + confirmed-spendable balance is not overestimated, and so can be trusted + by the user. To enable this we define two kinds of TXOs: @@ -142,29 +143,51 @@ respectively. The following confirmation policy is RECOMMENDED: * 10 confirmations, for untrusted TXOs; * 3 confirmations, for trusted TXOs. +Rationale for the given numbers of confirmations +'''''''''''''''''''''''''''''''''''''''''''''''' + +The rationale for choosing three confirmations for trusted TXOs is that +empirically, reorgs are usually less than three blocks. + +The consequences of attempting to spend an untrusted note in the case of a +rollback may be less severe than attempting to spend a trusted note. The value +received from a trusted note should always be recoverable, whereas recovering +value received from an untrusted note may require the user to request that +funds are re-sent. + Categories of TXOs according to spendability -------------------------------------------- -A TXO is *confirmed spendable*, relative to a given block chain state, +A TXO is *spendable*, relative to a given block chain and wallet state, if and only if all of the following are true in that state: +* the TXO is unspent; +* the TXO is not committed to be spent in another transaction created + by this wallet; and +* the wallet has the TXO's spending key. + +A TXO is *confirmed-spendable*, relative to a given block chain and +wallet state, if and only if all of the following are true in that state: + * the wallet is synchronized; and -* the TXO is unspent; and -* the wallet has the TXO's spending key; and +* the TXO is spendable; and * either auto-shielding is disabled or the TXO is shielded; and * the TXO is trusted and has at least the required confirmations for trusted TXOs, or it is untrusted and has at least the required confirmations for untrusted TXOs. -A TXO is *unconfirmed spendable*, relative to a given block chain state, -if and only if it is unspent, the wallet has its spending key, and it is -not confirmed spendable. +A TXO is *unconfirmed-spendable*, relative to a given block chain and +wallet state, if and only if the TXO is spendable but is not +confirmed-spendable in that state. A TXO is *watch-only* if and only if the wallet has its full viewing key (or address in the case of a transparent TXO) but not its spending key. -A wallet MUST NOT attempt to spend a TXO that is not confirmed spendable. +A wallet MUST NOT attempt to spend a TXO that is not confirmed-spendable. + +Note: the definition of a TXO includes outputs in mempool transactions +that are unconflicted from the perspective of the wallet. Reporting of balances @@ -172,34 +195,29 @@ Reporting of balances Wallets SHOULD report: -* Spendable balance. +* Confirmed-spendable balance. * Pending balance, *or* total balance. These are calculated as follows: -* The spendable balance is the sum of values of confirmed spendable TXOs. -* The pending balance is the sum of values of unconfirmed spendable TXOs. -* The total balance is the spendable balance plus the pending balance. +* The confirmed-spendable balance is the sum of values of + confirmed-spendable TXOs. +* The pending balance is the sum of values of unconfirmed-spendable TXOs. +* The total balance is the confirmed-spendable balance plus the pending + balance. -Note: the definition of "confirmed spendable" above ensures that: +Note: the definition of "confirmed-spendable" above ensures that: * if auto-shielding is enabled, transparent funds will be reported in - the pending or total balance, but not in the spendable balance; -* if the wallet is not synchronized, the spendable balance will be - zero. + the pending or total balance, but not in the confirmed-spendable + balance; +* if the wallet is not synchronized, the confirmed-spendable balance + will be zero. If auto-shielding is disabled, the wallet MAY report shielded and transparent balances separately. If it does so, it MUST make clear -whether each reported balance corresponds to a spendable, pending, or -total subset of funds. - -TODO: refine this in terms of the following categories: - -* Funds at rest (not involved in any not-fully-confirmed transfer). -* Outgoing funds to an external source (might come back if the tx - doesn't go through). -* Incoming funds from an external source. -* Funds we are sending to ourself. +whether each reported balance corresponds to a confirmed-spendable, +pending, or total subset of funds. Rationale for reporting of balances ''''''''''''''''''''''''''''''''''' @@ -224,9 +242,9 @@ and watch-only incoming balances MUST be reported separately. Incoming transactions ''''''''''''''''''''' -A transaction is incoming if it contains unconfirmed TXOs. Incoming -transactions SHOULD be reported with their number of confirmations and -their balances as described in `Reporting of balances`_. +A transaction is incoming if it contains unconfirmed-spendable TXOs. +Incoming transactions SHOULD be reported with their number of confirmations +and their balances as described in `Reporting of balances`_. Sent transactions ''''''''''''''''' @@ -237,7 +255,8 @@ A transaction is sent if it was either: * detected as having been sent from one of the wallet's watch-only addresses. Sent transactions SHOULD be reported with their number of confirmations, -how long until they expire, and their balances as described in `Reporting of balances`_. +how long until they expire, and their balances as described in +`Reporting of balances`_. Transaction creation @@ -246,14 +265,40 @@ Transaction creation Anchor selection '''''''''''''''' -TODO: choose anchors at the trusted confirmation depth. This avoids leaking information -about whether or not we spent trusted notes. +A wallet SHOULD choose an anchor a number of blocks back from the head of the +chain equal to the trusted confirmation depth. That is, if the current block +is at height H, the anchor SHOULD reflect the final treestate of the block at +height H-3. Rationale for anchor selection '''''''''''''''''''''''''''''' -TODO +* If the chain rolls back past the block at which the anchor is chosen, then + the anchor and the transaction will be invalidated. This is undesirable both + for reliability, and because the nullifiers of spent notes will have been + revealed, linking this transaction to any future transactions that spend those + notes. +* On the other hand, it is undesirable to choose an anchor too many blocks back, + because that prevents more recently received notes from being spent. +* Using a fixed anchor depth (as opposed to a different depth depending on whether + or not we are spending trusted notes) avoids leaking information about whether + or not we spent trusted notes. + + +Note selection +'''''''''''''' + +TODO: consider what we should do when nullifiers are revealed in a transaction +that is then invalidated. Should those notes be prioritized to be spent soon, +or should they be used in a note management tx? + + +Expiration height +''''''''''''''''' + +A wallet SHOULD create transactions using the default expiration height of 40 blocks +from the current height, as specified in [#zip-0203]_. Linkability of transactions or addresses @@ -452,3 +497,4 @@ References ========== .. [#RFC2119] `RFC 2119: Key words for use in RFCs to Indicate Requirement Levels `_ +.. [#zip-0203] `ZIP 203: Transaction Expiry `_ From af13104ae9b048e148d721703344375ce21adb2a Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Wed, 28 Sep 2022 19:19:30 +0100 Subject: [PATCH 08/21] ZIP 315: line rewrapping. Signed-off-by: Daira Hopwood --- zip-0315.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/zip-0315.rst b/zip-0315.rst index fe8872f7..3178409a 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -275,15 +275,15 @@ Rationale for anchor selection '''''''''''''''''''''''''''''' * If the chain rolls back past the block at which the anchor is chosen, then - the anchor and the transaction will be invalidated. This is undesirable both - for reliability, and because the nullifiers of spent notes will have been - revealed, linking this transaction to any future transactions that spend those - notes. -* On the other hand, it is undesirable to choose an anchor too many blocks back, - because that prevents more recently received notes from being spent. -* Using a fixed anchor depth (as opposed to a different depth depending on whether - or not we are spending trusted notes) avoids leaking information about whether - or not we spent trusted notes. + the anchor and the transaction will be invalidated. This is undesirable + both for reliability, and because the nullifiers of spent notes will have + been revealed, linking this transaction to any future transactions that + spend those notes. +* On the other hand, it is undesirable to choose an anchor too many blocks + back, because that prevents more recently received notes from being spent. +* Using a fixed anchor depth (as opposed to a different depth depending on + whether or not we are spending trusted notes) avoids leaking information + about whether or not we spent trusted notes. Note selection @@ -297,8 +297,8 @@ or should they be used in a note management tx? Expiration height ''''''''''''''''' -A wallet SHOULD create transactions using the default expiration height of 40 blocks -from the current height, as specified in [#zip-0203]_. +A wallet SHOULD create transactions using the default expiration height of +40 blocks from the current height, as specified in [#zip-0203]_. Linkability of transactions or addresses From e8525a38248d3deec1dd854e116a6bfc6a54b864 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Wed, 28 Sep 2022 19:20:16 +0100 Subject: [PATCH 09/21] ZIP 315: new content. Co-authored-by: Kris Nuttycombe Signed-off-by: Daira Hopwood --- zip-0315.rst | 124 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 121 insertions(+), 3 deletions(-) diff --git a/zip-0315.rst b/zip-0315.rst index 3178409a..8cfd5412 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -60,7 +60,7 @@ This ZIP covers best practices for: * how to handle interactions between the ZIP 32 key tree and Unified Addresses; * when to use external or internal keys/addresses; * sharing addresses and viewing keys; -* sending and receiving funds; +* sending and receiving funds (including fee selection); * migrating funds between pools. @@ -262,6 +262,118 @@ how long until they expire, and their balances as described in Transaction creation -------------------- +Obtaining user consent for information leakage +'''''''''''''''''''''''''''''''''''''''''''''' + +Motivation +~~~~~~~~~~ + +The privacy provided by a Zcash transaction depends on the information leaked +in the creation of that transaction and the process of it being broadcast for +inclusion in the block chain. + +The requirements in this section are intended to minimize the leakage of such +information where possible, and to ensure that the user is informed of any +remaining information that would be leaked, and consents to such leakage. + +The list below describes the kinds of information that might be leaked. After +a candidate transaction has been created and prior to it being revealed +outside a trusted path to the user, the wallet user interface SHOULD obtain +the user's consent for all of the leaked information. + +Assumption: There is always a transaction confirmation step for transactions +that send funds out of the wallet. + + +Kinds of information leakage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Transaction version (v4 or v5, as of NU5) + +SHOULD use v5 (unless you're spending Sprout funds). + +* Lock time (rarely used; may be a distinguisher if it is) + +SHOULD be zero. + +* Expiry height and anchor position + +See `Anchor selection`_ below. + +These give information about what block height the creator was synced to, and +some policy information. + +* Transparent inputs and outputs + +See `Linkability of transactions or addresses`_. + +* Public value balances + + * Together with the transparent inputs and outputs, these determine the fee + and the amount being transferred between pools. + * The fee is dependent on policy, but for a given policy we attempt to make + it only depend on other already-leaked metadata. + +SHOULD try to create fully shielded transactions where possible. + +Open question: Are we going to describe the policy that zcashd uses? + + +* Numbers of JoinSplits, Spends, Outputs, and Actions + + * This could correlate with other information under certain circumstances. + For example in a “dusting attack”, the adversary sends a victim lots of + small-valued notes (or notes with strategically chosen values), + increasing the probability that the victim’s transactions will have a + larger number of spends than other transactions (or an identifiable + number of spends). There are note management strategies that can mitigate + this, but they have not been implemented yet. + +* Which spends of given notes are repeated across transactions + + * This may happen because a previous transaction expired and the user is + trying to spend some of the same notes. + +* Whether the transaction is coinbase + +* For coinbase transactions, the amounts / destination addresses / memos of + shielded outputs + +* Orchard flags (enableSpends/enableOutputs) + + * Under normal circumstances these only depend on whether the transaction + is coinbase. + + +Linkability of transactions or addresses +'''''''''''''''''''''''''''''''''''''''' + +Motivation +~~~~~~~~~~ + +We want to support creating unlinkable addresses, in order that a user can +give different addresses to different counterparties, in such a way that the +counterparties (even if they collude) cannot tell that the addresses were +provided by the same or distinct users. + +If multiple UTXOs are received at the same transparent address, it is safe +to shield them all in the same transaction, because that is not leaking +additional information. + +UTXOs received on different transparent receivers SHOULD NOT be shielded +in the same transaction. Ideally, when they are shielded in separate +transactions, this should be done in such a way that the timing of those +transactions is not linkable. + +When spending transparent UTXOs, they should only be sent to an internal +shielded receiver belonging to the wallet. + +A wallet MUST NOT send funds to a transparent address unless all of the +source funds come from shielded pools, and this SHOULD be a single shielded +pool. + +We want to minimize pool crossing. + Anchor selection '''''''''''''''' @@ -301,8 +413,14 @@ A wallet SHOULD create transactions using the default expiration height of 40 blocks from the current height, as specified in [#zip-0203]_. -Linkability of transactions or addresses ----------------------------------------- +Open question +''''''''''''' + +How should wallet developers time transactions to avoid linkability? + +* when we roll addresses with transparent components, we have to consider + how that could allow linking of shielded components + TODO: dusting attack mitigation From 85c6b73a46991dc169afd49e5d1dd67d0b1ded06 Mon Sep 17 00:00:00 2001 From: Daira Emma Hopwood Date: Thu, 2 Mar 2023 13:16:52 +0000 Subject: [PATCH 10/21] ZIP 315: change title; add @nuttycom to Owners and @pacu to Credits. Signed-off-by: Daira Hopwood --- zip-0315.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/zip-0315.rst b/zip-0315.rst index 8cfd5412..fe17695c 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -1,9 +1,11 @@ :: ZIP: 315 - Title: Best Practices for Wallet Handling of Multiple Pools + Title: Best Practices for Wallet Implementations Owners: Daira Emma Hopwood Jack Grigg + Kris Nuttycombe + Credits: Francisco Gindre Status: Proposed Category: Wallet Discussions-To: From d12a0a3aa5bb9345e38ac6dd6addb411bcd256bd Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Wed, 28 Sep 2022 19:30:00 +0100 Subject: [PATCH 11/21] ZIP 315: deduplicate section headings. Signed-off-by: Daira Hopwood --- zip-0315.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/zip-0315.rst b/zip-0315.rst index fe17695c..38894d50 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -267,8 +267,8 @@ Transaction creation Obtaining user consent for information leakage '''''''''''''''''''''''''''''''''''''''''''''' -Motivation -~~~~~~~~~~ +Information leakage analysis +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The privacy provided by a Zcash transaction depends on the information leaked in the creation of that transaction and the process of it being broadcast for @@ -350,8 +350,8 @@ Open question: Are we going to describe the policy that zcashd uses? Linkability of transactions or addresses '''''''''''''''''''''''''''''''''''''''' -Motivation -~~~~~~~~~~ +Motivation for choices reducing linkability +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We want to support creating unlinkable addresses, in order that a user can give different addresses to different counterparties, in such a way that the From 8e1cd7f9563801fbf2d5cf23768ef4f831cb6fcd Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Sat, 3 Dec 2022 15:17:30 +0000 Subject: [PATCH 12/21] ZIP 315: apply suggestions from code review. Co-authored-by: Deirdre Connolly Signed-off-by: Daira Emma Hopwood --- zip-0315.rst | 69 +++++++++++++++++++++++++++++----------------------- 1 file changed, 39 insertions(+), 30 deletions(-) diff --git a/zip-0315.rst b/zip-0315.rst index 38894d50..caa734ed 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -38,8 +38,8 @@ Opportunistic migration transaction. Transaction output (TXO) - An output (transparent TXO or note) of a transaction on the consensus block chain - or in the mempool visible to a wallet. + An output (transparent coin or shielded note) of a transaction on the consensus + block chain or in the mempool visible to a wallet. Motivation @@ -59,7 +59,7 @@ that they have enough information to assess the consequences of their economic a This ZIP covers best practices for: * what information to display to the user about transactions and balances; -* how to handle interactions between the ZIP 32 key tree and Unified Addresses; +* how to handle interactions between the ZIP 32 [#zip-0032]_ key tree and Unified Addresses [#zip-0316]_; * when to use external or internal keys/addresses; * sharing addresses and viewing keys; * sending and receiving funds (including fee selection); @@ -94,16 +94,17 @@ Prompt accessibility of funds Wallets need to take account of two concerns: * enabling funds to be spent as quickly as possible to reduce latency; -* waiting for long enough before spending TXOs to ensure that the +* waiting long enough before spending TXOs to ensure that the confirmed-spendable balance is not overestimated, and so can be trusted by the user. To enable this we define two kinds of TXOs: -* An untrusted TXO is a TXO received from a party that may try to double-spend. * A trusted TXO is a TXO received from a party where the wallet trusts a double-spend not to occur, e.g. TXOs created by the wallet's internal TXO handling. +* An untrusted TXO is a TXO received by the wallet that is not trusted. + Wallets can then require that untrusted TXOs need more confirmations before they become spendable than trusted TXOs. This provides an improved trade-off @@ -116,9 +117,9 @@ Specification Long-term storage of funds -------------------------- -It is RECOMMENDED that wallets only hold funds as shielded in the long-term; +It is RECOMMENDED that wallets only hold funds as shielded in the long term; that is, if a wallet supports receiving transparent funds (or supports -importing a seed from another wallet that may have done so), then it SHOULD +importing a seed from another wallet that might have done so), then it SHOULD either auto-shield or opportunistically shield such funds by default. Following this recommendation improves both collective privacy and the user's @@ -151,11 +152,11 @@ Rationale for the given numbers of confirmations The rationale for choosing three confirmations for trusted TXOs is that empirically, reorgs are usually less than three blocks. -The consequences of attempting to spend an untrusted note in the case of a -rollback may be less severe than attempting to spend a trusted note. The value -received from a trusted note should always be recoverable, whereas recovering -value received from an untrusted note may require the user to request that -funds are re-sent. +The consequences of attempting to spend a trusted TXO may be less severe in the +case of a rollback than the consequences of attempting to spend an untrusted TXO. +The value received from a trusted TXO should always be recoverable, whereas +recovering value received from an untrusted TXO may require the user to request +that funds are re-sent. Categories of TXOs according to spendability @@ -167,7 +168,7 @@ if and only if all of the following are true in that state: * the TXO is unspent; * the TXO is not committed to be spent in another transaction created by this wallet; and -* the wallet has the TXO's spending key. +* the wallet has the TXO's spending key (for whatever protocol the TXO uses). A TXO is *confirmed-spendable*, relative to a given block chain and wallet state, if and only if all of the following are true in that state: @@ -253,12 +254,16 @@ Sent transactions A transaction is sent if it was either: * created by the wallet, or -* detected using the wallet's outgoing viewing keys, or -* detected as having been sent from one of the wallet's watch-only addresses. +* detected by using the wallet's outgoing viewing keys to decrypt + Sapling or Orchard outputs, or +* detected as spending a note that was at some time held by the + wallet by recognizing that note's nullifier, or +* detected as spending a transparent TXO associated with one of + the wallet's addresses (including watch-only addresses). Sent transactions SHOULD be reported with their number of confirmations, -how long until they expire, and their balances as described in -`Reporting of balances`_. +how long until they expire (if they are unmined and have an expiry +height), and their balances as described in `Reporting of balances`_. Transaction creation @@ -331,10 +336,10 @@ Open question: Are we going to describe the policy that zcashd uses? number of spends). There are note management strategies that can mitigate this, but they have not been implemented yet. -* Which spends of given notes are repeated across transactions +* Which spends of given TXOs are repeated across transactions * This may happen because a previous transaction expired and the user is - trying to spend some of the same notes. + trying to spend some of the same TXOs. * Whether the transaction is coinbase @@ -367,7 +372,7 @@ in the same transaction. Ideally, when they are shielded in separate transactions, this should be done in such a way that the timing of those transactions is not linkable. -When spending transparent UTXOs, they should only be sent to an internal +When spending transparent UTXOs, they SHOULD only be sent to an internal shielded receiver belonging to the wallet. A wallet MUST NOT send funds to a transparent address unless all of the @@ -390,14 +395,16 @@ Rationale for anchor selection * If the chain rolls back past the block at which the anchor is chosen, then the anchor and the transaction will be invalidated. This is undesirable - both for reliability, and because the nullifiers of spent notes will have - been revealed, linking this transaction to any future transactions that - spend those notes. + both for reliability, and because the nullifiers of spent shielded notes + will have been revealed, linking this transaction to any future transactions + that spend those notes. * On the other hand, it is undesirable to choose an anchor too many blocks - back, because that prevents more recently received notes from being spent. + back, because that prevents more recently received shielded notes from + being spent. * Using a fixed anchor depth (as opposed to a different depth depending on - whether or not we are spending trusted notes) avoids leaking information - about whether or not we spent trusted notes. + whether or not we are spending trusted shielded notes) avoids leaking + information about whether or not the shielded notes we spent were + trusted. Note selection @@ -488,14 +495,16 @@ Information leakage for transfers between pools If no auto-migration, if you can satisfy a transfer request to Sapling from your Sapling funds, do so. -The user's consent is needed to reveal amounts. Therefore, there should be -per-transaction opt-in for any amount-revealing transfer. +The user's consent is needed to reveal amounts publically (as opposed +to revealing them to the holder of a viewing key authorized to see that +amount). Therefore, there should be per-transaction opt-in for any +transfer that publically reveals amounts on chain. * there may be a compatibility issue for amount-revealing cross-pool txns that were previously allowed without opt-in -Don't automatically combine funds across pools to satisfy a transfer (since that -could reveal the total funds in some pool). +Wallets MUST NOT automatically combine funds across pools to satisfy a transfer +(since that could reveal the total funds the user holds in some pool). In order to maintain the integrity of IVK guarantees, wallets should not generate unified addresses that contain internal receivers, nor expose internal receivers From e7418d3dd2a6f62dc41ab027f03106c170d7f74b Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 16 Jul 2024 01:57:58 +0100 Subject: [PATCH 13/21] Minor editorial changes from review Co-authored-by: Daira-Emma Hopwood Co-authored-by: Deirdre Connolly --- zip-0315.rst | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/zip-0315.rst b/zip-0315.rst index dd430a72..6abe6f9a 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -9,14 +9,15 @@ Status: Proposed Category: Wallet Discussions-To: - Pull-Request: + Pull-Request: Terminology =========== -The key words "MUST", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be -interpreted as described in RFC 2119. [#RFC2119]_ +The key words "MUST", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", +and "MAY" in this document are to be interpreted as described in BCP 14 [#BCP14]_ +when, and only when, they appear in all capitals. The terms below are to be interpreted as follows: @@ -98,7 +99,7 @@ Wallets need to take account of two concerns: confirmed-spendable balance is not overestimated, and so can be trusted by the user. -To enable this we define two kinds of TXOs: +To support this we define two kinds of TXOs: * A trusted TXO is a TXO received from a party where the wallet trusts a double-spend not to occur, e.g. TXOs created by the wallet's internal TXO @@ -175,7 +176,8 @@ wallet state, if and only if all of the following are true in that state: * the wallet is synchronized; and * the TXO is spendable; and -* either auto-shielding is disabled or the TXO is shielded; and +* either auto-shielding is not active or the TXO is shielded; and +* auto-migration *from* whatever protocol the TXO uses is not active; and * the TXO is trusted and has at least the required confirmations for trusted TXOs, or it is untrusted and has at least the required confirmations for untrusted TXOs. @@ -239,8 +241,8 @@ and pool migration/usage. (Does the spec satisfy this?) Reporting of transactions ------------------------- -If a transaction contains both spendable and watch-only TXOs, its spendable -and watch-only incoming balances MUST be reported separately. +If a transaction includes watch-only received TXOs, its watch-only incoming +balance MUST be reported separately to any potentially spendable balance. Incoming transactions ''''''''''''''''''''' @@ -262,8 +264,9 @@ A transaction is sent if it was either: the wallet's addresses (including watch-only addresses). Sent transactions SHOULD be reported with their number of confirmations, -how long until they expire (if they are unmined and have an expiry -height), and their balances as described in `Reporting of balances`_. +an estimate of how long until they expire (if they are unmined and +have an expiry height), and their balances as described in +`Reporting of balances`_. Transaction creation @@ -467,7 +470,7 @@ Wallets SHOULD NOT spend funds from a transparent address to an external address unless the user gives explicit consent for this on a per-transaction basis. In order to support this policy, wallets SHOULD implement a system of auto-shielding -with the following characteristics. +with the following characteristics: If auto-shielding functionality is available in a wallet, then users MUST be able @@ -625,5 +628,5 @@ over showing different UAs at different heights References ========== -.. [#RFC2119] `RFC 2119: Key words for use in RFCs to Indicate Requirement Levels `_ +.. [#BCP14] `Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words" `_ .. [#zip-0203] `ZIP 203: Transaction Expiry `_ From c24a1514bf8ffff091d0505066b0bd0fd17eccfc Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 16 Jul 2024 02:06:18 +0100 Subject: [PATCH 14/21] Recommend against opportunistic shielding The recipient in an opportunistic shielding transaction learns a transparent address that they can assume is associated with the transaction sender. While the transparent protocol does not attempt to hide this information, and it might be learnable from other sources, we don't need to make it easy. Co-authored-by: Daira-Emma Hopwood --- zip-0315.rst | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/zip-0315.rst b/zip-0315.rst index 6abe6f9a..5b93a331 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -25,10 +25,6 @@ Auto-shielding The process of automatically transferring transparent funds to the most recent shielded pool on receipt. -Opportunistic shielding - The process of transferring previously received transparent funds to the most - recent shielded pool as part of a user-initiated transaction. - Auto-migration The process of automatically transferring shielded funds from older pools to the most preferred (usually the most recent) pool on receipt. @@ -121,13 +117,32 @@ Long-term storage of funds It is RECOMMENDED that wallets only hold funds as shielded in the long term; that is, if a wallet supports receiving transparent funds (or supports importing a seed from another wallet that might have done so), then it SHOULD -either auto-shield or opportunistically shield such funds by default. +auto-shield such funds by default. -Following this recommendation improves both collective privacy and the user's -individual privacy, by maximizing the size of the note anonymity set over time. +A shielding transaction is always linked to the transparent addresses it +spends from. This can cause undesirable information leaks: +a) if there are multiple transparent addresses, they will be linked to each + other; +b) a link between the input transparent address(es) and the payment will be + visible to the recipient(s), or to any other holder of an Incoming Viewing + Key for the destination address(es). -The remainder of this specification assumes a wallet that follows the above -recommendation, except where explicitly noted. +Despite the fact that it is not possible to achieve strong privacy guarantees +from *any* use of transparent addresses, it is undesirable to reveal this +additional information. In particular, issue b) motivates ruling out the use +of "opportunistic shielding", i.e. shielding previously received transparent +funds as part of a user-initiated transaction. + +Wallets SHOULD NOT auto-shield from multiple transparent addresses in the +same transaction, and SHOULD NOT use opportunistic shielding. + +Following all of the recommendations in this section improves both collective +privacy and the user's individual privacy, by maximizing the size of the note +anonymity set over time and minimizing the potential linkage of shielding +transactions to other transactions. + +The remainder of this specification assumes a wallet that follows all of these +recommendations, except where explicitly noted. A wallet MAY allow users to disable auto-shielding. From beeaa53342fc5ff6a0d33748a9da73cee0e7eb31 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 16 Jul 2024 02:27:13 +0100 Subject: [PATCH 15/21] Change `spendable` term to `known-spendable` This frees up "spendable" for colloquial usage. Co-authored-by: Daira-Emma Hopwood --- zip-0315.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/zip-0315.rst b/zip-0315.rst index 5b93a331..4a6cf5e1 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -178,10 +178,11 @@ that funds are re-sent. Categories of TXOs according to spendability -------------------------------------------- -A TXO is *spendable*, relative to a given block chain and wallet state, +A TXO is *known-spendable*, relative to a given block chain and wallet state, if and only if all of the following are true in that state: -* the TXO is unspent; +* the TXO is unspent at the wallet's view of the chain tip, and that view is + reasonably up-to-date; * the TXO is not committed to be spent in another transaction created by this wallet; and * the wallet has the TXO's spending key (for whatever protocol the TXO uses). @@ -190,7 +191,7 @@ A TXO is *confirmed-spendable*, relative to a given block chain and wallet state, if and only if all of the following are true in that state: * the wallet is synchronized; and -* the TXO is spendable; and +* the TXO is known-spendable; and * either auto-shielding is not active or the TXO is shielded; and * auto-migration *from* whatever protocol the TXO uses is not active; and * the TXO is trusted and has at least the required confirmations for @@ -198,7 +199,7 @@ wallet state, if and only if all of the following are true in that state: confirmations for untrusted TXOs. A TXO is *unconfirmed-spendable*, relative to a given block chain and -wallet state, if and only if the TXO is spendable but is not +wallet state, if and only if the TXO is known-spendable but is not confirmed-spendable in that state. A TXO is *watch-only* if and only if the wallet has its full viewing key @@ -257,7 +258,7 @@ Reporting of transactions ------------------------- If a transaction includes watch-only received TXOs, its watch-only incoming -balance MUST be reported separately to any potentially spendable balance. +balance MUST be reported separately to any potentially known-spendable balance. Incoming transactions ''''''''''''''''''''' From 0d33eee0a21bfe246f00f7b7e0063832bd91f6e3 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 16 Jul 2024 02:37:31 +0100 Subject: [PATCH 16/21] Improvements to Requirements language from review Co-authored-by: Daira-Emma Hopwood --- zip-0315.rst | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/zip-0315.rst b/zip-0315.rst index 4a6cf5e1..1bf68fee 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -38,6 +38,12 @@ Transaction output (TXO) An output (transparent coin or shielded note) of a transaction on the consensus block chain or in the mempool visible to a wallet. +TODO: Add informal definitions of: +* known-spendable and confirmed-spendable TXOs; +* trusted and untrusted TXOs. + +These should forward-reference the specification section with the formal definitions. + Motivation ========== @@ -88,24 +94,29 @@ share some of their keys. Prompt accessibility of funds ----------------------------- -Wallets need to take account of two concerns: +Wallets need to take account of two main concerns with respect to +accessibility of funds: * enabling funds to be spent as quickly as possible to reduce latency; -* waiting long enough before spending TXOs to ensure that the - confirmed-spendable balance is not overestimated, and so can be trusted - by the user. +* ensuring that the confirmed-spendable balance is not overestimated, + and so can be trusted by the user. + +These concerns affect the way that balances should be computed, which +notes are selected for spending, and how the wallet should ensure that +sufficient notes are available to cover multiple spends within a short +period. To support this we define two kinds of TXOs: -* A trusted TXO is a TXO received from a party where the wallet trusts a - double-spend not to occur, e.g. TXOs created by the wallet's internal TXO - handling. +* A trusted TXO is a TXO received from a party where the wallet trusts that + it will remain mined in its original transaction, such as TXOs created by + the wallet's internal TXO handling. * An untrusted TXO is a TXO received by the wallet that is not trusted. - Wallets can then require that untrusted TXOs need more confirmations before -they become spendable than trusted TXOs. This provides an improved trade-off -between latency on the one hand, and reliability and safety on the other. +they become confirmed-spendable than trusted TXOs. This provides an improved +trade-off between latency on the one hand, and reliability and safety on the +other. Specification From 841119dea9408c3e67519257217e705e09664d11 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 16 Jul 2024 04:35:19 +0100 Subject: [PATCH 17/21] Apply various suggestions from review Co-authored-by: Daira-Emma Hopwood --- zip-0315.rst | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/zip-0315.rst b/zip-0315.rst index 1bf68fee..473db8ab 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -155,7 +155,18 @@ transactions to other transactions. The remainder of this specification assumes a wallet that follows all of these recommendations, except where explicitly noted. -A wallet MAY allow users to disable auto-shielding. +A wallet MAY allow users to disable auto-shielding, auto-migration, +and/or opportunistic migration. If it does so, this need not be via +three independent settings. + +Automatic shielding and automatic/opportunistic migration SHOULD NOT be +applied to inputs where the cost of shielding or migrating them will +exceed their economic value. If these transactions are paying the +ZIP 317 conventional fee [#zip-0317]_, that will be the case if the +amount of the UTXO to be shielded/migrated exceeds the marginal +fee, and cannot be accommodated by an input that would be present +in any case due to padding of the number of inputs from a given +shielded pool. Trusted and untrusted TXOs @@ -177,7 +188,7 @@ Rationale for the given numbers of confirmations '''''''''''''''''''''''''''''''''''''''''''''''' The rationale for choosing three confirmations for trusted TXOs is that -empirically, reorgs are usually less than three blocks. +anecdotally, reorgs are usually less than three blocks. The consequences of attempting to spend a trusted TXO may be less severe in the case of a rollback than the consequences of attempting to spend an untrusted TXO. @@ -243,8 +254,8 @@ Note: the definition of "confirmed-spendable" above ensures that: * if auto-shielding is enabled, transparent funds will be reported in the pending or total balance, but not in the confirmed-spendable balance; -* if the wallet is not synchronized, the confirmed-spendable balance - will be zero. +* if the wallet has not synchronized at least the nullifier set to the + chain tip, the confirmed-spendable balance will be zero. If auto-shielding is disabled, the wallet MAY report shielded and transparent balances separately. If it does so, it MUST make clear @@ -255,12 +266,14 @@ Rationale for reporting of balances ''''''''''''''''''''''''''''''''''' If auto-shielding is disabled, then separate shielded and transparent -balances (and potentially, for expert users, separate shielded balances -per pool) can constitute useful information. If auto-shielding is enabled +balances can constitute useful information. If auto-shielding is enabled then the wallet can and will automatically spend transparent TXOs in order to shield them, and so transparent TXOs need to be presented as pending, not as part of the balance spendable by the user. +Potentially, for expert users, separate shielded balances per pool +could also be useful. + TODO: The specification of balance reporting is intended to give the user visibility into the operation of auto-shielding, opportunistic shielding, and pool migration/usage. (Does the spec satisfy this?) @@ -327,7 +340,7 @@ Kinds of information leakage * Transaction version (v4 or v5, as of NU5) -SHOULD use v5 (unless you're spending Sprout funds). +It is RECOMMENDED to use v5 transactions unless Sprout funds are being spent. * Lock time (rarely used; may be a distinguisher if it is) @@ -657,3 +670,4 @@ References .. [#BCP14] `Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words" `_ .. [#zip-0203] `ZIP 203: Transaction Expiry `_ +.. [#zip-0317] `ZIP 317: Proportional Transfer Fee Mechanism `_ From bbaa637abe6ad0417a825b81fafda51f31521117 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 16 Jul 2024 04:58:05 +0100 Subject: [PATCH 18/21] ZIP 315: Update TODOs and open questions Co-authored-by: Deirdre Connolly Co-authored-by: Daira-Emma Hopwood --- zip-0315.rst | 43 ++++++++++++++++++++++++++++++++----------- 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/zip-0315.rst b/zip-0315.rst index 473db8ab..ac5f999d 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -205,6 +205,10 @@ if and only if all of the following are true in that state: * the TXO is unspent at the wallet's view of the chain tip, and that view is reasonably up-to-date; + + TODO: consider undoing the up-to-date part, as when combined with the + definition of balance below, it causes wallet balance to drop to zero in + the short window between opening and updating the wallet's chain tip view. * the TXO is not committed to be spent in another transaction created by this wallet; and * the wallet has the TXO's spending key (for whatever protocol the TXO uses). @@ -227,7 +231,11 @@ confirmed-spendable in that state. A TXO is *watch-only* if and only if the wallet has its full viewing key (or address in the case of a transparent TXO) but not its spending key. -A wallet MUST NOT attempt to spend a TXO that is not confirmed-spendable. +A wallet MUST NOT attempt to spend a TXO in a user-initiated transaction +that is not confirmed-spendable. + +Open question: what should be specified about which TXOs can be spent +in non-user-initiated transactions? Note: the definition of a TXO includes outputs in mempool transactions that are unconflicted from the perspective of the wallet. @@ -274,9 +282,9 @@ pending, not as part of the balance spendable by the user. Potentially, for expert users, separate shielded balances per pool could also be useful. -TODO: The specification of balance reporting is intended to give the user -visibility into the operation of auto-shielding, opportunistic shielding, -and pool migration/usage. (Does the spec satisfy this?) +Open question: Does the specification of balance reporting give the user +sufficient visibility into the operation of auto-shielding and pool +migration/usage? Reporting of transactions ------------------------- @@ -364,10 +372,7 @@ See `Linkability of transactions or addresses`_. * The fee is dependent on policy, but for a given policy we attempt to make it only depend on other already-leaked metadata. -SHOULD try to create fully shielded transactions where possible. - -Open question: Are we going to describe the policy that zcashd uses? - +TODO: we SHOULD try to create fully shielded transactions where possible. * Numbers of JoinSplits, Spends, Outputs, and Actions @@ -415,6 +420,10 @@ in the same transaction. Ideally, when they are shielded in separate transactions, this should be done in such a way that the timing of those transactions is not linkable. +TODO: move this. Daira-Emma thinks that if we only document leakage rather +than explicitly say in the specification of how to construct transactions +how to mitigate it, then implementors will ignore it. + When spending transparent UTXOs, they SHOULD only be sent to an internal shielded receiver belonging to the wallet. @@ -432,6 +441,8 @@ chain equal to the trusted confirmation depth. That is, if the current block is at height H, the anchor SHOULD reflect the final treestate of the block at height H-3. +TODO: Define a parameter for this depth, and then RECOMMEND a value of 3. + Rationale for anchor selection '''''''''''''''''''''''''''''' @@ -441,6 +452,8 @@ Rationale for anchor selection both for reliability, and because the nullifiers of spent shielded notes will have been revealed, linking this transaction to any future transactions that spend those notes. + + TODO: Reword this given the proposed note management mitigation below. * On the other hand, it is undesirable to choose an anchor too many blocks back, because that prevents more recently received shielded notes from being spent. @@ -453,9 +466,13 @@ Rationale for anchor selection Note selection '''''''''''''' -TODO: consider what we should do when nullifiers are revealed in a transaction -that is then invalidated. Should those notes be prioritized to be spent soon, -or should they be used in a note management tx? +TODO: recommend that when nullifiers are revealed in a transaction that is then +invalidated (or revealed in some other detectable way), they SHOULD be used in +a note management tx to avoid linking the invalidated tx with some arbitrary +future tx. Provided that there are no transparent outputs leaving this wallet's +control, the same arities and transparent outputs SHOULD be preserved, which +also avoids revealing whether the user changed their mind about whether to send +the original semantic transaction. Expiration height @@ -509,6 +526,10 @@ Auto-shielding Wallets SHOULD NOT spend funds from a transparent address to an external address, unless the user gives explicit consent for this on a per-transaction basis. +TODO: Reword this to define the source transparent address as any transparent +address (external, internal, or ephemeral), except in the case of ephemeral as +allowed for implementing ZIP 320. + In order to support this policy, wallets SHOULD implement a system of auto-shielding with the following characteristics: From 75457390e7c36f2421104f1783da4b08729765c9 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 16 Jul 2024 05:01:51 +0100 Subject: [PATCH 19/21] ZIP 315: Allow transparent spends in the context of ZIP 320 There are other parts that will also need updating, but this gets the reference in. --- zip-0315.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/zip-0315.rst b/zip-0315.rst index ac5f999d..6c8027fc 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -425,7 +425,8 @@ than explicitly say in the specification of how to construct transactions how to mitigate it, then implementors will ignore it. When spending transparent UTXOs, they SHOULD only be sent to an internal -shielded receiver belonging to the wallet. +shielded receiver belonging to the wallet, except when they are generated +and spent ephemerally as part of a ZIP 320 transfer [#zip-0320]_. A wallet MUST NOT send funds to a transparent address unless all of the source funds come from shielded pools, and this SHOULD be a single shielded @@ -692,3 +693,4 @@ References .. [#BCP14] `Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words" `_ .. [#zip-0203] `ZIP 203: Transaction Expiry `_ .. [#zip-0317] `ZIP 317: Proportional Transfer Fee Mechanism `_ +.. [#zip-0320] `ZIP 320: Defining an Address Type to which funds can only be sent from Transparent Addresses `_ From c6e71167b8ab2a76e85683131f85e359101cda84 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 16 Jul 2024 05:29:28 +0100 Subject: [PATCH 20/21] ZIP 315: Change state back to Draft We will finish it across subsequent PRs. Co-authored-by: Daira-Emma Hopwood --- zip-0315.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zip-0315.rst b/zip-0315.rst index 6c8027fc..c64c7bd6 100644 --- a/zip-0315.rst +++ b/zip-0315.rst @@ -6,7 +6,7 @@ Jack Grigg Kris Nuttycombe Credits: Francisco Gindre - Status: Proposed + Status: Draft Category: Wallet Discussions-To: Pull-Request: From f8ab117c9f537a06f832a2d244ca1cababc6776d Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 16 Jul 2024 04:31:07 +0000 Subject: [PATCH 21/21] Render manually, while the CI-based rendering is broken --- README.rst | 2 +- index.html | 2 +- zip-0173.html | 5 + zip-0315.html | 407 +++++++++++++++++++++++++++++++++++++++++++++++++- 4 files changed, 410 insertions(+), 6 deletions(-) diff --git a/README.rst b/README.rst index 313b78be..920e58e6 100644 --- a/README.rst +++ b/README.rst @@ -115,7 +115,7 @@ Index of ZIPs 312 Shielded Multisignatures using FROST Reserved 313 Reduce Conventional Transaction Fee to 1000 zatoshis Obsolete 314 Privacy upgrades to the Zcash light client protocol Reserved - 315 Best Practices for Wallet Handling of Multiple Pools Reserved + 315 Best Practices for Wallet Implementations Draft 316 Unified Addresses and Unified Viewing Keys Revision 0: Final, Revision 1: Proposed 317 Proportional Transfer Fee Mechanism Active 318 Associated Payload Encryption Reserved diff --git a/index.html b/index.html index c86c21f9..fb400c4e 100644 --- a/index.html +++ b/index.html @@ -90,7 +90,7 @@ 312 Shielded Multisignatures using FROST Reserved 313 Reduce Conventional Transaction Fee to 1000 zatoshis Obsolete 314 Privacy upgrades to the Zcash light client protocol Reserved - 315 Best Practices for Wallet Handling of Multiple Pools Reserved + 315 Best Practices for Wallet Implementations Draft 316 Unified Addresses and Unified Viewing Keys Revision 0: Final, Revision 1: Proposed 317 Proportional Transfer Fee Mechanism Active 318 Associated Payload Encryption Reserved diff --git a/zip-0173.html b/zip-0173.html index 78829305..52e120c7 100644 --- a/zip-0173.html +++ b/zip-0173.html @@ -193,6 +193,11 @@ def bech32_verify_checksum(hrp, data):
  • In C++
    • +
  • Encoders and decoders written specifically for Zcash: +
      +
    • For C# (Bech32 and Bech32m)
      • +
    +
  • Encoders and decoders written for Bitcoin:
    • For C
      • diff --git a/zip-0315.html b/zip-0315.html index 810c1900..380f111d 100644 --- a/zip-0315.html +++ b/zip-0315.html @@ -1,18 +1,417 @@ - ZIP 315: Best Practices for Wallet Handling of Multiple Pools + ZIP 315: Best Practices for Wallet Implementations 
      ZIP: 315
-Title: Best Practices for Wallet Handling of Multiple Pools
+Title: Best Practices for Wallet Implementations
 Owners: Daira-Emma Hopwood <daira-emma@electriccoin.co>
         Jack Grigg <jack@electriccoin.co>
-Status: Reserved
+        Kris Nuttycombe <kris@electriccoin.co>
+Credits: Francisco Gindre
+Status: Draft
 Category: Wallet
-Discussions-To: <https://github.com/zcash/zips/issues/447>
      +Discussions-To: <https://github.com/zcash/zips/issues/447> +Pull-Request: <https://github.com/zcash/zips/pull/607> +

      Terminology

      +

      The key words "MUST", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", and "MAY" in this document are to be interpreted as described in BCP 14 1 when, and only when, they appear in all capitals.

      +

      The terms below are to be interpreted as follows:

      +
      +
      Auto-shielding
      +
      The process of automatically transferring transparent funds to the most recent shielded pool on receipt.
      +
      Auto-migration
      +
      The process of automatically transferring shielded funds from older pools to the most preferred (usually the most recent) pool on receipt.
      +
      Opportunistic migration
      +
      The process of transferring previously received shielded funds from older pools to the most preferred (usually the most recent) pool as part of a user-initiated transaction.
      +
      Transaction output (TXO)
      +
      An output (transparent coin or shielded note) of a transaction on the consensus block chain or in the mempool visible to a wallet.
      +
      +

      TODO: Add informal definitions of: * known-spendable and confirmed-spendable TXOs; * trusted and untrusted TXOs.

      +

      These should forward-reference the specification section with the formal definitions.

      +
      +

      Motivation

      +

      Zcash wallets have to serve two purposes as a user agent:

      +
        +
      • to manage the economic actions dictated by the user;
        • +
      • to manage the privacy implications of these actions.
        • +
      +

      The goal of this ZIP is to document security and privacy best practices when handling funds and transactions as the user's agent. These best practices are intended to provide as much privacy as is feasible by default, while still enabling the user's desired transactions to occur, and exposing any privacy implications to the user so that they have enough information to assess the consequences of their economic actions.

      +

      This ZIP covers best practices for:

      +
        +
      • what information to display to the user about transactions and balances;
        • +
      • how to handle interactions between the ZIP 32 [#zip-0032]_ key tree and Unified Addresses [#zip-0316]_;
        • +
      • when to use external or internal keys/addresses;
        • +
      • sharing addresses and viewing keys;
        • +
      • sending and receiving funds (including fee selection);
        • +
      • migrating funds between pools.
        • +
      +
      +

      Requirements

      + +

      Prompt accessibility of funds

      +

      Wallets need to take account of two main concerns with respect to accessibility of funds:

      +
        +
      • enabling funds to be spent as quickly as possible to reduce latency;
        • +
      • ensuring that the confirmed-spendable balance is not overestimated, and so can be trusted by the user.
        • +
      +

      These concerns affect the way that balances should be computed, which notes are selected for spending, and how the wallet should ensure that sufficient notes are available to cover multiple spends within a short period.

      +

      To support this we define two kinds of TXOs:

      +
        +
      • A trusted TXO is a TXO received from a party where the wallet trusts that it will remain mined in its original transaction, such as TXOs created by the wallet's internal TXO handling.
        • +
      • An untrusted TXO is a TXO received by the wallet that is not trusted.
        • +
      +

      Wallets can then require that untrusted TXOs need more confirmations before they become confirmed-spendable than trusted TXOs. This provides an improved trade-off between latency on the one hand, and reliability and safety on the other.

      +
      +
      +

      Specification

      +

      Long-term storage of funds

      +

      It is RECOMMENDED that wallets only hold funds as shielded in the long term; that is, if a wallet supports receiving transparent funds (or supports importing a seed from another wallet that might have done so), then it SHOULD auto-shield such funds by default.

      +

      A shielding transaction is always linked to the transparent addresses it spends from. This can cause undesirable information leaks: a) if there are multiple transparent addresses, they will be linked to each

      +
      +

      System Message: ERROR/3 (zip-0315.rst line 136)

      +

      Unexpected indentation.

      +
      +
      +

      other;

      +
      +
      +

      System Message: WARNING/2 (zip-0315.rst line 137)

      +

      Block quote ends without a blank line; unexpected unindent.

      +
      +
        +
      1. a link between the input transparent address(es) and the payment will be visible to the recipient(s), or to any other holder of an Incoming Viewing Key for the destination address(es).
        2. +
      +
      +

      System Message: INFO/1 (zip-0315.rst line 123)

      +

      Enumerated list start value not ordinal-1: "b" (ordinal 2)

      +
      +

      Despite the fact that it is not possible to achieve strong privacy guarantees from any use of transparent addresses, it is undesirable to reveal this additional information. In particular, issue b) motivates ruling out the use of "opportunistic shielding", i.e. shielding previously received transparent funds as part of a user-initiated transaction.

      +

      Wallets SHOULD NOT auto-shield from multiple transparent addresses in the same transaction, and SHOULD NOT use opportunistic shielding.

      +

      Following all of the recommendations in this section improves both collective privacy and the user's individual privacy, by maximizing the size of the note anonymity set over time and minimizing the potential linkage of shielding transactions to other transactions.

      +

      The remainder of this specification assumes a wallet that follows all of these recommendations, except where explicitly noted.

      +

      A wallet MAY allow users to disable auto-shielding, auto-migration, and/or opportunistic migration. If it does so, this need not be via three independent settings.

      +

      Automatic shielding and automatic/opportunistic migration SHOULD NOT be applied to inputs where the cost of shielding or migrating them will exceed their economic value. If these transactions are paying the ZIP 317 conventional fee 3, that will be the case if the amount of the UTXO to be shielded/migrated exceeds the marginal fee, and cannot be accommodated by an input that would be present in any case due to padding of the number of inputs from a given shielded pool.

      +
      +

      Trusted and untrusted TXOs

      +

      A wallet SHOULD treat received TXOs that are outputs of transactions created by the same wallet, as trusted TXOs. Wallets MAY enable users to mark specific external transactions as trusted, allowing their received TXOs also to be classified as trusted TXOs.

      +

      A wallet SHOULD have a policy that is clearly communicated to the user for the number of confirmations needed to spend untrusted and trusted TXOs respectively. The following confirmation policy is RECOMMENDED:

      +
        +
      • 10 confirmations, for untrusted TXOs;
        • +
      • 3 confirmations, for trusted TXOs.
        • +
      +

      Rationale for the given numbers of confirmations

      +

      The rationale for choosing three confirmations for trusted TXOs is that anecdotally, reorgs are usually less than three blocks.

      +

      The consequences of attempting to spend a trusted TXO may be less severe in the case of a rollback than the consequences of attempting to spend an untrusted TXO. The value received from a trusted TXO should always be recoverable, whereas recovering value received from an untrusted TXO may require the user to request that funds are re-sent.

      +
      +
      +

      Categories of TXOs according to spendability

      +

      A TXO is known-spendable, relative to a given block chain and wallet state, if and only if all of the following are true in that state:

      +
        +
      • the TXO is unspent at the wallet's view of the chain tip, and that view is reasonably up-to-date; +

        TODO: consider undoing the up-to-date part, as when combined with the definition of balance below, it causes wallet balance to drop to zero in the short window between opening and updating the wallet's chain tip view.

        +
        • +
      • the TXO is not committed to be spent in another transaction created by this wallet; and
        • +
      • the wallet has the TXO's spending key (for whatever protocol the TXO uses).
        • +
      +

      A TXO is confirmed-spendable, relative to a given block chain and wallet state, if and only if all of the following are true in that state:

      +
        +
      • the wallet is synchronized; and
        • +
      • the TXO is known-spendable; and
        • +
      • either auto-shielding is not active or the TXO is shielded; and
        • +
      • auto-migration from whatever protocol the TXO uses is not active; and
        • +
      • the TXO is trusted and has at least the required confirmations for trusted TXOs, or it is untrusted and has at least the required confirmations for untrusted TXOs.
        • +
      +

      A TXO is unconfirmed-spendable, relative to a given block chain and wallet state, if and only if the TXO is known-spendable but is not confirmed-spendable in that state.

      +

      A TXO is watch-only if and only if the wallet has its full viewing key (or address in the case of a transparent TXO) but not its spending key.

      +

      A wallet MUST NOT attempt to spend a TXO in a user-initiated transaction that is not confirmed-spendable.

      +

      Open question: what should be specified about which TXOs can be spent in non-user-initiated transactions?

      +

      Note: the definition of a TXO includes outputs in mempool transactions that are unconflicted from the perspective of the wallet.

      +
      +

      Reporting of balances

      +

      Wallets SHOULD report:

      +
        +
      • Confirmed-spendable balance.
        • +
      • Pending balance, or total balance.
        • +
      +

      These are calculated as follows:

      +
        +
      • The confirmed-spendable balance is the sum of values of confirmed-spendable TXOs.
        • +
      • The pending balance is the sum of values of unconfirmed-spendable TXOs.
        • +
      • The total balance is the confirmed-spendable balance plus the pending balance.
        • +
      +

      Note: the definition of "confirmed-spendable" above ensures that:

      +
        +
      • if auto-shielding is enabled, transparent funds will be reported in the pending or total balance, but not in the confirmed-spendable balance;
        • +
      • if the wallet has not synchronized at least the nullifier set to the chain tip, the confirmed-spendable balance will be zero.
        • +
      +

      If auto-shielding is disabled, the wallet MAY report shielded and transparent balances separately. If it does so, it MUST make clear whether each reported balance corresponds to a confirmed-spendable, pending, or total subset of funds.

      +

      Rationale for reporting of balances

      +

      If auto-shielding is disabled, then separate shielded and transparent balances can constitute useful information. If auto-shielding is enabled then the wallet can and will automatically spend transparent TXOs in order to shield them, and so transparent TXOs need to be presented as pending, not as part of the balance spendable by the user.

      +

      Potentially, for expert users, separate shielded balances per pool could also be useful.

      +

      Open question: Does the specification of balance reporting give the user sufficient visibility into the operation of auto-shielding and pool migration/usage?

      +
      +
      +

      Reporting of transactions

      +

      If a transaction includes watch-only received TXOs, its watch-only incoming balance MUST be reported separately to any potentially known-spendable balance.

      +

      Incoming transactions

      +

      A transaction is incoming if it contains unconfirmed-spendable TXOs. Incoming transactions SHOULD be reported with their number of confirmations and their balances as described in Reporting of balances.

      +
      +

      Sent transactions

      +

      A transaction is sent if it was either: * created by the wallet, or * detected by using the wallet's outgoing viewing keys to decrypt

      +
      +

      System Message: ERROR/3 (zip-0315.rst line 308)

      +

      Unexpected indentation.

      +
      +
      +

      Sapling or Orchard outputs, or

      +
      +
      +

      System Message: WARNING/2 (zip-0315.rst line 309)

      +

      Block quote ends without a blank line; unexpected unindent.

      +
      +
        +
      • detected as spending a note that was at some time held by the wallet by recognizing that note's nullifier, or
        • +
      • detected as spending a transparent TXO associated with one of the wallet's addresses (including watch-only addresses).
        • +
      +

      Sent transactions SHOULD be reported with their number of confirmations, an estimate of how long until they expire (if they are unmined and have an expiry height), and their balances as described in Reporting of balances.

      +
      +
      +

      Transaction creation

      + +

      Linkability of transactions or addresses

      +
      Motivation for choices reducing linkability
      +

      We want to support creating unlinkable addresses, in order that a user can give different addresses to different counterparties, in such a way that the counterparties (even if they collude) cannot tell that the addresses were provided by the same or distinct users.

      +

      If multiple UTXOs are received at the same transparent address, it is safe to shield them all in the same transaction, because that is not leaking additional information.

      +

      UTXOs received on different transparent receivers SHOULD NOT be shielded in the same transaction. Ideally, when they are shielded in separate transactions, this should be done in such a way that the timing of those transactions is not linkable.

      +

      TODO: move this. Daira-Emma thinks that if we only document leakage rather than explicitly say in the specification of how to construct transactions how to mitigate it, then implementors will ignore it.

      +

      When spending transparent UTXOs, they SHOULD only be sent to an internal shielded receiver belonging to the wallet, except when they are generated and spent ephemerally as part of a ZIP 320 transfer 4.

      +

      A wallet MUST NOT send funds to a transparent address unless all of the source funds come from shielded pools, and this SHOULD be a single shielded pool.

      +

      We want to minimize pool crossing.

      +
      +
      +

      Anchor selection

      +

      A wallet SHOULD choose an anchor a number of blocks back from the head of the chain equal to the trusted confirmation depth. That is, if the current block is at height H, the anchor SHOULD reflect the final treestate of the block at height H-3.

      +

      TODO: Define a parameter for this depth, and then RECOMMEND a value of 3.

      +
      +

      Rationale for anchor selection

      +
        +
      • If the chain rolls back past the block at which the anchor is chosen, then the anchor and the transaction will be invalidated. This is undesirable both for reliability, and because the nullifiers of spent shielded notes will have been revealed, linking this transaction to any future transactions that spend those notes. +

        TODO: Reword this given the proposed note management mitigation below.

        +
        • +
      • On the other hand, it is undesirable to choose an anchor too many blocks back, because that prevents more recently received shielded notes from being spent.
        • +
      • Using a fixed anchor depth (as opposed to a different depth depending on whether or not we are spending trusted shielded notes) avoids leaking information about whether or not the shielded notes we spent were trusted.
        • +
      +
      +

      Note selection

      +

      TODO: recommend that when nullifiers are revealed in a transaction that is then invalidated (or revealed in some other detectable way), they SHOULD be used in a note management tx to avoid linking the invalidated tx with some arbitrary future tx. Provided that there are no transparent outputs leaving this wallet's control, the same arities and transparent outputs SHOULD be preserved, which also avoids revealing whether the user changed their mind about whether to send the original semantic transaction.

      +
      +

      Expiration height

      +

      A wallet SHOULD create transactions using the default expiration height of 40 blocks from the current height, as specified in 2.

      +
      +

      Open question

      +

      How should wallet developers time transactions to avoid linkability?

      +
        +
      • when we roll addresses with transparent components, we have to consider how that could allow linking of shielded components
        • +
      +

      TODO: dusting attack mitigation

      +
      +
      +

      Network-layer privacy

      +
      +

      Viewing keys

      +

      What they are supposed to reveal; see ZIP 310 for Sapling (needs updating for Orchard). https://github.com/zcash/zips/issues/606

      +
      +

      Allowed transfers

      +
        +
      • Sprout -> transparent or Sapling
        • +
      • Sapling -> transparent or Sapling or Orchard
        • +
      • Orchard -> transparent or Sapling or Orchard
        • +
      • if auto-shielding is off: * transparent -> transparent or Sapling or Orchard
        • +
      • if auto-shielding is on: * transparent -> internal Orchard or Sapling
        • +
      +

      Note: wallets MAY further restrict the set of transfers they perform.

      +
      +

      Auto-shielding

      +

      Wallets SHOULD NOT spend funds from a transparent address to an external address, unless the user gives explicit consent for this on a per-transaction basis.

      +

      TODO: Reword this to define the source transparent address as any transparent address (external, internal, or ephemeral), except in the case of ephemeral as allowed for implementing ZIP 320.

      +

      In order to support this policy, wallets SHOULD implement a system of auto-shielding with the following characteristics:

      +

      If auto-shielding functionality is available in a wallet, then users MUST be able to explicitly consent to one of the following possibilities:

      +
        +
      • auto-shielding is always on;
        • +
      • auto-shielding is always off;
        • +
      • the user specifies a policy...
        • +
      +

      Auto-shielding MUST be one of:

      +
        +
      • "must opt in or out" (zcashd will do this -- i.e. refuse to start unless the option is configured), or
        • +
      • always on.
        • +
      +
      +

      Auto-migration

      +
      +

      Information leakage for transfers between pools

      +

      If no auto-migration, if you can satisfy a transfer request to Sapling from your Sapling funds, do so.

      +

      The user's consent is needed to reveal amounts publically (as opposed to revealing them to the holder of a viewing key authorized to see that amount). Therefore, there should be per-transaction opt-in for any transfer that publically reveals amounts on chain.

      +
        +
      • there may be a compatibility issue for amount-revealing cross-pool txns that were previously allowed without opt-in
        • +
      +

      Wallets MUST NOT automatically combine funds across pools to satisfy a transfer (since that could reveal the total funds the user holds in some pool).

      +

      In order to maintain the integrity of IVK guarantees, wallets should not generate unified addresses that contain internal receivers, nor expose internal receivers (such as those used for auto-shielding and change outputs) in any way.

      +

      Open questions:

      +
        +
      • should there be an auto-migration option from Sapling to Orchard?
        • +
      +

      # str4d notes

      +

      If we want to have both automatic and opportunistic shielding, and keep the two indistinguishable, then we can't auto-shield when the transparent balance reaches some threshold (otherwise opportunistic would either never be used, or would be identifiable when it uses the balance below the threshold).

      +

      Instead, a proposition: we define a distribution of "time since last payment to the address" from which we sample the time at which the auto-shielding transaction will be created. This distribution is weighted by the balance in the address, so as more funds accrue, the auto-shielding transaction is more likely to be created.

      +
        +
      • It ensures that all funds will eventually be auto-shielded, while preventing fee-dusting attacks (where dust is sent in order to repeatedly consume fees from the wallet), as the auto-shielding transaction is not directly triggered by payment receipt.
        • +
      • If the user makes a shielding transaction in the meantime, we opportunistically shield, without it being clearly not an auto-shielding transaction.
        • +
      • If a wallet is offline for a long time, then it would likely auto-shield as soon as it finishes syncing. This maybe isn't enough to reveal that the wallet came online, except that it _might_ result in auto-shielding transactions for multiple transparent addresses being created at the same time. So we might want to special-case this?
        • +
      +

      Properties we want from auto-shielding:

      +
        +
      • Auto-shielding transactions MUST NOT shield from multiple transparent receivers in the same transaction. - Doing so would trivially link diversified UAs containing transparent receivers.
        • +
      +

      Properties we want from auto-migration:

      +
        +
      • Receipt of a shielded payment MUST NOT trigger any on-chain behaviour (as that reveals transaction linkability).
        • +
      +

      Both auto-shielding and auto-migration are time-triggered actions, not receipt-triggered actions. An auto-shielding or auto-migration transaction MUST NOT be created as a direct result of a payment being received.

      +

      Both of these are opportunistic: if the user's wallet is making a transaction in which one of these actions would occur anyway, then the wallet takes the opportunity to migrate as much as it would do if it were generating an autoshielding transaction. This both saves on a transaction, and removes the need for any kind of transparent change address within UAs.

      +

      TODO: what pool should change go to?

      +
        +
      • Proposal: the most recent pool already involved in the transaction.
        • +
      +
      +

      Wallet Recovery

      +

      In the case where we are recovering a wallet from a backed-up mnemonic phrase, and not from a wallet.dat, we don't have enough information to figure out what receiver types the user originally used when deriving each UA under an account. We have a similar issue if someone exports a UFVK, derives an address from it, and has a payment sent to the address: zcashd will detect the payment, but has no way to figure out what address it should display in the UI. A wallet could store this information in the memo field of change outputs, but that adds a bunch of coordination to the problem, and assumes ongoing on-chain state storage.

      +
        +
      • If the receiver matches an address that the wallet knows was derived via z_getaddressforaccount, show that UA as expected (matching the receiver types the user selected).
        • +
      • If the receiver matches a UFVK in the wallet, and we are looking it up because we detected a received note in some block, show the UA with the default receiver types that zcashd was using as of that block height (ideally the earliest block height we detect), and cache this for future usage.
        • +
      • For zcashd's current policy of "best and second-best shielded pools, plus transparent pool", that would mean Orchard, Sapling, and transparent for current block heights.
        • +
      • For each release of a wallet, the wallet should specify a set of receiver types and an associated range of block heights during which the wallet will, by default, generate unified addresses using that set of receiver types.
        • +
      • For zcashd we know how the policy evolves because each zcashd release has an approximate release height and End-of-Service height that defines the window.
        • +
      • Subsequent releases of a wallet SHOULD NOT retroactively change their policies for previously defined block height ranges.
        • +
      • If the receiver type for a note received at a given time is not a member of the set of receiver types expected for the range of block heights, the policy corresponding to the nearest block height range that includes that receiver type SHOULD be used.
        • +
      • If the receiver matches a UFVK in the wallet, and we have no information about when this receiver may have been first used, show the UA corresponding to the most recent receiver types policy that includes the receiver's type.
        • +
      • As part of this, we're also going to change the "Sapling receiver to UfvkId" logic to trial-decrypt after trying internal map, so that we will detect all receivers linked to UFVKs in the wallet, not just receivers in addresses generated via z_getaddressforaccount. The internal map lookup is then just an optimisation (and a future refactor to have Orchard do the same is possible, but for now we will only trial-decrypt so we don't need to refactor to access the Rust wallet). TODO: express this in a less zcashd-specific way.
        • +
      +

      TODO: Mention recommendations (not requirements) of receiver types based on settled ('accepted') network upgrades, as defined in §3.3 of the Zcash Protocol Specification, at the time of the release of the wallet.

      +

      TODO: Rationale subsection explaining why earliest block height at detection and the rules/recommendations in place at that block height are preferred over showing different UAs at different heights

      +
      +
      +

      References

      + + + + + + + +
      1Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words"
      + + + + + + + +
      2ZIP 203: Transaction Expiry
      + + + + + + + +
      3ZIP 317: Proportional Transfer Fee Mechanism
      + + + + + + + +
      4ZIP 320: Defining an Address Type to which funds can only be sent from Transparent Addresses
      +
      +
      +
      +

      Docutils System Messages

      +
      +

      System Message: ERROR/3 (zip-0315.rst line 65)

      +

      Too many autonumbered footnote references: only 0 corresponding footnotes available.

      +
      +
      +

      System Message: ERROR/3 (zip-0315.rst line 65) footnote-reference-2

      +

      Unknown target name: "zip-0032".

      +
      +
      +

      System Message: ERROR/3 (zip-0315.rst line 65) footnote-reference-3

      +

      Unknown target name: "zip-0316".

      +
      \ No newline at end of file