From 890ac36c84c4438bcc724cdfa6a4ff248ea315d0 Mon Sep 17 00:00:00 2001 From: "F. Eugene Aumson" Date: Fri, 23 Aug 2024 13:00:28 -0400 Subject: [PATCH 1/2] staking: small README improvements Signed-off-by: F. Eugene Aumson --- contracts/staking/README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/contracts/staking/README.md b/contracts/staking/README.md index 0794c14a7..c086b0c25 100644 --- a/contracts/staking/README.md +++ b/contracts/staking/README.md @@ -20,7 +20,7 @@ If the Subnet has no validators registered on the P-Chain, then it will not be a Validator registration is initiated with a call to `initializeValidatorRegistration` on the concrete Validator Manager contract. The Validator Manager contract constructs a [`RegisterSubnetValidatorMessage`](#registersubnetvalidatormessage) Warp message to be sent to the P-Chain. Each validator registration request includes all of the information needed to identify the validator and its stake weight, as well as an `expiry` timestamp before which the `RegisterSubnetValidatorMessage` must be delivered to the P-Chain. -The `RegisterSubnetValidatorMessage` is delivered to the P-Chain as the Warp message payload of a `RegisterSubnetValidatorTx`. Please see the transaction [specification](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#step-2-issue-a-registersubnetvalidatortx-on-the-p-chain) for validity requirements. The successful `RegisterSubnetValidatorTx` results in a `SubnetValidatorRegistrationMessage` Warp message indicating that the specified validation was successfully registered on the P-Chain. +The `RegisterSubnetValidatorMessage` is delivered to the P-Chain as the Warp message payload of a [`RegisterSubnetValidatorTx`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#registersubnetvalidatortx). Please see the transaction [specification](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#step-2-issue-a-registersubnetvalidatortx-on-the-p-chain) for validity requirements. The successful `RegisterSubnetValidatorTx` results in a [`SubnetValidatorRegistrationMessage`](#subnetvalidatorregistrationmessage) Warp message indicating that the specified validator was successfully registered on the P-Chain. The `SubnetValidatorRegistrationMessage` is delivered to the Validator Manager contract via a call to `completeValidatorRegistration`. For PoS Validator Managers, staking rewards begin accruing at this time. @@ -30,21 +30,21 @@ In the case of a missed expiry, the `RegisterSubnetValidatorTx` will result in a ### Exiting the Validator Set -Validator exit is initiated with a call to `initializeEndValidation` on the Validator Manager contract. For PoS Validator Managers, a `ValidationUptimeMessage` Warp message may optionally be provided in order to calculate the staking rewards; otherwise the validator's uptime will be set to `0`. This proof may be requested from the P-Chain, which will provide it in a [`ValidationUptimeMessage`](#validationuptimemessage) Warp message. Once `initializeEndValidation` is called, staking rewards cease accruing for PoS Validator Managers. The Validator Manager contract constructs a [`SetSubnetValidatorWeightMessage`](#setsubnetvalidatorweightmessage) Warp message, setting the weight to `0`. +Validator exit is initiated with a call to `initializeEndValidation` on the Validator Manager contract. For PoS Validator Managers, a [`ValidationUptimeMessage`](#validationuptimemessage) Warp message may optionally be provided in order to calculate the staking rewards; otherwise the validator's uptime will be set to `0`. This proof may be requested from the P-Chain, which will provide it in a `ValidationUptimeMessage` Warp message. Once `initializeEndValidation` is called, staking rewards cease accruing for PoS Validator Managers: the Validator Manager contract constructs a [`SetSubnetValidatorWeightMessage`](#setsubnetvalidatorweightmessage) Warp message, setting the weight to `0`. -The `SetSubnetValidatorWeightMessage` is delivered to the P-Chain as the payload of a `SetValidatorWeightTx`. The P-Chain acknowledges validator exit by signing either a `SetSubnetValidatorWeightMessage` with the `weight=0`, or a `SubnetValidatorRegistrationMessage` with `valid=0`. `completeEndValidation` is then called on the Validator Manager contract, with `setWeightMessageType` set according to the Warp message type being delivered. The validation is removed from the contract's state, and for PoS Validator Managers, staking rewards are disbursed and stake is returned. +The `SetSubnetValidatorWeightMessage` is delivered to the P-Chain as the payload of a [`SetSubnetValidatorWeightTx`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#setsubnetvalidatorweighttx). The P-Chain acknowledges validator exit by signing either a `SetSubnetValidatorWeightMessage` with the `weight=0`, or a `SubnetValidatorRegistrationMessage` with `valid=0`. `completeEndValidation` is then called on the Validator Manager contract, with `setWeightMessageType` set according to the Warp message type being delivered. The validation is removed from the contract's state, and for PoS Validator Managers, staking rewards are disbursed and stake is returned. #### Exit the Validator Set Directly on the P-Chain -ACP-77 also provides a method for validators to exit a Subnet's validator set without interacting with the Subnet directly. The P-Chain transaction [`ExitValidatorSetTx`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#exitvalidatorsettx) removes the validator from the Subnet validator set tracked on the P-Chain. The P-Chain will will sign a `SetSubnetValidatorWeightMessage` or a `SubnetValidatorRegistrationMessage`, that may then be provided to the Staking Manager contract via a call to `completeEndValidation`, as described above. Note however that without the uptime proof provided in the initial call to `initializeEndValidation`, the Staking Manager will not credit any staking rewards to the validator. +ACP-77 also provides a method for validators to exit a Subnet's validator set without interacting with the Subnet directly. The P-Chain transaction [`ExitValidatorSetTx`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#exitvalidatorsettx) removes the validator from the Subnet validator set tracked on the P-Chain. The P-Chain will sign a `SetSubnetValidatorWeightMessage` or a `SubnetValidatorRegistrationMessage`, which may then be provided to the Validator Manager contract via a call to `completeEndValidation`, as described above. Note however that without the uptime proof provided in the initial call to `initializeEndValidation`, the Validator Manager will not credit any staking rewards to the validator. ## Warp Message Format Reference ### `RegisterSubnetValidatorMessage` -Description: Used to register a Subnet validator on the P-Chain +Description: Issued by the Validator Manager contract in order to register a Subnet validator -Signed by: Subnet +Signed by: Subnet validators Specification: @@ -71,7 +71,7 @@ Specification: ### `SubnetValidatorRegistrationMessage` -Description: Used to confirm Subnet validator registration on the P-Chain +Description: Issued by the P-Chain in order to confirm Subnet validator registration Signed by: P-Chain @@ -93,7 +93,7 @@ Specification: ### `ValidationUptimeMessage` -Description: Used to provide validator uptime to the Subnet to calculate staking rewards +Description: Issued by the P-Chain in order to provide validator uptime to the Subnet to calculate staking rewards Signed by: P-Chain @@ -137,12 +137,12 @@ Specification: +----------+ ``` -## Types of Staking Managers +## Types of Validator Managers ### Proof of Authority -The Proof of Authority (PoA) staking manager is ownable, and only allows the owner to modify changes to the validator set of the Subnet. Validators are given a weight by the owner, but do not accrue staking rewards. +The Proof of Authority (PoA) validator manager is ownable, and only allows the owner to modify changes to the validator set of the Subnet. Validators are given a weight by the owner, but do not accrue staking rewards. ### Proof of Stake -The Proof of Stake (PoS) staking manager allows any validator to register and exit the Subnet validator set. Validators are given a weight based on the amount of stake they provide, and accrue staking rewards based on their uptime. The staking rewards can be either native or erc20 tokens. +The Proof of Stake (PoS) validator manager allows any validator to register and exit the Subnet validator set. Validators are given a weight based on the amount of stake they provide, and accrue staking rewards based on their uptime. The staking rewards can be either native or erc20 tokens. From 7414d70398cf3070913d691edba9e7c279715dbc Mon Sep 17 00:00:00 2001 From: "F. Eugene Aumson" Date: Tue, 27 Aug 2024 12:27:43 -0400 Subject: [PATCH 2/2] fix nit addresses review comment https://github.com/ava-labs/teleporter/pull/502#discussion_r1729545517 Signed-off-by: F. Eugene Aumson --- contracts/staking/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/staking/README.md b/contracts/staking/README.md index c086b0c25..8e724082b 100644 --- a/contracts/staking/README.md +++ b/contracts/staking/README.md @@ -44,7 +44,7 @@ ACP-77 also provides a method for validators to exit a Subnet's validator set wi Description: Issued by the Validator Manager contract in order to register a Subnet validator -Signed by: Subnet validators +Signed by: Subnet Specification: