Group
Abstract
The following documents specify the group module.
This module allows the creation and management of on-chain multisig accounts and enables voting for message execution based on configurable decision policies.
Contents
Concepts
Group
A group is simply an aggregation of accounts with associated weights. It is not an account and doesn't have a balance. It doesn't in and of itself have any sort of voting or decision weight. It does have an "administrator" which has the ability to add, remove and update members in the group. Note that a group policy account could be an administrator of a group, and that the administrator doesn't necessarily have to be a member of the group.
Group Policy
A group policy is an account associated with a group and a decision policy. Group policies are abstracted from groups because a single group may have multiple decision policies for different types of actions. Managing group membership separately from decision policies results in the least overhead and keeps membership consistent across different policies. The pattern that is recommended is to have a single master group policy for a given group, and then to create separate group policies with different decision policies and delegate the desired permissions from the master account to those "sub-accounts" using the x/authz
module.
Decision Policy
A decision policy is the mechanism by which members of a group can vote on proposals, as well as the rules that dictate whether a proposal should pass or not based on its tally outcome.
All decision policies generally would have a mininum execution period and a maximum voting window. The minimum execution period is the minimum amount of time that must pass after submission in order for a proposal to potentially be executed, and it may be set to 0. The maximum voting window is the maximum time after submission that a proposal may be voted on before it is tallied.
The chain developer also defines an app-wide maximum execution period, which is the maximum amount of time after a proposal's voting period end where users are allowed to execute a proposal.
The current group module comes shipped with two decision policies: threshold and percentage. Any chain developer can extend upon these two, by creating custom decision policies, as long as they adhere to the DecisionPolicy
interface:
Threshold decision policy
A threshold decision policy defines a threshold of yes votes (based on a tally of voter weights) that must be achieved in order for a proposal to pass. For this decision policy, abstain and veto are simply treated as no's.
This decision policy also has a VotingPeriod window and a MinExecutionPeriod window. The former defines the duration after proposal submission where members are allowed to vote, after which tallying is performed. The latter specifies the minimum duration after proposal submission where the proposal can be executed. If set to 0, then the proposal is allowed to be executed immediately on submission (using the TRY_EXEC
option). Obviously, MinExecutionPeriod cannot be greater than VotingPeriod+MaxExecutionPeriod (where MaxExecution is the app-defined duration that specifies the window after voting ended where a proposal can be executed).
Percentage decision policy
A percentage decision policy is similar to a threshold decision policy, except that the threshold is not defined as a constant weight, but as a percentage. It's more suited for groups where the group members' weights can be updated, as the percentage threshold stays the same, and doesn't depend on how those member weights get updated.
Same as the Threshold decision policy, the percentage decision policy has the two VotingPeriod and MinExecutionPeriod parameters.
Proposal
Any member(s) of a group can submit a proposal for a group policy account to decide upon. A proposal consists of a set of messages that will be executed if the proposal passes as well as any metadata associated with the proposal.
Voting
There are four choices to choose while voting - yes, no, abstain and veto. Not all decision policies will take the four choices into account. Votes can contain some optional metadata. In the current implementation, the voting window begins as soon as a proposal is submitted, and the end is defined by the group policy's decision policy.
Withdrawing Proposals
Proposals can be withdrawn any time before the voting period end, either by the admin of the group policy or by one of the proposers. Once withdrawn, it is marked as PROPOSAL_STATUS_WITHDRAWN
, and no more voting or execution is allowed on it.
Aborted Proposals
If the group policy is updated during the voting period of the proposal, then the proposal is marked as PROPOSAL_STATUS_ABORTED
, and no more voting or execution is allowed on it. This is because the group policy defines the rules of proposal voting and execution, so if those rules change during the lifecycle of a proposal, then the proposal should be marked as stale.
Tallying
Tallying is the counting of all votes on a proposal. It happens only once in the lifecycle of a proposal, but can be triggered by two factors, whichever happens first:
either someone tries to execute the proposal (see next section), which can happen on a
Msg/Exec
transaction, or aMsg/{SubmitProposal,Vote}
transaction with theExec
field set. When a proposal execution is attempted, a tally is done first to make sure the proposal passes.or on
EndBlock
when the proposal's voting period end just passed.
If the tally result passes the decision policy's rules, then the proposal is marked as PROPOSAL_STATUS_ACCEPTED
, or else it is marked as PROPOSAL_STATUS_REJECTED
. In any case, no more voting is allowed anymore, and the tally result is persisted to state in the proposal's FinalTallyResult
.
Executing Proposals
Proposals are executed only when the tallying is done, and the group account's decision policy allows the proposal to pass based on the tally outcome. They are marked by the status PROPOSAL_STATUS_ACCEPTED
. Execution must happen before a duration of MaxExecutionPeriod
(set by the chain developer) after each proposal's voting period end.
Proposals will not be automatically executed by the chain in this current design, but rather a user must submit a Msg/Exec
transaction to attempt to execute the proposal based on the current votes and decision policy. Any user (not only the group members) can execute proposals that have been accepted, and execution fees are paid by the proposal executor. It's also possible to try to execute a proposal immediately on creation or on new votes using the Exec
field of Msg/SubmitProposal
and Msg/Vote
requests. In the former case, proposers signatures are considered as yes votes. In these cases, if the proposal can't be executed (i.e. it didn't pass the decision policy's rules), it will still be opened for new votes and could be tallied and executed later on.
A successful proposal execution will have its ExecutorResult
marked as PROPOSAL_EXECUTOR_RESULT_SUCCESS
. The proposal will be automatically pruned after execution. On the other hand, a failed proposal execution will be marked as PROPOSAL_EXECUTOR_RESULT_FAILURE
. Such a proposal can be re-executed multiple times, until it expires after MaxExecutionPeriod
after voting period end.
Pruning
Proposals and votes are automatically pruned to avoid state bloat.
Votes are pruned:
either after a successful tally, i.e. a tally whose result passes the decision policy's rules, which can be trigged by a
Msg/Exec
or aMsg/{SubmitProposal,Vote}
with theExec
field set,or on
EndBlock
right after the proposal's voting period end. This applies to proposals with statusaborted
orwithdrawn
too.
whichever happens first.
Proposals are pruned:
on
EndBlock
whose proposal status iswithdrawn
oraborted
on proposal's voting period end before tallying,and either after a successful proposal execution,
or on
EndBlock
right after the proposal'svoting_period_end
+max_execution_period
(defined as an app-wide configuration) is passed,
whichever happens first.
State
The group
module uses the orm
package which provides table storage with support for primary keys and secondary indexes. orm
also defines Sequence
which is a persistent unique key generator based on a counter that can be used along with Table
s.
Here's the list of tables and associated sequences and indexes stored as part of the group
module.
Group Table
The groupTable
stores GroupInfo
: 0x0 | BigEndian(GroupId) -> ProtocolBuffer(GroupInfo)
.
groupSeq
The value of groupSeq
is incremented when creating a new group and corresponds to the new GroupId
: 0x1 | 0x1 -> BigEndian
.
The second 0x1
corresponds to the ORM sequenceStorageKey
.
groupByAdminIndex
groupByAdminIndex
allows to retrieve groups by admin address: 0x2 | len([]byte(group.Admin)) | []byte(group.Admin) | BigEndian(GroupId) -> []byte()
.
Group Member Table
The groupMemberTable
stores GroupMember
s: 0x10 | BigEndian(GroupId) | []byte(member.Address) -> ProtocolBuffer(GroupMember)
.
The groupMemberTable
is a primary key table and its PrimaryKey
is given by BigEndian(GroupId) | []byte(member.Address)
which is used by the following indexes.
groupMemberByGroupIndex
groupMemberByGroupIndex
allows to retrieve group members by group id: 0x11 | BigEndian(GroupId) | PrimaryKey -> []byte()
.
groupMemberByMemberIndex
groupMemberByMemberIndex
allows to retrieve group members by member address: 0x12 | len([]byte(member.Address)) | []byte(member.Address) | PrimaryKey -> []byte()
.
Group Policy Table
The groupPolicyTable
stores GroupPolicyInfo
: 0x20 | len([]byte(Address)) | []byte(Address) -> ProtocolBuffer(GroupPolicyInfo)
.
The groupPolicyTable
is a primary key table and its PrimaryKey
is given by len([]byte(Address)) | []byte(Address)
which is used by the following indexes.
groupPolicySeq
The value of groupPolicySeq
is incremented when creating a new group policy and is used to generate the new group policy account Address
: 0x21 | 0x1 -> BigEndian
.
The second 0x1
corresponds to the ORM sequenceStorageKey
.
groupPolicyByGroupIndex
groupPolicyByGroupIndex
allows to retrieve group policies by group id: 0x22 | BigEndian(GroupId) | PrimaryKey -> []byte()
.
groupPolicyByAdminIndex
groupPolicyByAdminIndex
allows to retrieve group policies by admin address: 0x23 | len([]byte(Address)) | []byte(Address) | PrimaryKey -> []byte()
.
Proposal Table
The proposalTable
stores Proposal
s: 0x30 | BigEndian(ProposalId) -> ProtocolBuffer(Proposal)
.
proposalSeq
The value of proposalSeq
is incremented when creating a new proposal and corresponds to the new ProposalId
: 0x31 | 0x1 -> BigEndian
.
The second 0x1
corresponds to the ORM sequenceStorageKey
.
proposalByGroupPolicyIndex
proposalByGroupPolicyIndex
allows to retrieve proposals by group policy account address: 0x32 | len([]byte(account.Address)) | []byte(account.Address) | BigEndian(ProposalId) -> []byte()
.
ProposalsByVotingPeriodEndIndex
proposalsByVotingPeriodEndIndex
allows to retrieve proposals sorted by chronological voting_period_end
: 0x33 | sdk.FormatTimeBytes(proposal.VotingPeriodEnd) | BigEndian(ProposalId) -> []byte()
.
This index is used when tallying the proposal votes at the end of the voting period, and for pruning proposals at VotingPeriodEnd + MaxExecutionPeriod
.
Vote Table
The voteTable
stores Vote
s: 0x40 | BigEndian(ProposalId) | []byte(voter.Address) -> ProtocolBuffer(Vote)
.
The voteTable
is a primary key table and its PrimaryKey
is given by BigEndian(ProposalId) | []byte(voter.Address)
which is used by the following indexes.
voteByProposalIndex
voteByProposalIndex
allows to retrieve votes by proposal id: 0x41 | BigEndian(ProposalId) | PrimaryKey -> []byte()
.
voteByVoterIndex
voteByVoterIndex
allows to retrieve votes by voter address: 0x42 | len([]byte(voter.Address)) | []byte(voter.Address) | PrimaryKey -> []byte()
.
Msg Service
Msg/CreateGroup
A new group can be created with the MsgCreateGroup
, which has an admin address, a list of members and some optional metadata.
The metadata has a maximum length that is chosen by the app developer, and passed into the group keeper as a config.
It's expected to fail if
metadata length is greater than
MaxMetadataLen
configmembers are not correctly set (e.g. wrong address format, duplicates, or with 0 weight).
Msg/UpdateGroupMembers
Group members can be updated with the UpdateGroupMembers
.
In the list of MemberUpdates
, an existing member can be removed by setting its weight to 0.
It's expected to fail if:
the signer is not the admin of the group.
for any one of the associated group policies, if its decision policy's
Validate()
method fails against the updated group.
Msg/UpdateGroupAdmin
The UpdateGroupAdmin
can be used to update a group admin.
It's expected to fail if the signer is not the admin of the group.
Msg/UpdateGroupMetadata
The UpdateGroupMetadata
can be used to update a group metadata.
It's expected to fail if:
new metadata length is greater than
MaxMetadataLen
config.the signer is not the admin of the group.
Msg/CreateGroupPolicy
A new group policy can be created with the MsgCreateGroupPolicy
, which has an admin address, a group id, a decision policy and some optional metadata.
It's expected to fail if:
the signer is not the admin of the group.
metadata length is greater than
MaxMetadataLen
config.the decision policy's
Validate()
method doesn't pass against the group.
Msg/CreateGroupWithPolicy
A new group with policy can be created with the MsgCreateGroupWithPolicy
, which has an admin address, a list of members, a decision policy, a group_policy_as_admin
field to optionally set group and group policy admin with group policy address and some optional metadata for group and group policy.
It's expected to fail for the same reasons as Msg/CreateGroup
and Msg/CreateGroupPolicy
.
Msg/UpdateGroupPolicyAdmin
The UpdateGroupPolicyAdmin
can be used to update a group policy admin.
It's expected to fail if the signer is not the admin of the group policy.
Msg/UpdateGroupPolicyDecisionPolicy
The UpdateGroupPolicyDecisionPolicy
can be used to update a decision policy.
It's expected to fail if:
the signer is not the admin of the group policy.
the new decision policy's
Validate()
method doesn't pass against the group.
Msg/UpdateGroupPolicyMetadata
The UpdateGroupPolicyMetadata
can be used to update a group policy metadata.
It's expected to fail if:
new metadata length is greater than
MaxMetadataLen
config.the signer is not the admin of the group.
Msg/SubmitProposal
A new proposal can be created with the MsgSubmitProposal
, which has a group policy account address, a list of proposers addresses, a list of messages to execute if the proposal is accepted and some optional metadata. An optional Exec
value can be provided to try to execute the proposal immediately after proposal creation. Proposers signatures are considered as yes votes in this case.
It's expected to fail if:
metadata, title, or summary length is greater than
MaxMetadataLen
config.if any of the proposers is not a group member.
Msg/WithdrawProposal
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).
It's expected to fail if:
the signer is neither the group policy admin nor proposer of the proposal.
the proposal is already closed or aborted.
Msg/Vote
A new vote can be created with the MsgVote
, given a proposal id, a voter address, a choice (yes, no, veto or abstain) and some optional metadata. An optional Exec
value can be provided to try to execute the proposal immediately after voting.
It's expected to fail if:
metadata length is greater than
MaxMetadataLen
config.the proposal is not in voting period anymore.
Msg/Exec
A proposal can be executed with the MsgExec
.
The messages that are part of this proposal won't be executed if:
the proposal has not been accepted by the group policy.
the proposal has already been successfully executed.
Msg/LeaveGroup
The MsgLeaveGroup
allows group member to leave a group.
It's expected to fail if:
the group member is not part of the group.
for any one of the associated group policies, if its decision policy's
Validate()
method fails against the updated group.
Events
The group module emits the following events:
EventCreateGroup
Type | Attribute Key | Attribute Value |
---|---|---|
message | action | /cosmos.group.v1.Msg/CreateGroup |
cosmos.group.v1.EventCreateGroup | group_id | {groupId} |
EventUpdateGroup
Type | Attribute Key | Attribute Value |
---|---|---|
message | action | /cosmos.group.v1.Msg/UpdateGroup{Admin|Metadata|Members} |
cosmos.group.v1.EventUpdateGroup | group_id | {groupId} |
EventCreateGroupPolicy
Type | Attribute Key | Attribute Value |
---|---|---|
message | action | /cosmos.group.v1.Msg/CreateGroupPolicy |
cosmos.group.v1.EventCreateGroupPolicy | address | {groupPolicyAddress} |
EventUpdateGroupPolicy
Type | Attribute Key | Attribute Value |
---|---|---|
message | action | /cosmos.group.v1.Msg/UpdateGroupPolicy{Admin|Metadata|DecisionPolicy} |
cosmos.group.v1.EventUpdateGroupPolicy | address | {groupPolicyAddress} |
EventCreateProposal
Type | Attribute Key | Attribute Value |
---|---|---|
message | action | /cosmos.group.v1.Msg/CreateProposal |
cosmos.group.v1.EventCreateProposal | proposal_id | {proposalId} |
EventWithdrawProposal
Type | Attribute Key | Attribute Value |
---|---|---|
message | action | /cosmos.group.v1.Msg/WithdrawProposal |
cosmos.group.v1.EventWithdrawProposal | proposal_id | {proposalId} |
EventVote
Type | Attribute Key | Attribute Value |
---|---|---|
message | action | /cosmos.group.v1.Msg/Vote |
cosmos.group.v1.EventVote | proposal_id | {proposalId} |
EventExec
Type | Attribute Key | Attribute Value |
---|---|---|
message | action | /cosmos.group.v1.Msg/Exec |
cosmos.group.v1.EventExec | proposal_id | {proposalId} |
cosmos.group.v1.EventExec | logs | {logs_string} |
EventLeaveGroup
Type | Attribute Key | Attribute Value |
---|---|---|
message | action | /cosmos.group.v1.Msg/LeaveGroup |
cosmos.group.v1.EventLeaveGroup | proposal_id | {proposalId} |
cosmos.group.v1.EventLeaveGroup | address | {address} |
EventProposalPruned
Type | Attribute Key | Attribute Value |
---|---|---|
message | action | /cosmos.group.v1.Msg/LeaveGroup |
cosmos.group.v1.EventProposalPruned | proposal_id | {proposalId} |
cosmos.group.v1.EventProposalPruned | status | {ProposalStatus} |
cosmos.group.v1.EventProposalPruned | tally_result | {TallyResult} |
Client
CLI
A user can query and interact with the group
module using the CLI.
Query
The query
commands allow users to query group
state.
group-info
The group-info
command allows users to query for group info by given group id.
Example:
Example Output:
group-policy-info
The group-policy-info
command allows users to query for group policy info by account address of group policy .
Example:
Example Output:
group-members
The group-members
command allows users to query for group members by group id with pagination flags.
Example:
Example Output:
groups-by-admin
The groups-by-admin
command allows users to query for groups by admin account address with pagination flags.
Example:
Example Output:
group-policies-by-group
The group-policies-by-group
command allows users to query for group policies by group id with pagination flags.
Example:
Example Output:
group-policies-by-admin
The group-policies-by-admin
command allows users to query for group policies by admin account address with pagination flags.
Example:
Example Output:
proposal
The proposal
command allows users to query for proposal by id.
Example:
Example Output:
proposals-by-group-policy
The proposals-by-group-policy
command allows users to query for proposals by account address of group policy with pagination flags.
Example:
Example Output:
vote
The vote
command allows users to query for vote by proposal id and voter account address.
Example:
Example Output:
votes-by-proposal
The votes-by-proposal
command allows users to query for votes by proposal id with pagination flags.
Example:
Example Output:
votes-by-voter
The votes-by-voter
command allows users to query for votes by voter account address with pagination flags.
Example:
Example Output:
Transactions
The tx
commands allow users to interact with the group
module.
create-group
The create-group
command allows users to create a group which is an aggregation of member accounts with associated weights and an administrator account.
Example:
update-group-admin
The update-group-admin
command allows users to update a group's admin.
Example:
update-group-members
The update-group-members
command allows users to update a group's members.
Example:
update-group-metadata
The update-group-metadata
command allows users to update a group's metadata.
Example:
create-group-policy
The create-group-policy
command allows users to create a group policy which is an account associated with a group and a decision policy.
Example:
create-group-with-policy
The create-group-with-policy
command allows users to create a group which is an aggregation of member accounts with associated weights and an administrator account with decision policy. If the --group-policy-as-admin
flag is set to true
, the group policy address becomes the group and group policy admin.
Example:
update-group-policy-admin
The update-group-policy-admin
command allows users to update a group policy admin.
Example:
update-group-policy-metadata
The update-group-policy-metadata
command allows users to update a group policy metadata.
Example:
update-group-policy-decision-policy
The update-group-policy-decision-policy
command allows users to update a group policy's decision policy.
Example:
submit-proposal
The submit-proposal
command allows users to submit a new proposal.
Example:
withdraw-proposal
The withdraw-proposal
command allows users to withdraw a proposal.
Example:
vote
The vote
command allows users to vote on a proposal.
Example:
exec
The exec
command allows users to execute a proposal.
Example:
leave-group
The leave-group
command allows group member to leave the group.
Example:
gRPC
A user can query the group
module using gRPC endpoints.
GroupInfo
The GroupInfo
endpoint allows users to query for group info by given group id.
Example:
Example Output:
GroupPolicyInfo
The GroupPolicyInfo
endpoint allows users to query for group policy info by account address of group policy.
Example:
Example Output:
GroupMembers
The GroupMembers
endpoint allows users to query for group members by group id with pagination flags.
Example:
Example Output:
GroupsByAdmin
The GroupsByAdmin
endpoint allows users to query for groups by admin account address with pagination flags.
Example:
Example Output:
GroupPoliciesByGroup
The GroupPoliciesByGroup
endpoint allows users to query for group policies by group id with pagination flags.
Example:
Example Output:
GroupPoliciesByAdmin
The GroupPoliciesByAdmin
endpoint allows users to query for group policies by admin account address with pagination flags.
Example:
Example Output:
Proposal
The Proposal
endpoint allows users to query for proposal by id.
Example:
Example Output:
ProposalsByGroupPolicy
The ProposalsByGroupPolicy
endpoint allows users to query for proposals by account address of group policy with pagination flags.
Example:
Example Output:
VoteByProposalVoter
The VoteByProposalVoter
endpoint allows users to query for vote by proposal id and voter account address.
Example:
Example Output:
VotesByProposal
The VotesByProposal
endpoint allows users to query for votes by proposal id with pagination flags.
Example:
Example Output:
VotesByVoter
The VotesByVoter
endpoint allows users to query for votes by voter account address with pagination flags.
Example:
Example Output:
REST
A user can query the group
module using REST endpoints.
GroupInfo
The GroupInfo
endpoint allows users to query for group info by given group id.
Example:
Example Output:
GroupPolicyInfo
The GroupPolicyInfo
endpoint allows users to query for group policy info by account address of group policy.
Example:
Example Output:
GroupMembers
The GroupMembers
endpoint allows users to query for group members by group id with pagination flags.
Example:
Example Output:
GroupsByAdmin
The GroupsByAdmin
endpoint allows users to query for groups by admin account address with pagination flags.
Example:
Example Output:
GroupPoliciesByGroup
The GroupPoliciesByGroup
endpoint allows users to query for group policies by group id with pagination flags.
Example:
Example Output:
GroupPoliciesByAdmin
The GroupPoliciesByAdmin
endpoint allows users to query for group policies by admin account address with pagination flags.
Example:
Example Output:
Proposal
The Proposal
endpoint allows users to query for proposal by id.
Example:
Example Output:
ProposalsByGroupPolicy
The ProposalsByGroupPolicy
endpoint allows users to query for proposals by account address of group policy with pagination flags.
Example:
Example Output:
VoteByProposalVoter
The VoteByProposalVoter
endpoint allows users to query for vote by proposal id and voter account address.
Example:
Example Output:
VotesByProposal
The VotesByProposal
endpoint allows users to query for votes by proposal id with pagination flags.
Example:
Example Output:
VotesByVoter
The VotesByVoter
endpoint allows users to query for votes by voter account address with pagination flags.
Example:
Example Output:
Metadata
The group module has four locations for metadata where users can provide further context about the on-chain actions they are taking. By default all metadata fields have a 255 character length field where metadata can be stored in json format, either on-chain or off-chain depending on the amount of data required. Here we provide a recommendation for the json structure and where the data should be stored. There are two important factors in making these recommendations. First, that the group and gov modules are consistent with one another, note the number of proposals made by all groups may be quite large. Second, that client applications such as block explorers and governance interfaces have confidence in the consistency of metadata structure across chains.
Proposal
Location: off-chain as json object stored on IPFS (mirrors gov proposal)
:::note The authors
field is an array of strings, this is to allow for multiple authors to be listed in the metadata. In v0.46, the authors
field is a comma-separated string. Frontends are encouraged to support both formats for backwards compatibility. :::
Vote
Location: on-chain as json within 255 character limit (mirrors gov vote)
Group
Location: off-chain as json object stored on IPFS
Decision policy
Location: on-chain as json within 255 character limit
Last updated