Skip to main content

Governance (Multisig)

Overview​

Governance workflows allow organizations to manage approvals via groups, policies, and proposals. These features are primarily for read operations, enabling you to inspect existing governance structures and activity. Write operations for governance (e.g., creating groups, submitting proposals) must be built in Vault and broadcast via Node RPC.

What success looks like:​

  • Group exists with correct members & weights.
  • Group policy exists with expected threshold/quorum/voting period.
  • Proposal lifecycle works: created → voting → accepted/failed, votes recorded, and (when accepted) executed.
  • Reads reflect the final state (policy/proposal/votes endpoints).

Groups​

A group is a collection of members with assigned weights.

Code snippet
# Group info (by ID)
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/group_info/{group_id}"

# Groups by admin / by member
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/groups_by_admin/pb1ADMIN..."

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/groups_by_member/pb1MEMBER..."

# Group members
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/group_members/{group_id}"

Policies​

Code snippet
# Policies for a group (by group_id)
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/group_policies_by_group/{group_id}"

# Policies administered by address (admin)
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/group_policies_by_admin/pb1ADMIN..."

# Group policy info (by policy address)
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/group_policy_info/pb1POLICY..."

Proposals & Votes​

Code snippet
# Proposals under a group policy
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/proposals_by_group_policy/pb1POLICY..."

# Proposal details (by ID)
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/proposal/\{proposal_id\}"

# Votes for a proposal
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/votes_by_proposal/\{proposal_id\}"

Use-case Writes (Tx)​

Governance Use Cases: Creating Groups, Policies, and Proposals Governance workflows allow organizations to manage approvals via groups, policies, and proposals. This section demonstrates how to:

  • Create a group with specific members and weights.
  • Define a group policy with voting thresholds.
  • Propose a change and vote on it.

Writes (Tx): Build in Vault → sign → broadcast → verify
Use Vault to build the unsigned tx, sign with your key, broadcast via Node RPC, then verify via the read endpoints listed below.

Sign & Broadcast: use the JSON-RPC call in Broadcast (RPC) above (broadcast_tx_sync|async|commit).

Code snippet
# Broadcast (RPC) -- choose one per UX
curl -X POST "https://pio-mainnet-1-rpc.provlabs.com" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"broadcast_tx_sync","params":["<BASE64_SIGNED_TX>"]}'
# or: broadcast_tx_async / broadcast_tx_commit

Create a Group (Tx) → Verify​

Build Tx (Vault): MsgCreateGroup with:

  • admin (pb1...)
  • members[] (address, weight)
  • metadata (optional)

Sign & Broadcast (RPC): use one of broadcast_tx_sync | broadcast_tx_async | broadcast_tx_commit (see Broadcast (RPC) above).

Verify (reads):

Code snippet
# Group info (by ID)
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/group_info/{group_id}"

# Members of the group
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/group_members/{group_id}"

# Groups by admin / by member
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/groups_by_admin/pb1ADMIN..."

curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/groups_by_member/pb1MEMBER..."

Create a Group Policy (Tx) → Verify​

Build Tx (Vault): MsgCreateGroupPolicy with:

  • group_id
  • decision_policy (e.g., ThresholdDecisionPolicy or PercentageDecisionPolicy)
  • metadata (optional)

Sign & Broadcast (RPC): use one of broadcast_tx_sync | broadcast_tx_async | broadcast_tx_commit (see Broadcast (RPC) above).

Verify (reads):

Code snippet
# Policies for a group
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/group_policies_by_group/{group_id}"

# Policy details (by policy address)
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/group_policy_info/pb1POLICY..."

Propose & Vote (Tx) → Verify​

Build Tx (Vault):

  • Submit proposal via MsgSubmitProposal under the group_policy_address; include your business messages (e.g., MsgSend) in the proposal.
  • Cast votes via MsgVote from group members (YES/NO/ABSTAIN/NO_WITH_VETO).

Sign & Broadcast (RPC): use one of broadcast_tx_sync | broadcast_tx_async | broadcast_tx_commit (see Broadcast (RPC) above).

Verify (reads):

Code snippet
# Proposals under a group policy
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/proposals_by_group_policy/pb1POLICY..."

# Votes for a proposal
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/votes_by_proposal/\{proposal_id\}"

Execute a Proposal (Tx) → Verify​

  • Build Tx (Vault): MsgExec (or submit with exec=EXEC_TRY to auto-execute on pass).
  • Sign & Broadcast (RPC): use one of broadcast_tx_sync | broadcast_tx_async | broadcast_tx_commit (see Broadcast (RPC) above).
  • Verify (reads):
Code snippet
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_REST_BASE/cosmos/group/v1/proposal/\{proposal_id\}"
# status should reflect execution / final state