# 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. ![](https://i.imgur.com/hiKbXRe.png) 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) ```sequence Google.com-->Ethereum.org: becoming a staker ethereum Ethereum.org-->Launchpad: get staking Launchpad-->deposit cli: create keys deposit cli-->Launchpad: upload key Note left of deposit cli: metamask deposit Launchpad-->Prysm: link to Prysm Note left of Prysm: install Prysm Prysm-->eth1: reg/install client eth1-->Prysm: sync client or get url Note right of Prysm: begin beacon sync Note right of Prysm: ui onboarding Note right of Prysm: wait for activation ``` - 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 ```sequence Ethereum.org-->Prysm:url Note right of Prysm: install Prysm Prysm-->eth1: reg/install client eth1-->Prysm: sync client or get url Note right of Prysm: begin beacon sync Prysm-->Launchpad:link to mainnet/testnet Launchpad-->deposit cli: create keys deposit cli-->Launchpad: upload key Note left of deposit cli: metamask deposit Launchpad-->Prysm: link to Prysm Note right of Prysm: ui onboarding Note right of Prysm: wait for activation ``` url - https://ethereum.org/en/eth2/get-involved/ - cons - perpetuates the term eth2 or ethereum 2.0 when searching get involved ```sequence Note right of cmd: import keys not needed cmd-->webui: validator cli with --web Note right of cmd: create wallet password webui-->onboarding page: localhost:7500 Note left of onboarding page: recover/import wallet Note right of onboarding page: import keys Note right of onboarding page: enter password for keys Note right of onboarding page: enter password for wallet Note right of onboarding page: create ui password onboarding page-->dashboard: enters Note right of dashboard: activation queue ``` UI workflow #### Ideal Entry Point ```sequence Google.com-->Ethereum.org: becoming a staker ethereum Note left of Launchpad: pick your network Note left of Launchpad: mainnet/testnet Ethereum.org-->Launchpad: get staking Launchpad-->Prysm: link to Prysm Note right of Prysm: install Prysm Prysm-->eth1: reg/install client eth1-->Prysm: sync client or get url Note right of Prysm: begin beacon sync Note right of Prysm: begin ui onboarding Note right of Prysm: ui password creation Prysm-->Launchpad: return to create keys Launchpad-->deposit cli: create keys deposit cli-->Launchpad: upload key Note left of Launchpad: metamask deposit Launchpad-->Prysm: import key/enter key password Note left of Prysm: wallet password creation Launchpad-->Prysm: complete ui onboarding Note right of Prysm: wait for activation ``` or ```sequence Note left of Prysm: Choose your network Note left of Prysm: mainnet/testnet Note right of Prysm: install Prysm Prysm-->eth1: reg/install client eth1-->Prysm: sync client or get url Note right of Prysm: begin beacon sync Note right of Prysm: begin ui onboarding Note right of Prysm: ui password creation Prysm-->Launchpad: return to create keys Launchpad-->deposit cli: create keys deposit cli-->Launchpad: upload key Note left of Launchpad: metamask deposit Launchpad-->Prysm: import key/enter key password Note right of Prysm: wallet password creation Launchpad-->Prysm: complete ui onboarding Note right of Prysm: wait for activation ``` ### 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 ![Uploading file..._1wmxcjtqz]() - 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 ![current_onboarding](https://i.imgur.com/sdxFxgn.png) 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](https://docs.google.com/document/d/16nFVUjMSySa2H1hgUyQMTRxa-4sUmwzDohN7Uq3o0Tk/edit#) - 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?