From 8113552260b58fe2f316abd209d0cf5724d68071 Mon Sep 17 00:00:00 2001 From: Nicolas Ochem Date: Wed, 14 Sep 2022 18:22:08 +0200 Subject: [PATCH 1/5] Consensus key documentation The consensus key is introduced in proto L. Release notes already have details about the new operations and rpc commands: https://tezos.gitlab.io/protocols/alpha.html#consensus-key This MR introduces more genric documentation to help delegates use the feature. This belongs to the "Key management" section. This should be merged later, when protocol L is voted in. --- docs/introduction/howtorun.rst | 4 +++ docs/user/key-management.rst | 61 ++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) diff --git a/docs/introduction/howtorun.rst b/docs/introduction/howtorun.rst index b6540466d5c7..315dea10cb23 100644 --- a/docs/introduction/howtorun.rst +++ b/docs/introduction/howtorun.rst @@ -184,6 +184,10 @@ Note that ``--liquidity-baking-toggle-vote`` must be placed **Never** use the same account on two daemons. +.. note:: + + It is possible to bake and endorse using a dedicated :ref:`consensus_key` instead of the delegate's key. + .. note:: In protocols before Ithaca, a separate daemon, the endorser, is responsible for emitting endorsements. diff --git a/docs/user/key-management.rst b/docs/user/key-management.rst index f2cdb7b4c5fc..436cc2e8df0f 100644 --- a/docs/user/key-management.rst +++ b/docs/user/key-management.rst @@ -259,6 +259,67 @@ However, this setup **does not guarantee confidentiality**: an eavesdropper can see the transactions that you sign (on a public blockchain this may be less of a concern). In order to avoid that, you can use the ``https`` scheme or a tunnel to encrypt your traffic. +.. _consensus_key: + +Consensus Key +------------- + +A delegate may choose to use a different key to sign consensus operations (bakes, endorsements and preendorsements). + +The consensus key can then be rotated without redelegation. + +It also allows establishment of baking operations in an environment where access is not ultimately guaranteed: +for example, a cloud platform providing hosted Key Management Systems where the private key is +generated within the system and can never be downloaded by the operator. The baker can designate +such KMS key as consensus key. Shall they lose access to the cloud platform for any reason, they can simply rotate to a new key. + +However, both the delegate key and the consensus have total control over the delegate's funds: indeed, the consensus key may sign a +Drain operation to transfer the delegate's free balance to a third account of their choice. + +As a consequence, the consensus key should be treated with equal care than the delegate's key. + +Registering a Consensus Key +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A consensus key can be changed at any point. This may be done with the command:: + + tezos-client set consensus key for to + +The update becomes active after `PRESERVED_CYCLES + 1` cycles. We therefore distinguish +the active consensus key and the pending consensus keys. (There can be multiple pending updates.) +The active consensus key is by default the baker’s regular key, called its manager key, which cannot change. + +It is also possible to register as a delegate and immediately set the consensus key:: + + tezos-client register key as delegate with consensus key + +Baking With a Consensus Key +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In your baker's command, replace the delegate's manager key alias with the consenus key alias:: + + tezos-baker-0XX-Psxxxxxx run with local node ~/.tezos-node --liquidity-baking-toggle-vote pass + +While transitioning from the delegate's manager key, it is possible to pass the alias for both delegate's manager key and consensus key. +The baker will seamlessly keep baking when the transition happens:: + + tezos-baker-0XX-Psxxxxxx run with local node ~/.tezos-node --liquidity-baking-toggle-vote pass + +Draining a Manager's Account With its Consensus Key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This operation immediately transfers all the spendable balance of the `baker_pkh`’s implicit account into the `destination_pkh` implicit account:: + + tezos-client drain delegate to + +The active consensus key is the signer for this operation, therefore the private key associated to the consensus key must be available +in the wallet of the client typing the command. The delegate's private key needs not be present. + +`drain delegate` has no effect on the frozen balance. + +A fixed fraction of the drained baker’s spendable balance is transferred as fees to the baker that includes the operation, +i.e. the maximum between 1tz or 1% of the spendable balance. + .. _activate_fundraiser_account: Getting keys for fundraiser accounts -- GitLab From 00078a0d7ee5c754ba7ec8995c091ff25982839b Mon Sep 17 00:00:00 2001 From: Nicolas Ochem Date: Fri, 16 Sep 2022 14:19:13 +0000 Subject: [PATCH 2/5] Apply 7 suggestion(s) to 1 file(s) --- docs/user/key-management.rst | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/user/key-management.rst b/docs/user/key-management.rst index 436cc2e8df0f..2cf7536730cb 100644 --- a/docs/user/key-management.rst +++ b/docs/user/key-management.rst @@ -264,19 +264,19 @@ In order to avoid that, you can use the ``https`` scheme or a tunnel to encrypt Consensus Key ------------- -A delegate may choose to use a different key to sign consensus operations (bakes, endorsements and preendorsements). +A delegate may choose to use a different key to sign in the consensus protocol, i.e. for signing blocks while baking, and for signing consensus operations (preendorsements and endorsements). The consensus key can then be rotated without redelegation. It also allows establishment of baking operations in an environment where access is not ultimately guaranteed: -for example, a cloud platform providing hosted Key Management Systems where the private key is +for example, a cloud platform providing hosted Key Management Systems (KMS) where the private key is generated within the system and can never be downloaded by the operator. The baker can designate -such KMS key as consensus key. Shall they lose access to the cloud platform for any reason, they can simply rotate to a new key. +such a KMS key as its consensus key. Shall they lose access to the cloud platform for any reason, they can simply rotate to a new key. -However, both the delegate key and the consensus have total control over the delegate's funds: indeed, the consensus key may sign a +However, both the delegate key and the consensus key have total control over the delegate's funds: indeed, the consensus key may sign a Drain operation to transfer the delegate's free balance to a third account of their choice. -As a consequence, the consensus key should be treated with equal care than the delegate's key. +As a consequence, the consensus key should be treated with equal care as the delegate's key. Registering a Consensus Key ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -289,7 +289,7 @@ The update becomes active after `PRESERVED_CYCLES + 1` cycles. We therefore dist the active consensus key and the pending consensus keys. (There can be multiple pending updates.) The active consensus key is by default the baker’s regular key, called its manager key, which cannot change. -It is also possible to register as a delegate and immediately set the consensus key:: +However, it is also possible to register as a delegate and immediately set the consensus key:: tezos-client register key as delegate with consensus key @@ -310,7 +310,11 @@ Draining a Manager's Account With its Consensus Key This operation immediately transfers all the spendable balance of the `baker_pkh`’s implicit account into the `destination_pkh` implicit account:: - tezos-client drain delegate to + tezos-client drain delegate to with + +If the destination is the consensus key account, this can be simplified to:: + + tezos-client drain delegate to The active consensus key is the signer for this operation, therefore the private key associated to the consensus key must be available in the wallet of the client typing the command. The delegate's private key needs not be present. -- GitLab From 3fa457f134ea4621c2e4019199872cd648bea0f6 Mon Sep 17 00:00:00 2001 From: Nicolas Ochem Date: Fri, 16 Sep 2022 16:40:29 +0200 Subject: [PATCH 3/5] address review comments --- docs/user/key-management.rst | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/docs/user/key-management.rst b/docs/user/key-management.rst index 2cf7536730cb..57aa3453ab92 100644 --- a/docs/user/key-management.rst +++ b/docs/user/key-management.rst @@ -264,19 +264,24 @@ In order to avoid that, you can use the ``https`` scheme or a tunnel to encrypt Consensus Key ------------- -A delegate may choose to use a different key to sign in the consensus protocol, i.e. for signing blocks while baking, and for signing consensus operations (preendorsements and endorsements). +.. note:: -The consensus key can then be rotated without redelegation. + Consensus key is available starting with the Tezos L protocol. + +By default, the baker's key, also called manager key, is used to sign in the consensus protocol, i.e. signing blocks while baking, +and signing consensus operations (preendorsements and endorsements). + +A delegate may elect instead to choose a dedicated key: the consensus key. It can then be changed without redelegation. It also allows establishment of baking operations in an environment where access is not ultimately guaranteed: for example, a cloud platform providing hosted Key Management Systems (KMS) where the private key is -generated within the system and can never be downloaded by the operator. The baker can designate -such a KMS key as its consensus key. Shall they lose access to the cloud platform for any reason, they can simply rotate to a new key. +generated within the system and can never be downloaded by the operator. The delegate can designate +such a KMS key as its consensus key. Shall they lose access to the cloud platform for any reason, they can simply switch to a new key. -However, both the delegate key and the consensus key have total control over the delegate's funds: indeed, the consensus key may sign a -Drain operation to transfer the delegate's free balance to a third account of their choice. +However, both the delegate key and the consensus key give total control over the delegate's funds: indeed, the consensus key may sign a +Drain operation to transfer the delegate's free balance to an arbitrary account. -As a consequence, the consensus key should be treated with equal care as the delegate's key. +As a consequence, the consensus key should be treated with equal care as the manager key. Registering a Consensus Key ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -286,13 +291,16 @@ A consensus key can be changed at any point. This may be done with the command:: tezos-client set consensus key for to The update becomes active after `PRESERVED_CYCLES + 1` cycles. We therefore distinguish -the active consensus key and the pending consensus keys. (There can be multiple pending updates.) -The active consensus key is by default the baker’s regular key, called its manager key, which cannot change. +the active consensus key and the pending consensus keys. +The active consensus key is by default the delegate’s manager key, which cannot change. However, it is also possible to register as a delegate and immediately set the consensus key:: tezos-client register key as delegate with consensus key +There can be multiple pending updates: it is possile to have multiple pending consensus keys for multiple future cycles. +A subsequent update within the same cycle takes precedences over the initial one. + Baking With a Consensus Key ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -301,7 +309,7 @@ In your baker's command, replace the delegate's manager key alias with the conse tezos-baker-0XX-Psxxxxxx run with local node ~/.tezos-node --liquidity-baking-toggle-vote pass While transitioning from the delegate's manager key, it is possible to pass the alias for both delegate's manager key and consensus key. -The baker will seamlessly keep baking when the transition happens:: +The delegate will seamlessly keep baking when the transition happens:: tezos-baker-0XX-Psxxxxxx run with local node ~/.tezos-node --liquidity-baking-toggle-vote pass @@ -321,8 +329,8 @@ in the wallet of the client typing the command. The delegate's private key needs `drain delegate` has no effect on the frozen balance. -A fixed fraction of the drained baker’s spendable balance is transferred as fees to the baker that includes the operation, -i.e. the maximum between 1tz or 1% of the spendable balance. +A fixed fraction of the drained delegate’s spendable balance is transferred as fees to the baker that includes the operation, +i.e. the maximum between 1 tez or 1% of the spendable balance. .. _activate_fundraiser_account: -- GitLab From 4b2809eb8cd3a17f37b963c05c1c9e16fa8fc45e Mon Sep 17 00:00:00 2001 From: Nicolas Ochem Date: Fri, 16 Sep 2022 18:52:03 +0200 Subject: [PATCH 4/5] typo --- docs/user/key-management.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/key-management.rst b/docs/user/key-management.rst index 57aa3453ab92..7da3428008a4 100644 --- a/docs/user/key-management.rst +++ b/docs/user/key-management.rst @@ -298,7 +298,7 @@ However, it is also possible to register as a delegate and immediately set the c tezos-client register key as delegate with consensus key -There can be multiple pending updates: it is possile to have multiple pending consensus keys for multiple future cycles. +There can be multiple pending updates: it is possible to have multiple pending consensus keys for multiple future cycles. A subsequent update within the same cycle takes precedences over the initial one. Baking With a Consensus Key -- GitLab From 145dc8b9a176aa9237a21ffbe11974e58c997ae1 Mon Sep 17 00:00:00 2001 From: Nicolas Ochem Date: Mon, 7 Nov 2022 14:41:15 -0800 Subject: [PATCH 5/5] add instructions on how to import a pub key before registering --- docs/user/key-management.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/user/key-management.rst b/docs/user/key-management.rst index 7da3428008a4..8c309f5e3dac 100644 --- a/docs/user/key-management.rst +++ b/docs/user/key-management.rst @@ -286,9 +286,17 @@ As a consequence, the consensus key should be treated with equal care as the man Registering a Consensus Key ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A consensus key can be changed at any point. This may be done with the command:: +A consensus key can be changed at any point. - tezos-client set consensus key for to +The operation is signed by the manager key and does not require the consensus private key to be accessible by the client. + +However the public key must be known by the client. It can be imported with the command:: + + tezos-client import public key consensus unencrypted:edpk... + +The command to update the consensus key is:: + + tezos-client set consensus key for to consensus The update becomes active after `PRESERVED_CYCLES + 1` cycles. We therefore distinguish the active consensus key and the pending consensus keys. -- GitLab