Gas and fees

List of the general fee and gas-management functions. For the context and state-related functions, see:

• myStorageDue()
• gasConsumed()

getStorageFee

Available since Tact 1.5

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

Calculates and returns the storage fee in nanoToncoin 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 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 specifying the exact limits. In addition, make sure you take into account the deduplication of cells with the same hash.

Attempts to specify a 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 nanoToncoin Int for a transaction that consumed a 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 config param 20 for the masterchain and config param 21 for the basechain of TON Blockchain.

When 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 used below this threshold, the higher the minimum price will be. See the example for getSimpleComputeFee() to derive that threshold.

Attempts to specify a 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 the minimum price to pay if gasUsed is less than a certain threshold called flat_gas_limit. Calculates and returns only the gasUsed multiplied by the current gas price.

Attempts to specify a negative value for 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()

getForwardFee

Available since Tact 1.5

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

Calculates and returns the forward fee in nanoToncoin as an Int for an outgoing message consisting of a given number of cells and bits. Uses the prices of the masterchain if isMasterchain is true, or the prices of the basechain otherwise. The current prices are obtained from 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 on the basechain, 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 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 account for the deduplication of cells with the same hash; for example, the root cell and its data bits do not count toward the forward fee and are covered by the lump_price.

Attempts to specify a 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
//                           |      |      are not 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 amounts of cells or bits. Calculates and returns only the cells multiplied by the current cell price plus the bits multiplied by the current bit price.

Attempts to specify a 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 nanoToncoin 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, 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(fwdFee, false);

Useful links:

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

setGasLimit

Available since Tact 1.6

fun setGasLimit(limit: Int);

Sets the gas_limit to the Int limit and resets the gas_credit to 0. Note that specifying a limit higher than the maximum allowed value of $2^{63} - 1$ will have the same result as 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 them.

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

Note

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