Reference
Advanced

Advanced

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

⚠️

Proceed with caution.

Context.readForwardFee

extends fun readForwardFee(self: Context): Int

Extension function for the Context.

Reads forward fee (opens in a new tab) 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 (opens in a new tab) 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)!!;
💡

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 (opens in a new tab).

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

commit

fun commit();

Commits the current state of registers (opens in a new tab) 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 (opens in a new tab).

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 256256-bit random number just like randomInt(), but doesn't initialize the random generator with nativePrepareRandom() beforehand.

💡

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

nativeRandomInterval

fun nativeRandomInterval(max: Int): Int;

Generates and returns a 256256-bit random number in the range from 00 to max similar to random(), but doesn't initialize the random generator with nativePrepareRandom() beforehand.

💡

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.

💡

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.

⚠️

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

Base modes

The resulting mode value can have the following base modes:

Mode valueConstant nameDescription
00ReserveExactReserves exactly the specified amount of nanoToncoins.
11ReserveAllExceptReserves all, but the specified amount of nanoToncoins.
22ReserveAtMostReserves at most the specified amount of nanoToncoins.

Optional flags

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

Flag valueConstant nameDescription
+4+4ReserveAddOriginalBalanceIncreases the amount by the original balance of the current account (before the compute phase), including all extra currencies.
+8+8ReserveInvertSignNegates the amount value before performing the reservation.
+16+16ReserveBounceIfActionFailBounces 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