Describe Network Upgrade activation logic in the UX quite early to give users sufficient heads up.

[nathan-at-least]

We just decided to commit to block height as the activation trigger, see https://github.com/zcash/zcash/issues/2286#issuecomment-301625612. Therefore, this ticket becomes rather simple: new releases will say "Notice, a protocol upgrade is scheduled at block height $HEIGHT. This software will enable new consensus rules at that height."

[daira]

Don't they need the heads-up earlier than the release that implements the new rules? We can say which release that will be in advance, even though we won't have the block height.

[nathan-at-least]

One suggestion is to refuse to create new transactions as we get near the activation height, with an immediate error message to users that gives them clear instructions such as "please wait $X hours then reissue your request."

[nathan-at-least]

Note, it's important for this to integrate with #2738.

[lindanlee]

I'll propose something that is more sympathetic to user needs, but I know would require more technical work. I'm not saying that we need to do this, but I think it can help frame the problem.

The best case scenario is that when a hard fork happens, the user doesn't need to take any additional actions (reduce workload), doesn't need to translate what the message means (reduce cognitive load) and they are informed about how it will affect them. My proposed solution is:

• informing users in advance, which helps manage expectations (as suggested above!). Translating any technical information, telling them what happens, and telling them what they need to do, if any,is helpful, i.e.

"In about 3 weeks, at block height $H, transactions may be delayed for a couple hours while we upgrade. There is nothing you need to do at this time."

• informing users in context is an important followup (and great for also suggesting it above, intuition is correct!). I suggest only showing a message to users who try to make a transaction during the time window affected, and not bothering someone who doesn't try to make a transaction at the time. It would be ideal if the user didn't need to retry the transaction and put the burden of waiting and remembering on them. We should automatically stage the transaction and retry at a later time, informing that this is happening, and sending them a notification after the transaction does go through at the later time. This does require wallets to implement such behavior, though. My ideal solution is to show them a message like,

"We're currently upgrading our protocol. This is for all of Zcash, and not specific to your wallet or exchange. Your transaction will be sent after the upgrade is complete."

and

"Your transaction for $ZEC to $ADDR has been sent."

• I don't know what to do if someone urgently wants to send funds specifically during the window, and they get angry. A nice message or explanation would do some good, but I don't know what that is.

I'm really happy that a discussion like this is happening--great UX is like great customer service, and Zcash is really paying attention to it!

[lindanlee]

@str4d and I met today, and this is the result of our meeting.

We need to inform users of three things: 1) technical information and updates, "an upgrade is happening in three weeks, affecting everyone" 2) the specifics of the upgrade, "this upgrade does this and that and that" 3) how wallets/other GUIs present it to the users,-- how it can be consistent across wallets (everyone uses popups, or something?), and how it can be consistent with Zcash's messaging

We need to do three things: 1) information about the fact that an upgrade is coming: height and release details 2) informing people when the upgrade is happening and how it affects them 3) informing people when the upgrade is complete and what is different

Solutions:

• A guide for how to handle upgrades: timing, interface elements, upgrade messaging, etc.
• RPC call that returns a list of upgrades, associated messages, and statuses that should be displayed to users. This can be something that allows us to message our users directly, but the GUI wallets can present it in the native UI.
• Expose the data in the metrics UI, debug.log, -alertnotify to reach any of the users that may be listening to any of those channels.
• Reach out to wallet devs in a consistent manner, showing them the guide + appropriate calls/etc.
• Push out the information on the blog, forum, GitHub, and other places that we have a presence.

Remaining considerations:

• what do we do about translating strings? --> maybe we can link to a blog post, which can be translated into different languages.
• how do we get the wallets/GUIs to implement thing in a consistent manner? --> giving them guidance and making decisions for them will make it easier for them to implement what we suggest.

[lindanlee]

From slack, by @str4d:

My expectation though is that the RPC call will return something like:

  {
    "upgradeid": "A",
    "status": "complete",
    "height": X,
    "info": "https://z.cash/foobar", // Or
    "info": "Text string about the upgrade",
  },
  {
    "upgradeid": "B",
    "status": "in-progress",
    "height": Y,
    "info": "https://z.cash/upgrade/B", // Or
    "info": "Text string about the upgrade",
  },
  {
    "upgradeid": "C",
    "status": "pending",
    "height": Z,
    "info": "https://z.cash/upgrade/C", // Or
    "info": "Text string about the upgrade",
  } 

where pending could just be the initial status shown when the upgrade info is added as the user upgrades to 1.1.0, or could be a status set e.g. 3 weeks out; in-progress would be during the upgrade itself (from maybe a few blocks before to some window afterwards); and complete is historic.

We could have other statuses before the upgrade height too, depending on how much granularity @linda thinks is useful. (note: I think too much would be complicated, and we should go for a minimal set of statuses. We definitely need a before, during, and after.)

The idea being that then the user-presented messaging changes with status.

[arcalinea]

@lindanlee I just opened a sub-ticket to spec out this RPC call, since this is a broad UX ticket and there are other actionable pieces in here, like metrics screen improvements and documentation as well

[lindanlee]

@nathan-at-least says:

We should have a user-facing FAQ on what network upgrades are, so that we can explain why network upgrades are happening. This document should be quite general, and should explain network upgrades in general, not just explain NU0. It should also anticipate the fact that there could be different factions that are fighting for different network upgrades.

We're trying to choose features and NU0 to make future upgrades safer, and a lot of those features are user-facing. Maybe writing this guide would be an easier first step than implementing all the specifics.

[lindanlee]

An idea @nathan-at-least, @ioptio, and I all like is to advise that wallets and exchanges halt transactions a couple hours before the upgrade, and inform users that the upgrade is happening and that it's down. That's a good in-between "just notify users that an upgrade is happening and they have to be careful, remember when it happens, etc." and "take away all the work by informing them of the update and then automate everything to proceed as normal afterward."

[daira]

Note that we already have an alert system. That system doesn't have particularly good surfacing of messages to users, but if we improve that then it would be nice for the improvements to also apply to alerts.

[str4d]

In 1.0.15 we added RPC interfaces for wallets to expose this information in their GUIs. We still need to add this information to the metrics screen.

[daira]

I think it's ok if this ends up being less polished for Overwinter than for subsequent upgrades. But note that, to my knowledge, there are no current GUI wallets that expose the information provided by the RPC.