Managing ETH Validator Keys

Validator key management is an advanced feature set. It is relatively new and may be missing functionality. Please read the docs carefully and use with caution!

Lattice firmware v0.17.0 or greater is required for managing validator keys.

If you are interested in staking on Ethereum, you can now manage validator keys using your Lattice1 device with the Lattice CLI.

Please download the Lattice CLI and connect to your Lattice before continuing. Read the documentation if you are having issues connecting.


Creating New Validator(s)

Your Lattice cannot perform your validator duties - it can only serve as a key management system. In order to participate in the daily activities of Ethereum staking, you must set up a separate staking machine.

If you would like to create one or more validators, you will need following for each one:

  1. An encrypted BLS private key (a.k.a. "keystore"), which must be imported into your consensus client so that it can make signatures for attestations/proposals using your new validator.

  2. An on-chain deposit to the Ethereum Deposit Contract. This transaction must include information about your new validator and sufficient ether to fund it.

Both types of data can be generated with the Lattice CLI using the Export ETH2 Deposit Data command. The user flow for running that command will now be detailed.

1. Defining Export Options

When you run the Export ETH2 Deposit Data command, you will be asked several setup questions:

1. Select Withdrawal Key Type

It is highly recommended you use the default ETH1 option; if you choose to use BLS withdrawal credentials, you will need to update those credentials (for each validator) prior to making any withdrawals, as it is not possible to withdraw ether to a BLS public key on the execution layer.

You will first be asked what type of withdrawal key you would like to use: BLS or ETH1:

  • The default option is to use an ETH1 address; if you select this, the CLI will ask you for a (properly formatted) Ethereum address. Please make sure you have access to the associated private key.

  • If you choose BLS-style credentials, the CLI will automatically derive the withdrawal key for each validator according to EIP2334.

2. Set Deposit Amount

You will now be asked to set a deposit amount. By default this is 32 ETH, which is what you should stick with unless you have a good reason to use a different amount.

3. Set a Starting Validator Index

Finally, you will be asked for a validator index at which to start generating data. Note that this index is the i value in the EIP2334 derivation path. If you have not created any validators with this wallet, you should probably start at the 0 index. If you are coming back to create more, start from where you left off.

4. Select Export Data Type

Now you will be asked about what format of data you want to export. There are two options:

  • JSON file for Ethereum Launchpad - This is the default option and is what you should choose if you are using the Launchpad. The output data will include a JSON file that you can drop directly into your browser. This is recommended for most users.

  • Raw transaction calldata - If you want to create your own deposit transactions and send them to the deposit contract yourself, you should choose this option. The output will be a calldata string for each validator, which you can include in a transaction whose msg.value matches the deposit amount you specified in step 2. This is a more advanced option and isn't recommended for most users.

2. Generating Validator Deposit Data

Now that you have defined your parameters, the CLI will start generating data for your first validator. The CLI will run through the following operations for each validator you want to create:

  1. Export the encrypted validator keystore. This is the BLS12-381 private key of your validator, encrypted and serialized according to EIP2335. This is done automatically. Note that this step takes about 30 seconds for each keystore.

  2. If you selected BLS withdrawal credentials, fetch the withdrawal public key from the Lattice. This is done automatically.

  3. Build some initial deposit data and ask for a signature from the validator's private key. You will need to authorize this signature on your Lattice.

  4. Ask if you want to generate data (i.e. repeat steps 1-3) for the next validator. For example, if you just generated data for validator at index 0, it would ask if you want to now generate data for validator at index 1, and so on until you decline.

3. Exporting Deposit Data

Now that all data has been generated, the CLI will ask you where to save that data on your filesystem. By default, it will be saved to a local directory ./deposit-data. The contents of this directory will include:

  • deposit-X-{timestamp}.json (where X is either -data- or -calldata, depending on selected export type)

  • For each validator index (i): keystore-m_12381_3600_{i}_0_0-{timestamp}.json

Activating your Validator(s)

Now that you have the data in hand, you can start your new validator(s)!

  1. Import all keystore(s) (validator-{i}-{pubkey}-{timestamp}.json) into your consensus client on your validator machine. If you are unsure how to do this, please read the docs for your specific client. Once keystore(s) are imported you should expect to see new validators on your client which are marked as inactive -- this is because you haven't deposited to them yet!

  2. Now you can make your on-chain deposit(s). If you are using the Launchpad, take your deposit-data-{timestamp}.json file and drop it into the browser application. You will be prompted to make one deposit transaction per validator using e.g. MetaMask. If you are instead using raw calldata, form your own transaction(s) and broadcast to the execution layer.

  3. Ensure your deposit transaction(s) succeeded and wait for your new validator(s) to become active (~16-24 hours, usually). Your staking machine should automatically start attesting and, if you're lucky, proposing!

Upgrading Withdrawal Credentials (BLS->ETH1)

Coming soon!

Withdrawing from a Validator

Coming soon!

Exiting a Validator

If you would like to stop performing duties for a validator, you can perform a voluntary exit. Note that this is not the same as a withdrawal.

Unlike the other key management options, voluntary exits are made by your consensus client and do not involve your Lattice. Recall that your consensus client has a keystore for each validator you have added, so it can sign messages with the validator key (but not the withdrawal key).

To perform a voluntary exit, please see your own consensus client's documentation. Here are the related pages for some of the clients:

Last updated