Advanced

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

Caution

Proceed with caution.

Context.readForwardFee

extends fun readForwardFee(self: Context): Int

Extension function for the Context.

Reads forward fee and returns it as Int amount of nanoToncoins.

Usage example:

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

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

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.

acceptMessage

fun acceptMessage();

Agrees to buy some gas to finish the current transaction. This action is required to process external messages, which bring no value (hence no gas) with themselves.

Usage example:

contract Timeout {
    timeout: Int;

    init() {
        self.timeout = now() + 5 * 60; // 5 minutes from now
    }

    external("timeout") {
        if (now() > self.timeout) {
            acceptMessage(); // start accepting external messages once timeout went out
        }
    }
}

Note

For more details, see: Accept Message Effects in TON Docs.

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 compute phase is thrown later.

Usage example:

commit();  // now, transaction is considered "successful"
throw(42); // and this won't fail it

nativePrepareRandom

fun nativePrepareRandom();

Prepares a random number generator by using nativeRandomizeLt(). Automatically called by randomInt() and random() functions.

Usage example:

nativePrepareRandom(); // prepare the RNG
// ... do your random things ...

nativeRandomize

fun nativeRandomize(x: Int);

Randomizes the pseudo-random number generator with the specified seed x.

Usage example:

nativeRandomize();          // now, random numbers are less predictable
let idk: Int = randomInt(); // ???, it's random!

nativeRandomizeLt

fun nativeRandomizeLt();

Randomizes the random number generator with the current logical time.

Usage example:

nativeRandomizeLt();        // now, random numbers are unpredictable for users,
                            // but still may be affected by validators or collators
                            // as they determine the seed of the current block.
let idk: Int = randomInt(); // ???, it's random!

nativeRandom

fun nativeRandom(): Int;

Generates and returns an $256$-bit random number just like randomInt(), but doesn’t initialize the random generator with nativePrepareRandom() beforehand.

Note

Don’t use this function directly, and prefer using randomInt() instead.

nativeRandomInterval

fun nativeRandomInterval(max: Int): Int;

Generates and returns a $256$-bit random number in the range from $0$ to max similar to random(), but doesn’t initialize the random generator with nativePrepareRandom() beforehand.

Note

Don’t use this function directly, and prefer using random() instead.

nativeSendMessage

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

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

Note

Prefer using a much more common and user-friendly send() function unless you have a complex logic that can’t be expressed otherwise.

nativeReserve

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

Calls native raw_reserve function with specified amount and mode. The raw_reserve is a function that creates an output action to reserve a specific amount of nanoToncoins from the remaining balance of the account.

It has the following signature in FunC:

raw_reserve(int amount, int mode) impure asm "RAWRESERVE";

The function takes two arguments:

• amount: The number of nanoToncoins to reserve.
• mode: Determines the reservation behavior.

Function raw_reserve is roughly equivalent to creating an outbound message carrying the specified amount of nanoToncoins (or b $-$ amount nanoToncoins, where b is the remaining balance) to oneself. This ensures that subsequent output actions cannot spend more money than the remainder.

It’s possible to use raw Int values and manually provide them for the mode, but for your convenience there’s a set of constants which you may use to construct the compound mode with ease. Take a look at the following tables for more information on base modes and optional flags.

Caution

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

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 nanoToncoins.
$1$	ReserveAllExcept	Reserves all, but the specified amount of nanoToncoins.
$2$	ReserveAtMost	Reserves at most the specified amount of nanoToncoins.

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 reservation fails.

Combining modes with flags

To make the Int value for mode parameter, you just have to 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 would fail
//            amount of nanoToncoins to reserve

parseStdAddress

Available since Tact 1.5

fun parseStdAddress(slice: Slice): StdAddress;

Converts a Slice containing an address into the StdAddress Struct and returns it. The StdAddress is a built-in Struct that consists of:

Field	Type	Description
workchain	Int as int8	Workchain ID of the address, usually $0$ (basechain) or $-1$ (masterchain)
address	Int as uint256	Address in the specified workchain

Attempts to pass a Slice with layout different from the StdAddress or to load more data than a given Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let addr = address("EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2");
let parsedAddr = parseStdAddress(addr.asSlice());

parsedAddr.workchain; // 0
parsedAddr.address;   // 107...lots of digits...287

// Using newAddress() function with the contents of StdAddress will yield the initial Address:
let addr2: Address = newAddress(parsedAddr.workchain, parsedAddr.address);
addr2 == addr; // true

Note

For parsing addresses of variable length, see the parseVarAddress() function.

parseVarAddress

Available since Tact 1.5

fun parseVarAddress(slice: Slice): VarAddress;

Converts a Slice containing an address of variable length into the VarAddress Struct and returns it. The VarAddress is a built-in Struct consisting of:

Field	Type	Description
workchain	Int as int32	Workchain ID of the variable length address
address	Slice	Address in the specified workchain

Attempts to pass a Slice with layout different from the VarAddress or to load more data than a given Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let varAddrSlice = beginCell()
    .storeUint(6, 3)     // to recognize the following as a VarAddress
    .storeUint(123, 9)   // make address occupy 123 bits
    .storeUint(234, 32)  // specify workchain ID of 234
    .storeUint(345, 123) // specify address of 345
    .asSlice();
let parsedVarAddr = parseVarAddress(varAddrSlice);

parsedVarAddr.workchain;             // 234
parsedVarAddr.address;               // CS{Cell{002...2b3} bits: 44..167; refs: 0..0}
parsedVarAddr.address.loadUint(123); // 345

Caution

Variable-length addresses are intended for future extensions, and while validators must be ready to accept them in inbound messages, the standard (non-variable) addresses are used whenever possible.