protocolpool

package
v0.53.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 8, 2025 License: Apache-2.0 Imports: 24 Imported by: 9

README

sidebar_position: 1

x/protocolpool

Concepts

x/protocolpool is a supplemental Cosmos SDK module that handles functionality for community pool funds. The module provides a separate module account for the community pool making it easier to track the pool assets. Starting with v0.53 of the Cosmos SDK, community funds can be tracked using this module instead of the x/distribution module. Funds are migrated from the x/distribution module's community pool to x/protocolpool's module account automatically.

This module is supplemental; it is not required to run a Cosmos SDK chain. x/protocolpool enhances the community pool functionality provided by x/distribution and enables custom modules to further extend the community pool.

Note: as long as an external commmunity pool keeper (here, x/protocolpool) is wired in DI configs, x/distribution will automatically use it for its external pool.

Usage Limitations

The following x/distribution handlers will now return an error when the protocolpool module is used with x/distribution:

QueryService

  • CommunityPool

MsgService

  • CommunityPoolSpend
  • FundCommunityPool

If you have services that rely on this functionality from x/distribution, please update them to use the x/protocolpool equivalents.

State Transitions

FundCommunityPool

FundCommunityPool can be called by any valid account to send funds to the x/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 x/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);

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 distribute a percentage of funds to an address continuously.
  // This ContinuousFund can be indefinite or run until a given expiry time.
  // Funds come from validator block rewards from x/distribution, but may also come from
  // any user who funds the ProtocolPoolEscrow module account directly through x/bank.
  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 x/protocolpool module account address, you can directly use bank send transaction instead. :::

https://github.com/cosmos/cosmos-sdk/blob/release/v0.53.x/proto/cosmos/protocolpool/v1/tx.proto#L43-L53
  • The msg will fail if the amount cannot be transferred from the sender to the x/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 x/protocolpool module account to the recipient using DistributeFromCommunityPool keeper method.

https://github.com/cosmos/cosmos-sdk/blob/release/v0.53.x/proto/cosmos/protocolpool/v1/tx.proto#L58-L69

The message will fail under the following conditions:

  • The amount cannot be transferred to the recipient from the x/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)
}

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/release/v0.53.x/proto/cosmos/protocolpool/v1/tx.proto#L114-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 will be updated with the new ContinuousFund. :::

https://github.com/cosmos/cosmos-sdk/blob/release/v0.53.x/x/protocolpool/keeper/msg_server.go#L103-L166

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 begin block, and the state object will be removed.

https://github.com/cosmos/cosmos-sdk/blob/release/v0.53.x/x/protocolpool/proto/cosmos/protocolpool/v1/tx.proto#L136-L161

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/release/v0.53.x/x/protocolpool/keeper/msg_server.go#L188-L226

Client

It takes the advantage of AutoCLI

https://github.com/cosmos/cosmos-sdk/blob/release/v0.53.x/x/protocolpool/autocli.go

Documentation

Index

Constants

View Source 
const ConsensusVersion = 1

ConsensusVersion defines the current x/protocolpool module consensus version.

Variables

This section is empty.

Functions

This section is empty.

Types

type AppModule 

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

AppModule implements an application module for the pool module

func NewAppModule 

func NewAppModule(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) BeginBlock 

func (am AppModule) BeginBlock(ctx context.Context) error

BeginBlock implements appmodule.HasBeginBlocker.

func (AppModule) ConsensusVersion 

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements HasConsensusVersion

func (AppModule) DefaultGenesis 

func (am AppModule) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage

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

func (AppModule) ExportGenesis 

func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage

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 sdk.Context, cdc codec.JSONCodec, data json.RawMessage)

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 protocolpool module's name. Deprecated: kept for legacy reasons.

func (AppModule) ProposalMsgs 

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

ProposalMsgs returns msgs used for governance proposals for simulations. migrate to ProposalMsgsX. This method is ignored when ProposalMsgsX exists and will be removed in the future.

func (AppModule) ProposalMsgsX 

func (am AppModule) ProposalMsgsX(weight simsx.WeightSource, reg simsx.Registry)

ProposalMsgsX registers governance proposal messages in the simulation registry.

func (AppModule) RegisterGRPCGatewayRoutes 

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

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes

func (AppModule) RegisterInterfaces 

func (AppModule) RegisterInterfaces(ir codectypes.InterfaceRegistry)

RegisterInterfaces registers interfaces and implementations of the protocolpool module.

func (AppModule) RegisterLegacyAminoCodec 

func (am AppModule) RegisterLegacyAminoCodec(amino *codec.LegacyAmino)

func (AppModule) RegisterServices 

func (am AppModule) RegisterServices(configurator module.Configurator)

RegisterServices registers module services.

func (AppModule) RegisterStoreDecoder 

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

RegisterStoreDecoder registers a decoder for protocolpool module's types

func (AppModule) ValidateGenesis 

func (am AppModule) ValidateGenesis(cdc codec.JSONCodec, _ client.TxEncodingConfig, 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. migrate to WeightedOperationsX. This method is ignored when WeightedOperationsX exists and will be removed in the future

func (AppModule) WeightedOperationsX 

func (am AppModule) WeightedOperationsX(weight simsx.WeightSource, reg simsx.Registry)

WeightedOperationsX registers weighted protocolpool module operations for simulation.

type ModuleInputs 

type ModuleInputs struct {
	depinject.In

	Config       *modulev1.Module
	Codec        codec.Codec
	StoreService store.KVStoreService

	AccountKeeper types.AccountKeeper
	BankKeeper    types.BankKeeper
}

type ModuleOutputs 

type ModuleOutputs struct {
	depinject.Out

	Keeper keeper.Keeper
	Module appmodule.AppModule
}

func ProvideModule 

func ProvideModule(in ModuleInputs) ModuleOutputs

Source Files

View all Source files

Directories

Path Synopsis
Package testutil is a generated GoMock package.
 Package testutil is a generated GoMock package.
Package types is a reverse proxy.
 Package types is a reverse proxy.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.