From 81b5b751cee19ea1ee9091a04a412c4791dd583e Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Tue, 29 Apr 2025 12:59:02 -0400 Subject: [PATCH] docs: protocolpool wiring (backport #24607) (#24611) Co-authored-by: Alex | Interchain Labs --- UPGRADE_GUIDE.md | 2 ++ x/distribution/README.md | 23 +++++++++++++++++++++++ x/protocolpool/README.md | 2 ++ 3 files changed, 27 insertions(+) diff --git a/UPGRADE_GUIDE.md b/UPGRADE_GUIDE.md index ed494c4152..84ec6e7e08 100644 --- a/UPGRADE_GUIDE.md +++ b/UPGRADE_GUIDE.md @@ -161,6 +161,8 @@ app.ModuleManager.SetOrderInitGenesis( ### DI Wiring +Note: _as long as an external community pool keeper (here, `x/protocolpool`) is wired in DI configs, `x/distribution` will automatically use it for its external pool._ + First, set up the keeper for the application. Import the protocolpool keeper: diff --git a/x/distribution/README.md b/x/distribution/README.md index ce33bc0c80..8259b60e0d 100644 --- a/x/distribution/README.md +++ b/x/distribution/README.md @@ -125,6 +125,29 @@ is created which might need to reference the historical record, the reference co Each time one object which previously needed to reference the historical record is deleted, the reference count is decremented. If the reference count hits zero, the historical record is deleted. +### External Community Pool Keepers + +An external pool community keeper is defined as: + +```go +// ExternalCommunityPoolKeeper is the interface that an external community pool module keeper must fulfill +// for x/distribution to properly accept it as a community pool fund destination. +type ExternalCommunityPoolKeeper interface { + // GetCommunityPoolModule gets the module name that funds should be sent to for the community pool. + // This is the address that x/distribution will send funds to for external management. + GetCommunityPoolModule() string + // FundCommunityPool allows an account to directly fund the community fund pool. + FundCommunityPool(ctx sdk.Context, amount sdk.Coins, senderAddr sdk.AccAddress) error + // DistributeFromCommunityPool distributes funds from the community pool module account to + // a receiver address. + DistributeFromCommunityPool(ctx sdk.Context, amount sdk.Coins, receiveAddr sdk.AccAddress) error +} +``` + +By default, the distribution module will use a community pool implementation that is internal. An external community pool +can be provided to the module which will have funds be diverted to it instead of the internal implementation. The reference +external community pool maintained by the Cosmos SDK is [`x/protocolpool`](../protocolpool/README.md). + ## State ### FeePool diff --git a/x/protocolpool/README.md b/x/protocolpool/README.md index 89613f01b1..c7e379d679 100644 --- a/x/protocolpool/README.md +++ b/x/protocolpool/README.md @@ -10,6 +10,8 @@ sidebar_position: 1 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`: