Prysm Web UI Revamp

Objective

To define a set of comprehensive requirements for upgrading the Prysm web interface to version 1, which will resolve the majority of bugs and bad experiences people have encountered in our beta version and will have feature parity with the Prysm CLI. This means that users can have a full experience of running our software by navigating through a website instead of needing to ssh into servers and use command line flags to accomplish their desired goals.

Background

Prysmatic Labs builds open source software for the Ethereum blockchain, which runs the second largest cryptocurrency in the world, Ether. Our flagship project is called Prysm, which is an open source implementation of the Ethereum 2.0 protocol. Anyone around the world can run our software to put 32 ETH at stake and participate in the consensus algorithm of the network to earn rewards. The Ethereum 2.0 network was launched December 1st, 2020, and it currently secures over $6 billion USD worth of value. Our software, Prysm, is what over 50% of the nodes in the network choose to run today.

The users of our software range from enthusiasts that believe in the future of Ethereum and want to stake their ETH to earn rewards and secure the network, professional staking providers and large cryptocurrency exchanges, investors which may not have a very technical background, and deeply technical software engineers. As such, our software needs to meet the needs of these different types of users. For the technical users, dealing with command line flags is normal and the same for advanced cloud deployments. However, many enthusiasts at home would benefit from a graphical user interface to interact with our software and accomplish command tasks.

Current State

Our software is meant to run on different operating systems and computers, so creating a desktop GUI is not the best solution. Instead, we opted for creating a web interface for our platform given it is a common, modern approach towards making software friendlier. We decided on creating an open source web interface hosted at https://github.com/prysmaticlabs.com/prysm-web-ui which is built and included into our software’s binaries. When you run Prysm with the –web option, you can navigate to http://localhost:7500 and see the web interface.

A mock version of the interface is also hosted at https://prysm-web-ui.netlify.app.

The main problem with our web UI today is that it is still in early beta and was not designed by front-end professionals. Moreover, it is limited in its features. If a user needs to perform more advanced actions, they need to SSH or login to the terminal of the computer where the web interface runs and interact with the software via CLI commands. This is unacceptable for users that are not technical.

User Journey

Important Emotions

• Users are nervous on setting up Prysm
  • They already sent a lot of money, any bugs can cause panic or fear
  • Documentation being confusing can be tricky
  • UI bugs can be devastating
• Displaying the right progress bars, information while not-yet-ready
• What happens if I lose my JSON files with deposit information?
• Without knowing the block explorer, users cannot tell the current state of their validator
• Can we emphasize from the web UI that users can always recover their keys from a mnemonic?
• If syncing: don't freak out, here is what's happening. If you lose your keys, here's what you can do

Personas

Personas help us

Individual

• care about a fast reliable way to setup and onboard
• like step by step guides, not a fan of loaded documents
• Personal money is at stake and may be anxious
• Cares about security but usually just goes with the recommended or bare minimum of management
• May not have extremely performant machines
• Likely uses the launch pad websites
• Limited consideration on resiliency
• not operating several hundred keys
• possibly even has less than 32 eth…
• Likely using a single machine
• launches from sh script
• Accessible social media
• Usually not too concerned about backups
• preference to gui, some use cli
• Typically ok with Logs sitting in the console

Institution ( investment/trading i.e. robinhood, big banks, FAANG)

• Likely compiles from a scanned source/image
• needs detailed documentation, not nessassarily handholding
• Cares a lot about making their use of the software more resilient through load balancing and other techniques
• Likely using multiple containers/computers
• Cares a lot of about key generation, key management, and key security
• no real access to social media ( within network)
• Likely will not use the launch site for depositing on mainnet
• could manage hundreds to thousands of keys potentially
• Cares a lot about the APIs that Prysm provides and recoverability features
• Cares about Log management/ centralizing logs
• Cares about professional support

Initial Entry

Major goal(s)

• Safety and comfort for the user
• streamlined and predictable experience

Things to emphasize

• Explain to the user where they are in the process of validating
• Explain to users about the activation process
• Make sure you have your stuff all synced before sending your deposit

Launchpad
a website for making ethereum deposits to become a staker/validator.

Current Entry Point(s)

• cons
  • Throws users into setting up Mainnet instead of Testnet
  • has users deposit before they are synced on eth1/eth2 beacons which may result in user getting penalized on their original stake for not setting up quick enough

url - https://ethereum.org/en/eth2/get-involved/

• cons
  • perpetuates the term eth2 or ethereum 2.0 when searching get involved

UI workflow

Ideal Entry Point

or

Suggested Revisions

The following suggested revisions bring us closer to a streamlined predictable approach to entering the ethereum proof of stake network.
Focus:

• prysm onboarding/beacon chain entry
• individual user experience ( as opposed to institution )

Ethereum.org

• Bring network (mainnet/testnet) selection into the forefront of participation
  • Currently the main page forces users to join the mainnet right away which may bring unintented risk and confusion for new users
  • link users to the correct launch pad based on network selection
  • provide information on how to get initial eth based on network
• Begin migration away from ue of Eth2 term and adjusting page (https://ethereum.org/en/eth2/get-involved/) for participation to reflect
• update get involved website with new prysmatic labs website

Launchpad

• adjust order of launchpad onboarding having users onboard and sync their beacon client ( Prysm ) prior to their deposit.
  • currently this is suggested after the user has deposited their 32 eth
• suggest more clearly an appropriate Eth1 client ( suggestions based on network )
• Link to Beacon node web page ( Prysm ) specific to the network
• provide more information on how to get initial eth for testnet onboarding
• change UI design ( like color ) and possibly some of the risks based on network selection.
• Stretch: provide a launchpad for advanced users that would like to skip the checklist warnings ( suggestion detect if user already went through launchpad once somehow )
  • usecase for advanced users or ones that have been through the process prior

Prysm Documentation

• Prysm documention needs to be more clear on how to interface with the validator
  • API
  • CLI
  • WEB

Prysm UI

• Users should not be prompted for wallet creation if running –web setting on initialization

Onboarding

Onboarding to prysm includes the following:

• prerequisite assumptions on Ethereum
• prerequisite tech proficiency
• prerequisite hardware requirements
• installation of nessesary software
  • eth1 client ( erigon, geth, infura)
  • gpg - mac only
  • beacon client (Prysm Beacon Node)
  • beacon validator ( Prysm Validator - cli,api,ui)
  • crypto wallet software (Metamask)
  • web browser
• Eth1 client sync
• Beacon Node sync
• Deposit Key creation ( has password)
• Get your goerli eth ( if on testnet )
• Upload Deposit Key to Launch pad and consuct Metamask Transaction
• Prysm Wallet creation with key import (has password)
• Prysm UI password creation ( if using UI)
• Prysm Dashboard Entry

Web Features

Wallet

Major goals

• Reducing confusion in terminology and usability

Current flow

• Web UI asks you to pick how to begin (1) import keystores (from the deposit-cli keystores), (2) recover wallet from mnemonic
• It says "create a prysm wallet" which can be confusing
• Each button says "select wallet"
• Import keystores asks users to (1) upload keystores from the deposit-cli, (2) set a web UI password, (3) set a wallet password
• Recover wallet asks you to (1) enter your mnemonic (2) how many "accounts" to recover. Finally, it asks to set a UI password and a wallet password

understanding the Validator queue and Activation of Validator

Double check anything on initialization ( accounts, wallet, etc, public key, etc)

What's the difference between keys and accounts? Maybe

Importing accounts into the wallet is confusing

TODO: Explore better and simple terminology

Auth

Major goals

• Quick and feels safe
• Make the auth flow simple

Current flow

• On login, users have to enter their web UI password to proceed
• Sometimes, password validation is flawed, some long passwords don't work, rules are easy to forget
• It is not clear how to recover a forgotten password, or reset password
• It's annoying that the web password is different than the wallet password

Maybe we can explore a different authentication flow? Perhaps through auth tokens printed via the CLI?

Assumptions

• User has access to fileshare/computer where terminal and ui are running.

Usecases

• User is on work station where terminal and UI are running.
• User is remote and exposes port to public for web login. remote users should not have access to reset password?

Passwords

• When using the deposit-cli, it asks you to set a password to encrypt each keystore and you have a mnemonic to recover them if you ever lose the keystores. The deposit-cli does not have any password requirements
• Prysm allows you to import keystores created from the deposit-cli process. Prysm asks you for the password to unlock those keystores, then Prysm packages them up into its own wallet and asks you to set a new, strong password
• The web UI password is only for the web UI and used for authenticating and receiving JWT tokens for using the web interface
• Prysm password requirements are quite strict: at least 8 chars, 1 uppercase, 1 lowercase, 1 symbol, and 1 number. We can get similar entropy by just asking people to enter 4 different words in plain english
• How to recover passwords? If you lose the Prysm wallet password, you can delete and re-import but you can lose your slashing protection history. If you lose your keystores, you can recover them from a mnemonic, if you lose your web ui password you can delete a file called rpc-password-hash in the wallet directory

Security Features?

• timed tokens
• suggest password reset after 3-5 entries
• what kind of login lock feature should be implemented if someone tries to brute force?
• feature to log ( locally) ips that try to login?

Launching the website via the CLI is not clear, it isn't that clear users need to open localhost:7500. Maybe it can open the default browser automatically? Should we ship a point-and-click application on Mac and Windows that spins up the website itself or a GUI?

TODO: Explore password strength requirements, auth strategies for mixed CLI+web applications, explore not having any passwords except for the deposit-cli password

Techniques to consider

• password based login: your standard flow of creating a password, confirming password,and using password upon login prompt.

  • PROs
    • users are familiar with this process
  • CONs
    • strict password requirements result in users easily forgetting password
    • password resets are unfamiliar and can't be done through the UI due to vulnerability concerns
    • requires signup, if users exposed their port during this process users could have unintentionally exposed their setup to the open internet. a reminder in the cli begins if it notices that the user hasn't signed up despite running the –web flag

• user gets prompted to create webui password in cli prior to running –web

  • PROs
    • user protected from unintended onboarding
    • follows similar ux to ethereum deposit cli
  • CONs
    • forces partial onboarding through cli
    • password resets require restarting validator

• query parameter token based login

  • PROs
    • users don't need to remember a web ui password
  • CONs
    • if your link gets exposed someone else will get access to your dashboard
    • intialization url is printed in console output and may be logged

• token generated in CLI

  • PROs
    • prevents hackers from signing up on your validator before the intended user does
  • CONs
    • user copy pastes from cli which is tedious
    • token is logged in console which may be logged on some log file

Current Authentication Path( masterbranch)

user enters –web to run validator, user goes to web browser localhost:7500, takes user to initialize component ,checks back end intialize api to see if user is signed up/has psrym wallet. redirects to onboarding page if no wallet/no login otherwise redirects to dashboard that redirects to gains and losses page. on onboarding user is instructed to recover a wallet or import keys. import keys , unlock keys, web ui password, wallet password then brings you to dashboard with gains and losses page loaded

issue(s)

• if user goes to a prefixed path such as dashboard without onboarding they won't be redirected to onboarding
• built and packaged production site redirects to login instead of onboarding page if user goes to another url ( without authenticating )
• import keys keeps stacking the same error ( no way to clear either) and doesn't show file selected correctly
• going to Login after signup brings you back to the login component. you can also still access the onboarding page after you already went through it.
• missing redirect logic when bearer token expires
• wallet
• persist token longer if we want to use this, web
• global error handling should account for browser

Intented Authentication Path

query parameter token based

user enters –web to run validator, validator checks if user credentials file exists/ creates one and returns the session token in an updated url such as http:localhost:7500/intialize?token=1312asdda0123
and instructs user to copy that to browser.
app component checks local store(s)

• if session token expiration exists otherwise checks url token parameter to make api call to retrieve session token expiration.
• if both don't exist redirect user to static page that instructs them to copy from cli.
• if url or cache token are invalid then redirect user to static page again to instruct copying link from cli.
• if user clears browser/local cache then user will either need to relogin with url or restart validator –web

once token and token expiration is in local store, redirect to initialize component which will call the intialize api.

• If this will update flag of if the user is signed up and wallet exists.
• if the wallet exists proceed to dashboard, otherwise redirect user to onboarding.

create root route activator function to check items of local store token, token expiration, signed up, and wallet exists.

Maintaining as a validator

Understand changes in my rewards and penalties

Understanding the state of the network ( how many active, any big changes)

Understand current state of my validator ( cpu usage, how my progress is continuing)

If state changes understand What my options are and consequences are

Understand my duties as a validator, and what actions my validator is taking

Management of accounts, wallets, keys etc

Withdraw and Exit

Understand the current state of my Account

Understand why I am exiting ( voluntary vs involuntary)

Understand when I will exit

Understand when I will be given remaining funds

Understand the consequences of exiting/ reEntry

Requirements

• Redesign Proposal
• TODO:

Client/Server Architecture

The components of the Prysm project are as follows:

• beacon-node: a typical node in a blockchain vocabulary, meaning a server that connects to others via p2p network discovery, can download blocks, process state transitions, and provide an RPC API for interacting with it. We use gRPC and support JSON over HTTP using REST API definitions
• validator-client: another process which connects to a beacon-node via gRPC. This process has access to a user’s blockchain wallet, able to receive messages from the beacon-node, cryptographically sign them, and send them back to the beacon-node for propagation to the network. The validator-client exposes a gRPC and JSON REST API. The validator-client also embeds a built-version of the web UI which it hosts on port :7500 by default
• web-ui: the web UI is built and embedded into the validator client. Users can launch prysm validator --web and access the angular website on localhost:7500. This website interacts with the validator by making API requests to /api/v2/validator

That is, the architecture looks like:

• beacon-node <-> validator-client <-> web-ui

Development Environment

Installing and Building the Web UI

The development environment to develop the web-ui is simply to clone https://github.com/prysmaticlabs/prysm-web-ui, npm install, and run with npm start. The web interface uses a mock HTTP interceptor if running in development mode which mocks all API responses to simulate the real, functioning application.

Tests and Lint

npm test runs all the angular unit tests
npm run test:watch runs tests in watch mode

Running in Staging Mode

In order to run the web-ui with a real backend for staging tests, you will need to run a beacon-node and validator as processes on localhost first. See our instructions on how to install Prysm here: https://docs.prylabs.network/docs/install/install-with-script

In short, you can run the beacon node with:

./prysm.sh beacon-node --http-web3provider=https://goerli.prylabs.network --pyrmont

And the validator client in a separate terminal window with:

./prysm.sh validator --web

Then, to run the web-ui in staging mode, edit https://github.com/prysmaticlabs/prysm-web-ui/blob/baafe405c985ed86b6d314ba39252b69bf86831e/src/app/app.module.ts#L38 to comment out the mock interceptor. Then, the web UI should be connecting to your running processes.

Development Workflow

We use Github for Prysm and the Prysm Web UI here: https://github.com/prysmaticlabs/prysm and https://github.com/prysmaticlabs/prysm-web-ui. For all our project tracking. For the web-ui, we can follow the process of:

Creating a tracking issue for a major feature, for example:

[Tracking] - Implement Wallet Recover”

Creating a feature branch, such as feature/recover-wallet
The tracking issue can have a checklist of items that need to be completed for the feature to be marked as closed. An example is:

[x] Implement the service API definitions for the feature
[x] Define the components with tests
[x] Define custom validators for the form

For organization and easy review, we recommend keeping pull requests relatively small (200-400 lines of real changes, not including generated code or tests). Pull request descriptions and titles should have full context needed for review

Bad: “Implement feature”, Good: “Define Angular Services for Wallet Recover”
PR descriptions should have context about what it is you are resolving. Example of a good PR description: https://github.com/prysmaticlabs/prysm/pull/8508

Work Estimates

Future considerations

internationalization for cli/ui?