Purpose and Scope
This document describes the GovValidator system contract, which manages validator set governance on the StableNet blockchain.GovValidator is responsible for validator registration and removal, BLS key management, and network-wide gas tip policy. For an overview of all system contracts, see System Contracts Overview.
For minting governance, refer to Minting Governance (GovMasterMinter and GovMinter).
Overview
GovValidator (0x0000000000000000000000000000000000001001) is a genesis-deployed system contract that implements on-chain governance for the validator set.Unlike traditional staking-based validator systems, StableNet uses a Proof-of-Authority (PoA) model in which validators are managed through collective voting by existing governance members. Key responsibilities:
- Validator set management: Registering and removing validators through governance voting
- Key management: Managing operator keys, validator keys, and BLS public keys for each validator
- Gas tip policy: Setting and enforcing a mandatory network-wide gas tip
- Quorum-based decisions: All governance actions require member votes that meet a quorum threshold
Architecture Overview
The GovValidator contract interacts with the WBFT consensus engine to apply validator set changes and gas tip policies.Validator Key Structure
StableNet validators use three types of keys: Operator key, Validator key, and BLS key.For detailed roles, generation/derivation procedures, and genesis configuration examples, see Validator Operations.
Genesis Configuration
GovValidator is initialized at genesis with the following parameters:| Parameter | Type | Description |
|---|---|---|
members | address[] | List of operator key addresses |
validators | address[] | List of validator key addresses |
blsPublicKeys | bytes[] | List of BLS public keys |
quorum | uint256 | Minimum number of approvals required for governance actions |
expiry | uint256 | Proposal expiration time (seconds) |
memberVersion | uint256 | Version of the member/validator set |
gasTip | uint256 | Initial network-wide gas tip |
init.validators / init.blsPublicKeys are used only for the first epoch.From the second epoch onward, the values stored in the GovValidator contract are authoritative.
Validator Governance Flow
Adding a Validator
Validator addition follows these steps:- A governance member creates a proposal containing the new validator information
- Other members cast votes
- Once approvals reach the quorum, the proposal is executed
memberVersionis incremented- The new validator becomes active from the next epoch
Removing a Validator
Validator removal follows the same quorum-based proposal, voting, and execution flow.Removed validators stop participating in consensus and block signing starting from the next epoch.
Gas Tip Policy Management
GovValidator manages the mandatory gas tip applied network-wide.Normal accounts must comply with this value, while Authorized accounts are allowed to specify a custom tip.
Gas Tip Lifecycle
- A governance member proposes
setGasTip(newTip) - Quorum approval is reached
- The
gasTipvalue in contract storage is updated - The new value is reflected in the next block header
- Workers and the TxPool synchronize to the new minimum value
Application During Transaction Selection
| Transaction Type | Gas Tip Rule |
|---|---|
| Normal Account | Governance gasTip enforced |
| Authorized Account | User-defined tip allowed |
| Below Minimum | Rejected by TxPool |
Integration with WBFT Consensus
GovValidator supplies the active validator set to the WBFT consensus engine at every epoch block. At epoch transition:- The consensus engine detects the epoch block
- Reads
validators[]andblsPublicKeys[]from GovValidator storage - Constructs
EpochInfo - Encodes it into the block header Extra data
- Activates the new set in the next epoch
Contract Storage Layout
| Variable | Type | Description |
|---|---|---|
members | address[] | Governance operator keys |
validators | address[] | Validator keys |
blsPublicKeys | bytes[] | BLS public keys |
memberVersion | uint256 | Set change version |
quorum | uint256 | Minimum approval count |
expiry | uint256 | Proposal expiration time |
gasTip | uint256 | Mandatory network gas tip |
Governance Member Operations
| Operation | Effect |
|---|---|
| Add Validator | Add a validator starting from the next epoch |
| Remove Validator | Remove a validator starting from the next epoch |
| Set Gas Tip | Change the network minimum priority fee |
| Query Validators | Retrieve the current validator list |
| Query Gas Tip | Retrieve the current gas tip |
Relationship with Other Contracts
GovValidator is part of the StableNet governance system,with clearly separated responsibilities from minting policy (GovMasterMinter/GovMinter) and account policy (GovCouncil). This separation allows consensus and validator operations to be managed independently from monetary policy.