diff --git a/docs/run-a-node/participate/generate_keys.md b/docs/run-a-node/participate/generate_keys.md index db3c5688..d1d3d4bc 100644 --- a/docs/run-a-node/participate/generate_keys.md +++ b/docs/run-a-node/participate/generate_keys.md @@ -9,25 +9,30 @@ _[Read more about how Participation Keys function in the Algorand Consensus Prot - 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. -!!! warning - All the `goal` commands in this page must be run under the user that owns the `data` directory and runs `algod`. They should never run under the user `root`, as this may compromise permissions in the `data` folder. For example, with a default installation of the Debian package, `goal account ...` should be replaced by `sudo -u algorand -E goal account ...`. - # Generate the participation key with `goal` To generate a participation key, use the [`goal account addpartkey`](../../../clis/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](../../../get-details/algorand_consensus#verifiable-random-function) 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" ```zsh - $ goal account addpartkey -a --roundFirstValid= --roundLastValid= --keyDilution= + $ goal account addpartkey -a --roundFirstValid= --roundLastValid= Participation key generation successful ``` -This creates a participation key in the ledger directory of the node, which is where it should ultimately live. Use the `-o` flag to specify a different directory in the case where you will eventually transfer your key to a different node's ledger directory. +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. It 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. + 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 -# Check that the key exists in the node's ledger directory +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. + +```bash +$ goal account installpartkey --partkey ALICE...VWXYZ.0.30000.partkey --delete-input +``` + +# Check that the key exists The [`goal account listpartkeys`](../../../clis/goal/account/listpartkeys) command will check for any participation keys that live on the node and display pertinent information about them. @@ -41,8 +46,6 @@ The [`goal account listpartkeys`](../../../clis/goal/account/listpartkeys) comma 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 (`.`) 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. -If the key you generated does not show up, check that it was correctly placed in the ledger directory `ls $ALGORAND_DATA// | grep `. If not, move it there and run this command again to confirm. - !!! warning 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](./renew.md) section. diff --git a/docs/run-a-node/participate/online.md b/docs/run-a-node/participate/online.md index a29b0b08..f3b6c48d 100644 --- a/docs/run-a-node/participate/online.md +++ b/docs/run-a-node/participate/online.md @@ -151,7 +151,7 @@ Use the appropriate [authorization method](../../../get-details/transactions/sig !!! tip It is recommended that you authorize the transaction offline to protect the security of your private keys, especially for high-value participating accounts. -[Verify that the participation key is in the node's ledger directory](../generate_keys#check-that-the-key-exists-in-the-nodes-ledger-directory) prior to submitting the signed transaction. Once verified, wait for the network to reach the transaction's first valid round, then [submit](../../../archive/build-apps/hello_world#submit-the-transaction) the transaction and the SDK method "wait for confirmation". +[Verify that the participation key is on the node](../generate_keys#check-that-the-key-exists) prior to submitting the signed transaction. Once verified, wait for the network to reach the transaction's first valid round, then [submit](../../../archive/build-apps/hello_world#submit-the-transaction) the transaction and the SDK method "wait for confirmation". # Check that the node is participating @@ -167,4 +167,4 @@ $ grep 'VoteBroadcast' node.log **See also** - [Key Registration Transactions](../../../get-details/transactions/#key-registration-transaction) -- [Register account online](../../../get-details/transactions/#register-account-online) \ No newline at end of file +- [Register account online](../../../get-details/transactions/#register-account-online) diff --git a/docs/run-a-node/participate/renew.md b/docs/run-a-node/participate/renew.md index 643bf65f..bc3f0413 100644 --- a/docs/run-a-node/participate/renew.md +++ b/docs/run-a-node/participate/renew.md @@ -9,10 +9,9 @@ The validity ranges of participation keys can overlap. For any account, at any t # Step-by-Step 1. [Create a new participation key](./generate_keys.md) 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). -2. Place both keys in the participating node's ledger directory. -3. Once the network reaches the first voting round for the new key, [submit an online key registration transaction for the new participation key](./online.md). -4. Wait at least 320 rounds to [validate that the node is participating](./online.md#check-that-the-node-is-participating). -5. Once participation is confirmed, it is safe to [delete the old participation key](#removing-old-keys). +2. Once the network reaches the first voting round for the new key, [submit an online key registration transaction for the new participation key](./online.md). +3. Wait at least 320 rounds to [validate that the node is participating](./online.md#check-that-the-node-is-participating). +4. Once participation is confirmed, it is safe to [delete the old participation key](#removing-old-keys).
![Renewal Window](../../imgs/renew-0.png)
*Example key rotation window*
@@ -22,9 +21,9 @@ The validity ranges of participation keys can overlap. For any account, at any t # Removing Old Keys -When a participation key is no longer in use, the only way to remove it is by calling the node's participation API endpoint. +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. ```bash -$ curl -X DELETE $URL/v2/participation/$partKeyID -H "X-Algo-API-Token: $token" +$ 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.