ZIP: issue guidance on UI for confirmations and spendability

[zookozcash]

Write a document for makers of wallet UIs:

You MUST NOT show an incoming payment as having the same appearance as a confirmed incoming payment until the number of confirmations of the incoming payment exceeds 10.

For incoming payments with fewer than 10 confirmations, they MUST either be omitted entirely from the UI (not shown to the user) or shown but clearly marked as unconfirmed.

It is RECOMMENDED that unconfirmed incoming payments be shown with the string '(unconfirmed)' after it, and in a greyed-out font color.

You MUST NOT show the wallet balance as reflecting the additional funds from unconfirmed payments. You MAY show a second wallet balance, for example:

BALANCE: 621.14321 ZEC (+55.012 ZEC unconfirmed)

or

BALANCE: 621.14321 ZEC (676.15521 unconfirmed)

Showing the number of confirmations of an incoming payment is not sufficient to satisfy these requirements. You MUST also visually and/or textually mark incoming payments with < 10 confirmations as unconfirmed. For example:

date time amount confirmations ---- ---- ------ ------------ 2017-03-28 16:20 UTC-4 173.13 730 2017-03-29 16:00 UTC-4 200.30 155 2017-03-29 20:00 UTC-4 100.00 59 2017-03-29 22:10 UTC-4 255.00 (unconfirmed) 7

[daira]

That sounds like it should be a ZIP.

[daira]

@zookozcash wrote:

... until the number of confirmations of the incoming payment exceeds 10.

You mean "is at least 10".

[tromer]

What about insufficiently-confirmed change to self? The user is guaranteed to "own" that much ZEC at that point in time (whether or not the transaction ends on the chain; assuming the user didn't double-spend), but the change isn't immediately available for spendable. See zcash/zcash#1962.

[daira]

Note that as we've been using the word "change", it includes interior change of a chained JoinSplit. Such change is immediately spendable within the JoinSplit. It's "exterior change" that isn't immediately available for spending.

(For Sapling "interior change" does not involve chaining but the effect is the same, and "exterior change" is still not immediately available for spending.)

[nathan-at-least]

cc'ing @ioptio since she's working on user education and this dovetails with that, and we were just recently having a conversation about the need for this kind of document.

One problem for me is that I don't know if 10 should be the number or not. Let's go with 10 (which is the number I advocated in https://github.com/zcash/zcash/issues/952#issuecomment-286514993 recently), but we need to be able to update that later and have participating UI creators know about the change.

Why don't we know if 10 is acceptable? Well, for one thing because we haven't done good empirical investigation of the distribution of re-org lengths. That's in zcash/zcash#2004 which has been planned for 'the upcoming milestone' since January and keeps getting bumped back. I'll work with @ageis and others to keep that from slipping perpetually.

[daira]

If we want to be able to update this recommendation for all external wallets, then we should have an RPC call (or field in the response of an existing call) that returns the value.

Note that the best analysis available shows that the safe value for this parameter is not a constant. It depends on how long recent blocks have actually taken to find: https://arxiv.org/abs/1702.02867 An RPC call could take into account this analysis by returning how many more confirmations are expected to be needed on top of a given block, for a given acceptable risk.