Merge pull request #2484 from CosmWasm/co/ibc-callbacks-funds

chipshort · web-flow · commit ec91dcb7838a · 2025-05-26T15:11:18.000+02:00
Add special handling for IBC Transfer to destination callback
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -35,6 +35,8 @@ and this project adheres to
   ([#2480])
 - cosmwasm-std: Add `WasmQuery::RawRange` query to allow querying raw storage
   ranges of different contracts. ([#2471])
+- cosmwasm-std: Add `transfer` field to `IbcDestinationCallbackMsg`, providing
+  an easier way to handle an IBC transfer in a destination callback. ([#2484])
 
 ## Changed
 
@@ -138,6 +140,7 @@ and this project adheres to
 [#2477]: https://github.com/CosmWasm/cosmwasm/pull/2477
 [#2479]: https://github.com/CosmWasm/cosmwasm/pull/2479
 [#2480]: https://github.com/CosmWasm/cosmwasm/pull/2480
+[#2484]: https://github.com/CosmWasm/cosmwasm/pull/2484
 
 ## [2.2.0] - 2024-12-17
 
diff --git a/contracts/ibc-callbacks/schema/ibc-callbacks.json b/contracts/ibc-callbacks/schema/ibc-callbacks.json
@@ -148,6 +148,22 @@
           "description": "Binary is a wrapper around Vec<u8> to add base64 de/serialization with serde. It also adds some helper methods to help encode inline.\n\nThis is only needed as serde-json-{core,wasm} has a horrible encoding for Vec<u8>. See also <https://github.com/CosmWasm/cosmwasm/blob/main/docs/MESSAGE_TYPES.md>.",
           "type": "string"
         },
+        "Coin": {
+          "type": "object",
+          "required": [
+            "amount",
+            "denom"
+          ],
+          "properties": {
+            "amount": {
+              "$ref": "#/definitions/Uint256"
+            },
+            "denom": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        },
         "IbcAckCallbackMsg": {
           "type": "object",
           "required": [
@@ -193,6 +209,17 @@
             },
             "packet": {
               "$ref": "#/definitions/IbcPacket"
+            },
+            "transfer": {
+              "description": "When the underlying packet is a successful transfer message, this field contains information about the transfer. Otherwise it is empty.\n\nThis is always empty on chains using CosmWasm < 3.0",
+              "anyOf": [
+                {
+                  "$ref": "#/definitions/IbcTransferCallback"
+                },
+                {
+                  "type": "null"
+                }
+              ]
             }
           },
           "additionalProperties": false
@@ -325,6 +352,36 @@
           },
           "additionalProperties": false
         },
+        "IbcTransferCallback": {
+          "type": "object",
+          "required": [
+            "funds",
+            "receiver",
+            "sender"
+          ],
+          "properties": {
+            "funds": {
+              "description": "The funds that were transferred.\n\nWhen the callback is executed, the transfer is completed already and the coins are now owned by the receiver.",
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/Coin"
+              }
+            },
+            "receiver": {
+              "description": "Address of the receiver of the transfer. Since this is on the destination chain, this is a valid address.",
+              "allOf": [
+                {
+                  "$ref": "#/definitions/Addr"
+                }
+              ]
+            },
+            "sender": {
+              "description": "Address of the sender of the transfer. Note that this is *not* a valid address on the destination chain.",
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        },
         "Timestamp": {
           "description": "A point in time in nanosecond precision.\n\nThis type can represent times from 1970-01-01T00:00:00Z to 2554-07-21T23:34:33Z.\n\n## Examples\n\n``` # use cosmwasm_std::Timestamp; let ts = Timestamp::from_nanos(1_000_000_202); assert_eq!(ts.nanos(), 1_000_000_202); assert_eq!(ts.seconds(), 1); assert_eq!(ts.subsec_nanos(), 202);\n\nlet ts = ts.plus_seconds(2); assert_eq!(ts.nanos(), 3_000_000_202); assert_eq!(ts.seconds(), 3); assert_eq!(ts.subsec_nanos(), 202); ```",
           "allOf": [
@@ -333,6 +390,10 @@
             }
           ]
         },
+        "Uint256": {
+          "description": "An implementation of u256 that is using strings for JSON encoding/decoding, such that the full u256 range can be used for clients that convert JSON numbers to floats, like JavaScript and jq.\n\n# Examples\n\nUse `new` to create instances out of u128, `from` for other primitive uint types or `from_be_bytes` to provide big endian bytes:\n\n``` # use cosmwasm_std::Uint256; let a = Uint256::new(258u128); let b = Uint256::from(258u16); let c = Uint256::from_be_bytes([ 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 1u8, 2u8, ]); assert_eq!(a, b); assert_eq!(a, c); ```",
+          "type": "string"
+        },
         "Uint64": {
           "description": "A thin wrapper around u64 that is using strings for JSON encoding/decoding, such that the full u64 range can be used for clients that convert JSON numbers to floats, like JavaScript and jq.\n\n# Examples\n\nUse `from` to create instances of this and `u64` to get the value out:\n\n``` # use cosmwasm_std::Uint64; let a = Uint64::from(42u64); assert_eq!(a.u64(), 42);\n\nlet b = Uint64::from(70u32); assert_eq!(b.u64(), 70); ```",
           "type": "string"
diff --git a/contracts/ibc-callbacks/schema/raw/response_to_callback_stats.json b/contracts/ibc-callbacks/schema/raw/response_to_callback_stats.json
@@ -38,6 +38,22 @@
       "description": "Binary is a wrapper around Vec<u8> to add base64 de/serialization with serde. It also adds some helper methods to help encode inline.\n\nThis is only needed as serde-json-{core,wasm} has a horrible encoding for Vec<u8>. See also <https://github.com/CosmWasm/cosmwasm/blob/main/docs/MESSAGE_TYPES.md>.",
       "type": "string"
     },
+    "Coin": {
+      "type": "object",
+      "required": [
+        "amount",
+        "denom"
+      ],
+      "properties": {
+        "amount": {
+          "$ref": "#/definitions/Uint256"
+        },
+        "denom": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
     "IbcAckCallbackMsg": {
       "type": "object",
       "required": [
@@ -83,6 +99,17 @@
         },
         "packet": {
           "$ref": "#/definitions/IbcPacket"
+        },
+        "transfer": {
+          "description": "When the underlying packet is a successful transfer message, this field contains information about the transfer. Otherwise it is empty.\n\nThis is always empty on chains using CosmWasm < 3.0",
+          "anyOf": [
+            {
+              "$ref": "#/definitions/IbcTransferCallback"
+            },
+            {
+              "type": "null"
+            }
+          ]
         }
       },
       "additionalProperties": false
@@ -215,6 +242,36 @@
       },
       "additionalProperties": false
     },
+    "IbcTransferCallback": {
+      "type": "object",
+      "required": [
+        "funds",
+        "receiver",
+        "sender"
+      ],
+      "properties": {
+        "funds": {
+          "description": "The funds that were transferred.\n\nWhen the callback is executed, the transfer is completed already and the coins are now owned by the receiver.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/Coin"
+          }
+        },
+        "receiver": {
+          "description": "Address of the receiver of the transfer. Since this is on the destination chain, this is a valid address.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/Addr"
+            }
+          ]
+        },
+        "sender": {
+          "description": "Address of the sender of the transfer. Note that this is *not* a valid address on the destination chain.",
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
     "Timestamp": {
       "description": "A point in time in nanosecond precision.\n\nThis type can represent times from 1970-01-01T00:00:00Z to 2554-07-21T23:34:33Z.\n\n## Examples\n\n``` # use cosmwasm_std::Timestamp; let ts = Timestamp::from_nanos(1_000_000_202); assert_eq!(ts.nanos(), 1_000_000_202); assert_eq!(ts.seconds(), 1); assert_eq!(ts.subsec_nanos(), 202);\n\nlet ts = ts.plus_seconds(2); assert_eq!(ts.nanos(), 3_000_000_202); assert_eq!(ts.seconds(), 3); assert_eq!(ts.subsec_nanos(), 202); ```",
       "allOf": [
@@ -223,6 +280,10 @@
         }
       ]
     },
+    "Uint256": {
+      "description": "An implementation of u256 that is using strings for JSON encoding/decoding, such that the full u256 range can be used for clients that convert JSON numbers to floats, like JavaScript and jq.\n\n# Examples\n\nUse `new` to create instances out of u128, `from` for other primitive uint types or `from_be_bytes` to provide big endian bytes:\n\n``` # use cosmwasm_std::Uint256; let a = Uint256::new(258u128); let b = Uint256::from(258u16); let c = Uint256::from_be_bytes([ 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 0u8, 1u8, 2u8, ]); assert_eq!(a, b); assert_eq!(a, c); ```",
+      "type": "string"
+    },
     "Uint64": {
       "description": "A thin wrapper around u64 that is using strings for JSON encoding/decoding, such that the full u64 range can be used for clients that convert JSON numbers to floats, like JavaScript and jq.\n\n# Examples\n\nUse `from` to create instances of this and `u64` to get the value out:\n\n``` # use cosmwasm_std::Uint64; let a = Uint64::from(42u64); assert_eq!(a.u64(), 42);\n\nlet b = Uint64::from(70u32); assert_eq!(b.u64(), 70); ```",
       "type": "string"
diff --git a/contracts/ibc-callbacks/src/contract.rs b/contracts/ibc-callbacks/src/contract.rs
@@ -1,5 +1,5 @@
 use cosmwasm_std::{
-    entry_point, to_json_binary, Binary, Deps, DepsMut, Empty, Env, IbcBasicResponse,
+    ensure, entry_point, to_json_binary, Binary, Deps, DepsMut, Empty, Env, IbcBasicResponse,
     IbcDestinationCallbackMsg, IbcDstCallback, IbcSourceCallbackMsg, IbcSrcCallback, IbcTimeout,
     MessageInfo, Response, StdError, StdResult, TransferMsgBuilder,
 };
@@ -132,6 +132,23 @@ pub fn ibc_destination_callback(
 ) -> StdResult<IbcBasicResponse> {
     let mut counts = load_stats(deps.storage)?;
 
+    // Assert that the receiver has the funds in the message.
+    // This is just for testing purposes and to show that the funds are already available during
+    // the callback.
+    if let Some(transfer) = &msg.transfer {
+        for coin in &transfer.funds {
+            let balance = deps
+                .querier
+                .query_balance(&transfer.receiver, &coin.denom)?;
+            ensure!(
+                balance.amount >= coin.amount,
+                StdError::generic_err(format!(
+                    "Didn't receive expected funds. expected: {coin}, have: {balance}"
+                ))
+            );
+        }
+    }
+
     // save the receive
     counts.ibc_destination_callbacks.push(msg);
 
diff --git a/packages/std/src/ibc/callbacks.rs b/packages/std/src/ibc/callbacks.rs
@@ -4,7 +4,7 @@
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
-use crate::{Addr, IbcAcknowledgement, IbcPacket, Uint64};
+use crate::{Addr, Coin, IbcAcknowledgement, IbcPacket, Uint64};
 
 /// This is just a type representing the data that has to be sent with the IBC message to receive
 /// callbacks. It should be serialized and sent with the IBC message.
@@ -191,6 +191,27 @@ impl IbcTimeoutCallbackMsg {
 pub struct IbcDestinationCallbackMsg {
     pub packet: IbcPacket,
     pub ack: IbcAcknowledgement,
+    /// When the underlying packet is a successful transfer message,
+    /// this field contains information about the transfer. Otherwise it is empty.
+    ///
+    /// This is always empty on chains using CosmWasm < 3.0
+    #[serde(default)]
+    pub transfer: Option<IbcTransferCallback>,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
+pub struct IbcTransferCallback {
+    /// Address of the sender of the transfer.
+    /// Note that this is *not* a valid address on the destination chain.
+    pub sender: String,
+    /// Address of the receiver of the transfer.
+    /// Since this is on the destination chain, this is a valid address.
+    pub receiver: Addr,
+    /// The funds that were transferred.
+    ///
+    /// When the callback is executed, the transfer is completed already and the coins are now owned
+    /// by the receiver.
+    pub funds: Vec<Coin>,
 }
 
 #[cfg(test)]
diff --git a/packages/std/src/lib.rs b/packages/std/src/lib.rs
@@ -75,7 +75,7 @@ pub use crate::ibc::{
     IbcDestinationCallbackMsg, IbcDstCallback, IbcEndpoint, IbcMsg, IbcOrder, IbcPacket,
     IbcPacketAckMsg, IbcPacketReceiveMsg, IbcPacketTimeoutMsg, IbcReceiveResponse,
     IbcSourceCallbackMsg, IbcSrcCallback, IbcTimeout, IbcTimeoutBlock, IbcTimeoutCallbackMsg,
-    TransferMsgBuilder,
+    IbcTransferCallback, TransferMsgBuilder,
 };
 pub use crate::ibc2::{
     Ibc2Msg, Ibc2PacketAckMsg, Ibc2PacketReceiveMsg, Ibc2PacketSendMsg, Ibc2PacketTimeoutMsg,
