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:

Field	Type	Description
`bounce`	`Bool`	When set to `true` (default) message bounces back to the sender if the receiver contract doesn’t exist or wasn’t able to process the message.
`to`	`Address`	Receiver internal `Address` in TON blockchain.
`value`	`Int`	The amount of nanoToncoins you want to send with the message. This value is usually used to cover forward fees, unless the optional flag `SendPayGasSeparately` is used.
`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 (the compiled bytecode)
`data`	`Cell?`	Optional initial data of the contract (arguments of `init()` function of the contract)

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

Send simple reply

The simplest message is a reply to the incoming message returning all excess value of a 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 SendParameters Struct directly.

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

send(SendParameters{
    // bounce is set to true by default
    to: sender(), // sending message back to the sender
    value: 0, // don't add Toncoins to the message...
    mode: SendRemainingValue | SendIgnoreErrors, // ...except for 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 of a comment with a 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, // will send the message despite any errors
    body: "Hello, World!".asComment(),
});

The optional flag SendIgnoreErrors means that if an error occurs during message send, 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, // don't stop 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, // don't stop in case of errors
    code: init.code,
    data: init.data,
    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 compute phase, but are not sent in that phase. Instead, they’re queued in order of appearance for the action phase, where all actions listed in compute phase, like outbound messages or reserve requests, are executed.

As all the values are computed in compute phase, all the fees computed by the end of it, and exceptions do not revert the transaction during action phase, outbound message sends can fail without bounce due to insufficient action fees or forward fees.

Consider the following example:

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

        // 2nd outbound message evaluated and queued (but not sent yet, and never will be!)
        send(SendParameters{
            to: sender(),
            value: 0,
            mode: SendRemainingValue | SendIgnoreErrors,
        });
    }
}

There, the second message won’t actually be sent:

After finishing the compute phase, the remaining value $\mathrm{R}$ of the contract is computed.
During the outbound message processing and assuming that there was enough value 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, contract tries to send $\mathrm{R}$ nanoToncoins, but fails to do so because there is already a smaller amount left.

Message sending limits

In total, there could be no more than $255$ actions queued for execution, which means 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 action phase: Action list is too long.

Message sending functions

Read more about all message sending functions in the Reference: