Sending messages

TON Blockchain is message-based — to communicate with other contracts and to deploy new ones, you need to send messages.

Messages in Tact are commonly composed using a built-in Struct SendParameters, which 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.
code	Cell?	Optional initial code of the contract (compiled bitcode).
data	Cell?	Optional initial data of the contract (arguments of the init() function or values of contract parameters).
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.
to	Address	Recipient internal Address on TON Blockchain.
bounce	Bool	When set to true (default), the message bounces back to the sender if the recipient contract doesn’t exist or wasn’t able to process the message.

The fields code and data are what’s called an init package, which is used in deployments of new contracts.

Send a simple reply

The simplest message is a reply to an incoming message that returns all excess value from the message:

self.reply("Hello, World!".asComment()); // asComment converts a String to a Cell with a comment

Send message

If you need more advanced logic, you can use the send() function and the SendParameters Struct directly.

In fact, the previous example with .reply() can be made using the following call to the send() function:

send(SendParameters{
    // bounce is set to true by default
    to: sender(), // sending message back to the sender
    value: 0, // don't add Toncoin to the message...
    mode: SendRemainingValue | SendIgnoreErrors, // ...except for the ones received from the sender due to SendRemainingValue
    body: "Hello, World".asComment(), // asComment converts a String to a Cell with a comment
});

Another example sends a message to the specified Address with a value of 1 TON and the body as a comment containing the String "Hello, World!":

let recipient: Address = address("...");
let value: Int = ton("1");
send(SendParameters{
    // bounce is set to true by default
    to: recipient,
    value: value,
    mode: SendIgnoreErrors, // skip the message in case of errors
    body: "Hello, World!".asComment(),
});

The optional flag SendIgnoreErrors means that if an error occurs during message sending, it will be ignored, and the given message will be skipped. Message-related action phase exit codes that might be thrown without the SendIgnoreErrors set are:

• $36$: Invalid destination address in outbound message
• $37$: Not enough Toncoin
• $39$: Outbound message doesn't fit into a cell
• $40$: Cannot process a message

Send typed message

To send a typed message, you can use the following code:

let recipient: Address = address("...");
let value: Int = ton("1");
send(SendParameters{
    // bounce is set to true by default
    to: recipient,
    value: value,
    mode: SendIgnoreErrors, // skip the message in case of errors
    body: SomeMessage{arg1: 123, arg2: 1234}.toCell(),
});

Deploy contract

To deploy a contract, you need to calculate its address and initial state with initOf, then send them in the initialization message:

let init: StateInit = initOf SecondContract(arg1, arg2);
let address: Address = contractAddress(init);
let value: Int = ton("1");
send(SendParameters{
    // bounce is set to true by default
    to: address,
    value: value,
    mode: SendIgnoreErrors, // skip the message in case of errors
    code: init.code,
    data: init.data,
    body: "Hello, World!".asComment(), // not necessary, can be omitted
});

Available since Tact 1.6

For cheaper on-chain deployments, prefer using the deploy() function instead. It computes the address of the contract based on its initial code and data and efficiently composes the resulting message:

deploy(DeployParameters{
    // bounce is set to true by default
    init: initOf SecondContract(arg1, arg2), // initial code and data
    mode: SendIgnoreErrors, // skip the message in case of errors
    value: ton("1"), // a whole Toncoin
    body: "Hello, World!".asComment(), // not necessary, can be omitted
});

Outbound message processing

Each transaction on TON Blockchain consists of multiple phases. Outbound messages are evaluated in the compute phase, but are not sent in that phase. Instead, they are queued for execution in the action phase in the order of their appearance in the compute phase.

Outgoing message sends may fail in the action phase due to insufficient action fees or forward fees, in which case they will not bounce and will not revert the transaction. This can happen because all values are calculated in the compute phase, all fees are computed by its end, and exceptions do not roll back the transaction during the action phase.

To skip or ignore the queued messages at the action phase in case they cannot be sent, set the optional SendIgnoreErrors flag when composing the message.

Consider the following example:

// This contract initially has 0 nanoToncoins on the balance
contract FailureIsNothingButAnotherStep {
    // All the funds it obtains are from inbound internal messages
    receive() {
        // 1st outbound message evaluated and queued (but not yet sent)
        send(SendParameters{
            to: sender(),
            value: ton("0.042"), // plus forward fee due to SendPayGasSeparately
            mode: SendIgnoreErrors | SendPayGasSeparately,
            // body is null by default
        });

        // 2nd outbound message evaluated and queued,
        // but not yet sent, and never will be!
        send(SendParameters{
            to: sender(),
            value: 0,
            mode: SendRemainingValue | SendIgnoreErrors,
            // body is null by default
        });
    } // exit code 37 during action phase!
}

There, the second message will not actually be sent:

• After finishing the compute phase, the remaining value $\mathrm{R}$ of the contract is computed.

• During outbound message processing and assuming that sufficient value was provided in the inbound message, the first message leaves $\mathrm{R} - (0.042 + \mathrm{forward\_fees})$ nanoToncoins on the balance.

• When the second message is processed, the contract attempts to send $\mathrm{R}$ nanoToncoins, but fails because a smaller amount remains.

• Thus, an error with exit code 37 is thrown: Not enough Toncoin.

Note that such failures are not exclusive to the send() function and may also occur when using other message-sending functions.

For instance, let us replace the first call to the send() function in the previous example with the emit() function. The latter queues the message using the default mode, i.e. 0, and spends some nanoToncoins to pay the forward fees.

If a subsequent message is then sent with a SendRemainingValue base mode, it will cause the same error as before:

// This contract initially has 0 nanoToncoins on the balance
contract IfItDiesItDies {
    // All the funds it obtains are from inbound internal messages
    receive() {
        // 1st outbound message evaluated and queued (but not yet sent)
        // with the mode 0, which is the default
        emit("Have you seen this message?".asComment());

        // 2nd outbound message evaluated and queued,
        // but not yet sent, and never will be!
        send(SendParameters{
            to: sender(),
            value: 0,
            bounce: false, // brave and bold
            mode: SendRemainingValue,
            body: "Not this again!".asComment(),
        });
    } // exit code 37 during action phase!
}

Note

To avoid dealing with similar cases and to simplify future debugging sessions, consider having only one call to one of the message-sending functions per receiver function.

Alternatively, see the suggested solutions below.

The previous examples discussed a case where the contract has 0 nanoToncoins on the balance, which is rather rare—in most real-world scenarios, some funds would be present. As such, it is usually better to use the SendRemainingBalance base mode, paired with the necessary call to the nativeReserve() function.

Like outbound messages, reserve requests are queued during the compute phase and executed during the action phase.

// This contract has some Toncoins on the balance, e.g., 0.2 or more
contract MyPrecious {
    // Extra funds can be received via a "topup" message
    receive("topup") {}

    // The rest of the logic is expressed here
    receive() {
        // 1st outbound message evaluated and queued (but not yet sent)
        // with the mode 0, which is the default
        emit("Have you seen this message?".asComment());

        // Try to keep most of the balance from before this transaction
        // Note that nativeReserve() only queues an action to be performed during the action phase
        nativeReserve(ton("0.05"), ReserveAtMost | ReserveAddOriginalBalance);
        //            -----------  -------------   -------------------------
        //            ↑            ↑               ↑
        //            |            |               keeping the balance from before compute phase start
        //            |            might keep less, but will not fail in doing so
        //            just a tad more on top of the balance, for the fees

        // 2nd outbound message evaluated and queued
        // with SendRemainingBalance mode
        send(SendParameters{
            to: sender(),
            value: 0,
            mode: SendRemainingBalance, // because of the prior nativeReserve(),
                                        // using this mode is safe and will keep
                                        // the original balance plus a little more
            body: "I give you my all! Well, all that's not mine!".asComment(),
        });
    }
}

If, instead, you want all outgoing messages to preserve a fixed amount of funds on the balance and send the rest of the balance, consider using one of the following functions. Note that these functions require a prior override of the self.storageReserve constant:

• self.reply()
• self.notify()
• self.forward()

If you take only one thing away from this section, please remember this: be very careful with the base modes of the message-sending functions, including the implicitly set modes.

Message sending limits

In total, there can be no more than 255 actions queued for execution, meaning that the maximum allowed number of messages sent per transaction is 255.

Attempts to queue more throw an exception with an exit code 33 during the action phase: Action list is too long.

Message-sending functions

Read more about all message-sending functions in the Reference:

• send()
• message()
• deploy()
• emit()
• cashback()
• self.notify()
• self.reply()
• self.forward()
• nativeSendMessage()
• nativeSendMessageReturnForwardFee()