Tact 语言基础 | Cells、Builders 和 Slices

riyad

Cells、Builders 和 Slices 是 TON 区块链的底层 primitives。 TON 区块链的虚拟机 TVM 使用cell来表示持久存储中的所有数据结构，以及内存中的大部分数据结构。

Cells

Cell是一种 primitive 和数据结构，它通常由多达 10231023 个连续排列的比特和多达 44 个指向其他 cell 的引用(refs)组成。 循环引用在 TVM 中是被禁止的，因此无法通过 TVM 的机制创建循环引用。这意味着，单元（cells）可以被视为自身的 [四叉树][quadtree] 或 有向无环图（DAG）。 智能合约代码本身由树形结构的cell表示。

单元（Cells）和单元原语是以位（bit）为导向的，而非字节（byte）为导向的：TVM 将存储在单元中的数据视为最多 10231023 位的序列（字符串或流），而不是字节。 如有必要，合约可以自由使用 2121-bit 整数字段，并将其序列化为 TVM cell，从而使用更少的持久存储字节来表示相同的数据。

种类

虽然 TVM 类型 Cell 指的是所有cell，但存在不同的cell类型，其内存布局也各不相同。 前面 描述的通常被称为 普通 (或简单) cell—这是最简单、最常用的cell，只能包含数据。 绝大多数关于cell及其用法的描述、指南和 参考文献 都假定是普通cell。

其他类型的cell统称为 exotic cell (或特殊cell)。 它们有时会出现在 TON 区块链上的区块和其他数据结构的实际表示中。 它们的内存布局和用途与普通cell大不相同。

所有cell的种类 (或子类型) 都由 −1−1 和 255255之间的整数编码。 普通cell用 −1−1编码，特殊cell可用该范围内的任何其他整数编码。 奇异cell的子类型存储在其数据的前 88 位，这意味着有效的奇异cell总是至少有 88 个数据位。

TVM 目前支持以下exotic cell子类型：

• Pruned branch cell，子类型编码为 [size=1.21em]11 - 它们代表删除的cell子树。
• Library reference cell，子类型编码为 [size=1.21em]22 - 它们用于存储库，通常在 masterchain 上下文中使用。
• Merkle proof cell，子类型编码为 [size=1.21em]33 - 它们用于验证其他cell的树数据的某些部分是否属于完整树。
• Merkle update cell，子类型编码为 [size=1.21em]44 - 它们总是有两个引用，对这两个引用的行为类似于默克尔证明。
  . y7 F, x& w% R4 ]( P9 [

- l8 Z0 k8 W# c
' Z: A! u' @5 Z( x+ f6 m& f' \
* L) l, m7 i+ @0 z5 q3 bLevels

作为 [四叉树][quadtree]，每个单元格都有一个名为 level 的属性，它由 00 和 33之间的整数表示。 普通 cell的级别总是等于其所有引用级别的最大值。 也就是说，没有引用的普通 cell 的层级为 00。

Exotic cell有不同的规则来决定它们的层级，这些规则在TON Docs 的本页上有描述。

序列化

在通过网络传输 cell 或在磁盘上存储 cell 之前，必须对其进行序列化。 有几种常用格式，如标准 Cell 表示法和 BoC。

标准表示法

标准 Cell 表示法是 tvm.pdf 中首次描述的 cells 通用序列化格式。 它的算法以八进制（字节）序列表示cell，首先将称为描述符的第一个 22 字节序列化：

• 引用描述符（Refs descriptor）根据以下公式计算：[size=1.21em]r+8k+32lr+8k​+32l​，其中 [size=1.21em]rr 是 cell 中包含的引用数量（介于 [size=1.21em]00 和 [size=1.21em]44 之间），[size=1.21em]kk 是 cell 类型的标志（[size=1.21em]00 表示普通，[size=1.21em]11 表示特殊），[size=1.21em]ll 是 cell 的层级（介于 [size=1.21em]00 和 [size=1.21em]33 之间）。
• 位描述符（Bits descriptor）根据以下公式计算：[size=1.21em]⌊b8⌋+⌈b8⌉⌊8b​⌋+⌈8b​⌉，其中 [size=1.21em]bb 是 cell 中的位数（介于 [size=1.21em]00 和 [size=1.21em]10231023 之间）。
  1 }- H, @* Q" e. b7 f

然后，cell 本身的数据位被序列化为 ⌈b8⌉⌈8b​⌉ 88-bit octets（字节）。 如果 bb 不是 8 的倍数，则在数据位上附加一个二进制 11 和最多六个二进制 00s。

接下来， 22 字节存储了引用的深度，即Cell树根（当前Cell）和最深引用（包括它）之间的cells数。 例如，如果一个cell只包含一个引用而没有其他引用，则其深度为 11，而被引用cell的深度为 00。

最后，为每个参考cell存储其标准表示的 SHA-256 哈希值，每个参考cell占用 3232 字节，并递归重复上述算法。 请注意，不允许循环引用cell，因此递归总是以定义明确的方式结束。 请注意，不允许循环引用cell，因此递归总是以定义明确的方式结束。

如果我们要计算这个cell的标准表示的哈希值，就需要将上述步骤中的所有字节连接在一起，然后使用 SHA-256 哈希值进行散列。 如果我们要计算这个cell的标准表示的哈希值，就需要将上述步骤中的所有字节连接在一起，然后使用 SHA-256 哈希值进行散列。 这是TVM的HASHCU和HASHSU指令以及 Tact 的Cell.hash()和Slice.hash()函数背后的算法。

Bag of Cells

如 boc.tlb TL-B schema 所述，Bag of Cells（简称 BoC）是一种将cell序列化和去序列化为字节数组的格式。

在 TON Docs 中阅读有关 BoC 的更多信息：Bag of Cells。

不变性 (Immutability)

cell是只读和不可变的，但 TVM 中有两组主要的 ordinary cell操作指令：

• cell创建（或序列化）指令，用于根据先前保存的值和cell构建新cell；
• cell解析（或反序列化）指令，用于提取或加载之前通过序列化指令存储到cell中的数据。
  2 G# S& A! n9 M/ z" @; O; Q

此外，还有专门针对 exotic cell的指令来创建这些cell并期望它们的值。 此外，exotic cell 有专门的指令来创建它们并预期它们的值。不过，普通(ordinary) cell解析指令仍可用于 exotic cell，在这种情况下，它们会在反序列化尝试中被自动替换为 普通(ordinary) cell。

所有cell操作指令都需要将 Cell 类型的值转换为 Builder或 Slice类型，然后才能修改或检查这些cell。

Builders

Builder 是一种用于使用cell创建指令的cell操作基元。 它们就像cell一样不可改变，可以用以前保存的值和cell构建新的cell。 与cells不同，Builder类型的值只出现在TVM堆栈中，不能存储在持久存储中。 举例来说，这意味着类型为 Builder 的持久存储字段实际上是以cell的形式存储的。

Builder 类型表示部分组成的cell，为其定义了追加整数、其他cell、引用其他cell等快速操作：

• 核心库中的 Builder.storeUint()
• 核心库中的 Builder.storeInt()
• 核心库中的 Builder.storeBool()
• 核心库中的 Builder.storeSlice()
• 核心库中的 Builder.storeCoins()
• 核心库中的 Builder.storeAddress()
• 核心库中的 Builder.storeRef()
  

虽然您可以使用它们来手动构建 cell，但强烈建议使用[结构体][structs]：使用结构体构建cell。

Slices

Slice 是使用cell解析指令的cell操作基元。 与cell不同，它们是可变的，可以通过序列化指令提取或加载之前存储在cell中的数据。 此外，与cell不同，Slice 类型的值只出现在 TVM 堆栈中，不能存储在持久存储区中。 举例来说，这就意味着类型为 Slice 的持久存储字段实际上是以cell的形式存储的。

Slice 类型表示部分解析cell的剩余部分，或位于此类cell内并通过解析指令从中提取的值（子cell）：

• 核心库中的Slice.loadUint()
• 核心库中的Slice.loadInt()
• 核心库中的Slice.loadBool()
• 核心库中的Slice.loadBits()
• 核心库中的Slice.loadCoins()
• 核心库中的Slice.loadAddress()
• 核心库中的Slice.loadRef()
  

虽然您可以将它们用于cell的 手动解析，但强烈建议使用 [结构体][structs]：使用结构体解析cell。

序列化类型

与 Int类型的序列化选项类似，Cell、Builder 和Slice 在以下情况下也有不同的值编码方式：

• 作为合约和特性的存储变量，
• 以及 [Structs](/zh-cn/book/structs and-messages#structs) 和 [Messages](/zh-cn/book/structs and-messages#messages) 的字段。
  1. contract SerializationExample {
     $ b% q% r" W2 V% x% `
  2.     someCell: Cell as remaining;
     
  3.     someSlice: Slice as bytes32;
     
  4. 
     
  5.     // Constructor function,
     5 K: ?8 u. P& l! \* F3 j3 ]
  6.     // necessary for this example contract to compile
     
  7.     init() {
     $ ]! K& @7 F7 I5 C3 N- ]
  8.         self.someCell = emptyCell();
     
  9.         self.someSlice = beginCell().storeUint(42, 256).asSlice();
     ( v4 a7 J. r, z5 Z7 D
  10.     }
      # `& X7 m9 w% f, z8 q& ~1 |% W
  11. }

  复制代码
  remaining
  remaining 序列化选项可应用于 Cell、Builder和 Slice类型的值。
  它通过直接存储和加载cell值而不是作为引用来影响cell值的构建和解析过程。 它通过直接存储和加载cell值而不是作为引用来影响cell值的构建和解析过程。 与 cell操作指令 相似，指定 remaining 就像使用 Builder.storeSlice() 和 Slice.loadBits() 而不是 Builder.storeRef() 和 Slice.loadRef()，后者是默认使用的。
  此外，Tact 产生的 TL-B 表示也会发生变化：
  
  

1. contract SerializationExample {
   
2.     // By default
   
3.     cRef: Cell;    // ^cell in TL-B
   ; J6 d+ o' b+ a9 S
4.     bRef: Builder; // ^builder in TL-B
   , v: S6 `0 ]8 ?8 B0 D  F% E4 h
5.     sRef: Slice;   // ^slice in TL-B
   # N# W( X  }3 o# D
6. 
   
7.     // With `remaining`
   + }; Z$ X& ?# A* @  l7 r4 k
8.     cRem: Cell as remaining;    // remainder<cell> in TL-B
     v" l; w, l0 H6 X
9.     bRem: Builder as remaining; // remainder<builder> in TL-B
   
10.     sRem: Slice as remaining;   // remainder<slice> in TL-B
    
11. 
    
12.     // Constructor function,
    ) S. a3 [; k+ `" E  L
13.     // necessary for this example contract to compile
    ! n% ~+ F  x. y3 u2 a5 o  m. Q
14.     init() {
    
15.         self.cRef = emptyCell();
    
16.         self.bRef = beginCell();
    / z9 A+ N% B% }- k( \
17.         self.sRef = emptySlice();
    
18.         self.cRem = emptyCell();
    
19.         self.bRem = beginCell();
    + F/ K4 H8 b7 ?8 C" ?. e/ M
20.         self.sRem = emptySlice();
    ( v1 m- K7 X  H- l& g& F
21.     }
    
22. }

复制代码

2 A  K5 D) x& s1 [

其中，TL-B 语法中的 ^cell、^builder 和 ^slice 分别表示对 cell、builder和 slice值的引用、而 cell、builder 或 slice 的 remainder<…> 则表示给定值将直接存储为 Slice，而不是作为引用。

现在，举一个真实世界的例子，想象一下你需要注意到智能合约中的入站 jetton 传输并做出反应。 相应的 [信息][消息] 结构如下： 相应的 [信息][消息] 结构如下：

1. message(0x7362d09c) JettonTransferNotification {
   
2.     queryId: Int as uint64;             // arbitrary request number to prevent replay attacks
   - H: B# J$ c: {; ?( p, S3 _: z
3.     amount: Int as coins;               // amount of jettons transferred
   
4.     sender: Address;                    // address of the sender of the jettons
   
5.     forwardPayload: Slice as remaining; // optional custom payload
   ; L! T! O2 \6 S9 ^. j
6. }

复制代码

合同中的 receiver 应该是这样的：

1. receive(msg: JettonTransferNotification) {
   4 I3 ^2 `. ?( }
2.     // ... you do you ...
   3 W2 L# w. s4 ]. x2 O
3. }

复制代码

. z  n) R/ Y) H
* ~% C3 t! B0 G7 ?& m. f: w( W% c

收到 jetton 传输通知消息后，其cell体会被转换为 Slice，然后解析为 JettonTransferNotification 消息。在此过程结束时，forwardPayload 将包含原始信息cell的所有剩余数据。 在此过程结束时，forwardPayload 将包含原始信息cell的所有剩余数据。

在这里，将 forwardPayload: Slice as remaining 字段放在 JettonTransferNotification 消息中的任何其他位置都不会违反 jetton 标准。 这是因为 Tact 禁止在[Structs][结构]和[Messages][消息]的最后一个字段之外的任何字段中使用 as remaining，以防止滥用合同存储空间并减少 gas 消耗。

( o' B) ^5 V* Y# K7 t. f+ D

Using Structs

结构和[消息][messages]几乎就是活生生的TL-B 模式。 也就是说，它们本质上是用可维护、可验证和用户友好的 Tact 代码表达的TL-B 模式。 也就是说，它们本质上是用可维护、可验证和用户友好的 Tact 代码表达的TL-B 模式。

强烈建议使用它们及其 方法，如 Struct.toCell()和 [Struct.fromCell()][st-fc]，而不是手动构造和解析cell，因为这样可以得到更多声明性和不言自明的合约。

上文的手动解析示例可以使用Structs重新编写，如果愿意，还可以使用字段的描述性名称：

1. // First Struct
   
2. struct Showcase {
     l$ M  U9 N" I- ~( Y& q1 v4 z
3.     id: Int as uint8;
   
4.     someImportantNumber: Int as int8;
   
5.     isThatCool: Bool;
   
6.     payload: Slice;
   
7.     nanoToncoins: Int as coins;
     s0 t' ]) @  C5 c0 P
8.     wackyTacky: Address;
   
9.     jojoRef: Adventure; // another Struct
   
10. }
    
11. 
    
12. // Here it is
    
13. struct Adventure {
    
14.     bizarre: Bool = true;
    , m. u% n4 J' I# J8 _
15.     time: Bool = false;
    $ R2 |) @! G  o; w# k
16. }
    / S3 F( l# _, t7 d& `$ y/ S
17. 
    
18. fun example() {
    + y! ~% v' ^0 b" j( |
19.     // Basics
    
20.     let s = Showcase.fromCell(
    " S, v6 l/ x/ E
21.         Showcase{
    
22.             id: 7,
      q+ O  P* E$ C: ?
23.             someImportantNumber: 42,
    2 J3 C0 K. ^) d; I) ?6 l
24.             isThatCool: true,
    
25.             payload: emptySlice(),
    + j, `8 @* g! @$ D+ Q, b4 U: G, y/ \
26.             nanoToncoins: 1330 + 7,
    8 I1 m1 n2 p) x* T
27.             wackyTacky: myAddress(),
    
28.             jojoRef: Adventure{ bizarre: true, time: false },
    8 n6 v; ?# I% e3 c# O# r/ v8 q4 S/ i4 r& S
29.         }.toCell());
    
30.     s.isThatCool; // true
    
31. }

复制代码

" q/ C, C8 h/ `! _

2 U7 t+ `0 s1 J3 i3 ^% b5 U