feat(docs): refunds, message chains, and the carry-value pattern (#3422)

Author: novusnota

dev-docs/CHANGELOG-DOCS.md

@@ -7,7 +7,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ## Doc: 2025-06
 
 - Adjusted inline code tag highlighting to support global Starlight themes, and modified the One Light color theme to support proper highlighting of `keyword.operator.new` TextMate scopes: PR [#3346](https://github.com/tact-lang/tact/pull/3346)
-- Warned that imports are automatically exported: PR [#TBD](https://github.com/tact-lang/tact/pull/TBD)
+- Warned that imports are automatically exported: PR [#3368](https://github.com/tact-lang/tact/pull/3368)
+- Documented refunds, message chains, and the carry-value pattern for receivers: PR [#3422](https://github.com/tact-lang/tact/pull/3422)
 
 ## Doc: 2025-05
 

docs/src/content/docs/book/contracts.mdx

@@ -244,7 +244,7 @@ contract Example {
 
 :::note
 
-  Keep in mind that contracts cannot call each other's [getters](#getter-functions) or retrieve data from other contracts synchronously. Thus, as contracts exchange asynchronous messages and it is not possible to directly read state variables of one contract by another, because by the time a message with the data reaches your contract, the state variables on another contract might have changed already.
+  Keep in mind that contracts cannot call each other's [getters](#getter-functions) or retrieve data from other contracts synchronously. Thus, as contracts exchange asynchronous messages, it is not possible to directly read the state variables of one contract by another because, by the time a message with the data reaches your contract, the state variables on another contract might have changed already.
 
   Instead, prefer to write contracts that exchange messages as signals to perform a certain action on or with the sent data but never merely to read the state of another contract.
 

docs/src/content/docs/book/receive.mdx

@@ -81,6 +81,23 @@ contract Handler() {
 }
 ```
 
+## Wildcard parameters
+
+Naming the parameter of a receiver function with an underscore `_{:tact}` makes its value considered unused and discarded. This is useful when you don't need to inspect the message received and only want it to convey a specific opcode.
+
+```tact
+message(42) UniverseCalls {}
+
+contract Example() {
+    receive(_: UniverseCalls) {
+        // Got a message with opcode 42
+        UniverseCalls.opcode(); // 42
+    }
+}
+```
+
+Read more about other common function aspects: [Commonalities on the Functions page](/book/functions#commonalities).
+
 ## Processing order
 
 All receiver functions are processed in the order they are listed below. The first receiver that matches the message type processes the message:
@@ -123,8 +140,27 @@ Contracts are not required to declare receivers for all possible message types.
 
 Note that the receiver `receive(msg: Slice){:tact}` acts as a fallback that catches all messages that did not match previous receivers in the execution order list. If there is no receiver to process a message type and the fallback receiver `receive(msg: Slice){:tact}` is not declared, the transaction will fail with exit code [130](/book/exit-codes/#130).
 
+## Incoming funds
+
 Receivers accept all incoming funds by default. That is, without explicitly sending a message that will refund spare Toncoin with the [`cashback(){:tact}`](/ref/core-send#cashback) function, the contract will keep all the incoming message value.
 
+```tact
+contract ToCashOrNotToCash() {
+    receive() {
+        // Forward the remaining value in the
+        // incoming message back to the sender.
+        cashback(sender());
+    }
+
+    receive(_: Greed) {
+        // Unlike the previous one, this receiver does not return surplus Toncoin,
+        // and keeps all the incoming message value minus necessary fees.
+    }
+}
+
+message Greed {}
+```
+
 To check the amount of Toncoin (native coins) the incoming message carries with it, you can use the [`context(){:tact}`](/ref/core-contextstate#context) function and access the `value` field of its resulting [struct](/book/structs-and-messages#structs). Note, however, that the exact value by which the balance will be increased will be less than `context().value{:tact}` since the [compute fee](https://docs.ton.org/v3/documentation/smart-contracts/transaction-fees/fees-low-level#computation-fees) for contract execution will be deducted from this value.
 
 ```tact /context\(\).value/
@@ -148,14 +184,55 @@ message(0x706c7567) PluginRequestFunds {
 }
 ```
 
-Naming the parameter of a receiver function with an underscore `_{:tact}` makes its value considered unused and discarded. This is useful when you don't need to inspect the message received and only want it to convey a specific opcode:
+## Carry-value pattern
+
+Contracts cannot call each other's [getters](/book/functions#get) or retrieve data from other contracts synchronously. If you were to send the current values of the state variables to another contract, they would almost always become stale by the time the message carrying them is processed at the destination.
+
+To circumvent that, use the carry-value pattern, which involves passing state or data along the chain of required operations rather than attempting to store and retrieve the data in a synchronous fashion. Instead of querying data, each contract in the message chain receives some input, processes it, and passes the result or the new payload to the next contract in the sequence of sent messages. This way, messages work as signals to perform certain actions on or with the sent data.
+
+For example, upon receiving a message request to perform a [Jetton](/cookbook/jettons) transfer from the current owner to the target user's [Jetton Wallet](/cookbook/jettons#jetton-wallet-contract), Jetton Wallet contracts ensure the validity of the request from the standpoint of their current state. If everything is fine, they modify their token balance and always send the deployment message, regardless of whether the target Jetton Wallet exists or not.
+
+That is because it is impossible to obtain confirmation of the contract deployment synchronously. At the same time, sending a deployment message means attaching the [`StateInit{:tact}`](/book/expressions#initof) code and data of the future contract to the regular message and letting the TON Blockchain itself figure out whether the target contract is deployed or not, and discarding that `init` bundle if the destination contract is already deployed.
 
 ```tact
-message(42) UniverseCalls {}
+/// Child contract per each holder of N amount of given Jetton (token)
+contract JettonWallet(
+    /// Balance in Jettons.
+    balance: Int as coins,
+
+    /// Address of the user's wallet which owns this JettonWallet, and messages
+    /// from whom should be recognized and fully processed.
+    owner: Address,
+
+    /// Address of the main minting contract,
+    /// which deployed this Jetton wallet for the specific user's wallet.
+    master: Address,
+) {
+    /// Registers a binary receiver of the JettonTransfer message body.
+    receive(msg: JettonTransfer) {
+        // ...prior checks and update of the `self.balance`...
 
-contract Example {
-    receive(_: UniverseCalls) {
-        // Got a Message with opcode 42
+        // Transfers Jetton from the current owner to the target user's JettonWallet.
+        // If that wallet does not exist, it is deployed on-chain in the same transfer.
+        deploy(DeployParameters {
+            value: 0,
+            mode: SendRemainingValue,
+            bounce: true,
+            body: JettonTransferInternal{
+                queryId: msg.queryId, // Int as uint64
+                amount: msg.amount, // Int as coins
+                sender: self.owner, // Address
+                responseDestination: msg.responseDestination, // Address?
+                forwardTonAmount: msg.forwardTonAmount, // Int as coins
+                forwardPayload: msg.forwardPayload, // Slice as remaining
+            }.toCell(),
+            // Notice that we do not need to explicitly specify the target address,
+            // because it will be computed on the fly from the initial package.
+            //
+            // The `msg.destination` is the regular wallet address of the new owner
+            // of those Jettons and not the future address of the target Jetton Wallet itself.
+            init: initOf JettonWallet(0, msg.destination, self.master),
+        });
     }
 }
 ```