prysm
prysm copied to clipboard
prysmaticlabs
Clarify Differences Between Accounts Password File and Wallet Password File in CLI Help
💎 Issue
Background
In the Validator configuration in our docs portal, we list the parameters from the CLI help text. However, these don't include subcommands nor their associated flags. For example, the validator command has subcommands accounts, wallet, db, and more, but these do not appear in the parameters page. Each of these subcommands has flags that are important to their functionality. Many users rely on pages, such as our parameters page, to understand how to configure Prysm, as it is always up-to-date. However, users were having big problems with configuring the accounts subcommands as they had no reference for its flags visible in our docs portal.
Description
Prysm has a concept of a wallet and an account. An account is essentially a validator key along with some metadata, and a wallet is a directory that holds account plus some metadata, such as a validator slashing protection database.
When importing keys into a Prysm wallet, we ask the user to provide a strong password for their wallet, which is used when opening it and performing other sensitive operations. During the import process, we also ask the user to provide the passwords needed to unlock the individual keystores a user is attempting to import. Through an interactive process, we ask the user to provide the passwords needed to complete the import procedure. Unfortunately, for many users managing their workflows entirely via flags when using Docker configurations or cloud setups, this interactive user experience is not available and the flag documentation is lacking.
To import keystores into Prysm programmatically, a user needs to set the --wallet-password-file and --account-password-file flags. The former is a file containing a plain-text password to encrypt the password and the latter is a file containing a plain-text password to unlock the keystores a user is importing. When viewing the parameters page, only the --wallet-password-file is visible, as --account-password-file is only present in the validator accounts import subcommand, so it is easily missed. We need to clarify the differences between wallet password and account passwords when performing validator account commands, such as importing keys, and make it hard to miss when configuring.
Solutions
Option 1: Expand the documentation parameters page to include subcommands and their associated flags
The docs portal fetches the CLI help text from a server that runs this code. Essentially, it fetches the latest Prysm release, runs and extracts the help text, and returns the string to the caller via an HTTP endpoint. Currently, it cannot handle subcommands. A good resolution would be to add support for subcommands in the code. Then, we would need to show the help text for all the different subcommands in the parameters page to make things clear to the user. This could make for a big page in the docs portal, but it would satisfy a lot of technical users that prefer to read CLI help text than anything else.
Option 2: In the parameters page, clearly mention the limitations that subcommands are not shown. If a user is working with Prysm accounts and the import process, they should visit a specific page regarding Prysm account(s) management
Instead, we could create a page specific for importing accounts that has details on how to do it programmatically, mentioning very clearly the flags required and differences between the wallet and account password files.
Option 1 seems best over the long-run, as it will always be up-to-date and comprehensive. We are marking this as a good first issue for contributors.
I'll give this a try if it's still open. Would the corresponding PR be made in the periphery repository? Very new here :)
hi @jamesthesken thanks for wanting to contribute! Indeed the change would need to be in the periphery repository
Cleaning up the code and adding comments, should be ready for review soon