ICS 29: Fee Middleware

docs/architecture/README.md

@@ -30,6 +30,7 @@ To suggest an ADR, please make use of the [ADR template](./adr-template.md) prov
 | [001](./adr-001-coin-source-tracing.md) | ICS-20 coin denomination format | Accepted, Implemented |
 | [002](./adr-002-go-module-versioning.md) | Go module versioning | Accepted |
 | [003](./adr-003-ics27-acknowledgement.md) | ICS27 acknowledgement format | Accepted |
+| [004](./adr-004-ics29-lock-fee-module.md) | ICS29 module locking upon escrow out of balance | Accepted |
 | [015](./adr-015-ibc-packet-receiver.md) | IBC Packet Routing | Accepted |
 | [025](./adr-025-ibc-passive-channels.md) | IBC passive channels | Deprecated |
 | [026](./adr-026-ibc-client-recovery-mechanisms.md) | IBC client recovery mechansisms | Accepted |

docs/architecture/adr-004-ics29-lock-fee-module.md

@@ -0,0 +1,55 @@
+# ADR 004: Lock fee module upon escrow out of balance
+
+## Changelog
+* 03/03/2022: initial draft
+
+## Status
+
+Accepted
+
+## Context
+
+The fee module maintains an escrow account for all fees escrowed to incentivize packet relays. 
+It also tracks each packet fee escrowed separately from the escrow account. This is because the escrow account only maintains a total balance. It has no reference for which coins belonged to which packet fee. 
+In the presence of a severe bug, it is possible the escrow balance will become out of sync with the packet fees marked as escrowed.
+The ICS29 module should be capable of elegantly handling such a scenario.
+
+## Decision
+
+We will allow for the ICS29 module to become "locked" if the escrow balance is determined to be out of sync with the packet fees marked as escrowed. 
+A "locked" fee module will not allow for packet escrows to occur nor will it distribute fees. All IBC callbacks will skip performing fee logic, similar to fee disabled channels. 
+
+Manual intervention will be needed to unlock the fee module. 
+
+### Sending side
+
+Special behaviour will have to be accounted for in `OnAcknowledgementPacket`. Since the counterparty will continue to send incentivized acknowledgements for fee enabled channels, the acknowledgement will still need to be unmarshalled into an incentivized acknowledgement before calling the underlying application `OnAcknowledgePacket` callback. 
+
+When distributing fees, a cached context should be used. If the escrow account balance would become negative, the current state changes should be discarded and the fee module should be locked using the uncached context. This prevents fees from being partially distributed for a given packetID.
+
+### Receiving side
+
+`OnRecvPacket` should remain unaffected by the fee module becoming locked since escrow accounts only affect the sending side. 
+
+## Consequences
+
+### Positive
+
+The fee module can be elegantly disabled in the presence of severe bugs.
+
+### Negative
+
+Extra logic is added to account for edge cases which are only possible in the presence of bugs. 
+
+### Neutral
+
+## References
+
+Issues:
+- [#821](https://github.com/cosmos/ibc-go/issues/821)
+- [#860](https://github.com/cosmos/ibc-go/issues/860)
+
+PR's:
+- [#1031](https://github.com/cosmos/ibc-go/pull/1031)
+- [#1029](https://github.com/cosmos/ibc-go/pull/1029)
+- [#1056](https://github.com/cosmos/ibc-go/pull/1056)

modules/apps/29-fee/client/cli/cli.go

@@ -0,0 +1,42 @@
+package cli
+
+import (
+	"github.com/cosmos/cosmos-sdk/client"
+	"github.com/spf13/cobra"
+)
+
+// GetQueryCmd returns the query commands for 29-fee
+func GetQueryCmd() *cobra.Command {
+	queryCmd := &cobra.Command{
+		Use:                        "ibc-fee",
+		Short:                      "", // TODO
+		DisableFlagParsing:         true,
+		SuggestionsMinimumDistance: 2,
+	}
+
+	queryCmd.AddCommand(
+		GetCmdTotalRecvFees(),
+		GetCmdTotalAckFees(),
+		GetCmdTotalTimeoutFees(),
+	)
+
+	return queryCmd
+}
+
+// NewTxCmd returns the transaction commands for 29-fee
+func NewTxCmd() *cobra.Command {
+	txCmd := &cobra.Command{
+		Use:                        "ibc-fee",
+		Short:                      "Transaction subcommand for IBC relayer incentivization",
+		DisableFlagParsing:         true,
+		SuggestionsMinimumDistance: 2,
+		RunE:                       client.ValidateCmd,
+	}
+
+	txCmd.AddCommand(
+		NewPayPacketFeeAsyncTxCmd(),
+		NewRegisterCounterpartyAddress(),
+	)
+
+	return txCmd
+}

modules/apps/29-fee/client/cli/query.go

@@ -0,0 +1,151 @@
+package cli
+
+import (
+	"fmt"
+	"strconv"
+
+	"github.com/cosmos/cosmos-sdk/client"
+	"github.com/cosmos/cosmos-sdk/client/flags"
+	"github.com/cosmos/cosmos-sdk/version"
+	"github.com/cosmos/ibc-go/v3/modules/apps/29-fee/types"
+	channeltypes "github.com/cosmos/ibc-go/v3/modules/core/04-channel/types"
+	"github.com/spf13/cobra"
+)
+
+// GetCmdTotalRecvFees returns the command handler for the Query/TotalRecvFees rpc.
+func GetCmdTotalRecvFees() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "total-recv-fees [port-id] [channel-id] [sequence]",
+		Short:   "Query the total receive fees for a packet",
+		Long:    "Query the total receive fees for a packet",
+		Args:    cobra.ExactArgs(3),
+		Example: fmt.Sprintf("%s query ibc-fee total-recv-fees transfer channel-5 100", version.AppName),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			clientCtx, err := client.GetClientQueryContext(cmd)
+			if err != nil {
+				return err
+			}
+
+			portID, channelID := args[0], args[1]
+			seq, err := strconv.ParseUint(args[2], 10, 64)
+			if err != nil {
+				return err
+			}
+
+			packetID := channeltypes.NewPacketId(channelID, portID, seq)
+
+			if err := packetID.Validate(); err != nil {
+				return err
+			}
+
+			queryClient := types.NewQueryClient(clientCtx)
+
+			req := &types.QueryTotalRecvFeesRequest{
+				PacketId: packetID,
+			}
+
+			res, err := queryClient.TotalRecvFees(cmd.Context(), req)
+			if err != nil {
+				return err
+			}
+
+			return clientCtx.PrintProto(res)
+		},
+	}
+
+	flags.AddQueryFlagsToCmd(cmd)
+
+	return cmd
+}
+
+// GetCmdTotalAckFees returns the command handler for the Query/TotalAckFees rpc.
+func GetCmdTotalAckFees() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "total-ack-fees [port-id] [channel-id] [sequence]",
+		Short:   "Query the total acknowledgement fees for a packet",
+		Long:    "Query the total acknowledgement fees for a packet",
+		Args:    cobra.ExactArgs(3),
+		Example: fmt.Sprintf("%s query ibc-fee total-ack-fees transfer channel-5 100", version.AppName),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			clientCtx, err := client.GetClientQueryContext(cmd)
+			if err != nil {
+				return err
+			}
+
+			portID, channelID := args[0], args[1]
+			seq, err := strconv.ParseUint(args[2], 10, 64)
+			if err != nil {
+				return err
+			}
+
+			packetID := channeltypes.NewPacketId(channelID, portID, seq)
+
+			if err := packetID.Validate(); err != nil {
+				return err
+			}
+
+			queryClient := types.NewQueryClient(clientCtx)
+
+			req := &types.QueryTotalAckFeesRequest{
+				PacketId: packetID,
+			}
+
+			res, err := queryClient.TotalAckFees(cmd.Context(), req)
+			if err != nil {
+				return err
+			}
+
+			return clientCtx.PrintProto(res)
+		},
+	}
+
+	flags.AddQueryFlagsToCmd(cmd)
+
+	return cmd
+}
+
+// GetCmdTotalTimeoutFees returns the command handler for the Query/TotalTimeoutFees rpc.
+func GetCmdTotalTimeoutFees() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "total-timeout-fees [port-id] [channel-id] [sequence]",
+		Short:   "Query the total timeout fees for a packet",
+		Long:    "Query the total timeout fees for a packet",
+		Args:    cobra.ExactArgs(3),
+		Example: fmt.Sprintf("%s query ibc-fee total-timeout-fees transfer channel-5 100", version.AppName),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			clientCtx, err := client.GetClientQueryContext(cmd)
+			if err != nil {
+				return err
+			}
+
+			portID, channelID := args[0], args[1]
+			seq, err := strconv.ParseUint(args[2], 10, 64)
+			if err != nil {
+				return err
+			}
+
+			packetID := channeltypes.NewPacketId(channelID, portID, seq)
+
+			if err := packetID.Validate(); err != nil {
+				return err
+			}
+
+			queryClient := types.NewQueryClient(clientCtx)
+
+			req := &types.QueryTotalTimeoutFeesRequest{
+				PacketId: packetID,
+			}
+
+			res, err := queryClient.TotalTimeoutFees(cmd.Context(), req)
+			if err != nil {
+				return err
+			}
+
+			return clientCtx.PrintProto(res)
+		},
+	}
+
+	flags.AddQueryFlagsToCmd(cmd)
+
+	return cmd
+}

modules/apps/29-fee/client/cli/tx.go

@@ -0,0 +1,124 @@
+package cli
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/cosmos/cosmos-sdk/client"
+	"github.com/cosmos/cosmos-sdk/client/flags"
+	"github.com/cosmos/cosmos-sdk/client/tx"
+	sdk "github.com/cosmos/cosmos-sdk/types"
+	"github.com/cosmos/cosmos-sdk/version"
+	"github.com/spf13/cobra"
+
+	"github.com/cosmos/ibc-go/v3/modules/apps/29-fee/types"
+	channeltypes "github.com/cosmos/ibc-go/v3/modules/core/04-channel/types"
+)
+
+const (
+	flagRecvFee    = "recv-fee"
+	flagAckFee     = "ack-fee"
+	flagTimeoutFee = "timeout-fee"
+)
+
+// NewPayPacketFeeAsyncTxCmd returns the command to create a MsgPayPacketFeeAsync
+func NewPayPacketFeeAsyncTxCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "pay-packet-fee [src-port] [src-channel] [sequence]",
+		Short:   "Pay a fee to incentivize an existing IBC packet",
+		Long:    strings.TrimSpace(`Pay a fee to incentivize an existing IBC packet.`),
+		Example: fmt.Sprintf("%s tx ibc-fee pay-packet-fee transfer channel-0 1 --recv-fee 10stake --ack-fee 10stake --timeout-fee 10stake", version.AppName),
+		Args:    cobra.ExactArgs(3),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			clientCtx, err := client.GetClientTxContext(cmd)
+			if err != nil {
+				return err
+			}
+
+			// NOTE: specifying non-nil relayers is currently unsupported
+			var relayers []string
+
+			sender := clientCtx.GetFromAddress().String()
+			seq, err := strconv.ParseUint(args[2], 10, 64)
+			if err != nil {
+				return err
+			}
+
+			packetID := channeltypes.NewPacketId(args[1], args[0], seq)
+
+			recvFeeStr, err := cmd.Flags().GetString(flagRecvFee)
+			if err != nil {
+				return err
+			}
+
+			recvFee, err := sdk.ParseCoinsNormalized(recvFeeStr)
+			if err != nil {
+				return err
+			}
+
+			ackFeeStr, err := cmd.Flags().GetString(flagAckFee)
+			if err != nil {
+				return err
+			}
+
+			ackFee, err := sdk.ParseCoinsNormalized(ackFeeStr)
+			if err != nil {
+				return err
+			}
+
+			timeoutFeeStr, err := cmd.Flags().GetString(flagTimeoutFee)
+			if err != nil {
+				return err
+			}
+
+			timeoutFee, err := sdk.ParseCoinsNormalized(timeoutFeeStr)
+			if err != nil {
+				return err
+			}
+
+			fee := types.Fee{
+				RecvFee:    recvFee,
+				AckFee:     ackFee,
+				TimeoutFee: timeoutFee,
+			}
+
+			packetFee := types.NewPacketFee(fee, sender, relayers)
+			msg := types.NewMsgPayPacketFeeAsync(packetID, packetFee)
+
+			return tx.GenerateOrBroadcastTxCLI(clientCtx, cmd.Flags(), msg)
+		},
+	}
+
+	cmd.Flags().String(flagRecvFee, "", "Fee paid to a relayer for relaying a packet receive.")
+	cmd.Flags().String(flagAckFee, "", "Fee paid to a relayer for relaying a packet acknowledgement.")
+	cmd.Flags().String(flagTimeoutFee, "", "Fee paid to a relayer for relaying a packet timeout.")
+	flags.AddTxFlagsToCmd(cmd)
+
+	return cmd
+}
+
+// NewRegisterCounterpartyAddress returns the command to create a MsgRegisterCounterpartyAddress
+func NewRegisterCounterpartyAddress() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "register-counterparty [address] [counterparty-address] [channel-id]",
+		Short:   "Register a counterparty relayer address on a given channel.",
+		Long:    strings.TrimSpace(`Register a counterparty relayer address on a given channel.`),
+		Example: fmt.Sprintf("%s tx ibc-fee register-counterparty cosmos1rsp837a4kvtgp2m4uqzdge0zzu6efqgucm0qdh osmo1v5y0tz01llxzf4c2afml8s3awue0ymju22wxx2 channel-0", version.AppName),
+		Args:    cobra.ExactArgs(3),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			clientCtx, err := client.GetClientTxContext(cmd)
+			if err != nil {
+				return err
+			}
+
+			msg := types.NewMsgRegisterCounterpartyAddress(args[0], args[1], args[2])
+
+			return tx.GenerateOrBroadcastTxCLI(clientCtx, cmd.Flags(), msg)
+		},
+	}
+
+	flags.AddTxFlagsToCmd(cmd)
+
+	return cmd
+}