feat(bank): Allow injectable restrictions on bank transfers

CHANGELOG.md

@@ -41,6 +41,7 @@ Ref: https://keepachangelog.com/en/1.0.0/
 ### Features
 
 * (x/bank) [#16795](https://github.com/cosmos/cosmos-sdk/pull/16852) Add `DenomMetadataByQueryString` query in bank module to support metadata query by query string.
+* (x/bank) [#14224](https://github.com/cosmos/cosmos-sdk/pull/14224) Allow injection of restrictions on transfers using `AppendSendRestriction` or `PrependSendRestriction`.
 
 ### Improvements
 

x/bank/README.md

@@ -236,8 +236,12 @@ accounts. The send keeper does not alter the total supply (mint or burn coins).
 type SendKeeper interface {
     ViewKeeper
 
-    InputOutputCoins(ctx context.Context, inputs types.Input, outputs []types.Output) error
-    SendCoins(ctx context.Context, fromAddr sdk.AccAddress, toAddr sdk.AccAddress, amt sdk.Coins) error
+    AppendSendRestriction(restriction SendRestrictionFn)
+    PrependSendRestriction(restriction SendRestrictionFn)
+    ClearSendRestriction()
+
+    InputOutputCoins(ctx context.Context, input types.Input, outputs []types.Output) error
+    SendCoins(ctx context.Context, fromAddr, toAddr sdk.AccAddress, amt sdk.Coins) error
 
     GetParams(ctx context.Context) types.Params
     SetParams(ctx context.Context, params types.Params) error
@@ -256,6 +260,86 @@ type SendKeeper interface {
 }
 ```
 
+#### Send Restrictions
+
+The `SendKeeper` applies a `SendRestrictionFn` before each transfer of funds.
+
+```golang
+// A SendRestrictionFn can restrict sends and/or provide a new receiver address.
+type SendRestrictionFn func(ctx context.Context, fromAddr, toAddr sdk.AccAddress, amt sdk.Coins) (newToAddr sdk.AccAddress, err error)
+```
+
+After the `SendKeeper` (or `BaseKeeper`) has been created, send restrictions can be added to it using the `AppendSendRestriction` or `PrependSendRestriction` functions.
+Both functions compose the provided restriction with any previously provided restrictions.
+`AppendSendRestriction` adds the provided restriction to be run after any previously provided send restrictions.
+`PrependSendRestriction` adds the restriction to be run before any previously provided send restrictions.
+The composition will short-circuit when an error is encountered. I.e. if the first one returns an error, the second is not run.
+
+During `SendCoins`, the send restriction is applied after coins are removed from the from address, but before adding them to the to address.
+During `InputOutputCoins`, the send restriction is applied after the input coins are removed and once for each output before the funds are added.
+
+A send restriction function should make use of a custom value in the context to allow bypassing that specific restriction.
+
+For example, in your module's keeper package, you'd define the send restriction function:
+
+```golang
+var _ banktypes.SendRestrictionFn = Keeper{}.SendRestrictionFn
+
+func (k Keeper) SendRestrictionFn(ctx context.Context, fromAddr, toAddr sdk.AccAddress, amt sdk.Coins) (sdk.AccAddress, error) {
+	// Bypass if the context says to.
+	if mymodule.HasBypass(ctx) {
+		return toAddr, nil
+	}
+
+	// Your custom send restriction logic goes here.
+	return nil, errors.New("not implemented")
+}
+```
+
+The bank keeper should be provided to your keeper's constructor so the send restriction can be added to it:
+
+```golang
+func NewKeeper(cdc codec.BinaryCodec, storeKey storetypes.StoreKey, bankKeeper mymodule.BankKeeper) Keeper {
+	rv := Keeper{/*...*/}
+	bankKeeper.AppendSendRestriction(rv.SendRestrictionFn)
+	return rv
+}
+```
+
+Then, in the `mymodule` package, define the context helpers:
+
+```golang
+const bypassKey = "bypass-mymodule-restriction"
+
+// WithBypass returns a new context that will cause the mymodule bank send restriction to be skipped.
+func WithBypass(ctx context.Context) context.Context {
+	return sdk.UnwrapSDKContext(ctx).WithValue(bypassKey, true)
+}
+
+// WithoutBypass returns a new context that will cause the mymodule bank send restriction to not be skipped.
+func WithoutBypass(ctx context.Context) context.Context {
+	return sdk.UnwrapSDKContext(ctx).WithValue(bypassKey, false)
+}
+
+// HasBypass checks the context to see if the mymodule bank send restriction should be skipped.
+func HasBypass(ctx context.Context) bool {
+	bypassValue := ctx.Value(bypassKey)
+	if bypassValue == nil {
+		return false
+	}
+	bypass, isBool := bypassValue.(bool)
+	return isBool && bypass
+}
+```
+
+Now, anywhere where you want to use `SendCoins` or `InputOutputCoins`, but you don't want your send restriction applied:
+
+```golang
+func (k Keeper) DoThing(ctx context.Context, fromAddr, toAddr sdk.AccAddress, amt sdk.Coins) error {
+	return k.bankKeeper.SendCoins(mymodule.WithBypass(ctx), fromAddr, toAddr, amt)
+}
+```
+
 ### ViewKeeper
 
 The view keeper provides read-only access to account balances. The view keeper does not have balance alteration functionality. All balance lookups are `O(1)`.

x/bank/keeper/export_test.go

@@ -0,0 +1,14 @@
+package keeper
+
+import "github.com/cosmos/cosmos-sdk/x/bank/types"
+
+// This file exists in the keeper package to expose some private things
+// for the purpose of testing in the keeper_test package.
+
+func (k BaseSendKeeper) SetSendRestriction(restriction types.SendRestrictionFn) {
+	k.sendRestriction.fn = restriction
+}
+
+func (k BaseSendKeeper) GetSendRestrictionFn() types.SendRestrictionFn {
+	return k.sendRestriction.fn
+}

x/bank/keeper/keeper.go

@@ -25,7 +25,7 @@ var _ Keeper = (*BaseKeeper)(nil)
 // between accounts.
 type Keeper interface {
 	SendKeeper
-	WithMintCoinsRestriction(MintingRestrictionFn) BaseKeeper
+	WithMintCoinsRestriction(types.MintingRestrictionFn) BaseKeeper
 
 	InitGenesis(context.Context, *types.GenesisState)
 	ExportGenesis(context.Context) *types.GenesisState
@@ -61,12 +61,10 @@ type BaseKeeper struct {
 	ak                     types.AccountKeeper
 	cdc                    codec.BinaryCodec
 	storeService           store.KVStoreService
-	mintCoinsRestrictionFn MintingRestrictionFn
+	mintCoinsRestrictionFn types.MintingRestrictionFn
 	logger                 log.Logger
 }
 
-type MintingRestrictionFn func(ctx context.Context, coins sdk.Coins) error
-
 // GetPaginatedTotalSupply queries for the supply, ignoring 0 coins, with a given pagination
 func (k BaseKeeper) GetPaginatedTotalSupply(ctx context.Context, pagination *query.PageRequest) (sdk.Coins, *query.PageResponse, error) {
 	coins, pageResp, err := query.CollectionPaginate(ctx, k.Supply, pagination, func(key string, value math.Int) (sdk.Coin, error) {
@@ -105,7 +103,7 @@ func NewBaseKeeper(
 		ak:                     ak,
 		cdc:                    cdc,
 		storeService:           storeService,
-		mintCoinsRestrictionFn: func(ctx context.Context, coins sdk.Coins) error { return nil },
+		mintCoinsRestrictionFn: types.NoOpMintingRestrictionFn,
 		logger:                 logger,
 	}
 }
@@ -115,19 +113,8 @@ func NewBaseKeeper(
 // Previous restriction functions can be nested as such:
 //
 //	bankKeeper.WithMintCoinsRestriction(restriction1).WithMintCoinsRestriction(restriction2)
-func (k BaseKeeper) WithMintCoinsRestriction(check MintingRestrictionFn) BaseKeeper {
-	oldRestrictionFn := k.mintCoinsRestrictionFn
-	k.mintCoinsRestrictionFn = func(ctx context.Context, coins sdk.Coins) error {
-		err := check(ctx, coins)
-		if err != nil {
-			return err
-		}
-		err = oldRestrictionFn(ctx, coins)
-		if err != nil {
-			return err
-		}
-		return nil
-	}
+func (k BaseKeeper) WithMintCoinsRestriction(check types.MintingRestrictionFn) BaseKeeper {
+	k.mintCoinsRestrictionFn = check.Then(k.mintCoinsRestrictionFn)
 	return k
 }