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.

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

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:

Storage fee in TON Docs
Storage fee calculation in TON Docs

getStorageFee

Available since Tact 1.5

fun getStorageFee(cells: Int, bits: Int, seconds: Int, isMasterchain: Bool): Int;

Calculates and returns the storage fee in nanoToncoins Int for storing a contract with a given number of cells and bits for a number of seconds. Uses the prices of the masterchain if isMasterchain is true, otherwise the prices of the basechain. The current prices are obtained from the config param 18 of TON Blockchain.

Note, that specifying values of cells and bits higher than their maximum values listed in account state limits (max_acc_state_cells and max_acc_state_bits) will have the same result as with specifying the exact limits. In addition, make sure you take into account the deduplication of cells with the same hash.

Attempts to specify negative number of cells, bits or seconds throw an exception with exit code 5: Integer out of expected range.

Usage example:

let fee: Int = getStorageFee(1_000, 1_000, 1_000, false);
//                           -----  -----  -----  -----
//                           ↑      ↑      ↑      ↑
//                           |      |      |      Isn't on the masterchain,
//                           |      |      |      but on the basechain
//                           |      |      Number of seconds to calculate
//                           |      |      the storage fee for
//                           |      Number of bits in a contract
//                           Number of cells in a contract

Useful links:

Storage fee in TON Docs
Storage fee calculation in TON Docs

getComputeFee

Available since Tact 1.5

fun getComputeFee(gasUsed: Int, isMasterchain: Bool): Int;

Calculates and returns the compute fee in nanoToncoins Int for a transaction that consumed gasUsed amount of gas. Uses the prices of the masterchain if isMasterchain is true, otherwise the prices of the basechain. The current prices are obtained from the config param 20 for the masterchain and config param 21 for the basechain of TON Blockchain.

When the gasUsed is less than a certain threshold called flat_gas_limit, there’s a minimum price to pay based on the value of flat_gas_price. The less gas is used below this threshold, the higher the minimum price will be. See the example for getSimpleComputeFee() to derive that threshold.

Attempts to specify negative value of gasUsed throw an exception with exit code 5: Integer out of expected range.

Usage example:

let fee: Int = getComputeFee(1_000, false);
//                           -----  -----
//                           ↑      ↑
//                           |      Isn't on the masterchain,
//                           |      but on the basechain
//                           Number of gas units
//                           consumed per transaction

Useful links:

Compute fee in TON Docs
Compute fee calculation in TON Docs
getSimpleComputeFee()

getSimpleComputeFee

Available since Tact 1.5

fun getSimpleComputeFee(gasUsed: Int, isMasterchain: Bool): Int;

Similar to getComputeFee(), but without the flat_gas_price, i.e. without a minimum price to pay if the gasUsed is less than a certain threshold called flat_gas_limit. Calculates and returns only the gasUsed times the current gas price.

Attempts to specify negative value of gasUsed throw an exception with exit code 5: Integer out of expected range.

Usage example:

let fee = getComputeFee(0, false);
let feeNoFlat = getSimpleComputeFee(0, false);
let maxFlatPrice = fee - feeNoFlat;

Useful links:

Compute fee in TON Docs
Compute fee calculation in TON Docs
getComputeFee()

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

Useful links:

getOriginalFwdFee()

getForwardFee

Available since Tact 1.5

fun getForwardFee(cells: Int, bits: Int, isMasterchain: Bool): Int;

Calculates and returns the forward fee in nanoToncoins Int for an outgoing message consisting of a given number of cells and bits. Uses the prices of the masterchain if isMasterchain is true, otherwise the prices of the basechain. The current prices are obtained from the config param 24 for the masterchain and config param 25 for the basechain of TON Blockchain.

If both the source and the destination addresses are in the basechain, then specify isMasterchain as false. Otherwise, specify true.

Note, that specifying values of cells and bits higher than their maximum values listed in account state limits (max_msg_cells and max_msg_bits) will have the same result as with specifying the exact limits.

However, regardless of the values of cells and bits, this function always adds the minimum price based on the value of lump_price. See the example for getSimpleForwardFee() to derive it. In addition, make sure you take into account the deduplication of cells with the same hash, since for example the root cell and its data bits don’t count towards the forward fee and are covered by the lump_price.

Attempts to specify negative number of cells or bits throw an exception with exit code 5: Integer out of expected range.

Usage example:

let fee: Int = getForwardFee(1_000, 1_000, false);
//                           -----  -----  -----
//                           ↑      ↑      ↑
//                           |      |      Both source and destination
//                           |      |      isn't on the masterchain,
//                           |      |      but on the basechain
//                           |      Number of bits in a message
//                           Number of cells in a message

Useful links:

Forward fee in TON Docs
Forward fee calculation in TON Docs
CDATASIZEQ instruction for computing the number of distinct cells, data bits and refs in a Cell
getSimpleForwardFee()
getOriginalFwdFee()

getSimpleForwardFee

Available since Tact 1.5

fun getSimpleForwardFee(cells: Int, bits: Int, isMasterchain: Bool): Int;

Similar to getForwardFee(), but without the lump_price, i.e. without the minimum price to pay regardless of the amount of cells or bits. Calculates and returns only the cells times the current cell price plus bits times the current bit price.

Attempts to specify negative number of cells or bits throw an exception with exit code 5: Integer out of expected range.

Usage example:

let fee = getForwardFee(1_000, 1_000, false);
let feeNoLump = getSimpleForwardFee(1_000, 1_000, false);
let lumpPrice = fee - feeNoLump;

Useful links:

Forward fee in TON Docs
Forward fee calculation in TON Docs
getForwardFee()

getOriginalFwdFee

Available since Tact 1.5

fun getOriginalFwdFee(fwdFee: Int, isMasterchain: Bool): Int;

Calculates and returns the so-called original forward fee in nanoToncoins Int for an outgoing message based on the fwdFee obtained from the incoming message. If both the source and the destination addresses are in the basechain, then specify isMasterchain as false. Otherwise, specify true.

This function is useful when the outgoing message depends heavily on the structure of the incoming message, so much so that you cannot fully predict the fee using getForwardFee() alone. Even if you could, calculating the exact fee with nanoToncoin-level precision can be very expensive, so the approximation given by this function is often good enough.

Attempts to specify a negative value of fwdFee throw an exception with exit code 5: Integer out of expected range.

Usage example:

let fwdFee: Int = context().readForwardFee();
let origFee: Int = getOriginalFwdFee(fee, false);

Useful links:

Forward fee in TON Docs
Forward fee calculation in TON Docs
getForwardFee()
Context.readForwardFee()

setGasLimit

Available since Tact 1.6 (not released yet)

fun setGasLimit(limit: Int);

Sets the gas_limit to the Int limit and resets the gas_credit to $0$. Note that specifying the limit higher than the maximum allowed value of $2^{63} - 1$ will have the same result as with specifying that exact maximum or calling acceptMessage().

Attempts to specify a negative or insufficient value of limit will cause an exception with exit code -14: Out of gas error.

Usage example:

setGasLimit(42000);

Note

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

acceptMessage

fun acceptMessage();

Agrees to buy some gas to finish the current transaction by setting the gas_limit to its maximum allowed value of $2^{63} - 1$ and resetting the gas_credit to $0$. 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

myCode

Available since Tact 1.6 (not released yet)

fun myCode(): Cell;

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

Usage example:

let code: Cell = myCode();

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.

getSeed

Available since Tact 1.6 (not released yet)

fun getSeed(): Int;

Generates and returns an unsigned $256$-bit Int seed for the random number generator. The resulting seed is commonly used with the setSeed() and nativeRandomize() functions.

Usage example:

let seed: Int = getSeed();
setSeed(seed); // from now on the results of pseudorandom number generator
               // are completely determined by the seed, which can be handy in tests,
               // but must not be used in production code!

Useful links:

Random seed in Wikipedia
setSeed()
nativeRandomize()

setSeed

Available since Tact 1.6 (not released yet)

fun setSeed(seed: Int);

Sets the seed of the random number generator to the unsigned $256$-bit Int seed which can be obtained with the getSeed() function.

Attempts to specify a negative value of seed throw an exception with exit code 5: Integer out of expected range.

Usage example:

let seed: Int = getSeed();
setSeed(seed); // from now on the results of pseudorandom number generator
               // are completely determined by the seed, which can be handy in tests,
               // but must not be used in production code!

Useful links:

Random seed in Wikipedia
getSeed()

curLt

Available since Tact 1.6 (not released yet)

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

blockLt

Available since Tact 1.6 (not released yet)

fun blockLt(): Int;

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

Usage example:

let time: Int = blockLt();

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 pseudorandom number generator with the specified unsigned $256$-bit Int x by mixing it with the current seed. The new seed is the unsigned $256$-bit Int value of the SHA-256 hash of concatenated old seed and x in their $32$-byte strings big-endian representation.

Attempts to specify a negative value of x throw an exception with exit code 5: Integer out of expected range.

Usage example:

nativeRandomize(42);        // now, random numbers are less predictable
let idk: Int = randomInt(); // ???, it's random,
                            // but the seed was adjusted deterministically!

Useful links:

Random seed in Wikipedia

nativeRandomizeLt

fun nativeRandomizeLt();

Randomizes the random number generator with the logical time of the current transaction. Equivalent to calling nativeRandomize(curLt()).

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!

Useful links:

Random seed in Wikipedia
nativeRandomize
curLt()

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.

Attempts to queue more than $255$ messages throw an exception with an exit code 33: Action list is too long.

Note

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

nativeSendMessageReturnForwardFee

Gas-expensive Available since Tact 1.5

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

Similar to nativeSendMessage(), but also calculates and returns the forward fee in nanoToncoins.

Attempts to queue more than $255$ messages throw an exception with an exit code 33: Action list is too long.

nativeReserve

Gas-expensive

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.

Additionally, attempts to queue more than $255$ reservations in one transaction throw an exception with an 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 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.