Context and state

Contextual and state-related functions and structs.

Time

now

fun now(): Int;

Returns the current Unix time.

Usage example:

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

curLt

Available since Tact 1.6

fun curLt(): Int;

Returns the Int value of the logical time of the current transaction.

Usage example:

let lt: Int = curLt();
nativeRandomize(lt); // Equivalent to calling nativeRandomizeLt()

Useful links:

Random seed in Wikipedia
nativeRandomize
nativeRandomizeLt
Other random-related functions in the Core library

blockLt

Available since Tact 1.6

fun blockLt(): Int;

Returns the Int value of the starting logical time of the current block.

Usage example:

let time: Int = blockLt();

Incoming message

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.

inMsg

Available since Tact 1.6.7

fun inMsg(): Slice;

Returns the Slice with the original, raw body of the received message.

That Slice can:

• be empty, which means the contract has received an empty message body that is handled in the empty receiver receive() or the catch-all slice receiver receive(msg: Slice);
• start with 4 zero bytes, which means the contract has received a text message that is handled in the relevant receiver:
  • the exact text receiver receive("message"),
  • the catch-all string receiver receive(msg: String),
  • or the catch-all slice receiver receive(msg: Slice);
• start with 4 bytes of a non-zero message opcode that the corresponding binary receiver receive(msg: MessageStruct) or the catch-all slice receiver receive(msg: Slice) would handle.

Usage examples:

// This contract defines various kinds of receivers in their
// order of handling the corresponding incoming messages.
contract OrderOfReceivers() {
    receive() {
        let body = inMsg();
        body.bits(); // 0
    }

    receive("yeehaw!") {
        let body = inMsg();
        body.loadUint(32); // 0
        body.hash() == "yeehaw!".asSlice().hash(); // true
    }

    receive(str: String) {
        let body = inMsg();
        body.loadUint(32); // 0
        body == str.asSlice(); // true
    }

    receive(msg: Emergency) {
        let body = inMsg();
        body.preloadUint(32); // 911
    }

    receive(rawMsg: Slice) {
        let body = inMsg();
        body == rawMsg; // true
    }
}

message(911) Emergency {}

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 nanoToncoin 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.

Context.readForwardFee

extends fun readForwardFee(self: Context): Int;

Extension function for the Context struct.

Reads the forward fee provided in the incoming message and applies the getOriginalFwdFee() to it to calculate its approximate original value. Returns this value as an Int amount of nanoToncoin.

Usage example:

let origFwdFee: Int = context().readForwardFee();

Useful links:

getOriginalFwdFee()
Other fees and gas-related functions in the Core library

Contract and transaction state

myAddress

fun myAddress(): Address;

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

Usage example:

let meMyselfAndI: Address = myAddress();

Useful links:

Other address-related functions in the Core library

myCode

Available since Tact 1.6

fun myCode(): Cell;

Returns the smart contract code Cell obtained from the c7 register.

Usage example:

let code: Cell = myCode();

myStorageDue

Available since Tact 1.5

fun myStorageDue(): Int;

Returns the nanoToncoin Int amount of the accumulated storage fee debt. Storage fees are deducted from the incoming message value before the new contract balance is calculated.

Usage example:

let debt: Int = myStorageDue();

Useful links:

getStorageFee()
Other fees and gas-related functions in the Core library

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.

gasConsumed

Available since Tact 1.5

fun gasConsumed(): Int;

Returns the nanoToncoin Int amount of gas consumed by TVM in the current transaction so far. The resulting value includes the cost of calling this function.

Usage example:

let gas: Int = gasConsumed();

Useful links:

Gas in TON Docs
Other fees and gas-related functions in the Core library

nativeReserve

500+ gas

fun nativeReserve(amount: Int, mode: Int);

Executes the RAWRESERVE instruction with the specified amount and mode. It queues the reservation of the specific amount of nanoToncoin from the remaining account balance per the given mode.

The reservation action is queued to the output action list, which contains other actions such as message sends. In fact, the RAWRESERVE instruction is roughly equivalent to creating an outbound message carrying the specified amount of nanoToncoin or b - amount of nanoToncoin, where b is the remaining balance, to oneself. This ensures that subsequent output actions cannot spend more money than the remainder.

It is 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 construct the compound mode with ease. Take a look at the following tables for more information on base modes, optional flags, and how you can combine them together.

Caution

Currently, amount must be a non-negative integer, and mode must be in the range $0..31$, inclusive.

Additionally, attempts to queue more than $255$ reservations in one transaction throw an exception with exit code 33: Action list is too long.

Base modes

The resulting mode value can have the following base modes:

Mode value	Constant name	Description
$0$	ReserveExact	Reserves exactly the specified amount of nanoToncoin.
$1$	ReserveAllExcept	Reserves all but the specified amount of nanoToncoin.
$2$	ReserveAtMost	Reserves at most the specified amount of nanoToncoin.

Optional flags

Additionally, the resulting mode can have the following optional flags added:

Flag value	Constant name	Description
$+4$	ReserveAddOriginalBalance	Increases the amount by the original balance of the current account (before the compute phase), including all extra currencies.
$+8$	ReserveInvertSign	Negates the amount value before performing the reservation.
$+16$	ReserveBounceIfActionFail	Bounces the transaction if the reservation fails.

Combining modes with flags

To construct the Int value for the mode parameter, combine base modes with optional flags by applying the bitwise OR operation:

nativeReserve(ton("0.1"), ReserveExact | ReserveBounceIfActionFail);
//            ----------  ----------------------------------------
//            ↑           ↑
//            |           mode, which would bounce the transaction if exact reservation fails
//            amount of nanoToncoins to reserve

setData

Available since Tact 1.7 DANGEROUS

fun setData(data: Cell);

Replaces the current contract’s state data Cell with the new data. It is useful only in exceptional cases, such as contract upgrades, data migrations, or when processing external messages with a catch-all Slice receiver for maximum efficiency. Otherwise, do not use this function, as it immediately and permanently overrides the state with no ability to recover, which can result in the loss of funds and partial or full corruption of the contract’s data.

Caution

When using this function, make sure that all logical code branches within your receiver end with a call to the throw(0) function to terminate the execution of the contract early and prevent the automatic contract’s data save implicitly added by Tact after the end of each receiver. Conversely, your manual changes to data made with this function will be lost.

Usage example:

contract WalletV4(
    seqno: Int as uint32,
    // ...other parameters...
) {
    // ...
    external(_: Slice) {
        // ...various prior checks...

        acceptMessage();
        self.seqno += 1;

        // Manually saving the contract's state
        setData(self.toCell());

        // And halting the transaction to prevent a secondary save implicitly
        // added by Tact after the main execution logic of the receiver
        throw(0);
    }
}

Note

Tact automatically saves the contract’s state after the end of each receiver’s logic even when return statements are used for early termination. Thus, this function is almost never needed in regular contracts.

However, if you intend to use the throw(0) pattern to terminate the compute phase and save the state yourself or you want to replace the data when upgrading the contract, this function becomes useful. That said, make sure to double-check and test cover your every move such that the contract’s data won’t become corrupt or inadvertently gone.

commit

fun commit();

Commits the current state of registers c4 (persistent data) and c5 (actions), so that the current execution is considered “successful” with the saved values even if an exception in the compute phase is thrown later.

Usage example:

contract WalletV4(
    seqno: Int as uint32,
    // ...other parameters...
) {
    // ...
    external(_: Slice) {
        // ...various prior checks...

        acceptMessage();
        self.seqno += 1;
        setData(self.toCell());
        commit(); //  now, transaction is considered "successful"
        throw(42); // and this won't fail it
    }
}

Blockchain state

getConfigParam

fun getConfigParam(id: Int): Cell?;

Loads a configuration parameter of TON Blockchain by its id number.

Usage examples:

// Parameter 0, address of a special smart contract that stores the blockchain's configuration
let configAddrAsCell: Cell = getConfigParam(0)!!;

// Parameter 18, configuration for determining the prices for data storage
let dataStorageFeeConfig: Cell = getConfigParam(18)!!;

Note

The standard library @stdlib/config provides two related helper functions:
getConfigAddress() for retrieving config Address
getElectorAddress() for retrieving elector Address

Read more about other parameters: Config Parameters in TON Docs.