高级

各种小众、危险或不稳定的功能，可能会产生意想不到的结果，仅供更有经验的用户使用。

警告

谨慎行事。

gasConsumed

Available since Tact 1.5

fun gasConsumed(): Int;

返回当前交易中 TVM 到目前为止消耗的 gas 的 nanoToncoin Int 数量。 由此产生的值包括调用此功能的费用。

用法示例：

let gas: Int = gasConsumed();

Useful links:

TON Docs中的 Gas

myStorageDue

Available since Tact 1.5

fun myStorageDue(): Int;

返回累积的 storage fee 债务的 nanoToncoin Int 数量。 在计算新的合约余额之前，将从收到的信息值中扣除储存费。

用法示例：

let debt: Int = myStorageDue();

Useful links:

TON 文档中的存储费(存储费） TON 文档中的存储费计算

getStorageFee

Available since Tact 1.5

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

计算并返回在给定数量的 cells 和 bits 下存储合约指定 seconds 时间所需的 storage fee，以 nanoToncoins Int 表示。 如果isMasterchain 是 true，则使用 masterchain 的价格，否则 basechain 的价格。 当前价格来自TON Blockchain的配置参数18。

请注意，cells和bits的数值被用来作为它们最大的数值加上 $1$的模块。 也就是说，如果指定的值高于账户状态限制（max_acc_state_cells和max_acc_state_bits）中列出的值，其结果将与指定精确限制的结果相同。 此外，请确保您考虑到与同一哈希的 cells 分离。

试图指定负数的 cells、bits 或 seconds 会抛出异常export code 5：整数超出预期范围。

用法示例：

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:

TON 文档中的存储费(存储费） TON 文档中的存储费计算

getComputeFee

Available since Tact 1.5

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

计算并返回消耗了 gasUsed 数量的gas的交易的compute fee，单位为nanoToncoinsInt。 如果isMasterchain 是 true，则使用 masterchain 的价格，否则 basechain 的价格。 当前价格来源于 TON 区块链的 主链配置参数 20 和基本链配置参数 21。

当 gasUsed 小于称为 flat_gas_limit 的某个阈值时，需支付的最低费用基于 flat_gas_price 的值计算。 gas 使用量越小，最低价格就越高。 请参阅getSimpleComputeFee()的示例来得出这个阈值。

试图指定一个 gassUsed 的负值导致异常退出码 5：Integer out of expected range。

使用示例

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;

类似于getComputeFee()，但没有flat_gas_price，如果gassUsed小于一个叫做flat_gas_limit 的阈值，则不支付最低价格。 计算并只返回当前 gas 价格的 gasUsed 倍数。

试图指定一个 gassUsed 的负值导致异常退出码 5：Integer out of expected range。

示例用法：

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;

Context 的扩展函数。

读取forward fee，然后返回为 Int nanoToncoins。

示例用法：

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

Useful links:

getOriginalFwdFee()

getForwardFee

Available since Tact 1.5

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

计算并返回一个出站消息的转发费用，该消息由给定数量的cells和bits组成，费用以nanoToncoins表示，类型为Int。 如果isMasterchain 是 true，则使用 masterchain 的价格，否则 basechain 的价格。 当前价格来自 TON 区块链的主链配置参数 24 和基链配置参数 25。

如果源地址和目的地址都在 basechain中，那么指定isMasterchain 为 false。 否则，请指定 true。

请注意，cells 和 bits 的值取其最大值加上 $1$。 也就是说，指定高于账户状态限制（max_msg_cells 和 max_msg_bits）中所列值的值，会产生与指定精确限制相同的结果。

然而，不管cells和bits的数值如何，此函数总是添加基于lump_price 的最低价格。 请参阅getSimpleForwardFee() 的示例以获取它。 此外，请确保考虑到具有相同哈希的cell去重，因为例如 root cell 及其数据位不计入转发费用，并由lump_price覆盖。

试图指定负数的 cells 或 bits 会导致异常退出码 5：Integer out of expected range。

使用示例

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:

TON 文档中的转发费用
TON 文档中的转发费用计算
CDATASIZEQ 指令用于计算 Cell 中不同cell、数据位和引用的数量
getSimpleForwardFee()
getOriginalFwdFee()

getSimpleForwardFee

Available since Tact 1.5

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

类似于getForwardFee()，但没有 lump_price, 例如, 不考虑cells或bits的数量，支付最低价格。 计算并返回仅由 cells 乘以当前单元价格加上 bits 乘以当前位价格的结果。

试图指定负数的 cells 或 bits 会导致异常退出码 5：Integer out of expected range。

使用示例

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

Useful links:

TON 文档中的forward-fee( ） TON 文档中的forward-fee计算( ） getForwardFee()（{:tact}）

getOriginalFwdFee

Available since Tact 1.5

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

根据从传入信息中获取的 fwdFee 计算并返回传出信息的所谓 original 转发费，单位为 nano Toncoins Int。 如果源地址和目的地址都在 basechain中，那么指定isMasterchain 为 false。 否则，请指定 true。

当发出的信息在很大程度上取决于收到的信息的结构，以至于无法单独使用 getForwardFee() 来完全预测费用时，这个函数就非常有用。 即使可以，以 nanoToncoin 级别的精度计算精确费用也会非常昂贵，因此该函数给出的近似值通常已经足够好了。

试图指定一个 fwdFee 的负值导致异常退出码 5：Integer out of expected range。

用法示例：

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

Useful links:

TON 文档中的转发费用/ TON 文档中的转发费用计算/ getForwardFee()/ Context.readForwardFee()

getConfigParam

fun getConfigParam(id: Int): Cell?;

通过 id 加载 TON 区块链的配置参数。

使用示例：

// 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)!!;

注意

标准库 @stdlib/config 提供了两个相关的辅助函数：
getConfigAddress()，用于获取配置 Address/ getElectorAddress()，用于获取选区 Address。

了解有关其他参数的更多信息：TON 文档中的配置参数。

acceptMessage

fun acceptMessage();

同意购买一些 gas 来完成当前交易。 处理外部信息时需要这一操作，因为外部信息本身没有值（因此没有 gas ）。

用法示例：

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

注意

更多详情，请参阅TON 文档中的接受信息效果。

commit

fun commit();

提交 寄存器c4（“持久化数据”）和c5（“操作”）的当前状态，这样，即使随后在计算阶段出现异常，当前执行也会因保存的值而被视为 “成功”。

用法示例：

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

nativePrepareRandom

fun nativePrepareRandom();

使用 nativeRandomizeLt()准备随机数生成器。 由 randomInt() 和 random() 函数自动调用。

用法示例：

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

nativeRandomize

fun nativeRandomize(x: Int);

使用指定的种子 x 随机化伪随机数生成器。

用法示例：

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

nativeRandomizeLt

fun nativeRandomizeLt();

使用当前 逻辑时间 随机化随机数发生器。

用法示例：

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;

生成并返回 $256$-bit 随机数，就像 randomInt()，但不会事先用 nativePrepareRandom()初始化随机生成器。

注意

不要直接使用该函数，而应使用 randomInt()。

nativeRandomInterval

fun nativeRandomInterval(max: Int): Int;

生成并返回 $256$-bit 的随机数，范围从 $0$ 到 max，类似于 random()，但不会事先用 nativePrepareRandom()初始化随机生成器。

注意

不要直接使用该函数，而应使用 random()。

nativeSendMessage

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

排序消息将通过指定完整的 cell 和 message mode 发送。

注意

除非您有无法以其他方式表达的复杂逻辑，否则请优先使用更常见、更方便用户使用的 send()函数。

nativeReserve

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

以指定的金额和模式调用本地 raw_reserve 函数。 raw_reserve是一个能够创建输出动作的函数，从账户余额中保留一定数量的 nanoToncoins。

它在 FunC 中的签名如下

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

该函数有两个参数：

• amount: 保留的 nanoToncoins 个数。
• mode : 确定预订行为。

函数 raw_reserve 大致等同于创建一条向外发送的消息，将指定的 “数量” nano Toncoins(或 b $-$ “数量” nano Toncoins，其中 b为余额）发送给自己。 这就确保了后续产出行动所花费的资金不会超过剩余资金。

您可以使用原始的 Int值，并手动为 mode 提供这些值，但为了方便起见，您可以使用一组常量来轻松构建复合 mode。 有关基本模式和可选标记的更多信息，请参阅下表。

警告

目前，amount 必须是非负整数，mode 的范围必须是 $0..31$（含）。

基本模式

由此产生的 mode 值可以有以下基本模式：

模式值	常量名称	说明
$0$	ReserveExact	精确保留指定数量的 nanoToncoins。
$1$	ReserveAllExcept	保留所有，但是指定的 nanoToncoins 的amount 。
$2$	ReserveAtMost	最多保留指定数量的 nanoToncoins。

可选标记

此外，生成的 mode 还可以添加以下可选标记：

标志值	常量名称	描述
$+4$	ReserveAddOriginalBalance	增加 amount 的值，包含当前账户的原始余额（计算阶段之前），包括所有额外的货币。
$+8$	ReserveInvertSign	在执行预留操作之前，将 amount 值取反。
$+16$	ReserveBounceIfActionFail	保留失败时退回交易。

使用标志组合模式

要为 mode 参数创建 Int 值，只需通过应用 按位或操作 将基本模式与可选标志结合起来：

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;

将包含地址的 Slice 转换为 StdAddress Struct 并返回它。 StdAddress 是一个内置的 Struct 包含：

字段	类型	说明
workchain	Int as int8	地址的工作链ID，通常是 $0$ (basechain) 或 $-1$ (masterchain)
address	Int as uint256	指定的工作链中的地址

尝试传递具有不同布局的 Slice，或者加载的数据超过给定 Slice 所包含的数据，会抛出异常，带有 退出码 9：Cell underflow。

用法示例：

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

注意

要解析变量长度的地址，请参阅parseVarAddress() 函数。

parseVarAddress

Available since Tact 1.5

fun parseVarAddress(slice: Slice): VarAddress;

将包含可变长度的地址的 Slice 转换为 VarAddress Struct 并返回它。 VarAddress 是一个内置的 Struct 由以下部分组成：

字段	类型	函数 “raw_reserve “大致等同于创建一个向外发送的消息，将指定的 “金额”nanoToncoins（或 “b ” $-$ “金额”nanoToncoins，其中 “b “为余额）发送给自己。 这就确保了后续产出行动所花费的资金不会超过剩余资金。
workchain	Int as int32	变量长度地址的 Workchain ID
address	Slice	指定的工作链中的地址

尝试传递具有不同布局的 Slice，或者加载的数据超过给定 Slice 所包含的数据，会抛出异常，带有 退出代码 9：Cell underflow。

用法示例：

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

警告

可变长度地址是为未来扩展而设计的，虽然验证者必须准备好接受它们的入站消息，但标准（非可变）地址在可能的情况下仍然优先使用。