Validator keys for Gnosis staking - how to generate and deposit keystores?

Complete guide to generate and deposit validator keys for Gnosis staking.

Disclaimer

This guide is for informational purposes only. The author nor website owner does not guarantee accuracy of the information in this guide and is not responsible for any damages or losses incurred by following the guide.

What are validator keys (keystores) in Gnosis?

Validation keys, also known as validator keys or kezstores, are essential cryptographic keys used in Gnosis’s Proof of Stake (PoS) mechanism. These keys are associated with validators, which are entities responsible for proposing and attesting blocks on the Ethereum blockchain.

Key Points About Validation Keys and Validators:

  1. Registration and Activation

    Validators are registered and activated on the network after depositing the required stake. This deposit acts as collateral to ensure honest behavior.

  2. Staking Mechanism

    The deposited funds are not sent directly to the validator but are instead locked in a smart contract associated with the validator's public key. This smart contract enforces the rules of staking, such as slashing penalties for misbehavior.

  3. Penalties and Rewards

    Validators can lose part of their stake (slashing) if they act maliciously or fail to perform their duties. Conversely, they earn rewards for participating honestly in block proposals and attestations.

  4. Withdrawal Process

    When a validator exits the network, the funds locked in the smart contract are automatically sent to the withdrawal wallet specified during the generation of the validation keys.

By securely managing their validation keys, validators can ensure their participation in the network is both safe and compliant with Gnosis’s PoS protocol.

Note: This page is under construction.

Generate validator keys

Validator keys and their associated deposit data are generated securely on an offline computer to minimize the risk of key compromise. The process is based on a seed phrase and typically involves the following steps:

  • Prepare an Offline Environment

    Use a dedicated offline computer or operating system to ensure that the keys are generated in a secure and isolated environment.

    • You can e.g. install a dedicated Ubuntu Desktop on USB stick and use it to load Ubuntu Desktop on any PC unplagged to the internet and other drivers
    • You can look also at Tails OS.

  • Prepare a Key Generation Tool on the Offline PC

    1. Download the Key generation tool for OS you use on your offline PC
    2. Uncompress the downloaded client
    3. Move uncompressed client to your offline PC. You can use a flash disc to do so.
    4. What will be withdrawal address for your validators? Note: copy this address to your offline PC you will be generating keystores on as well.
    5. On the Offline PC, open terminal or command line from a directory you have the deposit tool in (or use an relative or absolute path to the deposit cli) to run preferred command below:

This option creates a new mnemonic and generates keystores based on that.

./deposit new-mnemonic --eth1_withdrawal_address 0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The output will be something like:

Please choose your language ['1. العربية', '2. ελληνικά', '3. English', '4. Français', '5. Bahasa melayu', '6. Italiano', '7. 日本語', '8. 한국어', '9. Português do Brasil', '10. român', '11. Türkçe', '12. 简体中文']: [English]:

Choose preferred langage or press enter to confirm default option English

Now the tool should print a seed (24 words). Carefully write them down on a paper and keep it carefully. This is a recovery seed based on which you can regenerate keystores if anything goes wrong in a time (e.g. your node gets broke).

After that, you will be asked to write the words back to client to verify you have them, see below

This option requires placement of a mnemonic and generates keystores based on that.

./deposit existing-mnemonic --eth1_withdrawal_address 0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The output will be something like below:

Please choose your language ['1. العربية', '2. ελληνικά', '3. English', '4. Français', '5. Bahasa melayu', '6. Italiano', '7. 日本語', '8. 한국어', '9. Português do Brasil', '10. român', '11. Türkçe', '12. 简体中文']: [English]:

Choose preferred langage or press enter to confirm default option English

Next, it will require the seed mnemonic, se below:

Please enter your mnemonic separated by spaces (" "). Note: you only need to enter the first 4 letters of each word if you'd prefer.:

Write your seed and press enter.

  • Next, it will require starting index, see Enter the index (key number) you wish to start generating more keys from. For example, if you've generated 4 keys in the past, you'd enter 4 here. [0]:

    There is always the same validator pubid for a combination of the same seed + validator index. This is the way you can regenerate lost keystores. Also, you can generate othe keystores (with higher index) to generate more keystores from the same seed.

  • After setting starting index, press enter and repeat it for confirmation, see 
    Please repeat the index to confirm: 0
  • Next, it will ask how many validators you wish to run, see: 
    Please choose how many new validators you wish to run: 1
  • Next, it will ask you for the chain, see: 
    Please choose the (mainnet or testnet) network/chain name ['mainnet', 'ropsten', 'goerli', 'kiln', 'sepolia', 'gnosis', 'chiado']:  [gnosis]:

    Confirm the option

  • Next, you will have to set a password that will be encrypt the keystores. You will need this password later for decrypting the keystores on registering them to consensus validator client. 
    Create a password that secures your validator keystore(s). You will need to re-enter this to decrypt them when you setup your Ethereum validators.:

    Then you will have to repeate it yet, see

    Repeat your keystore password for confirmation:
  • If anything went well, keystores generation is preocessed with following output (output below is for a sample of generating only one validator key): 
                                              
                  #####     #####                                 
                ##     #####     ##                               
    ###         ##   #######     #########################        
    ##  ##      #####               ##                   ##       
    ##     #####                 ##                       ##      
    ##     ##                     ##                      ###     
   ########                        ##                     ####    
   ##        ##   ###         #####                       #####   
   #                          ##                         # #####  
   #                            #                        #  ##### 
   ##                             ##                    ##        
   ##                              ##                   ##        
   ##             ###              ##                   ##        
   ###############                 ##                   ##        
   ###               ##                                 ##        
      #############################                    ##         
                     ##                             ###           
                     #######     #################     ###        
                     ##   ## ##        ##   ##    ###             
                     ##############          #############        
                                                                  
Creating your keys.
Creating your keystores:	  [####################################]  1/1
Verifying your keystores:	  [####################################]  1/1
Verifying your deposits:	  [####################################]  1/1

Success!

  • The output is a folder including a bunch of files:

    • validator_key.json that represents each validator. Each validator has an unique pubid. These files are registered to consensus validator client on the staking server.
    • deposit_keys.json that aggregates information about all generated validator_key.json files. This file is used for depositing through the web interface.

    Each file name ends with a series of numbers, known as a timestamp, which represents the time the file was generated. If you check this timestamp in a human-readable format in CET (Central European Time), you can input these numbers into a timestamp converter or tool below.

    Timestamp: → Mon Jan 27 2025 17:28:30 GMT+0100 (středoevropský standardní čas)

    Copy the output folder to flash disk for option move them from your offline machine to your staking node and PC you will be depositing from.

Note: This page is under construction.

Deposit validator keys

The funding of keys (deposit) can be done through the website https://deposit.gnosischain.com/.. Funds should be deposited only after the keys have been activated on the server.

The deposit process and verification details can be found at https://docs.gnosischain.com/node/guide/validator/deposit. It is possible to deposit for a maximum of 128 validators in a single transaction. The deposit_data-... file is uploaded to the web interface. If the file contains instructions for more than 128 validators, it must be split into smaller parts.

How to Verify in SafeWallet

Partial files such as deposit_data_1.json... are uploaded through the website https://deposit.gnosischain.com/. Each file is uploaded individually, and after successful validation, the deposit can be completed using either Metamask or Wallet Connect.

Pre-upload Check

Before uploading, always open the specific file and use search to verify the filled-in "withdrawal credentials", which should point to the withdrawal wallet. In the file, the x at the beginning of the address is replaced by a series of ones and zeros – this is normal. Use the search box (Ctrl+F) to find the wallet address, but input it without the first two characters.

When Sending the Transaction via Web

The following must be checked:

  1. Withdrawal Addresses in the Deposit File
    • Open the deposit file in a text editor and verify the withdrawal addresses.
    • Note the number of objects (see point 5). Keep in mind that the address lacks the human-readable 0x prefix.
  2. Transaction Method is transferAndCall
  3. Interact With GNOSIS GNO Token Contract Address 0x9C58BAcC331c9aa871AFD802DB6379a98e80CEdb (= you sending GNO token)
  4. Deposit Contract Address (_to(address)) is Gnosis: GBC Deposit 0x0B98057eA310F4d31F2a452B414647007d1645d9
  5. Number of Validators (_value(uint256)) corresponds with sending GNO amount
  6. The Hex data contain the withdrawal wallet and validator pubkeys. You can use (Command/Ctrl + F) to search and locate strings in the hex data. Note: Hex format does not include 0x prefix.

How to Verify in Metamask

  • Check Interact With Contract Address is 0x9C58BAcC331c9aa871AFD802DB6379a98e80CEdb (= you sending GNO token)

    To speed up verification for repeating deposits, you save this address in Metamask under a custom name, e.g., "GNO Deposit."

  • Check Transaction Type is transferAndCall
  • Switch to the Hex Tab and use search (Command/Ctrl + F) to locate the following strings in the hex data. Verify Deposit Contract Address (_to(address)) is Gnosis: GBC Deposit 0x0B98057eA310F4d31F2a452B414647007d1645d9, withdrawal wallet and pubids.