Message mode
As previously mentioned, messages sent via the send()
function utilize the mode
parameter of the SendParameters
structure. The mode
is an Int
value, which is combined from base modes and optional flags, which are also Int
values.
It’s possible to use raw Int
values and manually provide them for the mode
, but for your convenience there is a set of constants you may use to easily construct the compound mode
. Take a look at the following tables for more information on base modes and optional flags.
Note that there are other message-sending functions — they do not use the SendParameters
struct, but accept the mode
as one of their parameters.
Base modes
Mode value | Constant name | Description |
---|---|---|
Since Tact 1.6 SendDefaultMode | Ordinary message (default). | |
SendRemainingValue | Carries all the remaining value of the inbound message in addition to the value initially indicated in the new message. | |
Use with caution SendRemainingBalance | Carries all the remaining balance of the current smart contract instead of the value originally indicated in the message. | |
Since Tact 1.5 SendOnlyEstimateFee | Doesn’t send the message, only estimates the forward fees if the message-sending function computes these. |
The base mode SendRemainingValue
does not take previous actions into account, i.e., it doesn’t recalculate the remaining value of the incoming message based on previously sent messages or actions performed during the action phase.
Unlike SendRemainingValue
, the base mode SendRemainingBalance
always calculates the current value of the contract balance, which can help solve problems with complex outbound message processing.
However, be very careful when using SendRemainingBalance
, because it works with the balance of the entire contract, and any mistake with it can lead to a total loss of funds.
Optional flags
Flag value | Constant name | Description |
---|---|---|
SendPayGasSeparately | Deprecated since Tact 1.6.5 Use SendPayFwdFeesSeparately instead. | |
SendPayFwdFeesSeparately | Pay forward fees separately from the message value. | |
SendIgnoreErrors | Ignore any errors arising while processing this message during the action phase. | |
SendBounceIfActionFail | Bounce the transaction in case of any errors during the action phase. Has no effect if flag , SendIgnoreErrors , is used. | |
SendDestroyIfZero | The current account (contract) will be destroyed if its resulting balance is zero. This flag is often used with mode , SendRemainingBalance . |
Combining modes with flags
To create the Int
value for the mode
field of SendParameters
, you simply combine a base mode with optional flags using the bitwise OR operation.
For example, if you want to send a regular message and pay transfer fees separately, use the default mode and add flag to obtain mode = 1
, which is equivalent to using the constant SendPayFwdFeesSeparately
.
Alternatively, if you want to send the entire contract balance and destroy it immediately, use mode and add flag to get mode = 160
, which is equivalent to SendRemainingBalance | SendDestroyIfZero
.
Here’s how the latter example would look in code:
let to: Address = address("...");let value: Int = ton("1");send(SendParameters{ to: to, value: value, mode: SendRemainingBalance | SendDestroyIfZero, body: "Hello, World!".asComment(),});
Note that there can be only one base mode, but the number of optional flags may vary: you can use all, none, or only some of them.
Functions with implicit mode
Some message-sending functions do not allow setting a mode by passing an argument. This is because their internal logic requires a specific fixed set of modes to be used instead:
emit()
sends a message with theSendDefaultMode
().self.reply()
,self.notify()
, andself.forward()
all use theSendRemainingValue
mode unless theself.storageReserve
constant is overridden to be greater than , in which case they attempt to use theSendRemainingBalance
mode.