Group 模块 API 参考

概述

Group 模块提供了一套完整的 API，用于管理链上多签组和集体决策。 包名： cosmos.group.v1 Go 导入： github.com/cosmos/cosmos-sdk/enterprise/group/x/group

数据类型

GroupInfo

表示链上的一个组。

message GroupInfo {
  uint64 id = 1;
  string admin = 2;
  bytes metadata = 3;
  uint64 version = 4;
  string total_weight = 5;
  google.protobuf.Timestamp created_at = 6;
}

字段：

id (uint64)：组的唯一标识符，创建时自动分配
admin (string)：组管理员的 Cosmos SDK 地址
metadata (bytes)：可选的组元数据
version (uint64)：每次组更新时递增；用于检测过期提案
total_weight (string)：所有成员权重之和
created_at (Timestamp)：组创建时的区块时间

GroupMember

表示成员与组之间的关系。

message GroupMember {
  uint64 group_id = 1;
  Member member = 2;
}

message Member {
  string address = 1;
  string weight = 2;
  bytes metadata = 3;
  google.protobuf.Timestamp added_at = 4;
}

字段：

address (string)：成员的 Cosmos SDK 地址
weight (string)：投票权重。设置为 "0" 可移除该成员。
metadata (bytes)：可选的成员元数据
added_at (Timestamp)：成员添加时的区块时间

GroupPolicyInfo

表示一个组策略账户。

message GroupPolicyInfo {
  string address = 1;
  uint64 group_id = 2;
  string admin = 3;
  bytes metadata = 4;
  uint64 version = 5;
  google.protobuf.Any decision_policy = 6;
  google.protobuf.Timestamp created_at = 7;
}

字段：

address (string)：组策略的账户地址（自动生成）
group_id (uint64)：该策略关联的组
admin (string)：有权更新该策略的地址
decision_policy (Any)：策略的决策逻辑（阈值或百分比）
version (uint64)：每次更新时递增；用于检测已中止的提案

Proposal

表示提交给组策略的链上提案。

message Proposal {
  uint64 id = 1;
  string group_policy_address = 2;
  bytes metadata = 3;
  repeated string proposers = 4;
  google.protobuf.Timestamp submit_time = 5;
  uint64 group_version = 6;
  uint64 group_policy_version = 7;
  ProposalStatus status = 8;
  TallyResult final_tally_result = 9;
  google.protobuf.Timestamp voting_period_end = 10;
  ProposalExecutorResult executor_result = 11;
  repeated google.protobuf.Any messages = 12;
  string title = 13;
  string summary = 14;
}

ProposalStatus 取值：

PROPOSAL_STATUS_SUBMITTED - 开放投票中
PROPOSAL_STATUS_ACCEPTED - 已通过；可执行
PROPOSAL_STATUS_REJECTED - 计票未通过
PROPOSAL_STATUS_ABORTED - 投票期间组或策略已更新
PROPOSAL_STATUS_WITHDRAWN - 已由提案人或策略管理员撤回

ProposalExecutorResult 取值：

PROPOSAL_EXECUTOR_RESULT_NOT_RUN
PROPOSAL_EXECUTOR_RESULT_SUCCESS
PROPOSAL_EXECUTOR_RESULT_FAILURE

TallyResult

提案的累计投票计数。

message TallyResult {
  string yes_count = 1;
  string abstain_count = 2;
  string no_count = 3;
  string no_with_veto_count = 4;
}

查询 API

Query 服务提供对 Group 模块状态的只读访问。

GroupInfo

按 ID 获取组信息。 gRPC： cosmos.group.v1.Query/GroupInfo REST： GET /cosmos/group/v1/groups/{group_id} CLI：

simd q group group-info [group-id]

示例：

simd q group group-info 1

GroupPolicyInfo

获取组策略账户信息。 gRPC： cosmos.group.v1.Query/GroupPolicyInfo REST： GET /cosmos/group/v1/group_policies/{address} CLI：

simd q group group-policy-info [group-policy-account]

GroupMembers

列出某个组的所有成员。 gRPC： cosmos.group.v1.Query/GroupMembers REST： GET /cosmos/group/v1/groups/{group_id}/members CLI：

simd q group group-members [group-id]

GroupsByAdmin

列出由指定地址管理的所有组。 gRPC： cosmos.group.v1.Query/GroupsByAdmin REST： GET /cosmos/group/v1/groups/by_admin/{admin} CLI：

simd q group groups-by-admin [admin]

GroupPoliciesByGroup

列出与某个组关联的所有组策略。 gRPC： cosmos.group.v1.Query/GroupPoliciesByGroup REST： GET /cosmos/group/v1/groups/{group_id}/group_policies CLI：

simd q group group-policies-by-group [group-id]

GroupPoliciesByAdmin

列出由指定地址管理的所有组策略。 gRPC： cosmos.group.v1.Query/GroupPoliciesByAdmin REST： GET /cosmos/group/v1/group_policies/by_admin/{admin} CLI：

simd q group group-policies-by-admin [admin]

Proposal

按 ID 获取提案。 gRPC： cosmos.group.v1.Query/Proposal REST： GET /cosmos/group/v1/proposals/{proposal_id} CLI：

simd q group proposal [proposal-id]

ProposalsByGroupPolicy

列出某个组策略账户下的所有提案。 gRPC： cosmos.group.v1.Query/ProposalsByGroupPolicy REST： GET /cosmos/group/v1/proposals/by_group_policy/{address} CLI：

simd q group proposals-by-group-policy [group-policy-account]

VoteByProposalVoter

获取提案上的某一条具体投票。 gRPC： cosmos.group.v1.Query/VoteByProposalVoter REST： GET /cosmos/group/v1/votes/{proposal_id}/{voter} CLI：

simd q group vote [proposal-id] [voter]

VotesByProposal

列出某个提案上的所有投票。 gRPC： cosmos.group.v1.Query/VotesByProposal REST： GET /cosmos/group/v1/votes/by_proposal/{proposal_id} CLI：

simd q group votes-by-proposal [proposal-id]

TallyResult

获取提案的当前计票结果。 gRPC： cosmos.group.v1.Query/TallyResult REST： GET /cosmos/group/v1/proposals/{proposal_id}/tally CLI：

simd q group tally-result [proposal-id]

示例响应：

{
  "tally": {
    "yes_count": "2",
    "abstain_count": "0",
    "no_count": "1",
    "no_with_veto_count": "0"
  }
}

Groups

列出链上的所有组。 gRPC： cosmos.group.v1.Query/Groups REST： GET /cosmos/group/v1/groups CLI：

simd q group groups

交易消息（Msg 服务）

CreateGroup

创建一个带有管理员和初始成员的新组。 Msg： MsgCreateGroup CLI：

simd tx group create-group [admin] [metadata] [members-json-file]

成员 JSON 格式：

{
  "members": [
    {
      "address": "cosmos1...",
      "weight": "1",
      "metadata": "member description"
    }
  ]
}

授权： 任何地址都可以创建组。 失败条件：

元数据长度超过 MaxMetadataLen
成员包含无效地址、重复条目或零权重

UpdateGroupMembers

在组中添加、移除或重新设置成员权重。 Msg： MsgUpdateGroupMembers CLI：

simd tx group update-group-members [admin] [group-id] [members-json-file]

注意： 将成员的权重设置为 "0" 可将其从组中移除。 授权： 必须由组管理员签名。 失败条件：

签名者不是组管理员
任一关联组策略的 Validate() 方法在更新后的成员集合上校验失败

UpdateGroupAdmin

将组管理权转移给新地址。 Msg： MsgUpdateGroupAdmin CLI：

simd tx group update-group-admin [admin] [group-id] [new-admin]

授权： 必须由当前组管理员签名。

UpdateGroupMetadata

更新组的元数据。 Msg： MsgUpdateGroupMetadata CLI：

simd tx group update-group-metadata [admin] [group-id] [metadata]

授权： 必须由组管理员签名。

CreateGroupPolicy

创建一个带有决策策略的新组策略账户。 Msg： MsgCreateGroupPolicy CLI：

simd tx group create-group-policy [admin] [group-id] [metadata] [decision-policy-json]

阈值策略示例：

{
  "@type": "/cosmos.group.v1.ThresholdDecisionPolicy",
  "threshold": "2",
  "windows": {
    "voting_period": "24h",
    "min_execution_period": "0s"
  }
}

百分比策略示例：

{
  "@type": "/cosmos.group.v1.PercentageDecisionPolicy",
  "percentage": "0.5",
  "windows": {
    "voting_period": "48h",
    "min_execution_period": "0s"
  }
}

授权： 必须由组管理员签名。 失败条件：

签名者不是组管理员
元数据长度超过 MaxMetadataLen
决策策略的 Validate() 方法针对该组校验失败

CreateGroupWithPolicy

在单笔交易中同时创建组和组策略。 Msg： MsgCreateGroupWithPolicy CLI：

simd tx group create-group-with-policy [admin] [group-metadata] [group-policy-metadata] [members-json-file] [decision-policy-json]

设置 --group-policy-as-admin 可让组策略账户成为组管理员（实现自治组）。

UpdateGroupPolicyAdmin

将组策略管理权转移给新地址。 Msg： MsgUpdateGroupPolicyAdmin CLI：

simd tx group update-group-policy-admin [admin] [group-policy-account] [new-admin]

授权： 必须由组策略管理员签名。

UpdateGroupPolicyDecisionPolicy

更新组策略账户的决策策略。 Msg： MsgUpdateGroupPolicyDecisionPolicy CLI：

simd tx group update-group-policy-decision-policy [admin] [group-policy-account] [decision-policy-json]

授权： 必须由组策略管理员签名。 注意： 更新决策策略会中止该策略下所有进行中的提案。

UpdateGroupPolicyMetadata

更新组策略的元数据。 Msg： MsgUpdateGroupPolicyMetadata CLI：

simd tx group update-group-policy-metadata [admin] [group-policy-account] [metadata]

授权： 必须由组策略管理员签名。

SubmitProposal

向组策略账户提交提案。 Msg： MsgSubmitProposal CLI：

simd tx group submit-proposal [proposal-json-file] \
    --from proposer \
    --keyring-backend test

提案 JSON 格式：

{
  "group_policy_address": "cosmos1...",
  "proposers": ["cosmos1..."],
  "metadata": "proposal description",
  "title": "My Proposal",
  "summary": "A brief description of the proposal",
  "messages": [
    {
      "@type": "/cosmos.bank.v1beta1.MsgSend",
      "from_address": "cosmos1...",
      "to_address": "cosmos1...",
      "amount": [{"denom": "uatom", "amount": "1000"}]
    }
  ],
  "exec": 0
}

将 "exec": 1（EXEC_TRY）可设置为尝试立即执行。使用 EXEC_TRY 时，提案人会自动计为赞成票。 授权： 必须至少由一名组成员签名。 失败条件：

元数据、标题或摘要长度超过 MaxMetadataLen
提案人不是组成员

WithdrawProposal

撤回一个待处理提案。 Msg： MsgWithdrawProposal CLI：

simd tx group withdraw-proposal [proposal-id] [group-policy-admin-or-proposer]

授权： 必须由提案人或组策略管理员签名。 失败条件：

签名者既不是提案人也不是组策略管理员
提案已关闭或已中止

投票

对一个开放中的提案进行投票。 消息： MsgVote CLI：

simd tx group vote [proposal-id] [voter] [vote-option] [metadata]

投票选项：

VOTE_OPTION_YES
VOTE_OPTION_NO
VOTE_OPTION_ABSTAIN
VOTE_OPTION_NO_WITH_VETO

设置 --exec 1 以在投票后尝试立即执行。 授权： 必须由组成员签名。 失败条件：

元数据长度超过 MaxMetadataLen
提案已不再处于投票期

执行

执行一个已被接受的提案。 消息： MsgExec CLI：

simd tx group exec [proposal-id] \
    --from executor \
    --keyring-backend test

授权： 任何地址都可以执行一个已被接受的提案。 说明：

提案必须处于 ACCEPTED 状态
必须在投票期结束后的 MaxExecutionPeriod 内执行
执行失败（PROPOSAL_EXECUTOR_RESULT_FAILURE）后，在过期前可以重试

离开组

将自己从组中移除。 消息： MsgLeaveGroup CLI：

simd tx group leave-group [member-address] [group-id]

授权： 必须由离开的成员签名。 失败条件：

签名者不是组成员
任一关联的组策略在更新后的成员集合上执行其 Validate() 方法时失败

事件

Group 模块会发出以下事件：

事件类型	键	值
`cosmos.group.v1.EventCreateGroup`	`group_id`	`{groupId}`
`cosmos.group.v1.EventUpdateGroup`	`group_id`	`{groupId}`
`cosmos.group.v1.EventCreateGroupPolicy`	`address`	`{groupPolicyAddress}`
`cosmos.group.v1.EventUpdateGroupPolicy`	`address`	`{groupPolicyAddress}`
`cosmos.group.v1.EventCreateProposal`	`proposal_id`	`{proposalId}`
`cosmos.group.v1.EventWithdrawProposal`	`proposal_id`	`{proposalId}`
`cosmos.group.v1.EventVote`	`proposal_id`	`{proposalId}`
`cosmos.group.v1.EventExec`	`proposal_id`, `logs`	`{proposalId}`, `{logs}`
`cosmos.group.v1.EventLeaveGroup`	`proposal_id`, `address`	`{proposalId}`, `{address}`
`cosmos.group.v1.EventProposalPruned`	`proposal_id`, `status`, `tally_result`	清理详情

REST API 端点

方法	端点	描述
GET	`/cosmos/group/v1/groups/{group_id}`	获取组信息
GET	`/cosmos/group/v1/groups/by_admin/{admin}`	按管理员列出组
GET	`/cosmos/group/v1/groups`	列出所有组
GET	`/cosmos/group/v1/groups/{group_id}/members`	列出组成员
GET	`/cosmos/group/v1/group_policies/{address}`	获取组策略信息
GET	`/cosmos/group/v1/groups/{group_id}/group_policies`	列出组的策略
GET	`/cosmos/group/v1/group_policies/by_admin/{admin}`	按管理员列出策略
GET	`/cosmos/group/v1/proposals/{proposal_id}`	获取提案
GET	`/cosmos/group/v1/proposals/by_group_policy/{address}`	列出某策略的提案
GET	`/cosmos/group/v1/proposals/{proposal_id}/tally`	获取计票结果
GET	`/cosmos/group/v1/votes/{proposal_id}/{voter}`	获取某个特定投票
GET	`/cosmos/group/v1/votes/by_proposal/{proposal_id}`	列出某提案的投票

常见用例

1. 创建一个 2/3 多签组

# Create the group with 3 members of equal weight
simd tx group create-group cosmos1admin "" members.json --from admin


# members.json
{
  "members": [
    {"address": "cosmos1alice...", "weight": "1"},
    {"address": "cosmos1bob...",   "weight": "1"},
    {"address": "cosmos1carol...", "weight": "1"}
  ]
}


# Create a policy requiring 2 of 3 yes votes
simd tx group create-group-policy cosmos1admin 1 "" policy.json --from admin


# policy.json (threshold = 2)
{
  "@type": "/cosmos.group.v1.ThresholdDecisionPolicy",
  "threshold": "2",
  "windows": {"voting_period": "72h", "min_execution_period": "0s"}
}

2. 提交并执行提案

# Alice submits a proposal
simd tx group submit-proposal proposal.json --from alice


# Bob and Carol vote yes
simd tx group vote 1 cosmos1bob YES "" --from bob
simd tx group vote 1 cosmos1carol YES "" --from carol


# Anyone executes the accepted proposal
simd tx group exec 1 --from alice

3. 自治理组（策略作为管理员）

# Create group with policy as its own admin
simd tx group create-group-with-policy cosmos1admin "" "" members.json policy.json \
    --group-policy-as-admin \
    --from admin

4. 为不同操作设置多个策略

# Low-threshold policy for routine actions (1-of-3)
simd tx group create-group-policy cosmos1admin 1 "routine" low_policy.json --from admin


# High-threshold policy for critical actions (3-of-3)
simd tx group create-group-policy cosmos1admin 1 "critical" high_policy.json --from admin

Group Module API Reference

Overview

The Group module provides a comprehensive API for managing on-chain multisig groups and collective decision-making. Package: cosmos.group.v1 Go Import: github.com/cosmos/cosmos-sdk/enterprise/group/x/group

Data Types

GroupInfo

Represents a group on-chain.

message GroupInfo {
  uint64 id = 1;
  string admin = 2;
  bytes metadata = 3;
  uint64 version = 4;
  string total_weight = 5;
  google.protobuf.Timestamp created_at = 6;
}

Fields:

id (uint64): Unique group identifier, auto-assigned on creation
admin (string): Cosmos SDK address of the group administrator
metadata (bytes): Optional group metadata
version (uint64): Incremented on every group update; used to detect stale proposals
total_weight (string): Sum of all member weights
created_at (Timestamp): Block time when the group was created

GroupMember

Represents a member’s relationship to a group.

message GroupMember {
  uint64 group_id = 1;
  Member member = 2;
}

message Member {
  string address = 1;
  string weight = 2;
  bytes metadata = 3;
  google.protobuf.Timestamp added_at = 4;
}

Fields:

address (string): Cosmos SDK address of the member
weight (string): Voting weight. Set to "0" to remove a member.
metadata (bytes): Optional member metadata
added_at (Timestamp): Block time when the member was added

GroupPolicyInfo

Represents a group policy account.

message GroupPolicyInfo {
  string address = 1;
  uint64 group_id = 2;
  string admin = 3;
  bytes metadata = 4;
  uint64 version = 5;
  google.protobuf.Any decision_policy = 6;
  google.protobuf.Timestamp created_at = 7;
}

Fields:

address (string): The group policy’s account address (auto-generated)
group_id (uint64): The group this policy is associated with
admin (string): Address with authority to update the policy
decision_policy (Any): The policy’s decision logic (threshold or percentage)
version (uint64): Incremented on every update; used to detect aborted proposals

Proposal

Represents an on-chain proposal submitted to a group policy.

message Proposal {
  uint64 id = 1;
  string group_policy_address = 2;
  bytes metadata = 3;
  repeated string proposers = 4;
  google.protobuf.Timestamp submit_time = 5;
  uint64 group_version = 6;
  uint64 group_policy_version = 7;
  ProposalStatus status = 8;
  TallyResult final_tally_result = 9;
  google.protobuf.Timestamp voting_period_end = 10;
  ProposalExecutorResult executor_result = 11;
  repeated google.protobuf.Any messages = 12;
  string title = 13;
  string summary = 14;
}

ProposalStatus values:

PROPOSAL_STATUS_SUBMITTED - Open for voting
PROPOSAL_STATUS_ACCEPTED - Passed; ready for execution
PROPOSAL_STATUS_REJECTED - Failed tally
PROPOSAL_STATUS_ABORTED - Group or policy updated during voting
PROPOSAL_STATUS_WITHDRAWN - Withdrawn by proposer or policy admin

ProposalExecutorResult values:

PROPOSAL_EXECUTOR_RESULT_NOT_RUN
PROPOSAL_EXECUTOR_RESULT_SUCCESS
PROPOSAL_EXECUTOR_RESULT_FAILURE

TallyResult

The accumulated vote counts for a proposal.

message TallyResult {
  string yes_count = 1;
  string abstain_count = 2;
  string no_count = 3;
  string no_with_veto_count = 4;
}

Query API

The Query service provides read-only access to Group module state.

GroupInfo

Get information about a group by ID. gRPC: cosmos.group.v1.Query/GroupInfo REST: GET /cosmos/group/v1/groups/{group_id} CLI:

simd q group group-info [group-id]

Example:

simd q group group-info 1

GroupPolicyInfo

Get information about a group policy account. gRPC: cosmos.group.v1.Query/GroupPolicyInfo REST: GET /cosmos/group/v1/group_policies/{address} CLI:

simd q group group-policy-info [group-policy-account]

GroupMembers

List all members of a group. gRPC: cosmos.group.v1.Query/GroupMembers REST: GET /cosmos/group/v1/groups/{group_id}/members CLI:

simd q group group-members [group-id]

GroupsByAdmin

List all groups administered by a given address. gRPC: cosmos.group.v1.Query/GroupsByAdmin REST: GET /cosmos/group/v1/groups/by_admin/{admin} CLI:

simd q group groups-by-admin [admin]

GroupPoliciesByGroup

List all group policies associated with a group. gRPC: cosmos.group.v1.Query/GroupPoliciesByGroup REST: GET /cosmos/group/v1/groups/{group_id}/group_policies CLI:

simd q group group-policies-by-group [group-id]

GroupPoliciesByAdmin

List all group policies administered by a given address. gRPC: cosmos.group.v1.Query/GroupPoliciesByAdmin REST: GET /cosmos/group/v1/group_policies/by_admin/{admin} CLI:

simd q group group-policies-by-admin [admin]

Proposal

Get a proposal by ID. gRPC: cosmos.group.v1.Query/Proposal REST: GET /cosmos/group/v1/proposals/{proposal_id} CLI:

simd q group proposal [proposal-id]

ProposalsByGroupPolicy

List all proposals for a given group policy account. gRPC: cosmos.group.v1.Query/ProposalsByGroupPolicy REST: GET /cosmos/group/v1/proposals/by_group_policy/{address} CLI:

simd q group proposals-by-group-policy [group-policy-account]

VoteByProposalVoter

Get a specific vote on a proposal. gRPC: cosmos.group.v1.Query/VoteByProposalVoter REST: GET /cosmos/group/v1/votes/{proposal_id}/{voter} CLI:

simd q group vote [proposal-id] [voter]

VotesByProposal

List all votes on a proposal. gRPC: cosmos.group.v1.Query/VotesByProposal REST: GET /cosmos/group/v1/votes/by_proposal/{proposal_id} CLI:

simd q group votes-by-proposal [proposal-id]

TallyResult

Get the current tally for a proposal. gRPC: cosmos.group.v1.Query/TallyResult REST: GET /cosmos/group/v1/proposals/{proposal_id}/tally CLI:

simd q group tally-result [proposal-id]

Example Response:

{
  "tally": {
    "yes_count": "2",
    "abstain_count": "0",
    "no_count": "1",
    "no_with_veto_count": "0"
  }
}

Groups

List all groups on chain. gRPC: cosmos.group.v1.Query/Groups REST: GET /cosmos/group/v1/groups CLI:

simd q group groups

Transaction Messages (Msg Service)

CreateGroup

Create a new group with an admin and initial members. Msg: MsgCreateGroup CLI:

simd tx group create-group [admin] [metadata] [members-json-file]

Members JSON format:

{
  "members": [
    {
      "address": "cosmos1...",
      "weight": "1",
      "metadata": "member description"
    }
  ]
}

Authorization: Any address can create a group. Failure conditions:

Metadata length exceeds MaxMetadataLen
Members have invalid addresses, duplicate entries, or zero weight

UpdateGroupMembers

Add, remove, or reweight members in a group. Msg: MsgUpdateGroupMembers CLI:

simd tx group update-group-members [admin] [group-id] [members-json-file]

Note: Set a member’s weight to "0" to remove them from the group. Authorization: Must be signed by the group admin. Failure conditions:

Signer is not the group admin
Any associated group policy’s Validate() method fails against the updated member set

UpdateGroupAdmin

Transfer group administration to a new address. Msg: MsgUpdateGroupAdmin CLI:

simd tx group update-group-admin [admin] [group-id] [new-admin]

Authorization: Must be signed by the current group admin.

UpdateGroupMetadata

Update a group’s metadata. Msg: MsgUpdateGroupMetadata CLI:

simd tx group update-group-metadata [admin] [group-id] [metadata]

Authorization: Must be signed by the group admin.

CreateGroupPolicy

Create a new group policy account with a decision policy. Msg: MsgCreateGroupPolicy CLI:

simd tx group create-group-policy [admin] [group-id] [metadata] [decision-policy-json]

Threshold policy example:

{
  "@type": "/cosmos.group.v1.ThresholdDecisionPolicy",
  "threshold": "2",
  "windows": {
    "voting_period": "24h",
    "min_execution_period": "0s"
  }
}

Percentage policy example:

{
  "@type": "/cosmos.group.v1.PercentageDecisionPolicy",
  "percentage": "0.5",
  "windows": {
    "voting_period": "48h",
    "min_execution_period": "0s"
  }
}

Authorization: Must be signed by the group admin. Failure conditions:

Signer is not the group admin
Metadata length exceeds MaxMetadataLen
Decision policy’s Validate() method fails against the group

CreateGroupWithPolicy

Create a group and a group policy in a single transaction. Msg: MsgCreateGroupWithPolicy CLI:

simd tx group create-group-with-policy [admin] [group-metadata] [group-policy-metadata] [members-json-file] [decision-policy-json]

Set --group-policy-as-admin to make the group policy account the group admin (enabling a self-governed group).

UpdateGroupPolicyAdmin

Transfer group policy administration to a new address. Msg: MsgUpdateGroupPolicyAdmin CLI:

simd tx group update-group-policy-admin [admin] [group-policy-account] [new-admin]

Authorization: Must be signed by the group policy admin.

UpdateGroupPolicyDecisionPolicy

Update the decision policy for a group policy account. Msg: MsgUpdateGroupPolicyDecisionPolicy CLI:

simd tx group update-group-policy-decision-policy [admin] [group-policy-account] [decision-policy-json]

Authorization: Must be signed by the group policy admin. Note: Updating the decision policy aborts any in-flight proposals for that policy.

UpdateGroupPolicyMetadata

Update a group policy’s metadata. Msg: MsgUpdateGroupPolicyMetadata CLI:

simd tx group update-group-policy-metadata [admin] [group-policy-account] [metadata]

Authorization: Must be signed by the group policy admin.

SubmitProposal

Submit a proposal to a group policy account. Msg: MsgSubmitProposal CLI:

simd tx group submit-proposal [proposal-json-file] \
    --from proposer \
    --keyring-backend test

Proposal JSON format:

{
  "group_policy_address": "cosmos1...",
  "proposers": ["cosmos1..."],
  "metadata": "proposal description",
  "title": "My Proposal",
  "summary": "A brief description of the proposal",
  "messages": [
    {
      "@type": "/cosmos.bank.v1beta1.MsgSend",
      "from_address": "cosmos1...",
      "to_address": "cosmos1...",
      "amount": [{"denom": "uatom", "amount": "1000"}]
    }
  ],
  "exec": 0
}

Set "exec": 1 (EXEC_TRY) to attempt immediate execution. When using EXEC_TRY, proposers are automatically counted as yes votes. Authorization: Must be signed by at least one group member. Failure conditions:

Metadata, title, or summary length exceeds MaxMetadataLen
Proposer is not a group member

WithdrawProposal

Withdraw a pending proposal. Msg: MsgWithdrawProposal CLI:

simd tx group withdraw-proposal [proposal-id] [group-policy-admin-or-proposer]

Authorization: Must be signed by a proposer or the group policy admin. Failure conditions:

Signer is neither a proposer nor the group policy admin
Proposal is already closed or aborted

Vote

Cast a vote on an open proposal. Msg: MsgVote CLI:

simd tx group vote [proposal-id] [voter] [vote-option] [metadata]

Vote options:

VOTE_OPTION_YES
VOTE_OPTION_NO
VOTE_OPTION_ABSTAIN
VOTE_OPTION_NO_WITH_VETO

Set --exec 1 to attempt immediate execution after voting. Authorization: Must be signed by a group member. Failure conditions:

Metadata length exceeds MaxMetadataLen
Proposal is no longer in the voting period

Exec

Execute an accepted proposal. Msg: MsgExec CLI:

simd tx group exec [proposal-id] \
    --from executor \
    --keyring-backend test

Authorization: Any address can execute an accepted proposal. Notes:

Proposal must be in ACCEPTED status
Execution must occur before MaxExecutionPeriod after the voting period ends
A failed execution (PROPOSAL_EXECUTOR_RESULT_FAILURE) can be retried until expiry

LeaveGroup

Remove yourself from a group. Msg: MsgLeaveGroup CLI:

simd tx group leave-group [member-address] [group-id]

Authorization: Must be signed by the member leaving. Failure conditions:

Signer is not a group member
Any associated group policy’s Validate() method fails against the updated member set

Events

The Group module emits the following events:

Event Type	Key	Value
`cosmos.group.v1.EventCreateGroup`	`group_id`	`{groupId}`
`cosmos.group.v1.EventUpdateGroup`	`group_id`	`{groupId}`
`cosmos.group.v1.EventCreateGroupPolicy`	`address`	`{groupPolicyAddress}`
`cosmos.group.v1.EventUpdateGroupPolicy`	`address`	`{groupPolicyAddress}`
`cosmos.group.v1.EventCreateProposal`	`proposal_id`	`{proposalId}`
`cosmos.group.v1.EventWithdrawProposal`	`proposal_id`	`{proposalId}`
`cosmos.group.v1.EventVote`	`proposal_id`	`{proposalId}`
`cosmos.group.v1.EventExec`	`proposal_id`, `logs`	`{proposalId}`, `{logs}`
`cosmos.group.v1.EventLeaveGroup`	`proposal_id`, `address`	`{proposalId}`, `{address}`
`cosmos.group.v1.EventProposalPruned`	`proposal_id`, `status`, `tally_result`	pruning details

REST API Endpoints

Method	Endpoint	Description
GET	`/cosmos/group/v1/groups/{group_id}`	Get group info
GET	`/cosmos/group/v1/groups/by_admin/{admin}`	List groups by admin
GET	`/cosmos/group/v1/groups`	List all groups
GET	`/cosmos/group/v1/groups/{group_id}/members`	List group members
GET	`/cosmos/group/v1/group_policies/{address}`	Get group policy info
GET	`/cosmos/group/v1/groups/{group_id}/group_policies`	List policies for a group
GET	`/cosmos/group/v1/group_policies/by_admin/{admin}`	List policies by admin
GET	`/cosmos/group/v1/proposals/{proposal_id}`	Get proposal
GET	`/cosmos/group/v1/proposals/by_group_policy/{address}`	List proposals for a policy
GET	`/cosmos/group/v1/proposals/{proposal_id}/tally`	Get tally result
GET	`/cosmos/group/v1/votes/{proposal_id}/{voter}`	Get a specific vote
GET	`/cosmos/group/v1/votes/by_proposal/{proposal_id}`	List votes for a proposal

Common Use Cases

1. Create a 2-of-3 Multisig Group

# Create the group with 3 members of equal weight
simd tx group create-group cosmos1admin "" members.json --from admin

# members.json
{
  "members": [
    {"address": "cosmos1alice...", "weight": "1"},
    {"address": "cosmos1bob...",   "weight": "1"},
    {"address": "cosmos1carol...", "weight": "1"}
  ]
}

# Create a policy requiring 2 of 3 yes votes
simd tx group create-group-policy cosmos1admin 1 "" policy.json --from admin

# policy.json (threshold = 2)
{
  "@type": "/cosmos.group.v1.ThresholdDecisionPolicy",
  "threshold": "2",
  "windows": {"voting_period": "72h", "min_execution_period": "0s"}
}

2. Submit and Execute a Proposal

# Alice submits a proposal
simd tx group submit-proposal proposal.json --from alice

# Bob and Carol vote yes
simd tx group vote 1 cosmos1bob YES "" --from bob
simd tx group vote 1 cosmos1carol YES "" --from carol

# Anyone executes the accepted proposal
simd tx group exec 1 --from alice

3. Self-Governing Group (Policy as Admin)

# Create group with policy as its own admin
simd tx group create-group-with-policy cosmos1admin "" "" members.json policy.json \
    --group-policy-as-admin \
    --from admin

4. Multiple Policies for Different Actions

# Low-threshold policy for routine actions (1-of-3)
simd tx group create-group-policy cosmos1admin 1 "routine" low_policy.json --from admin

# High-threshold policy for critical actions (3-of-3)
simd tx group create-group-policy cosmos1admin 1 "critical" high_policy.json --from admin

​Group 模块 API 参考

​概述

​数据类型

​GroupInfo

​GroupMember

​GroupPolicyInfo

​Proposal

​TallyResult

​查询 API

​GroupInfo

​GroupPolicyInfo

​GroupMembers

​GroupsByAdmin

​GroupPoliciesByGroup

​GroupPoliciesByAdmin

​Proposal

​ProposalsByGroupPolicy

​VoteByProposalVoter

​VotesByProposal

​TallyResult

​Groups

​交易消息（Msg 服务）

​CreateGroup

​UpdateGroupMembers

​UpdateGroupAdmin

​UpdateGroupMetadata

​CreateGroupPolicy

​CreateGroupWithPolicy

​UpdateGroupPolicyAdmin

​UpdateGroupPolicyDecisionPolicy

​UpdateGroupPolicyMetadata

​SubmitProposal

​WithdrawProposal

​投票

​执行

​离开组

​事件

​REST API 端点

​常见用例

​1. 创建一个 2/3 多签组

​2. 提交并执行提案

​3. 自治理组（策略作为管理员）

​4. 为不同操作设置多个策略

​Group Module API Reference

​Overview

​Data Types

​GroupInfo

​GroupMember

​GroupPolicyInfo

​Proposal

​TallyResult

​Query API

​GroupInfo

​GroupPolicyInfo

​GroupMembers

​GroupsByAdmin

​GroupPoliciesByGroup

​GroupPoliciesByAdmin

​Proposal

​ProposalsByGroupPolicy

​VoteByProposalVoter

​VotesByProposal

​TallyResult

​Groups

​Transaction Messages (Msg Service)

​CreateGroup

​UpdateGroupMembers

​UpdateGroupAdmin

​UpdateGroupMetadata

​CreateGroupPolicy

​CreateGroupWithPolicy

​UpdateGroupPolicyAdmin

​UpdateGroupPolicyDecisionPolicy

​UpdateGroupPolicyMetadata

​SubmitProposal

​WithdrawProposal

​Vote

​Exec

​LeaveGroup

​Events

Group 模块 API 参考

概述

数据类型

GroupInfo

GroupMember

GroupPolicyInfo

Proposal

TallyResult

查询 API

GroupInfo

GroupPolicyInfo

GroupMembers

GroupsByAdmin

GroupPoliciesByGroup

GroupPoliciesByAdmin

Proposal

ProposalsByGroupPolicy

VoteByProposalVoter

VotesByProposal

TallyResult

Groups

交易消息（Msg 服务）

CreateGroup

UpdateGroupMembers

UpdateGroupAdmin

UpdateGroupMetadata

CreateGroupPolicy

CreateGroupWithPolicy

UpdateGroupPolicyAdmin

UpdateGroupPolicyDecisionPolicy

UpdateGroupPolicyMetadata

SubmitProposal

WithdrawProposal

投票

执行

离开组

事件

REST API 端点

常见用例

1. 创建一个 2/3 多签组

2. 提交并执行提案

3. 自治理组（策略作为管理员）

4. 为不同操作设置多个策略

Group Module API Reference

Overview

Data Types

GroupInfo

GroupMember

GroupPolicyInfo

Proposal

TallyResult

Query API

GroupInfo

GroupPolicyInfo

GroupMembers

GroupsByAdmin

GroupPoliciesByGroup

GroupPoliciesByAdmin

Proposal

ProposalsByGroupPolicy

VoteByProposalVoter

VotesByProposal

TallyResult

Groups

Transaction Messages (Msg Service)

CreateGroup

UpdateGroupMembers

UpdateGroupAdmin

UpdateGroupMetadata

CreateGroupPolicy

CreateGroupWithPolicy

UpdateGroupPolicyAdmin

UpdateGroupPolicyDecisionPolicy

UpdateGroupPolicyMetadata

SubmitProposal

WithdrawProposal

Vote

Exec

LeaveGroup

Events