protocolpool

README

---

sidebar_position: 1

x/protocolpool

Concepts

Protopool is a module that handle functionality around community pool funds. This provides a separate module account for community pool making it easier to track the pool assets. We no longer track community pool assets in distribution module, but instead in this protocolpool module. Funds are migrated from the distribution module's community pool to protocolpool's module account.

The module is also designed with a lazy "claim-based" system, which means that users are required to actively claim allocated funds from allocated budget if any budget proposal has been submitted and passed. The module does not automatically distribute funds to recipients. This design choice allows for more flexibility and control over fund distribution.

State Transitions

FundCommunityPool

FundCommunityPool can be called by any valid account to send funds to the protocolpool module account.

  // FundCommunityPool defines a method to allow an account to directly
  // fund the community pool.
  rpc FundCommunityPool(MsgFundCommunityPool) returns (MsgFundCommunityPoolResponse);

CommunityPoolSpend

CommunityPoolSpend can be called by the module authority (default governance module account) or any account with authorization to spend funds from the protocolpool module account to a receiver address.

  // CommunityPoolSpend defines a governance  operation for sending tokens from
  // the community pool in the x/protocolpool module to another account, which
  // could be the governance module itself. The authority is defined in the
  // keeper.
  rpc CommunityPoolSpend(MsgCommunityPoolSpend) returns (MsgCommunityPoolSpendResponse);

SubmitBudgetProposal

SubmitBudgetProposal is a message used to propose a budget allocation for a specific recipient. The proposed funds will be distributed periodically over a specified time frame.

It's the responsibility of users to actively claim their allocated funds based on the terms of the approved budget proposals.

  // SubmitBudgetProposal defines a method to set a budget proposal.
  rpc SubmitBudgetProposal(MsgSubmitBudgetProposal) returns (MsgSubmitBudgetProposalResponse);

ClaimBudget

ClaimBudget is a message used to claim funds from a previously submitted budget proposal. When a budget proposal is approved and funds are allocated, recipients can use this message to claim their share of the budget. Funds are distributed in tranches over specific periods, and users can claim their share of budget at the appropriate time.

  // ClaimBudget defines a method to claim the distributed budget.
  rpc ClaimBudget(MsgClaimBudget) returns (MsgClaimBudgetResponse);

CreateContinuousFund

CreateContinuousFund is a message used to initiate a continuous fund for a specific recipient. The proposed percentage of funds will be distributed only on withdraw request for the recipient. The fund distribution continues until expiry time is reached or continuous fund request is canceled. NOTE: This feature is designed to work with the SDK's default bond denom.

  // CreateContinuousFund defines a method to add funds continuously.
  rpc CreateContinuousFund(MsgCreateContinuousFund) returns (MsgCreateContinuousFundResponse);

CancelContinuousFund

CancelContinuousFund is a message used to cancel an existing continuous fund proposal for a specific recipient. Cancelling a continuous fund stops further distribution of funds, and the state object is removed from storage.

  // CancelContinuousFund defines a method for cancelling continuous fund.
  rpc CancelContinuousFund(MsgCancelContinuousFund) returns (MsgCancelContinuousFundResponse);

Messages

MsgFundCommunityPool

This message sends coins directly from the sender to the community pool.

:::tip If you know the protocolpool module account address, you can directly use bank send transaction instead. ::::

https://github.com/cosmos/cosmos-sdk/blob/97724493d792517ba2be8969078b5f92ad04d79c/proto/cosmos/protocolpool/v1/tx.proto#L32-L42

• The msg will fail if the amount cannot be transferred from the sender to the protocolpool module account.

func (k Keeper) FundCommunityPool(ctx context.Context, amount sdk.Coins, sender sdk.AccAddress) error {
	return k.bankKeeper.SendCoinsFromAccountToModule(ctx, sender, types.ModuleName, amount)
}

MsgCommunityPoolSpend

This message distributes funds from the protocolpool module account to the recipient using DistributeFromCommunityPool keeper method.

https://github.com/cosmos/cosmos-sdk/blob/97724493d792517ba2be8969078b5f92ad04d79c/proto/cosmos/protocolpool/v1/tx.proto#L47-L58

The message will fail under the following conditions:

• The amount cannot be transferred to the recipient from the protocolpool module account.
• The recipient address is restricted

func (k Keeper) DistributeFromCommunityPool(ctx context.Context, amount sdk.Coins, receiveAddr sdk.AccAddress) error {
	return k.bankKeeper.SendCoinsFromModuleToAccount(ctx, types.ModuleName, receiveAddr, amount)
}

MsgSubmitBudgetProposal

This message is used to submit a budget proposal to allocate funds for a specific recipient. The proposed funds will be distributed periodically over a specified time frame.

https://github.com/cosmos/cosmos-sdk/blob/97724493d792517ba2be8969078b5f92ad04d79c/proto/cosmos/protocolpool/v1/tx.proto#L64-L82

The message will fail under the following conditions:

• The total budget is zero.
• The recipient address is empty or restricted.
• The start time is less than current block time.
• The number of tranches is not a positive integer.
• The period length is not a positive integer.

:::warning If two budgets to the same address are created, the budget would be updated with the new budget. :::

https://github.com/cosmos/cosmos-sdk/blob/97724493d792517ba2be8969078b5f92ad04d79c/x/protocolpool/keeper/msg_server.go#L39-l61

MsgClaimBudget

This message is used to claim funds from a previously submitted budget proposal. When a budget proposal is passed and funds are allocated, recipients can use this message to claim their share of the budget.

https://github.com/cosmos/cosmos-sdk/blob/97724493d792517ba2be8969078b5f92ad04d79c/proto/cosmos/protocolpool/v1/tx.proto#L88-L92

The message will fail under the following conditions:

• The recipient address is empty or restricted.
• The budget proposal for the recipient does not exist.
• The budget proposal has not reached its distribution start time.
• The budget proposal's distribution period has not passed yet.

https://github.com/cosmos/cosmos-sdk/blob/97724493d792517ba2be8969078b5f92ad04d79c/x/protocolpool/keeper/msg_server.go#L25-L37

MsgCreateContinuousFund

This message is used to create a continuous fund for a specific recipient. The proposed percentage of funds will be distributed only on withdraw request for the recipient. This fund distribution continues until expiry time is reached or continuous fund request is canceled.

https://github.com/cosmos/cosmos-sdk/blob/44985ec56557e2d5b763c8676fabbed971f157ba/proto/cosmos/protocolpool/v1/tx.proto#L111-L130

The message will fail under the following conditions:

• The recipient address is empty or restricted.
• The percentage is zero/negative/greater than one.
• The Expiry time is less than the current block time.

:::warning If two continuous fund proposals to the same address are created, the previous ContinuousFund would be updated with the new ContinuousFund. :::

https://github.com/cosmos/cosmos-sdk/blob/44985ec56557e2d5b763c8676fabbed971f157ba/x/protocolpool/keeper/msg_server.go#L109-L140

MsgCancelContinuousFund

This message is used to cancel an existing continuous fund proposal for a specific recipient. Once canceled, the continuous fund will no longer distribute funds at each end block, and the state object will be removed. Users should be cautious when canceling continuous funds, as it may affect the planned distribution for the recipient.

https://github.com/cosmos/cosmos-sdk/blob/44985ec56557e2d5b763c8676fabbed971f157ba/proto/cosmos/protocolpool/v1/tx.proto#L136-L144

The message will fail under the following conditions:

• The recipient address is empty or restricted.
• The ContinuousFund for the recipient does not exist.

https://github.com/cosmos/cosmos-sdk/blob/44985ec56557e2d5b763c8676fabbed971f157ba/x/protocolpool/keeper/msg_server.go#L142-L174

Client

It takes the advantage of AutoCLI

https://github.com/cosmos/cosmos-sdk/blob/9dd34510e27376005e7e7ff3628eab9dbc8ad6dc/x/protocolpool/autocli.go

Documentation

Index

• Constants
• type AppModule
  • func NewAppModule(cdc codec.Codec, keeper keeper.Keeper, accountKeeper types.AccountKeeper, ...) AppModule
  • func (am AppModule) AutoCLIOptions() *autocliv1.ModuleOptions
  • func (AppModule) ConsensusVersion() uint64
  • func (am AppModule) DefaultGenesis() json.RawMessage
  • func (am AppModule) ExportGenesis(ctx context.Context) (json.RawMessage, error)
  • func (AppModule) GenerateGenesisState(simState *module.SimulationState)
  • func (am AppModule) InitGenesis(ctx context.Context, data json.RawMessage) error
  • func (AppModule) IsAppModule()
  • func (am AppModule) IsOnePerModuleType()
  • func (AppModule) Name() string
  • func (AppModule) ProposalMsgs(simState module.SimulationState) []simtypes.WeightedProposalMsg
  • func (AppModule) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *gwruntime.ServeMux)
  • func (AppModule) RegisterInterfaces(registrar registry.InterfaceRegistrar)
  • func (AppModule) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)
  • func (am AppModule) RegisterServices(registrar grpc.ServiceRegistrar) error
  • func (am AppModule) RegisterStoreDecoder(sdr simtypes.StoreDecoderRegistry)
  • func (am AppModule) ValidateGenesis(bz json.RawMessage) error
  • func (am AppModule) WeightedOperations(simState module.SimulationState) []simtypes.WeightedOperation
• type ModuleInputs
• type ModuleOutputs
  • func ProvideModule(in ModuleInputs) ModuleOutputs

Constants

const ConsensusVersion = 1

ConsensusVersion defines the current x/protocolpool module consensus version.

Types

type AppModule

type AppModule struct {
	// contains filtered or unexported fields
}

AppModule implements an application module for the pool module

func NewAppModule

func NewAppModule(cdc codec.Codec, keeper keeper.Keeper,
	accountKeeper types.AccountKeeper, bankKeeper types.BankKeeper,
) AppModule

NewAppModule creates a new AppModule object

func (AppModule) AutoCLIOptions

func (am AppModule) AutoCLIOptions() *autocliv1.ModuleOptions

AutoCLIOptions implements the autocli.HasAutoCLIConfig interface.

func (AppModule) ConsensusVersion

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements HasConsensusVersion

func (AppModule) DefaultGenesis

func (am AppModule) DefaultGenesis() json.RawMessage

DefaultGenesis returns default genesis state as raw bytes for the protocolpool module.

func (AppModule) ExportGenesis

func (am AppModule) ExportGenesis(ctx context.Context) (json.RawMessage, error)

ExportGenesis returns the exported genesis state as raw bytes for the protocolpool module.

func (AppModule) GenerateGenesisState

func (AppModule) GenerateGenesisState(simState *module.SimulationState)

GenerateGenesisState creates a randomized GenState of the protocolpool module.

func (AppModule) InitGenesis

func (am AppModule) InitGenesis(ctx context.Context, data json.RawMessage) error

InitGenesis performs genesis initialization for the protocolpool module.

func (AppModule) IsAppModule

func (AppModule) IsAppModule()

IsAppModule implements the appmodule.AppModule interface.

func (AppModule) IsOnePerModuleType

func (am AppModule) IsOnePerModuleType()

IsOnePerModuleType implements the depinject.OnePerModuleType interface.

func (AppModule) Name

func (AppModule) Name() string

Name returns the pool module's name.

func (AppModule) ProposalMsgs

func (AppModule) ProposalMsgs(simState module.SimulationState) []simtypes.WeightedProposalMsg

ProposalMsgs returns all the protocolpool msgs used to simulate governance proposals.

func (AppModule) RegisterGRPCGatewayRoutes

func (AppModule) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *gwruntime.ServeMux)

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes

func (AppModule) RegisterInterfaces

func (AppModule) RegisterInterfaces(registrar registry.InterfaceRegistrar)

RegisterInterfaces registers interfaces and implementations of the bank module.

func (AppModule) RegisterLegacyAminoCodec

func (AppModule) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)

RegisterLegacyAminoCodec registers the pool module's types on the LegacyAmino codec.

func (AppModule) RegisterServices

func (am AppModule) RegisterServices(registrar grpc.ServiceRegistrar) error

RegisterServices registers module services.

func (AppModule) RegisterStoreDecoder

func (am AppModule) RegisterStoreDecoder(sdr simtypes.StoreDecoderRegistry)

RegisterStoreDecoder registers a decoder for protocolpool module's types

func (AppModule) ValidateGenesis

func (am AppModule) ValidateGenesis(bz json.RawMessage) error

ValidateGenesis performs genesis state validation for the protocolpool module.

func (AppModule) WeightedOperations

func (am AppModule) WeightedOperations(simState module.SimulationState) []simtypes.WeightedOperation

WeightedOperations returns the all the protocolpool module operations with their respective weights.

type ModuleInputs

type ModuleInputs struct {
	depinject.In

	Config      *modulev1.Module
	Codec       codec.Codec
	Environment appmodule.Environment

	AccountKeeper types.AccountKeeper
	BankKeeper    types.BankKeeper
	StakingKeeper types.StakingKeeper
}

type ModuleOutputs

type ModuleOutputs struct {
	depinject.Out

	Keeper keeper.Keeper
	Module appmodule.AppModule
}

func ProvideModule

func ProvideModule(in ModuleInputs) ModuleOutputs