> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Validator Governance (GovValidator)

## 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](/en/governance-system/5.1-system-contracts-overview).\
For minting governance, refer to [Minting Governance (GovMasterMinter and GovMinter)](/en/governance-system/5.4-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](/en/operations-guide/11.2-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                                |

**Important:**\
`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:

1. A governance member creates a proposal containing the new validator information
2. Other members cast votes
3. Once approvals reach the quorum, the proposal is executed
4. `memberVersion` is incremented
5. 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

1. A governance member proposes `setGasTip(newTip)`
2. Quorum approval is reached
3. The `gasTip` value in contract storage is updated
4. The new value is reflected in the next block header
5. 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:

1. The consensus engine detects the epoch block
2. Reads `validators[]` and `blsPublicKeys[]` from GovValidator storage
3. Constructs `EpochInfo`
4. Encodes it into the block header Extra data
5. 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                    |

All state-changing operations are executed exclusively through quorum-based voting.

## 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.