ZIP 315: WIP from meeting.

Signed-off-by: Daira Hopwood <daira@jacaranda.org>

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