Skip to content

Commit

Permalink
docs: Groups spec cleanups (cosmos#11631)
Browse files Browse the repository at this point in the history 
## Description

ref: cosmos#10968



---

### Author Checklist

*All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.*

I have...

- [ ] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] added `!` to the type prefix if API or client breaking change
- [ ] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting))
- [ ] provided a link to the relevant issue or specification
- [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules)
- [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing)
- [ ] added a changelog entry to `CHANGELOG.md`
- [ ] included comments for [documenting Go code](https://blog.golang.org/godoc)
- [ ] updated the relevant documentation or specification
- [ ] reviewed "Files changed" and left comments if necessary
- [ ] confirmed all CI checks have passed

### Reviewers Checklist

*All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.*

I have...

- [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] confirmed `!` in the type prefix if API or client breaking change
- [ ] confirmed all author checklist items have been addressed 
- [ ] reviewed state machine logic
- [ ] reviewed API design and naming
- [ ] reviewed documentation is accurate
- [ ] reviewed tests and test coverage
- [ ] manually tested (if applicable)
  • Loading branch information
@amaury1093
amaury1093 authored Apr 15, 2022
1 parent 6ff6dce commit ec1c423
Show file tree
Hide file tree
Showing 4 changed files with 169 additions and 108 deletions.
71 changes: 53 additions & 18 deletions x/group/spec/01_concepts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,16 +30,23 @@ 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 perdio and a
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 in order for a proposal to potentially be executed, and it may
be set to 0. The maximum voting window is the maximum time that a proposal may
be voted on before it is closed.
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:

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta2/x/group/types.go#L23-L37

### Threshold decision policy

A threshold decision policy defines a threshold of yes votes (based on a tally
Expand All @@ -56,18 +63,33 @@ weights get updated.

## Proposal

Any member of a group can submit a proposal for a group policy account to decide upon.
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
### Voting

There are four choices to choose while voting - yes, no, abstain and veto. Not
all decision policies will support them. Votes can contain some optional metadata.
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.
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.

## Tallying
### 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
Expand All @@ -80,22 +102,36 @@ happens first:
- 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 `STATUS_CLOSED`, so no more voting is allowed anymore, and the tally
result is persisted to state.
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
### 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.
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.
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.
For now, if the proposal can't be executed, it'll still be opened for new votes and
could be executed later on.
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

Expand All @@ -105,7 +141,7 @@ 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 a
`Msg/{SubmitProposal,Vote}` with the `Exec` field,
`Msg/{SubmitProposal,Vote}` with the `Exec` field set,
- or on `EndBlock` right after the proposal's voting period end. This applies to proposals with status `aborted` or `withdrawn` too.

whichever happens first.
Expand All @@ -118,4 +154,3 @@ Proposals are pruned:
`max_execution_period` (defined as an app-wide configuration) is passed,

whichever happens first.

108 changes: 64 additions & 44 deletions x/group/spec/03_messages.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,134 +6,154 @@ order: 3

## Msg/CreateGroup

A new group can be created with the `MsgCreateGroup`, which has an admin address, a list of members and some optional metadata bytes.
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.

+++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L54-L65
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta2/proto/cosmos/group/v1/tx.proto#L65-L76

It's expecting to fail if metadata length is greater than `MaxMetadataLen` config.
It's expected to fail if

- metadata length is greater than `MaxMetadataLen`
config
- members are not correctly set (e.g. wrong address format, duplicates, or with 0 weight).

## Msg/UpdateGroupMembers

Group members can be updated with the `UpdateGroupMembers`.

+++https://github.com/cosmos/cosmos-sdk/blob/9aef070625e9676d7c0acb212c17ae9dba3c32dc/proto/cosmos/group/v1beta1/tx.proto#L74-L86
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta2/proto/cosmos/group/v1/tx.proto#L85-L98

In the list of `MemberUpdates`, an existing member can be removed by setting its weight to 0.

It's expecting to fail if the signer is not the admin of the group.
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.

+++ https://github.com/cosmos/cosmos-sdk/blob/9aef070625e9676d7c0acb212c17ae9dba3c32dc/proto/cosmos/group/v1beta1/tx.proto#L91-L102
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta2/proto/cosmos/group/v1/tx.proto#L103-L115

It's expecting to fail if the signer is not the admin of the group.
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.

+++ https://github.com/cosmos/cosmos-sdk/blob/9aef070625e9676d7c0acb212c17ae9dba3c32dc/proto/cosmos/group/v1beta1/tx.proto#L107-L118
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta2/proto/cosmos/group/v1/tx.proto#L120-L132

It's expecting to fail if:
It's expected to fail if:

* new metadata length is greater than `MaxMetadataLen` config.
* the signer is not the admin of the group.
- 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 bytes.
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.

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta2/proto/cosmos/group/v1/tx.proto#L141-L158

+++ https://github.com/cosmos/cosmos-sdk/blob/9aef070625e9676d7c0acb212c17ae9dba3c32dc/proto/cosmos/group/v1beta1/tx.proto#L127-L142
It's expected to fail if:

It's expecting to fail if metadata length is greater than `MaxMetadataLen` config.
- 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 bytes for group and group policy.
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.

+++ https://github.com/cosmos/cosmos-sdk/blob/likhita/MsgCreateGroupWithPolicy/proto/cosmos/group/v1beta1/tx.proto#L167-L188
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta2/proto/cosmos/group/v1/tx.proto#L181-L202

It's expecting to fail if group metadata or group policy metadata length is greater than some `MaxMetadataLength`.
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.

+++ https://github.com/cosmos/cosmos-sdk/blob/9aef070625e9676d7c0acb212c17ae9dba3c32dc/proto/cosmos/group/v1beta1/tx.proto#L151-L162
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta2/proto/cosmos/group/v1/tx.proto#L167-L179

It's expecting to fail if the signer is not the admin of the group policy.
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.

+++ https://github.com/cosmos/cosmos-sdk/blob/9aef070625e9676d7c0acb212c17ae9dba3c32dc/proto/cosmos/group/v1beta1/tx.proto#L167-L179
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta2/proto/cosmos/group/v1/tx.proto#L217-L231

It's expecting to fail if the signer is not the admin of the group 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.

+++ https://github.com/cosmos/cosmos-sdk/blob/9aef070625e9676d7c0acb212c17ae9dba3c32dc/proto/cosmos/group/v1beta1/tx.proto#L184-L195
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta2/proto/cosmos/group/v1/tx.proto#L236-L248

It's expecting to fail if:
It's expected to fail if:

* new metadata length is greater than `MaxMetadataLen` config.
* the signer is not the admin of the group.
- new metadata length is greater than `MaxMetadataLen` config.
- the signer is not the admin of the group.

## Msg/CreateProposal
## Msg/SubmitProposal

A new proposal can be created with the `MsgCreateProposal`, 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 bytes.
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.

+++ https://github.com/cosmos/cosmos-sdk/blob/9aef070625e9676d7c0acb212c17ae9dba3c32dc/proto/cosmos/group/v1beta1/tx.proto#L218-L239
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta2/proto/cosmos/group/v1/tx.proto#L271-L294

It's expected to fail if:

It's expecting to fail if metadata length is greater than `MaxMetadataLen` config.
- metadata 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 a `address` (can be either proposer or policy admin) and a `proposal_id` (which has to be withdrawn).
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).

+++ https://github.com/cosmos/cosmos-sdk/blob/f2d6f0e4bb1a9bd7f7ae3cdc4702c9d3d1fc0329/proto/cosmos/group/v1beta1/tx.proto#L251-L258
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta2/proto/cosmos/group/v1/tx.proto#L303-L310

It's expecting to fail if:
It's expected to fail if:

* the signer is neither policy address nor proposer of the proposal.
* the proposal is already closed or aborted.
- 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 bytes.
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.

+++ https://github.com/cosmos/cosmos-sdk/blob/9aef070625e9676d7c0acb212c17ae9dba3c32dc/proto/cosmos/group/v1beta1/tx.proto#L248-L265
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta2/proto/cosmos/group/v1/tx.proto#L315-L333

It's expected to fail if:

It's expecting to fail if metadata length is greater than `MaxMetadataLen` config.
- 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`.

+++ https://github.com/cosmos/cosmos-sdk/blob/9aef070625e9676d7c0acb212c17ae9dba3c32dc/proto/cosmos/group/v1beta1/tx.proto#L270-L278
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta2/proto/cosmos/group/v1/tx.proto#L338-L347

The messages that are part of this proposal won't be executed if:

* the proposal has not been accepted.
* the proposal status is not closed.
* the proposal has already been successfully executed.
- 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.

+++ https://github.com/cosmos/cosmos-sdk/blob/a635fd78663d04c5de23f4d032e5a3abea1b005a/proto/cosmos/group/v1beta1/tx.proto#L352-L361
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-beta2/proto/cosmos/group/v1/tx.proto#L352-L361

It's expecting to fail if:
It's expected to fail if:

* the group member is not part of the group.
- 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.
Loading

0 comments on commit ec1c423

Please sign in to comment.