​

PoA Module Architecture

​

Overview

​

Table of Contents

• Architecture
  • SDK Integration Points
  • Architectural Decisions
• Admin Control Flow
  • Setting Admin Authority
  • Managing Validator Set
  • Updating Parameters
• Validator Lifecycle
  • Validator Registration
  • Gaining Consensus Power
  • Removing Validators
• Fee Distribution → See distribution.md
• Governance → See governance.md
• Technical Implementation
  • Storage Design
  • ABCI Integration
  • Dependencies
• Security Considerations

​

Architecture

​

SDK Integration Points

1. Replaces x/staking: PoA provides validator management without token delegation or bonding
2. Integrates with x/gov: Custom governance hooks ensure only active validators can participate and tally function override allocates vote weight to validator power (details)
3. Uses x/auth & x/bank: Standard account and token management for fee distribution (details)
4. ABCI Lifecycle: Implements EndBlocker to communicate validator updates to CometBFT (details)

​

Architectural Decisions

• Enables permissioned networks with known validator identities
• Removes token requirement from validator participation (no token bonding required)
• Centralizes trust in the admin address (see Security Considerations)

• Fees allocated proportionally to validator power (not delegated stake)
• Validators withdraw fees on-demand
• See Fee Distribution for complete details

• Only active validators (power > 0) can submit, deposit, or vote on proposals
• Voting weight determined by validator power, not token holdings
• Prevents non-validator governance participation
• See Governance for implementation details

• Primary key: (power, consensus_address) enables efficient power-sorted iteration
• Secondary indexes on consensus and operator addresses for fast lookups
• Requires re-keying when power changes, but eliminates need for separate sorting
• See Storage Design for technical details

​

Admin Control Flow

​

Setting Admin Authority

• Update validator power (grant/revoke consensus participation)
• Modify module parameters
• Batch update the entire validator set

​

Managing Validator Set

1. Authentication: Transaction must be signed by the admin address
2. Validation: Each validator update is validated for:
   • Valid public key
   • Non-negative power
   • Valid metadata (operator address, moniker, description)
   • No duplicate operator addresses
3. Power Changes: Any power change triggers:
   • Fee checkpoint (allocates pending fees before power changes)
   • Total power recalculation
   • ABCI validator update queue
4. Consensus Update: Changes take effect at the end of the current block

​

Updating Parameters

• Transaction signed by current admin
• Validation of new parameters

​

Validator Lifecycle

​

Validator Registration

1. Submit Registration: Provide public key and metadata
   • PubKey: Ed25519
   • Operator Address: Account that will receive fees and manage the validator
   • Moniker: Human-readable name (max 256 chars)
   • Description: Additional details (max 256 chars)
2. Initial State: Created validators have power = 0 until the admin updates it via MsgUpdateValidators
   • Not participating in consensus
   • Not earning fees
   • Cannot vote in governance

​

Gaining Consensus Power

1. Admin Updates Power: Via MsgUpdateValidators
2. Power > 0: Validator becomes active
3. ABCI Update: CometBFT adds validator to active set at next block
4. Fee Eligibility: Validator starts accumulating fees proportionally
5. Governance Rights: Validator can submit proposals, deposit, and vote

• Power is an integer representing voting weight
• Higher power = more consensus influence and fee share
• Power can be adjusted up or down by admin
• Setting power = 0 removes validator from consensus without deleting

​

Removing Validators

• Admin sets validator power to 0
• Validator remains registered but inactive
• Can be reactivated by admin later
• Validator entry is preserved in the map of validators

​

Fee Distribution

• Fees accumulate in the fee_collector module account
• Allocated proportionally to validator power at checkpoints
• Checkpoints triggered by power changes or withdrawals
• Validators withdraw accumulated fees on-demand
• Uses DecCoins for precision to prevent dust accumulation

​

Governance

• Uses existing x/gov module
• Only active validators (power > 0) can submit, deposit, or vote on proposals
• Voting weight equals validator power
• Custom tally function replaces standard governance tallying
• Admin indirectly controls governance through power distribution

​

Technical Implementation

​

Storage Design

​

ABCI Integration

1. Power Changes: When validator power changes, create ValidatorUpdate
2. Queue Updates: Store updates in memory queue
3. EndBlock: At end of block, return all queued updates
4. CometBFT Processing: Consensus engine applies updates for next block
5. Clear Queue: After returning, clear the queue

ValidatorUpdate {
    PubKey: PublicKey  // Consensus public key
    Power:  int64      // New power (0 = remove)
}

​

Security Considerations

1. Single Point of Control:
   • Admin address controls entire validator set
2. Validator Registration:
   • Anyone can register as validator candidate
   • Only admin can grant consensus power
3. Total Power Invariant:
   • Total power must remain > 0
   • Prevents zero-power chain halts
   • Validated on every power adjustment via a checkpoint trigger
4. Governance Restrictions:
   • Only active validators (power > 0) can participate
   • Prevents governance spam from unauthorized users
   • Ensures governance represents actual consensus participants
5. Validator Indexing:
   • Unique consensus address prevents duplicate validators
   • Unique operator address prevents fee confusion