Common

List of the most commonly used built-in global static functions.

Contextual

now

fun now(): Int;

Returns the current Unix time.

Usage example:

let timeOffset: Int = now() + 1000; // thousand seconds from now()

myBalance

fun myBalance(): Int;

Returns the nanoToncoin Int balance of the smart contract as it was at the start of the compute phase of the current transaction.

Usage example:

let iNeedADolla: Int = myBalance();

Caution

Beware that all message-sending functions of Tact can change the actual balance of the contract, but they won’t update the value returned by this function.

myAddress

fun myAddress(): Address;

Returns the address of the current smart contract as an Address.

Usage example:

let meMyselfAndI: Address = myAddress();

sender

fun sender(): Address;

Returns the Address of the sender of the current message.

Usage example:

contract MeSee {
    receive() {
        let whoSentMeMessage: Address = sender();
    }
}

Caution

Behavior is undefined for getter functions, because they cannot have a sender nor can they send messages.

Note

In order to reduce gas usage, prefer using this function over calling context().sender when you only need to know the sender of the message.

context

fun context(): Context;

Returns Context struct, which consists of:

Field	Type	Description
bounceable	Bool	Indicates whether the received message can bounce back.
sender	Address	Internal address of the sender on the TON blockchain.
value	Int	Amount of nanoToncoins in the received message.
raw	Slice	The remainder of the received message as a Slice. It follows the internal message layout of TON, starting from the destination Address (MsgAddressInt in TL-B notation).

Usage example:

let ctx: Context = context();
require(ctx.value != 68 + 1, "Invalid amount of nanoToncoins, bye!");

Note

If you only need to know who sent the message, use the sender() function, as it is less gas-consuming.

Addressing

newAddress

Gas-expensive

fun newAddress(chain: Int, hash: Int): Address;

Creates a new Address based on the chain ID and the SHA-256 encoded hash value (account ID).

This function tries to resolve constant values at compile-time whenever possible.

Attempts to specify an invalid chain ID (not $-1$ or $0$) detectable at compile-time will result in a compilation error.

Usage example:

let oldTonFoundationAddr: Address =
    newAddress(0, 0x83dfd552e63729b472fcbcc8c45ebcc6691702558b68ec7527e1ba403a0f31a8);
    //         ↑  ↑
    //         |  SHA-256 hash of contract's init package (StateInit)
    //         chain ID: 0 is a workchain, -1 is a masterchain

Caution

Make sure you specify only supported workchain IDs: $0$ for the basechain and $-1$ for the masterchain.

Useful links:

chain (Workchain ID) in TON Docs
hash (Account ID) in TON Docs
Contract’s init package (StateInit)

hasSameBasechainAddress

Available since Tact 1.6.1

extends fun hasSameBasechainAddress(self: StateInit, sender: Address): Bool;

Efficiently compares whether the given address matches the basechain address of the contract. Returns true if the addresses are the same; false otherwise.

fun example() {
    let init = initOf SomeContract();
    init.hasSameBasechainAddress(sender()); // returns true if sender matches contract's basechain address
}

This function provides a gas-optimized implementation compared to direct address comparison:

fun example() {
    let init = initOf SomeContract();
    sender() == contractAddress(sender()); // less efficient approach
}

Note

This function works only for basechain addresses!

contractAddress

Gas-expensive

fun contractAddress(s: StateInit): Address;

Computes the smart contract’s Address in the workchain ID $0$ (basechain) using the StateInit s of the contract. An alias to contractAddressExt(0, s.code, s.data).

Usage example:

let s: StateInit = initOf SomeContract();
let foundMeSome: Address = contractAddress(s);
let andSomeMore: Address = contractAddressExt(0, s.code, s.data);

foundMeSome == andSomeMore; // true

contractAddressExt

Gas-expensive

fun contractAddressExt(chain: Int, code: Cell, data: Cell): Address;

Computes the smart contract’s Address in the given chain ID using the contract’s code and its initial state data. Use the initOf expression to obtain the initial code and initial data of a given contract.

This function tries to resolve constant values at compile-time whenever possible.

Attempts to specify an invalid chain ID (not $-1$ or $0$) that can be detected at compile-time will result in a compilation error.

Usage example:

let initPkg: StateInit = initOf SomeContract();
let hereBeDragons: Address = contractAddressExt(0, initPkg.code, initPkg.data);

contractHash

Available since Tact 1.6

fun contractHash(code: Cell, data: Cell): Int;

Computes and returns an Int value of the SHA-256 hash of the code and data of the given contract. To assemble the code and data cells together for hashing, the standard Cell representation is used.

This hash is commonly called the account ID. Together with the workchain ID, it deterministically forms the address of the contract on TON Blockchain.

Usage example:

let initPkg: StateInit = initOf SomeContract();
let accountId: Int = contractHash(initPkg.code, initPkg.data);
let basechainAddr: Address = newAddress(0, accountId);
let basechainAddr2: Address = contractAddressExt(0, initPkg.code, initPkg.data);

basechainAddr == basechainAddr2; // true

Useful links:

chain (Workchain ID) in TON Docs
hash (Account ID) in TON Docs
Contract’s init package (StateInit)
Standard Cell representation

Communication

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
});

Useful links:

Sending messages in the Book
Message mode in the Book
Single-contract communication in the Cookbook

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 body and code 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
});

Useful links:

Sending messages in the Book
Message mode in the Book

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)
});

Useful links:

Sending messages in the Book
Message mode in the Book

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.

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

Note

To analyze emit() calls, one must look at the external messages produced by the contract.

Read more: Logging via emit().