ICS27: add explanation about expected behavior for controller modules…

… `onRecvPacket` callback (cosmos#845) * add note about controller modules not doing anything in onRecvPacket * address review comment * typos Co-authored-by: Carlos Rodriguez <crodveg@gmail.com>
worldarchi · Oct 12, 2022 · 1ada61e · 1ada61e
1 parent 94baa3f
commit 1ada61e
Show file tree

Hide file tree

Showing 2 changed files with 14 additions and 1 deletion.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -59,3 +59,4 @@ Ref: https://keepachangelog.com/en/1.0.0/
 - [\#806](https://github.com/cosmos/ibc/pull/806) Adds previous version to UpgradeInit and UpgradeTry callback arguments
 - [\#807](https://github.com/cosmos/ibc/pull/807) Upgrade keys will now prefix the channel path to align with the rest of ICS4 keys
 - [\#842](https://github.com/cosmos/ibc/pull/842) Adds metadata field to FungibleTokenPacketData
+- [\#845](https://github.com/cosmos/ibc/pull/845) Adds explanation about `onRecvPacket` callback returning an error in interchain accounts controller modules
diff --git a/spec/app/ics-027-interchain-accounts/README.md b/spec/app/ics-027-interchain-accounts/README.md
@@ -527,7 +527,8 @@ function onChanCloseConfirm(
 `onRecvPacket` is called by the routing module when a packet addressed to this module has been received.
 
 ```typescript
-function OnRecvPacket(packet Packet) {
+// Called on Host Chain by Relayer
+function onRecvPacket(packet Packet) {
   ack = NewResultAcknowledgement([]byte{byte(1)})
 
 	// only attempt the application logic if the packet data
@@ -559,6 +560,7 @@ function OnRecvPacket(packet Packet) {
 `onAcknowledgePacket` is called by the routing module when a packet sent by this module has been acknowledged.
 
 ```typescript
+// Called on Controller Chain by Relayer
 function onAcknowledgePacket(
   packet: Packet,
   acknowledgement: bytes) {
@@ -568,12 +570,22 @@ function onAcknowledgePacket(
 ```
 
 ```typescript
+// Called on Controller Chain by Relayer
 function onTimeoutPacket(packet: Packet) {
     // call underlying app's OnTimeoutPacket callback 
     // see ICS-30 middleware for more information
 }
 ```
 
+Note that interchain accounts controller modules should not execute any logic upon packet receipt, i.e. the `OnRecvPacket` callback should not be called, and in case it is called, it should simply return an error acknowledgement:
+
+```typescript
+// Called on Controller Chain by Relayer
+function onRecvPacket(packet Packet) {
+  return NewErrorAcknowledgement(ErrInvalidChannelFlow)
+}
+```
+
 ### Identifier formats
 
 These are the formats that the port identifiers on each side of an interchain accounts channel must follow to be accepted by a correct interchain accounts module.