​

PoA 模块架构

​

概述

​

目录

• 架构
  • SDK 集成点
  • 架构决策
• 管理员控制流
  • 设置管理员权限
  • 管理验证者集合
  • 更新参数
• 验证者生命周期
  • 验证者注册
  • 获得共识权重
  • 移除验证者
• 费用分配 → 参见 distribution.md
• 治理 → 参见 governance.md
• 技术实现
  • 存储设计
  • ABCI 集成
  • 依赖项
• 安全注意事项

​

架构

​

SDK 集成点

1. 替代 x/staking：PoA 提供验证者管理能力，但不包含代币委托或绑定
2. 与 x/gov 集成：自定义治理钩子确保只有活跃验证者可以参与，并且 tally 函数覆盖会将投票权重分配给验证者权重（详情）
3. 使用 x/auth 和 x/bank：为费用分配提供标准账户和代币管理（详情）
4. ABCI 生命周期：实现 EndBlocker 以向 CometBFT 传递验证者更新（详情）

​

架构决策

• 支持验证者身份已知的许可型网络
• 取消验证者参与的代币要求（无需代币绑定）
• 将信任集中于管理员地址（参见安全注意事项）

• 费用通过自定义 ante handler 路由到 PoA 模块账户（完整细节参见 Fee Routing Setup）。
• 费用按验证者权重比例分配（而不是按委托质押）
• 验证者按需提取费用
• 完整细节参见费用分配

• 只有活跃验证者（权重 > 0）可以提交、存入或投票提案
• 投票权重由验证者权重决定，而不是由代币持有量决定
• 防止非验证者参与治理
• 实现细节参见治理

• 主键：(power, consensus_address) 支持按权重排序的高效迭代
• 在共识地址和操作员地址上建立二级索引以实现快速查询
• 当权重变化时需要重新设置键，但无需单独排序
• 技术细节参见存储设计

​

管理员控制流

​

设置管理员权限

• 更新验证者权重（授予或撤销共识参与资格）
• 修改模块参数
• 批量更新整个验证者集合

​

管理验证者集合

1. 身份认证：交易必须由管理员地址签名
2. 校验：每个验证者更新都会校验以下内容：
   • 有效的公钥
   • 非负权重
   • 有效的元数据（操作员地址、moniker、description）
   • 没有重复的操作员地址
3. 权重变化：任何权重变化都会触发：
   • 费用检查点（在权重变化前分配待处理费用）
   • 总权重重新计算
   • ABCI 验证者更新队列
4. 共识更新：变更会在当前区块结束时生效

​

更新参数

• 交易由当前管理员签名
• 对新参数进行校验

​

验证者生命周期

​

验证者注册

1. 提交注册：提供公钥和元数据
   • PubKey：Ed25519
   • Operator Address：将接收费费用并管理该验证者的账户
   • Moniker：人类可读名称（最多 256 个字符）
   • Description：附加详情（最多 256 个字符）
2. 初始状态：新创建的验证者初始 power = 0，直到管理员通过 MsgUpdateValidators 更新它
   • 不参与共识
   • 不赚取费用
   • 不能参与治理投票

​

获得共识权重

1. 管理员更新权重：通过 MsgUpdateValidators
2. 权重 > 0：验证者变为活跃状态
3. ABCI 更新：CometBFT 在下一个区块将验证者加入活跃集合
4. 费用资格：验证者开始按比例累积费用
5. 治理权利：验证者可以提交提案、存款并投票

• 权重是表示投票权重的整数
• 更高权重 = 更大的共识影响力和费用份额
• 管理员可以向上或向下调整权重
• 将权重设为 0 会把验证者移出共识，但不会删除该验证者

​

移除验证者

• 管理员将验证者权重设为 0
• 验证者仍保持已注册状态，但不再活跃
• 后续管理员可以重新激活该验证者
• 验证者条目会保留在验证者映射中

​

费用分配

• 费用累积在 PoA 模块账户 中
• 在检查点按验证者权重比例分配
• 检查点会在权重变化或提取时触发
• 验证者按需提取已累积的费用
• 使用 DecCoins 提高精度，防止零头累积

​

治理

• 使用现有的 x/gov 模块
• 只有活跃验证者（权重 > 0）可以提交、存入或投票提案
• 投票权重等于验证者权重
• 自定义 tally 函数替代标准治理计票逻辑
• 管理员通过权重分配间接控制治理

​

技术实现

​

存储设计

​

ABCI 集成

1. 权重变化：当验证者权重变化时，创建 ValidatorUpdate
2. 队列更新：将更新存储到内存队列中
3. EndBlock：在区块结束时，返回所有排队的更新
4. CometBFT 处理：共识引擎将更新应用到下一个区块
5. 清空队列：返回后清空队列

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

​

安全性考虑

1. 单一控制点：
   • 管理员地址控制整个验证者集合
2. 验证者注册：
   • 任何人都可以注册为验证者候选人
   • 只有管理员可以授予共识权重
3. 总权重不变量：
   • 总权重必须始终 > 0
   • 防止因零权重导致链停滞
   • 每次通过检查点触发器调整权重时都会执行校验
4. 治理限制：
   • 只有活跃验证者（权重 > 0）才能参与
   • 防止未授权用户发送治理垃圾信息
   • 确保治理代表真实的共识参与者
5. 验证者索引：
   • 唯一的共识地址可防止重复验证者
   • 唯一的操作员地址可防止费用混淆

​

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 are routed to the PoA module account via a custom ante handler (see Fee Routing Setup for complete details).
• 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 PoA 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