From 85821bd9538825c4a3b3947aa02f3ed4eaab1768 Mon Sep 17 00:00:00 2001
From: srdtrk <59252793+srdtrk@users.noreply.github.com>
Date: Wed, 23 Aug 2023 13:04:57 +0300
Subject: [PATCH] docs(callbacks): added godocs for defensive send packet
 validation (#4358)

* docs(callbacks): added godocs for send packet validation

* docs(callbacks): improved godocs

* docs(callbacks): used colin and damian suggested doc string

* docs(callbacks): fixed typo

* docs(callbacks): improved a minor typo
---
 modules/apps/callbacks/types/expected_keepers.go | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/modules/apps/callbacks/types/expected_keepers.go b/modules/apps/callbacks/types/expected_keepers.go
index f21d3dbd923..1fc9494c352 100644
--- a/modules/apps/callbacks/types/expected_keepers.go
+++ b/modules/apps/callbacks/types/expected_keepers.go
@@ -16,6 +16,11 @@ type ContractKeeper interface {
 	// gas limit, and handle any errors, or panics gracefully.
 	// If an error is returned, the transaction will be reverted by the callbacks middleware, and the
 	// packet will not be sent.
+	//
+	// Implementations are provided with the packetSenderAddress and MAY choose to use this to perform
+	// validation on the origin of a given packet. It is recommended to perform the same validation
+	// on all source chain callbacks (SendPacket, AcknowledgementPacket, TimeoutPacket). This
+	// defensively guards against exploits due to incorrectly wired SendPacket ordering in IBC stacks.
 	IBCSendPacketCallback(
 		ctx sdk.Context,
 		sourcePort string,
@@ -31,6 +36,11 @@ type ContractKeeper interface {
 	// the sender is unknown or undefined. The contract is expected to handle the callback within the
 	// user defined gas limit, and handle any errors, or panics gracefully.
 	// If an error is returned, state will be reverted by the callbacks middleware.
+	//
+	// Implementations are provided with the packetSenderAddress and MAY choose to use this to perform
+	// validation on the origin of a given packet. It is recommended to perform the same validation
+	// on all source chain callbacks (SendPacket, AcknowledgementPacket, TimeoutPacket). This
+	// defensively guards against exploits due to incorrectly wired SendPacket ordering in IBC stacks.
 	IBCOnAcknowledgementPacketCallback(
 		ctx sdk.Context,
 		packet channeltypes.Packet,
@@ -44,6 +54,11 @@ type ContractKeeper interface {
 	// empty if the sender is unknown or undefined. The contract is expected to handle the callback
 	// within the user defined gas limit, and handle any error, out of gas, or panics gracefully.
 	// If an error is returned, state will be reverted by the callbacks middleware.
+	//
+	// Implementations are provided with the packetSenderAddress and MAY choose to use this to perform
+	// validation on the origin of a given packet. It is recommended to perform the same validation
+	// on all source chain callbacks (SendPacket, AcknowledgementPacket, TimeoutPacket). This
+	// defensively guards against exploits due to incorrectly wired SendPacket ordering in IBC stacks.
 	IBCOnTimeoutPacketCallback(
 		ctx sdk.Context,
 		packet channeltypes.Packet,