feat(stdlib): add setData() (#3402)

Author: skywardboundd

dev-docs/CHANGELOG.md

@@ -13,6 +13,15 @@ The documentation changelog is kept separately: [CHANGELOG-DOCS](./CHANGELOG-DOC
 
 - Reordered arguments of the `__tact_store_address_opt` function to optimize gas consumption: PR [#3333](https://github.com/tact-lang/tact/pull/3333)
 
+### Standard Library
+
+- Added `setData()` function: PR [#3402](https://github.com/tact-lang/tact/pull/3402)
+
+### Release contributors
+
+- [skywardboundd](https://github.com/skywardboundd)
+- [Novus Nota](https://github.com/novusnota)
+
 ## [1.6.13] - 2025-05-29
 
 ### Language features

docs/src/content/docs/cookbook/single-communication.mdx

@@ -158,8 +158,6 @@ contract Sample(
     // which forwards the remaining value back to the sender
     receive() { cashback(sender()) }
 }
-
-asm fun setData(data: Cell) { c4 POP }
 ```
 
 :::tip[Hey there!]

docs/src/content/docs/cookbook/upgrades.mdx

@@ -84,9 +84,6 @@ trait Upgradable with Ownable {
 
 /// Change of code will be applied by the end of the current transaction.
 asm fun setCode(code: Cell) { SETCODE }
-
-/// Change of data is immediate.
-asm fun setData(data: Cell) { c4 POP }
 ```
 
 ## Time-locked upgrade
@@ -211,6 +208,4 @@ trait Upgradable with Ownable {
 }
 
 asm fun setCode(code: Cell) { SETCODE }
-
-asm fun setData(data: Cell) { c4 POP }
 ```

docs/src/content/docs/ref/core-contextstate.mdx

@@ -362,6 +362,55 @@ nativeReserve(ton("0.1"), ReserveExact | ReserveBounceIfActionFail);
 //            amount of nanoToncoins to reserve
 ```
 
+### setData
+
+<Badge text="Available since Tact 1.7" variant="tip" size="medium"/>
+<Badge text="DANGEROUS" title="Applies irreversible modifications to the contract — use only when you know what you are doing!" variant="danger" size="medium"/><p/>
+
+```tact
+fun setData(data: Cell);
+```
+
+Replaces the current contract's state data [`Cell{:tact}`][cell] with the new `data`. It is useful only in exceptional cases, such as contract upgrades, data migrations, or when processing external messages with a catch-all [`Slice{:tact}`][slice] receiver for maximum efficiency. Otherwise, do **not** use this function, as it immediately and permanently overrides the state with no ability to recover, which can result in the loss of funds and partial or full corruption of the contract's data.
+
+:::caution
+
+  When using this function, make sure that all logical code branches within your receiver end with a call to the [`throw(0){:tact}`](/ref/core-debug#throw) function to terminate the execution of the contract early and prevent the automatic contract's data save implicitly added by Tact after the end of each receiver. Conversely, your manual changes to data made with this function will be lost.
+
+:::
+
+Usage example:
+
+```tact {13}
+contract WalletV4(
+    seqno: Int as uint32,
+    // ...other parameters...
+) {
+    // ...
+    external(_: Slice) {
+        // ...various prior checks...
+
+        acceptMessage();
+        self.seqno += 1;
+
+        // Manually saving the contract's state
+        setData(self.toCell());
+
+        // And halting the transaction to prevent a secondary save implicitly
+        // added by Tact after the main execution logic of the receiver
+        throw(0);
+    }
+}
+```
+
+:::note
+
+  Tact automatically saves the contract's state after the end of each receiver's logic even when `return{:tact}` statements are used for early termination. Thus, this function is almost never needed in regular contracts.
+
+  However, if you intend to use the `throw(0){:tact}` pattern to terminate the compute phase and save the state yourself or you want to replace the data when upgrading the contract, this function becomes useful. That said, make sure to double-check and test cover your every move such that the contract's data won't become corrupt or inadvertently gone.
+
+:::
+
 ### commit
 
 ```tact
@@ -388,8 +437,6 @@ contract WalletV4(
         throw(42); // and this won't fail it
     }
 }
-
-asm fun setData(data: Cell) { c4 POP }
 ```
 
 ## Blockchain state

src/benchmarks/wallet-v4/tact/wallet-v4.tact

@@ -235,5 +235,3 @@ contract WalletV4(
         return self.extensions;
     }
 }
-
-asm fun setData(data: Cell) { c4 POP }

src/benchmarks/wallet-v5/tact/wallet-v5.tact

@@ -223,4 +223,3 @@ asm fun setC5(outActions: Cell) { c5 POP }
 asm extends mutates fun checkAndRemoveAddExtensionPrefix(self: Slice): Bool { x{02} SDBEGINSQ }
 asm extends mutates fun checkAndRemoveDeleteExtensionPrefix(self: Slice): Bool { x{03} SDBEGINSQ }
 asm extends mutates fun checkAndRemoveSetSignAllowedPrefix(self: Slice): Bool { x{04} SDBEGINSQ }
-asm fun setData(data: Cell) { c4 POP }

src/stdlib/stdlib.ts

@@ -99,7 +99,7 @@ struct StateInit {
 ///
 /// Checks if the given `address` corresponds to the contract address in the workchain ID 0 (basechain) derived from the `StateInit` `self`. Returns `true` if the addresses match and `false` otherwise.
 ///
-/// This function works correctly only for basechain addresses. It may produce false positives or negatives if the specified `address` or the address derived from the `StateInit{:tact}` `self{:tact}` has a non-zero workchain ID.
+/// This function works correctly only for basechain addresses. It may produce false positives or negatives if the specified `address` or the address derived from the `StateInit` `self` has a non-zero workchain ID.
 ///
 /// #### Usage
 ///
@@ -457,3 +457,52 @@ asm fun setSeed(seed: Int) { SETRAND }
 /// See: https://docs.tact-lang.org/ref/core-contextstate#mycode
 ///
 asm fun myCode(): Cell { MYCODE }
+
+/// Global function. Available since Tact 1.7.0. DANGEROUS: Applies irreversible modifications to the contract — use only when you know what you are doing!
+///
+/// Replaces the current contract's state data [`Cell`][cell] with the new `data`. It is useful only in exceptional cases, such as contract upgrades, data migrations, or when processing external messages with a catch-all [`Slice`][slice] receiver for maximum efficiency. Otherwise, do **not** use this function, as it immediately and permanently overrides the state with no ability to recover, which can result in the loss of funds and partial or full corruption of the contract's data.
+///
+/// #### Caution
+///
+/// When using this function, make sure that all logical code branches within your receiver end with a call to the [`throw(0)`][throw] function to terminate the execution of the contract early and prevent the automatic contract's data save implicitly added by Tact after the end of each receiver. Conversely, your manual changes to data made with this function will be lost.
+///
+/// #### Usage example
+///
+/// ```tact {13}
+/// contract WalletV4(
+///     seqno: Int as uint32,
+///     // ...other parameters...
+/// ) {
+///     // ...
+///     external(_: Slice) {
+///         // ...various prior checks...
+///
+///         acceptMessage();
+///         self.seqno += 1;
+///
+///         // Manually saving the contract's state
+///         setData(self.toCell());
+///
+///         // And halting the transaction to prevent a secondary save implicitly
+///         // added by Tact after the main execution logic of the receiver
+///         throw(0);
+///     }
+/// }
+/// ```
+///
+/// #### Note
+///
+/// Tact automatically saves the contract's state after the end of each receiver's logic even when `return` statements are used for early termination. Thus, this function is almost never needed in regular contracts.
+///
+/// However, if you intend to use the `throw(0)` pattern to terminate the compute phase and save the state yourself or you want to replace the data when upgrading the contract, this function becomes useful. That said, make sure to double-check and test cover your every move such that the contract's data won't become corrupt or inadvertently gone.
+///
+/// #### See also
+///
+/// - https://docs.tact-lang.org/ref/core-contextstate#setdata
+/// - https://docs.tact-lang.org/ref/core-debug#throw
+///
+/// [cell]: https://docs.tact-lang.org/book/cells#cells
+/// [slice]: https://docs.tact-lang.org/book/cells#slices
+/// [throw]: https://docs.tact-lang.org/ref/core-debug#throw
+///
+asm fun setData(data: Cell) { c4 POP }

src/stdlib/stdlib/std/internal/contract.tact

@@ -627,8 +627,6 @@ asm fun acceptMessage() { ACCEPT }
 ///         throw(42); // and this won't fail it
 ///     }
 /// }
-///
-/// asm fun setData(data: Cell) { c4 POP }
 /// ```
 ///
 /// See: https://docs.tact-lang.org/ref/core-contextstate#commit

src/stdlib/stdlib/std/internal/send.tact

@@ -17,5 +17,3 @@ contract Test(seqno: Int) {
         return self.seqno;
     }
 }
-
-asm fun setData(data: Cell) { c4 POP }