Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

staking: small README improvements #502

Merged
merged 2 commits into from
Aug 27, 2024
Merged

staking: small README improvements #502

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
890ac36
staking: small README improvements
feuGeneA Aug 23, 2024
7414d70
fix nit
feuGeneA Aug 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions contracts/staking/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -30,19 +30,19 @@ 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

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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.