FunC 标准库
本节讨论了 stdlib.fc 库,它包含了在 FunC 中使用的标准函数。
目前,该库只是最常用的 TVM 命令的汇编器的包装,这些命令不是内置的。库中使用的每个 TVM 命令的描述都可以在 TVM 文档部分找到。本文档也借用了一些描述。
文件中的一些函数被注释掉了。这意味着它们已经成为了优化目的的内置函数。然而,类型签名和语义保持不变。
请注意,stdlib 中没有呈现一些不太常见的命令。总有一天它们也会被添加。
元组操作原语
名称和类型大多是自解释的。有关多态函数的更多信息,请参见 多态性与 forall。
请注意,目前原子类型 tuple
的值不能转换为复合元组类型(例如 [int, cell]
),反之亦然。
Lisp 类型列表
列表可以表示为嵌套的 2 元组。空列表通常表示为 TVM null
值(可以通过调用 null()
获得)。例如,元组 (1, (2, (3, null)))
表示列表 [1, 2, 3]
。列表的元素可以是不同类型。
cons
forall X -> tuple cons(X head, tuple tail) asm "CONS";
在 Lisp 类型列表的开头添加一个元素。
uncons
forall X -> (X, tuple) uncons(tuple list) asm "UNCONS";
提取 Lisp 类型列表的头和尾。
list_next
forall X -> (tuple, X) list_next(tuple list) asm( -> 1 0) "UNCONS";
提取 Lisp 类型列表的头和尾。可用作 (非) 修改方法。
() foo(tuple xs) {
(_, int x) = xs.list_next(); ;; 获取第一个元素,`_` 表示不使用尾列表
int y = xs~list_next(); ;; 弹出第一个元素
int z = xs~list_next(); ;; 弹出第二个元素
}
car
forall X -> X car(tuple list) asm "CAR";
返回 Lisp 类型列表的头部。
cdr
tuple cdr(tuple list) asm "CDR";
返回 Lisp 类型列表的尾部。
其他元组原语
empty_tuple
tuple empty_tuple() asm "NIL";
创建 0 元素元组。
tpush
forall X -> tuple tpush(tuple t, X value) asm "TPUSH";
forall X -> (tuple, ()) ~tpush(tuple t, X value) asm "TPUSH";
将值 x
追加到 Tuple t = (x1, ..., xn)
,但只有在结果 Tuple t' = (x1, ..., xn, x)
不超过 255 个字符时才有效。否则,会抛出类型检查异常。
single
forall X -> [X] single(X x) asm "SINGLE";
创建单例,即长度为一的元组。
unsingle
forall X -> X unsingle([X] t) asm "UNSINGLE";
解包单例。
pair
forall X, Y -> [X, Y] pair(X x, Y y) asm "PAIR";
创建一对。
unpair
forall X, Y -> (X, Y) unpair([X, Y] t) asm "UNPAIR";
解包一对。
triple
forall X, Y, Z -> [X, Y, Z] triple(X x, Y y, Z z) asm "TRIPLE";
创建三元组。
untriple
forall X, Y, Z -> (X, Y, Z) untriple([X, Y, Z] t) asm "UNTRIPLE";
解包三元组。
tuple4
forall X, Y, Z, W -> [X, Y, Z, W] tuple4(X x, Y y, Z z, W w) asm "4 TUPLE";
创建四元组。
untuple4
forall X, Y, Z, W -> (X, Y, Z, W) untuple4([X, Y, Z, W] t) asm "4 UNTUPLE";
解包四元组。
first
forall X -> X first(tuple t) asm "FIRST";
返回元组的第一个元素。
second
forall X -> X second(tuple t) asm "SECOND";
返回元组的第二个元素。
third
forall X -> X third(tuple t) asm "THIRD";
返回元组的第三个元素。
fourth
forall X -> X fourth(tuple t) asm "3 INDEX";
返回元组的第四个元素。
pair_first
forall X, Y -> X pair_first([X, Y] p) asm "FIRST";
返回一对的第一个元素。
pair_second
forall X, Y -> Y pair_second([X, Y] p) asm "SECOND";
返回一对的第二个元素。
triple_first
forall X, Y, Z -> X triple_first([X, Y, Z] p) asm "FIRST";
返回三元组的第一个元素。
triple_second
forall X, Y, Z -> Y triple_second([X, Y, Z] p) asm "SECOND";
返回三元组的第二个元素。
triple_third
forall X, Y, Z -> Z triple_third([X, Y, Z] p) asm "THIRD";
返回三元组的第三个元素。
特定领域原语
从 c7 提取信息
关于智能合约调用的一些有用信息可以在 c7 特殊寄存器中找到。这些原语用于方便地提取数据。
now
int now() asm "NOW";
返回当前 Unix 时间作为整数。
my_address
slice my_address() asm "MYADDR";
以 Slice 形式返回当前智能合约的内部地址,其中包含 MsgAddressInt
。如果需要,可以进一步使用诸如 parse_std_addr
之类的原语进行解析。
get_balance
[int, cell] get_balance() asm "BALANCE";
以 tuple
形式返回智能合约的剩余余额,其中包括 int
(剩余余额,以nanoton计)和 cell
(一个包含 32 位键的字典,代表“额外代币”的余额)。注意,RAW 原语(如 send_raw_message
)不会更新此字段。
cur_lt
int cur_lt() asm "LTIME";
返回当前交易的逻辑时间。
block_lt
int block_lt() asm "BLOCKLT";
返回当前区块的起始逻辑时间。
config_param
cell config_param(int x) asm "CONFIGOPTPARAM";
以 cell
或 null
值的形式返回全局配置参数的值,其中整数索引为 i
。
哈希
cell_hash
int cell_hash(cell c) asm "HASHCU";
计算cell c
的 representation hash ,并将其作为一个256位无符号整数x
返回。用于签名和检查由cell树表示的任意实体的签名。
slice_hash
int slice_hash(slice s) asm "HASHSU";
计算slice s
的哈希,并将其作为一个256位无符号整数x
返回。结果与创建一个只包含s
的数据和引用的普通cell,并通过cell_hash
计算其哈希的情况相同。
string_hash
int string_hash(slice s) asm "SHA256U";
计算slice s
数据位的sha256。如果s
的位长度不能被八整除,则抛出一个cell下溢异常。哈希值作为一个256位无符号整数x
返回。
签名检 查
check_signature
int check_signature(int hash, slice signature, int public_key) asm "CHKSIGNU";
使用public_key
(也表示为一个256位无符号整数)检查hash
(通常作为某些数据的哈希计算得出的256位无符号整数)的Ed25519 signature
。签名必须包含至少512个数据位;只使用前512位。如果签名有效,结果为-1
;否则,为0
。请注意,CHKSIGNU
创建一个包含哈希的256位切片,并调用CHKSIGNS
。也就是说,如果hash
是作为某些数据的哈希计算的,这些数据会被_两次_哈希,第二次哈希发生在CHKSIGNS
内部。
check_data_signature
int check_data_signature(slice data, slice signature, int public_key) asm "CHKSIGNS";
检查signature
是否是使用public_key
的slice data
数据部分的有效Ed25519签名,类似于check_signature
。如果data
的位长度不能被八整除,则抛出一个cell下溢异常。Ed25519签名的验证是标准的,使用sha256将data
简化为实际签名的256位数字。
计算boc大小
下面的原语可能对于计算用户提供数据的存储费用有用。
compute_data_size?
(int, int, int, int) compute_data_size?(cell c, int max_cells) asm "CDATASIZEQ NULLSWAPIFNOT2 NULLSWAPIFNOT";
返回(x, y, z, -1)
或(null, null, null, 0)
。递归地计算以cell c
为根的DAG中不同cell的数量x
、数据位y
和cell引用z
,有效地返回此DAG使用的总存储量,同时考虑到相等cell的识别。x
、y
和z
的值通过对此DAG进行深度优先遍历来计算,并使用访问过的cell哈希的哈希表来防止已访问cell的重复访问。访问的cell总数x
不能超过非负的max_cells
;否则,在访问第(max_cells + 1)
个cell之前,计算将被中止,并返回零标志以指示失败。如果c
为null
,则返回x = y = z = 0
。
slice_compute_data_size?
(int, int, int, int) slice_compute_data_size?(slice s, int max_cells) asm "SDATASIZEQ NULLSWAPIFNOT2 NULLSWAPIFNOT";
类似于compute_data_size?
,但接受的是slice s
而不是cell
。返回的x
值不考
虑包含切片s
本身的cell;然而,s
的数据位和cell引用在y
和z
中要被考虑。
compute_data_size
(int, int, int) compute_data_size(cell c, int max_cells) impure asm "CDATASIZE";
compute_data_size?
的非静默版本,失败时抛出cell溢出异常(8)。
slice_compute_data_size
(int, int, int) slice_compute_data_size(slice s, int max_cells) impure asm "SDATASIZE";
slice_compute_data_size?
的非静默版本,失败时抛出cell溢出异常(8)。
持久存储保存和加载
get_data
cell get_data() asm "c4 PUSH";
返回持久化合约存储cell。稍后可以使用切片和构建器原语对其进行解析或修改。
set_data
() set_data(cell c) impure asm "c4 POP";
将cellc
设置为持久化合约数据。您可以使用这个原语更新持久化合约存储。
Continuation 原语
get_c3
cont get_c3() impure asm "c3 PUSH";
通常c3
有一个由合约的整个代码初始化的continuation。它用于函数调用。原语返回c3
的当前值。
set_c3
() set_c3(cont c) impure asm "c3 POP";
更新c3
的当前值。通常,它用于实时更新智能合约代码。请注意,在执行此原语之后,当前代码(以及递归函数调用堆栈)不会改变,但任何其他函数调用将使用新代码中的函数。
bless
cont bless(slice s) impure asm "BLESS";
将slice s
转换为一个简单的普通 continuation c
,其中c.code = s
,堆栈和保存列表为空。
与 gas 相关的原语
accept_message
() accept_message() impure asm "ACCEPT";
将当前 gas 限制gl
设置为其允许的最大值gm
,并将 gas 信用gc
重置为零,同时减少gr
的值gc
。换句话说,当前智能合约同意购买一些 gas 以完成当前交易。这个动作是处理不携带价值(因此不含 gas )的外部消息所必需的。
有关更多详细信息,请查看accept_message effects
set_gas_limit
() set_gas_limit(int limit) impure asm "SETGASLIMIT";
将当前 gas 限制gl
设置为limit
和gm
的最小值,并将 gas 信用gc
重置为零。此时,如果消耗的 gas 量(包括当前指令)超过gl
的结果值,则在设置新 gas 限制之前会抛出(未处理的) gas 不足异常。请注意,带有limit ≥ 2^63 − 1
参数的set_gas_limit
等同于accept_message
。
有 关更多详细信息,请查看accept_message effects
commit
() commit() impure asm "COMMIT";
提交寄存器c4
(“持久数据”)和c5
(“动作”)的当前状态,以便即使稍后抛出异常,当前执行也被视为“成功”,并保存这些值。
buy_gas
() buy_gas(int gram) impure asm "BUYGAS";
BUYGAS
操作码目前尚未实现
计算可以用gram
nanoton币购买的gas 量,并以与set_gas_limit
相同的方式相应地设置gl
。
动作原语
raw_reserve
() raw_reserve(int amount, int mode) impure asm "RAWRESERVE";
创建一个输出动作,该动作将准确地预留amount
nanoton 币(如果mode = 0
),最多amount
nanoton 币(如果mode = 2
),或除amount
nanoton 币以外的所有 nanoton 币(如果mode = 1
或mode = 3
)从账户的剩余余额中。它大致等同于创建一个携带amount
nanoton 币(或b − amount
nanoton 币,其中b
是剩余余额)的出站消息发送给自己,这样随后的输出动作就不会花费超过剩余部分的金额。mode
中的+2位意味着外部动作在无法预留指定金额时不会失败;相反,将预留所有剩余余额。mode
中的+8位意味着amount <- -amount
在进行任何进一步的动作之前。mode
中的+4位意味着在进行任何其他检查和动作之前,amount
会增加当前账户的原始余额(在 Compute Phase 之前),包括所有额外代币。目前,amount
必须是非负整数,mode
必须在0..15
范围内。
raw_reserve_extra
() raw_reserve_extra(int amount, cell extra_amount, int mode) impure asm "RAWRESERVEX";
类似于raw_reserve
,但还接受一个由cell
或null
表示的额外代币字典extra_amount
。这样,除了Toncoin以外的其他代币也可以被预留。
send_raw_message
() send_raw_message(cell msg, int mode) impure asm "SENDRAWMSG";
发送包含在msg
中的原始消息,它应该包含一个正确序列化的消息对象X,唯一的例外是源地址可以有一个虚拟值addr_none
(自动替换为当前智能合约地址),以及ihr_fee
、fwd_fee
、created_lt
和created_at
字段可以有任意值(在当前交易的 Action Phase 期间用正确的值重写)。整数参数mode
包含标志。
目前有3种消息Modes和3种消息Flags。您可以将单一Mode与多个(也许没有)标志组合以获得所需的mode
。组合只是意味着获取它们值的总和。下面给出了Modes和Flags的描述表格。
Mode | 描述 |
---|---|
0 | 普通消息 |
64 | 除了最初在新消息中指示的值之外,还携带入站消息的所有剩余价值 |
128 | 携带当前智能合约的所有剩余余额,而不是最初在消息中指示的值 |
Flag | 描述 |
---|---|
+1 | 单独支付消息价值之外的转移费用 |
+2 | 忽略在 Action Phase 处理此消息时出现的任何错误 |
+16 | 在 动作失败的情况下 - 弹回交易。如果使用+2 ,则无效。 |
+32 | 如果当前账户的最终余额为零,则必须销毁该账户(通常与模式128一起使用) |
例如,如果您想发送常规消息并单独支付转账费用,请使用Mode0
和Flag+1
以获得mode = 1
。如果
您想发送整个合约余额并立即销毁它,请使用Mode128
和Flag+32
以获得mode = 160
。
set_code
() set_code(cell new_code) impure asm "SETCODE";
创建一个输出动作,该动作将更改此智能合约的代码为cellnew_code
给出的代码。请注意,此更改仅在当前智能合约的当前运行成功终止后才生效。(参见[set_c3](/develop/func/stdlib#set_c3.))
随机数生成器原语
伪随机数生成器使用随机种子(一个无符号的256位整数)和(有时)c7中保存的其他数据。在TON区块链中执行智能合约之前,随机种子的初始值是智能合约地址和全局区块随机种子的哈希。如果在一个区块内有多次运行相同的智能合约,那么所有这些运行都将具有相同的随机种子。例如,可以通过在第一次使用伪随机数生成器之前运行randomize_lt
来解决这个问题。
请记住,如果您不使用额外的技巧,下面函数生成的随机数是可以预测的。
random
int random() impure asm "RANDU256";
生成一个新的伪随机无符号256位整数x
。算法如下:如果r
是旧的随机种子值,被视为一个32字节的数组(通过构造一个无符号256位整数的大端表示),那么计算其sha512(r)
;这个哈希的前32字节被存储为随机种子的新值r'
,剩余的32字节作为下一个随机值x
返回。
rand
int rand(int range) impure asm "RAND";
在范围0..range−1
(或range..−1
,如果range < 0
)内生成一个新的伪随机整数z
。更准确地说,生成一个无符号随机值x
,如random
中一样;然后计算z := x * range / 2^256
。
get_seed
int get_seed() impure asm "RANDSEED";
以一个无符号的256位整数返回当前随机种子。
set_seed
int set_seed(int seed) impure asm "SETRAND";
将随机种子设置为一个无符号的256位seed
。
randomize
() randomize(int x) impure asm "ADDRAND";
通过将随机种子设置为两个32字节字符串的串联的sha256来将一个无符号的256位整数x
混合到随机种子r
中,这两个32字节字符串:第一个包含旧种子r
的大端表示,第二个包含x
的大端表示。
randomize_lt
() randomize_lt() impure asm "LTIME" "ADDRAND";
相当于randomize(cur_lt());
。
地址操作原语
下面列出的地址操作 原语根据以下TL-B方案序列化和反序列化值。
addr_none$00 = MsgAddressExt;
addr_extern$01 len:(## 8) external_address:(bits len)
= MsgAddressExt;
anycast_info$_ depth:(#<= 30) { depth >= 1 }
rewrite_pfx:(bits depth) = Anycast;
addr_std$10 anycast:(Maybe Anycast)
workchain_id:int8 address:bits256 = MsgAddressInt;
addr_var$11 anycast:(Maybe Anycast) addr_len:(## 9)
work
chain_id:int32 address:(bits addr_len) = MsgAddressInt;
_ _:MsgAddressInt = MsgAddress;
_ _:MsgAddressExt = MsgAddress;
int_msg_info$0 ihr_disabled:Bool bounce:Bool bounced:Bool
src:MsgAddress dest:MsgAddressInt
value:CurrencyCollection ihr_fee:Grams fwd_fee:Grams
created_lt:uint64 created_at:uint32 = CommonMsgInfoRelaxed;
ext_out_msg_info$11 src:MsgAddress dest:MsgAddressExt
created_lt:uint64 created_at:uint32 = CommonMsgInfoRelaxed;
反序列化的MsgAddress
由元组t
表示,如下所述:
addr_none
表示为t = (0)
,即包含一个等于零的整数的元组addr_extern
表示为t = (1, s)
,其中切片s
包含字段external_address
。换句话说,t
是一个对(包含两个条目的元组),包含一个等于一的整数和切片s
addr_std
表示为t = (2, u, x, s)
,其中u
要么是null
(如果anycast
不存在),要么是包含rewrite_pfx
的切片s'
(如果anycast
存在)。接下来,整数x
是workchain_id
,切片s
包含地址addr_var
表示为t = (3, u, x, s)
,其中u
、x
和s
的含义与addr_std
相同
load_msg_addr
(slice, slice) load_msg_addr(slice s) asm( -> 1 0) "LDMSGADDR";
从 slice s
加载唯一有效的 MsgAddress
前缀,并返回此前缀 s'
及 s
的其余部分 s''
作为切片。
parse_addr
tuple parse_addr(slice s) asm "PARSEMSGADDR";
将包含有效 MsgAddress
的 slice s
分解为 tuple t
,并包含此 MsgAddress
的独立字段。如果 s
不是有效的 MsgAddress
,则抛出 cell 反序列化异常。
parse_std_addr
(int, int) parse_std_addr(slice s) asm "REWRITESTDADDR";
解析包含有效 MsgAddressInt
(通常为 msg_addr_std
)的切片 s
,将重写 anycast
(如果存在)应用到地址相同长度前缀,并返回工作链和256位地址作为整数。如果地址不是256位,或者 s
不是 MsgAddressInt
的有效序列化,抛出cell deserialization
异常。
parse_var_addr
(int, slice) parse_var_addr(slice s) asm "REWRITEVARADDR";
parse_std_addr
的变体,即使地址不是正好256位长(由 msg_addr_var
表示),也以切片 s
返回(重写后的)地址。
调试原语
目前,只有一个函数可用。
dump_stack
() dump_stack() impure asm "DUMPSTK";
转储堆栈(最多前255个值)并显示总堆栈深度。
切片原语
据说,如果原语返回数据及其余部分的切片,则称其为加载数据(因此也可用作修改方法)。
据说,如果原语仅返回数据,则称其为预加载数据(可用作非修改方法)。
除非另有说明,加载和预加载原语从切片的前缀读取数据。
begin_parse
slice begin_parse(cell c) asm "CTOS";
将 cell
转换为 slice
。注意,c
必须是普通cell或特殊cell(见 TVM.pdf, 3.1.2),自动加载以产生普通cell c'
,然后转换为 slice
。
end_parse
() end_parse(slice s) impure asm "ENDS";
检查 s
是否为空。如果不是,则抛出异常。