​
Group 模块架构

​
概述

Group 模块通过提案与投票系统支持集体决策。Group 是由一组账户及其对应投票权重构成的集合。每个 group 可以拥有一个或多个 policy account，每个 account 都有各自的决策策略，用于控制提案如何被接受或拒绝。你可以将它理解为一种动态的多重签名账户机制。

​
架构图

Group 模块架构 上图展示了 Group 模块的 actor model、数据结构以及提案生命周期，从提交、投票到执行的全过程。

​
核心概念

​
Group

Group 是带有关联投票权重的一组账户的聚合。它本身不是账户，也不持有余额。一个 group 拥有一个管理员，管理员可以添加、移除和更新成员。 关键点：
  • 管理员不需要是 group 的成员
  • group policy account 本身也可以作为 group 的管理员，从而实现 group 的自我治理
  • 成员拥有权重，这决定了他们在提案中的相对投票权

​
Group Policy

Group policy 是与某个 group 和某个决策策略关联的账户。之所以将 group policy 从 group 中抽象出来，是为了让同一个 group 能够针对不同类型的操作使用多个决策策略。 这种分离方式可以在不同策略之间保持成员集合一致，同时允许针对不同操作设置不同的授权阈值。推荐模式如下：
  1. 为某个 group 创建一个主 group policy
  2. 针对特定操作类型，创建使用不同决策策略的额外 group policy
  3. 使用 x/authz 模块，将权限从主账户委托给子账户

​
Decision Policy

Decision policy 是 group 成员对提案进行投票的机制，以及根据计票结果判断提案是否通过的规则。 所有 decision policy 都包含：
  • 最短执行期：提案提交后，距离允许执行所需的最短时间。可设置为 0，以允许立即执行。
  • 最大投票窗口：提案提交后，成员可以投票的最长时间。
链的开发者还会定义一个应用级最大执行期，即提案投票期结束后仍允许执行的时间窗口。

​
Threshold Decision Policy

Threshold decision policy 定义了提案通过所需的最小赞成票总权重。弃权票和否决票都会被视为反对票。 
{
  "@type": "/cosmos.group.v1.ThresholdDecisionPolicy",
  "threshold": "2",
  "windows": {
    "voting_period": "24h",
    "min_execution_period": "0s"
  }
}

​
Percentage Decision Policy

Percentage decision policy 将“通过”定义为：赞成票占 group 总权重的最小百分比达到要求。该策略更适用于成员动态变化的 group，因为当成员权重发生变化时，百分比阈值仍然具有明确意义。 
{
  "@type": "/cosmos.group.v1.PercentageDecisionPolicy",
  "percentage": "0.5",
  "windows": {
    "voting_period": "24h",
    "min_execution_period": "0s"
  }
}

​
Custom Decision Policies

链的开发者可以通过实现 DecisionPolicy 接口来实现自定义决策策略，从而将任意接受逻辑编码到 group policy 中。

​
Proposal

任何 group 成员都可以向某个 group policy account 提交提案。一个提案包括：
  • 如果提案被接受则要执行的消息列表
  • 可选的 metadata、title 和 summary
  • 可选的 Exec 字段，用于在提交时尝试立即执行

​
Voting

成员可使用以下四种选项之一进行投票：
  • VOTE_OPTION_YES
  • VOTE_OPTION_NO
  • VOTE_OPTION_ABSTAIN
  • VOTE_OPTION_NO_WITH_VETO
投票窗口会在提案提交后立即开启，并在 group policy 的 decision policy 所定义的时间关闭。

​
Tallying

在以下任一情况下会进行计票：
  1. Msg/Exec、Msg/SubmitProposal（带 TRY_EXEC）或 Msg/Vote（带 TRY_EXEC）触发了一次执行尝试
  2. 在 EndBlock 期间到达提案投票期结束时间
如果计票结果满足 decision policy 的规则，提案会被标记为 PROPOSAL_STATUS_ACCEPTED。否则会被标记为 PROPOSAL_STATUS_REJECTED。计票完成后不再允许继续投票。

​
Executing Proposals

已接受的提案必须在投票期结束后的 MaxExecutionPeriod 内执行。任何账户（不仅限于 group 成员）都可以提交 Msg/Exec 交易来执行一个已接受的提案。 当在提交消息或投票消息上将 Exec 设置为 EXEC_TRY 时，链会尝试立即执行。如果提案尚未满足通过条件，它将保持开启状态，等待后续投票。

​
Withdrawn and Aborted Proposals

  • 已撤回：任何提案发起人或 group policy admin 都可以在投票期结束前撤回提案。已撤回的提案不能执行。提案可以通过 MsgWithdrawProposal 撤回，该消息包含 address（可以是提案发起人或 group policy admin）以及 proposal_id（要撤回的提案 ID）。
  • 已中止：如果在投票期间 group 或 group policy 被更新，提案会被自动标记为 PROPOSAL_STATUS_ABORTED，因为其创建时所依据的规则已不再适用。

​
Pruning

提案和投票会被自动裁剪，以防止状态无限增长。 投票会在以下情况下被裁剪：
  • 由 Msg/Exec 或带 TRY_EXEC 的提交/投票触发成功计票之后
  • 在提案投票期结束后，于 EndBlock 中立即裁剪（包括已中止和已撤回的提案）
提案会在以下情况下被裁剪：
  • 对于已撤回或已中止的提案，在其投票期结束时于 EndBlock 中裁剪
  • 提案成功执行之后
  • 当 voting_period_end + max_execution_period 已经过期后，于 EndBlock 中裁剪

​
Group Module Architecture

​
Overview

The Group module enables collective decision-making through a proposal-and-vote system. Groups are collections of accounts with associated voting weights. Each group can have one or more policy accounts, each with its own decision policy governing how proposals are accepted or rejected. You can think of it like a dynamic multi-signature account.

​
Architecture Diagram

Group Module Architecture The diagram above shows the Group module’s actor model, data structures, and proposal lifecycle — from submission through voting to execution.

​
Core Concepts

​
Group

A group is an aggregation of accounts with associated voting weights. It is not itself an account and does not hold a balance. A group has an administrator who can add, remove, and update members. Key points:
  • The administrator does not need to be a member of the group
  • A group policy account can itself be the administrator of a group, enabling self-governed groups
  • Members have weights that determine their relative voting power within proposals

​
Group Policy

A group policy is an account associated with a group and a decision policy. Group policies are abstracted from groups so that a single group can have multiple decision policies for different types of actions. This separation keeps membership consistent across policies while allowing different authorization thresholds for different operations. The recommended pattern is:
  1. Create a master group policy for a given group
  2. Create additional group policies with different decision policies for specific action types
  3. Delegate permissions from the master account to sub-accounts using the x/authz module

​
Decision Policy

A decision policy is the mechanism by which group members vote on proposals and the rules that determine whether a proposal passes based on its tally outcome. All decision policies have:
  • Minimum Execution Period: The minimum time after submission before a proposal can be executed. Can be set to 0 to allow immediate execution.
  • Maximum Voting Window: The maximum time after submission during which members can vote.
The chain developer also defines an app-wide maximum execution period — the window after a proposal’s voting period ends during which execution is permitted.

​
Threshold Decision Policy

A threshold decision policy defines a minimum total weight of yes votes required for a proposal to pass. Abstain and veto votes are treated as no votes. 
{
  "@type": "/cosmos.group.v1.ThresholdDecisionPolicy",
  "threshold": "2",
  "windows": {
    "voting_period": "24h",
    "min_execution_period": "0s"
  }
}

​
Percentage Decision Policy

A percentage decision policy defines acceptance as a minimum percentage of total group weight voting yes. This policy is better suited for groups with dynamic membership, since the percentage threshold remains meaningful as member weights change. 
{
  "@type": "/cosmos.group.v1.PercentageDecisionPolicy",
  "percentage": "0.5",
  "windows": {
    "voting_period": "24h",
    "min_execution_period": "0s"
  }
}

​
Custom Decision Policies

Chain developers can implement custom decision policies by implementing the DecisionPolicy interface. This enables encoding arbitrary acceptance logic into a group policy.

​
Proposal

Any group member can submit a proposal to a group policy account. A proposal consists of:
  • A list of messages to execute if the proposal is accepted
  • Optional metadata, title, and summary
  • An optional Exec field to attempt immediate execution on submission

​
Voting

Members vote with one of four options:
  • VOTE_OPTION_YES
  • VOTE_OPTION_NO
  • VOTE_OPTION_ABSTAIN
  • VOTE_OPTION_NO_WITH_VETO
The voting window opens immediately on proposal submission and closes at the time defined by the group policy’s decision policy.

​
Tallying

Tallying occurs when either:
  1. A Msg/Exec, Msg/SubmitProposal (with TRY_EXEC), or Msg/Vote (with TRY_EXEC) triggers an execution attempt
  2. The proposal’s voting period end is reached during EndBlock
If the tally passes the decision policy’s rules, the proposal is marked PROPOSAL_STATUS_ACCEPTED. Otherwise it is marked PROPOSAL_STATUS_REJECTED. No further voting is permitted after tallying.

​
Executing Proposals

Accepted proposals must be executed before MaxExecutionPeriod after the voting period ends. Any account (not just group members) can submit a Msg/Exec transaction to execute an accepted proposal. When Exec is set to EXEC_TRY on a submit or vote message, the chain attempts immediate execution. If the proposal doesn’t yet pass, it remains open for further votes.

​
Withdrawn and Aborted Proposals

  • Withdrawn: Any proposer or the group policy admin can withdraw a proposal before the voting period ends. Withdrawn proposals cannot be executed. A proposal can be withdrawn using MsgWithdrawProposal which has an address (can be either a proposer or the group policy admin) and a proposal_id (which has to be withdrawn).
  • Aborted: If the group or group policy is updated during the voting period, the proposal is automatically marked as PROPOSAL_STATUS_ABORTED since the rules it was created under no longer apply.

​
Pruning

Proposals and votes are automatically pruned to prevent unbounded state growth. Votes are pruned:
  • After a successful tally triggered by Msg/Exec or a submit/vote with TRY_EXEC
  • On EndBlock immediately after the proposal’s voting period ends (including aborted and withdrawn proposals)
Proposals are pruned:
  • On EndBlock when a withdrawn or aborted proposal’s voting period ends
  • After a successful proposal execution
  • On EndBlock after voting_period_end + max_execution_period has passed