Remove Validator
Theory walkthrough of removing a PoS validator and claiming staking rewards
Removing a PoS Validator
Removing a validator in a PoS setup returns the staked tokens plus any earned staking rewards. Only the owner of the validation period (the address that initiated it) can remove the validator, and only after the minimum stake duration has elapsed.
Phase 1: Initiation (L1)
The validator owner calls initiateValidatorRemoval(validationID, includeUptimeProof, messageIndex) on the Staking Manager contract.
Under the hood, the contract:
- Verifies the caller is the validation period owner
- Ensures the minimum stake duration has passed
- An uptime proof may optionally be provided to determine reward eligibility
- Sets the validator status to
PendingRemoved - Constructs a weight message with
weight = 0(removal is encoded as a weight update to zero) - Sends a Warp message to the P-Chain
Uptime Proof: When you initiate removal, you can include a ValidationUptimeMessage as an uptime proof. The L1's own validators sign this message. The P-Chain does not track the uptime of L1 validators. If you do not include a proof, the contract uses the last uptime that it stored. With ExampleRewardCalculator, a validator with less than 80% uptime gets no reward, and initiateValidatorRemoval reverts. Use forceInitiateValidatorRemoval to exit without rewards. At 80% uptime or more, the reward does not change with uptime.
Phase 2: P-Chain Processing
The weight update message (weight = 0) is signed and submitted to the P-Chain as a SetL1ValidatorWeightTx:
- Aggregate signatures for the weight update
- Submit to the P-Chain
- The P-Chain removes the validator and acknowledges with a signed
L1ValidatorRegistrationMessagewithvalid = false
Phase 3: Completion (L1)
Call completeValidatorRemoval(messageIndex) with the P-Chain's signed response:
- Verifies the Warp message and
valid == false - Uses the staking reward that
initiateValidatorRemovalcalculated. It does not calculate the reward again. - Returns the staked tokens to the validator owner
- Distributes validator rewards (minted via Native Minter precompile for native token staking)
- Sets the status to Completed
- Emits
CompletedValidatorRemoval
Claiming Delegation Fees
Delegation fees earned by the validator are not distributed during completeValidatorRemoval to bound gas consumption. Instead, the validator must call claimDelegationFees(validationID) separately after the validation period ends.
Minimum Stake Duration
The minimum stake duration is set by the validator when they register. The validator cannot initiate removal until this duration has elapsed since the validation period started.
canRemove = block.timestamp >= startTime + minStakeDurationAppendix: PoS Validator Removal Flow
Is this guide helpful?
