From b7efd62db71972bc7032175e4dfe8501beabb12d Mon Sep 17 00:00:00 2001
From: Simon Warta <simon@warta.it>
Date: Tue, 30 Jan 2024 11:49:33 +0100
Subject: [PATCH] Add MIGRATING entry for payload

---
 MIGRATING.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/MIGRATING.md b/MIGRATING.md
index 3649f40243..2b20ac4b57 100644
--- a/MIGRATING.md
+++ b/MIGRATING.md
@@ -221,6 +221,47 @@ major releases of `cosmwasm`. Note that you can also view the
   +}))?;
   ```
 
+- A new `payload` field allows you to send arbitrary data from the original
+  contract into the `reply`. If you construct `SubMsg` manually, add the
+  `payload` field:
+
+  ```diff
+   SubMsg {
+       id: 12,
+  +    payload: Binary::default(),
+       msg: my_bank_send,
+       gas_limit: Some(12345u64),
+       reply_on: ReplyOn::Always,
+   },
+  ```
+
+  or with data:
+
+  ```diff
+   SubMsg {
+       id: 12,
+  +    payload: Binary::new(vec![9, 8, 7, 6, 5]),
+       msg: my_bank_send,
+       gas_limit: Some(12345u64),
+       reply_on: ReplyOn::Always,
+   },
+  ```
+
+  If you use a constructor function, you can set the payload as follows:
+
+  ```diff
+   SubMsg::new(BankMsg::Send {
+     to_address: payout,
+     amount: coins(123456u128,"gold")
+   })
+  +.with_payload(vec![9, 8, 7, 6, 5])
+  ```
+
+  The payload data will then be available in the new field `Reply.payload` in
+  the `reply` entry point. This functionality is an optional addition introduced
+  in 2.0. To keep the CosmWasm 1.x behaviour, just set payload to
+  `Binary::default()`.
+
 ## 1.4.x -> 1.5.0
 
 - Update `cosmwasm-*` dependencies in Cargo.toml (skip the ones you don't use):