Participation Key Management

Algorand provides a set of keys for voting and proposing blocks separate from account spending keys. These are called participation keys (sometimes referred to as partkeys). At a high-level, participation keys are a specialized set of keys located on a single node. Once this participation key set is associated with an account, the account has the ability to participate in consensus.

Read more about how Participation Keys function in the Algorand Consensus Protocol.

Note

• The account’s private spending key does not need to be on the node to generate a participation key. Technically, anyone can generate a participation key for a particular account, but only the private spending key of the account can authorize the transaction that would register the account to go online with a particular participation key. This distinction allows you to keep private keys in cold storage.
• For security, the individual keys for each round are deleted from the key file as each round is completed. It is critical for the safety of the Algorand blockchain to avoid storing backups of participation key files that have been registered for an account.
• The limit to the range you can specify for a partkey validity period is 2^24 - 1 (16,777,215). For security, it is recommended that the range does not exceed 3,000,000 rounds.

Generating Participation Keys With NodeKit

To generate your participation key with NodeKit, you can use our comprehensive guide that you can find here:

Nodekit Quick Start Generating Participation Keys

Generating Participation Keys With goal

To generate a participation key, use the goal account addpartkey command on the node where the participation key will reside. This command takes the address of the participating account, a range of rounds, and an optional key dilution parameter. It then generates a VRF key pair and, using optimizations, generates a set of single-round voting keys for each round of the range specified. The VRF private key is what is passed into the VRF to determine if you are selected to propose or vote on a block in any given round.

$ goal account addpartkey -a <address-of-participating-account> --roundFirstValid=<partkey-first-round> --roundLastValid=<partkey-last-round>
Participation key generation successful

This creates a participation key on the node. You can use the -o flag to specify a different location in the case where you will eventually transfer your key to a different node to construct the keyreg transaction.

Tip

To optimize storage, the Key Dilution parameter defaults to the square root of the participation period length but this can be overridden with the flag --keyDilution. The Key Dilution determines how many ephemeral keys will be stored on an algorand node, as they are generated in batches. For example, if your participation period is set to 3,000,000 rounds, a batch of 1,732 ephemeral keys will be generated upfront, with additional batches getting generated after each set is used.

Add Participation Key

If you chose to save the participation key and now want to add it to the server, you can use the following command to add the partkey file to the node.

$ goal account installpartkey --partkey ALICE...VWXYZ.0.30000.partkey --delete-input

Check that the Key Exists

The goal account listpartkeys command will check for any participation keys that live on the node and display pertinent information about them.

$ goal account listpartkeys
Registered  Account      ParticipationID   Last Used  First round  Last round
yes         TUQ4...NLQQ  GOWHR456...              27            0     3000000

The output above is an example of goal account listpartkeys run from a particular node. It displays all partkeys and whether or not each key has been registered, the filename of the participation key, the first and last rounds of validity for the partkey, the parent address (i.e. the address of the participating account) and the first key. The first key refers to the key batch and the index in that batch (<key-batch>.<index>) of the latest key that has not been deleted. This is useful in verifying that your node is participating (i.e. the batch should continue to increment as keys are deleted). It can also help ensure that you don’t store extra copies of registered participation keys that have past round keys intact.

Caution

It is okay to have multiple participation keys on a single node. However, if you generate multiple participation keys for the same account with overlapping rounds make sure you are aware of which one is the active one. It is recommended that you only keep one key per account - the active one - except during partkey renewal when you switch from the old key to the new key. Renewing participation keys is discussed in detail in the Renew Participation Keys section.

View Participation Key Info

Use goal account partkeyinfo to dump all the information about each participation key that lives on the node. This information is used to generate the online key registration transaction described in the next section.

$ goal account partkeyinfo
Dumping participation key info from /opt/data...

Participation ID:          GOWHR456IK3LPU5KIJ66CRDLZM55MYV2OGNW7QTZYF5RNZEVS33A
Parent address:            TUQ4HOIR3G5Z3BZUN2W2XTWVJ3AUUME4OKLINJFAGKBO4Y76L4UT5WNLQQ
Last vote round:           11
Last block proposal round: 12
Effective first round:     1
Effective last round:      3000000
First round:               0
Last round:                3000000
Key dilution:              10000
Selection key:             l6MsaTt7AiCAdG+69LG/wjaprsI1vImZuGN6gQ1jS88=
Voting key:                Rleu99r3UqlwuuhaxCTrTQUuq1C9qk5uJd2WQQEG+6U=

Above is the example output from a particular node. Use these values to create the key registration transaction that will place the account online.

Renew Participation Keys

The process of renewing a participation key is simply creating a new participation key and registering it online before the previous key expires.

You can renew a participation key anytime before it expires, and we recommend to do it at least two weeks (about 268,800 rounds) in advance so as not to risk having an account marked as online that is not participating.

The validity ranges of participation keys can overlap. For any account, at any time, at most one participation key is registered, namely the one included in the latest online key registration transaction for this account.

Step-by-Step

• Create a new participation key with a first voting round that is less than the last voting round of the current participation key. It should leave enough time to carry out this whole process (e.g. 40,000 rounds).
• Once the network reaches the first voting round for the new key, submit an online key registration transaction for the new participation key.
• Wait at least 320 rounds to validate that the node is participating.
• Once participation is confirmed, it is safe to delete the old participation key.

Example key rotation window

Note

goal supplies single commands to renew all participation keys on a node (goal account renewallpartkeys) or renew the participation key for a specific account (goal account renewpartkey). It is recommended that you only use these for testing purposes or for very low-stake accounts, since both of them require your private keys to be online.

Removing Old Keys

When a participation key is no longer in use, you can remove it by running the following goal command with the participation ID of the key you want to remove.

$ goal account deletepartkey --partkeyid IWBP2447JQIT54XWOZ7XKWOBVITS2AEIBOEZXDACX5Q6DZ4Z7VHA

Make sure to identify the correct key (i.e. make sure it is not the currently registered key) before deleting.