docs: msg types for fee middleware

[charleenfei]

Description

closes: #1409

---

Before we can merge this PR, please make sure that all the following items have been
checked off. If any of the checklist items are not applicable, please leave them but
write a little note why.

• Targeted PR against correct branch (see CONTRIBUTING.md)
• Linked to Github issue with discussion and accepted design OR link to spec that describes this work.
• Code follows the module structure standards.
• Wrote unit and integration tests
• Updated relevant documentation (docs/) or specification (x/<module>/spec/)
• Added relevant godoc comments.
• Added a relevant changelog entry to the Unreleased section in CHANGELOG.md
• Re-reviewed Files changed in the Github PR explorer
• Review Codecov Report in the comment section below once CI passes

[chatton]

really concise nice job! 🥇

[charleenfei]

note: i'll update the relayer operator section link once the pr from @damiannolan is in

[damiannolan]

I've opened #1577 for docs about fee distribution and relayer operators.
What do you think about this? #1577 (comment)

[crodriguezvega]

Suggested change

	Note that the `Relayers` field has been set up to allow for an optional whitelist of relayers permitted to the receive this fee, however, this feature has not yet been enabled at this time.
	Note that the `Relayers` field has been set up to allow for an optional whitelist of relayers permitted to receive this fee, however, this feature has not yet been enabled at this time.

[crodriguezvega]

The alignment is a bit off here.

[charleenfei]

it's on purpose, otherwise the generated HackMD doesnt look right

[seantking]

Maybe worth doing a make view docs and see how it looks there? If you look at the github readme version it seems a bit off too :)

[crodriguezvega]

Suggested change

	where the PacketFee also specifies the `Fee` to be paid as well as the refund address for fees which are not paid out
	where the `PacketFee` also specifies the `Fee` to be paid as well as the refund address for fees which are not paid out:

[crodriguezvega]

Suggested change

	The `Fee` message contained in this synchronous fee payment method configures different fees which will be paid out for `RecvPackets`, `Acknowledgements`, and `Timeouts`.
	The `Fee` message contained in this synchronous fee payment method configures different fees which will be paid out for `MsgRecvPacket`, `MsgAcknowledgement`, and `MsgTimeout`/`MsgTimeoutOnClose`.

[crodriguezvega]

Suggested change

In the case of a successful transaction, `RecvFee` will be paid out to the designated counterparty payee address which has been registered on the receiver chain and sent back with the `Acknowledgement`, `AckFee` will be paid out to the relayer address which has submitted the `Acknowledgement` on the sending chain (or the registered payee in case one has been registered for the relayer address), and `TimeoutFee` will be reimbursed to the account which escrowed the fee. In cases of timeout transactions, `RecvFee` and `AckFee` will be reimbursed.

In the case of a successful transaction, `RecvFee` will be paid out to the designated counterparty payee address which has been registered on the receiver chain and sent back with the `MsgAcknowledgement`, `AckFee` will be paid out to the relayer address which has submitted the `MsgAcknowledgement` on the sending chain (or the registered payee in case one has been registered for the relayer address), and `TimeoutFee` will be reimbursed to the account which escrowed the fee. In cases of timeout transactions, `RecvFee` and `AckFee` will be reimbursed.

[crodriguezvega]

Should you explain a bit what PacketId is?

[charleenfei]

i thought it was kind of self explanatory....the ID of the packet?

[damiannolan]

In my opinion we should add the Go type definitions with the in line comments. We can probably omit the protobuf and json tags within the back ticks.

type MsgPayPacketFeeAsync struct {
	// unique packet identifier comprised of the channel ID, port ID and sequence
	PacketId types.PacketId `protobuf:"bytes,1,opt,name=packet_id,json=packetId,proto3" json:"packet_id" yaml:"packet_id"`
	// the packet fee associated with a particular IBC packet
	PacketFee PacketFee `protobuf:"bytes,2,opt,name=packet_fee,json=packetFee,proto3" json:"packet_fee" yaml:"packet_fee"`
}

[crodriguezvega]

I thought that maybe explaining that packet ID consists of port ID, channel ID and sequence would be helpful, but feel free to keep it like this if you think that mentioning this is just too obvious...

[damiannolan]

Looks great so far, left a couple of small suggestions!

[damiannolan]

Should we maybe use Go type definitions here instead? Alternatively we could use proto but I think Go is more fitting considering.Eg. remove trailing commas and add type declaration

Suggested change

	```
	MsgPayPacketFee{
	Fee Fee,
	SourcePortId string,
	SourceChannelId string,
	Signer string,
	Relayers []string,
	}
	```
	```
	type MsgPayPacketFee struct {
	Fee Fee
	SourcePortId string
	SourceChannelId string
	Signer string
	Relayers []string
	}
	```

[damiannolan]

ditto! for all types :)

[damiannolan]

nit: feel free to ignore

Suggested change

	The fee middleware module can become locked if the situation arises that the escrow account for the fees does not have sufficient funds to pay out the fees which have been registered for each packet. This situation indicates a severe bug. In this case, the fee module will be locked until manual intervention fixes the issue.
	The fee middleware module can become locked if the situation arises that the escrow account for the fees does not have sufficient funds to pay out the fees which have been escrowed for each packet. This situation indicates a severe bug. In this case, the fee module will be locked until manual intervention fixes the issue.

[damiannolan]

Should we consider using the "payee" terminology here?

Suggested change

	Please note that fee payments are built on the assumption that sender chains are the source of incentives — the chain that sends the packets is the same chain where fee payments will occur -- please see <relayer operater> section to understand the flow for registering fee-receiving addresses.
	Please note that fee payments are built on the assumption that sender chains are the source of incentives — the chain that sends the packets is the same chain where fee payments will occur -- please see <relayer operater> section to understand the flow for registering fee payee addresses.

[damiannolan]

We should add this new page to the children array! I think you'll need to merge main first

[seantking]

Suggested change

[crodriguezvega]

Should this section be titled just Escrowing fees? Since I think there is only a reference to the messages to escrow fees here and the part about paying out fees is talked about in the next section.

[seantking]

Nice work! I pushed a commit just to satisfy the final nits and link to @damiannolan docs that were just merged.