# 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.

Copy // MsgCreateGroup is the Msg/CreateGroup request type. message MsgCreateGroup { option (cosmos.msg.v1.signer) = "admin"; // admin is the account address of the group admin. string admin = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // members defines the group members. repeated MemberRequest members = 2 [(gogoproto.nullable) = false]; // metadata is any arbitrary metadata to attached to the group. string metadata = 3; }

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.

Copy // MsgUpdateGroupMembers is the Msg/UpdateGroupMembers request type. message MsgUpdateGroupMembers { option (cosmos.msg.v1.signer) = "admin"; // admin is the account address of the group admin. string admin = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // group_id is the unique ID of the group. uint64 group_id = 2; // member_updates is the list of members to update, // set weight to 0 to remove a member. repeated MemberRequest member_updates = 3 [(gogoproto.nullable) = false]; }

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.

Copy // MsgUpdateGroupAdmin is the Msg/UpdateGroupAdmin request type. message MsgUpdateGroupAdmin { option (cosmos.msg.v1.signer) = "admin"; // admin is the current account address of the group admin. string admin = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // group_id is the unique ID of the group. uint64 group_id = 2; // new_admin is the group new admin account address. string new_admin = 3 [(cosmos_proto.scalar) = "cosmos.AddressString"]; }

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.

Copy // MsgUpdateGroupMetadata is the Msg/UpdateGroupMetadata request type. message MsgUpdateGroupMetadata { option (cosmos.msg.v1.signer) = "admin"; // admin is the account address of the group admin. string admin = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // group_id is the unique ID of the group. uint64 group_id = 2; // metadata is the updated group's metadata. string metadata = 3; }

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.

Copy // MsgCreateGroupPolicy is the Msg/CreateGroupPolicy request type. message MsgCreateGroupPolicy { option (cosmos.msg.v1.signer) = "admin"; option (gogoproto.goproto_getters) = false; // admin is the account address of the group admin. string admin = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // group_id is the unique ID of the group. uint64 group_id = 2; // metadata is any arbitrary metadata attached to the group policy. string metadata = 3; // decision_policy specifies the group policy's decision policy. google.protobuf.Any decision_policy = 4 [(cosmos_proto.accepts_interface) = "cosmos.group.v1.DecisionPolicy"]; }

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.

Copy // MsgCreateGroupWithPolicy is the Msg/CreateGroupWithPolicy request type. message MsgCreateGroupWithPolicy { option (cosmos.msg.v1.signer) = "admin"; option (gogoproto.goproto_getters) = false; // admin is the account address of the group and group policy admin. string admin = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // members defines the group members. repeated MemberRequest members = 2 [(gogoproto.nullable) = false]; // group_metadata is any arbitrary metadata attached to the group. string group_metadata = 3; // group_policy_metadata is any arbitrary metadata attached to the group policy. string group_policy_metadata = 4; // group_policy_as_admin is a boolean field, if set to true, the group policy account address will be used as group // and group policy admin. bool group_policy_as_admin = 5; // decision_policy specifies the group policy's decision policy. google.protobuf.Any decision_policy = 6 [(cosmos_proto.accepts_interface) = "cosmos.group.v1.DecisionPolicy"]; }

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.

Copy // MsgUpdateGroupPolicyAdmin is the Msg/UpdateGroupPolicyAdmin request type. message MsgUpdateGroupPolicyAdmin { option (cosmos.msg.v1.signer) = "admin"; // admin is the account address of the group admin. string admin = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // group_policy_address is the account address of the group policy. string group_policy_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // new_admin is the new group policy admin. string new_admin = 3 [(cosmos_proto.scalar) = "cosmos.AddressString"]; }

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.

Copy message MsgUpdateGroupPolicyAdminResponse {} // MsgUpdateGroupPolicyDecisionPolicy is the Msg/UpdateGroupPolicyDecisionPolicy request type. message MsgUpdateGroupPolicyDecisionPolicy { option (cosmos.msg.v1.signer) = "admin"; option (gogoproto.goproto_getters) = false; // admin is the account address of the group admin. string admin = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // group_policy_address is the account address of group policy. string group_policy_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // decision_policy is the updated group policy's decision policy. google.protobuf.Any decision_policy = 3 [(cosmos_proto.accepts_interface) = "cosmos.group.v1.DecisionPolicy"]; }

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.

Copy // MsgUpdateGroupPolicyMetadata is the Msg/UpdateGroupPolicyMetadata request type. message MsgUpdateGroupPolicyMetadata { option (cosmos.msg.v1.signer) = "admin"; // admin is the account address of the group admin. string admin = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // group_policy_address is the account address of group policy. string group_policy_address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // metadata is the updated group policy metadata. string metadata = 3; }

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.

Copy // MsgSubmitProposal is the Msg/SubmitProposal request type. message MsgSubmitProposal { option (cosmos.msg.v1.signer) = "proposers"; option (gogoproto.goproto_getters) = false; // group_policy_address is the account address of group policy. string group_policy_address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // proposers are the account addresses of the proposers. // Proposers signatures will be counted as yes votes. repeated string proposers = 2; // metadata is any arbitrary metadata to attached to the proposal. string metadata = 3; // messages is a list of `sdk.Msg`s that will be executed if the proposal passes. repeated google.protobuf.Any messages = 4; // exec defines the mode of execution of the proposal, // whether it should be executed immediately on creation or not. // If so, proposers signatures are considered as Yes votes. Exec exec = 5; }

It's expected to fail if:

  • 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 an address (can be either a proposer or the group policy admin) and a proposal_id (which has to be withdrawn).

Copy // MsgWithdrawProposal is the Msg/WithdrawProposal request type. message MsgWithdrawProposal { option (cosmos.msg.v1.signer) = "address"; // proposal is the unique ID of the proposal. uint64 proposal_id = 1; // address is the admin of the group policy or one of the proposer of the proposal. string address = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"]; }

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.

Copy // MsgVote is the Msg/Vote request type. message MsgVote { option (cosmos.msg.v1.signer) = "voter"; // proposal is the unique ID of the proposal. uint64 proposal_id = 1; // voter is the voter account address. string voter = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // option is the voter's choice on the proposal. VoteOption option = 3; // metadata is any arbitrary metadata to attached to the vote. string metadata = 4; // exec defines whether the proposal should be executed // immediately after voting or not. Exec exec = 5; }

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.

Copy // MsgVoteResponse is the Msg/Vote response type. message MsgVoteResponse {} // MsgExec is the Msg/Exec request type. message MsgExec { option (cosmos.msg.v1.signer) = "signer"; // proposal is the unique ID of the proposal. uint64 proposal_id = 1; // executor is the account address used to execute the proposal. string executor = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"]; }

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.

Copy message MsgLeaveGroup { option (cosmos.msg.v1.signer) = "address"; // address is the account address of the group member. string address = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"]; // group_id is the unique ID of the group. uint64 group_id = 2; }

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.