Communication and messaging

Primary message-sending functions.

To perform nanoToncoin reservations, use nativeReserve() function from the context and state-related functions reference page.

Common

send

Gas-expensive

fun send(params: SendParameters);

Queues the message to be sent using a SendParameters struct.

Attempts to queue more than 255 messages throw an exception with exit code 33: Action list is too long.

Usage example:

send(SendParameters{
    to: sender(),    // back to the sender,
    value: ton("1"), // with 1 Toncoin (1_000_000_000 nanoToncoin),
                     // and no message body
});

message

Gas-expensive Available since Tact 1.6

fun message(params: MessageParameters);

Queues the message to be sent using the MessageParameters struct. Allows for cheaper non-deployment regular messages compared to the send() function.

The MessageParameters struct is similar to the SendParameters struct, but without the code and data fields.

Attempts to queue more than 255 messages throw an exception with an exit code 33: Action list is too long.

Usage example:

message(MessageParameters{
    to: sender(),    // back to the sender,
    value: ton("1"), // with 1 Toncoin (1_000_000_000 nanoToncoin),
                     // and no message body
});

deploy

Gas-expensive Available since Tact 1.6

fun deploy(params: DeployParameters);

Queues the contract deployment message to be sent using the DeployParameters struct. Allows for cheaper on-chain deployments compared to the send() function.

The DeployParameters struct consists of the following fields:

Field	Type	Description
`mode`	`Int`	An 8-bit value that configures how to send a message, defaults to $0$ . See: Message `mode`.
`body`	`Cell?`	Optional message body as a `Cell`.
`value`	`Int`	The amount of nanoToncoins you want to send with the message. This value is used to cover forward fees unless the optional flag `SendPayGasSeparately` is used.
`bounce`	`Bool`	When set to `true` (default), the message bounces back to the sender if the recipient contract doesn’t exist or isn’t able to process the message.
`init`	`StateInit`	Initial package of the contract (initial code and initial data). See: `initOf`.

Attempts to queue more than 255 messages throw an exception with an exit code 33: Action list is too long.

Usage example:

deploy(DeployParameters{
    init: initOf SomeContract(), // with initial code and data of SomeContract
                                 // and no additional message body
    mode: SendIgnoreErrors,      // skip the message in case of errors
    value: ton("1"),             // send 1 Toncoin (1_000_000_000 nanoToncoin)
});

cashback

Gas-expensive Available since Tact 1.6.1

fun cashback(to: Address);

Queues an empty message to be sent with the SendRemainingValue mode with the SendIgnoreErrors to the destination address to. It is the most gas-efficient way to send the remaining value from the incoming message to the given address.

This function won’t forward excess values if any other message-sending functions were called in the same receiver before.

Attempts to queue more than 255 messages throw an exception with exit code 33: Action list is too long.

Usage examples:

// Forward the remaining value back to the sender
cashback(sender());

// The cashback() function above is cheaper, but functionally
// equivalent to the following call to the message() function
message(MessageParameters{
    mode: SendRemainingValue | SendIgnoreErrors,
    body: null,
    value: 0,
    to: sender(),
    bounce: false,
});

emit

Gas-expensive

fun emit(body: Cell);

Queues the message body to be sent to the outer world for the purpose of logging and analyzing it later off-chain. The message does not have a recipient and is more gas-efficient compared to using any other message-sending functions of Tact.

The message is sent with the default mode: SendDefaultMode ( $0$ ).

Attempts to queue more than $255$ messages throw an exception with an exit code 33: Action list is too long.

Usage example:

emit("Catch me if you can, Mr. Holmes".asComment()); // asComment() converts a String to a Cell

Advanced

Various niche, dangerous, or unstable features which can produce unexpected results and are meant to be used by more experienced users.

nativeSendMessage

Gas-expensive

fun nativeSendMessage(cell: Cell, mode: Int);

Queues the message to be sent by specifying the complete cell and the message mode.

Attempts to queue more than $255$ messages throw an exception with exit code 33: Action list is too long.

nativeSendMessageReturnForwardFee

Gas-expensive Available since Tact 1.5

fun nativeSendMessageReturnForwardFee(cell: Cell, mode: Int): Int;

Similar to nativeSendMessage(), but also calculates and returns the forward fee in [nanoToncoins][nanotoncoin].

Attempts to queue more than $255$ messages throw an exception with exit code 33: Action list is too long.