ZIP 315: Address review comments or add them as TODOs.

Co-authored-by: Deirdre Connolly <deirdre@zfnd.org>
Signed-off-by: Daira Hopwood <daira@jacaranda.org>

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
 ==========