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 - 它们总是有两个引用，对这两个引用的行为类似于默克尔证明。
  ; F8 G1 C" G* M

! h- V1 x4 O  F' `; I) W" {
Levels

作为 [四叉树][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 之间）。
  

然后，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中的数据。
  , J" t0 U) B/ @  J: \3 V( J' [

此外，还有专门针对 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()
  ! `2 `7 R5 s# {- h+ t. q$ K

虽然您可以使用它们来手动构建 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 {
     . l# S' i0 n) @
  2.     someCell: Cell as remaining;
     * t: o- U" B2 |. h  X. U( s. w* S
  3.     someSlice: Slice as bytes32;
     
  4. 
     : G3 Z# }. ?. }/ J, H
  5.     // Constructor function,
     
  6.     // necessary for this example contract to compile
     
  7.     init() {
     
  8.         self.someCell = emptyCell();
     : K1 ^3 A1 b0 N5 l! f4 J$ i$ F
  9.         self.someSlice = beginCell().storeUint(42, 256).asSlice();
     
  10.     }
      
  11. }

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

1. contract SerializationExample {
     ]% c/ i1 H8 h1 ^! T; |- R
2.     // By default
   
3.     cRef: Cell;    // ^cell in TL-B
   7 `; f) h5 I; u, y
4.     bRef: Builder; // ^builder in TL-B
   
5.     sRef: Slice;   // ^slice in TL-B
   
6. 
   
7.     // With `remaining`
   
8.     cRem: Cell as remaining;    // remainder<cell> in TL-B
   
9.     bRem: Builder as remaining; // remainder<builder> in TL-B
   
10.     sRem: Slice as remaining;   // remainder<slice> in TL-B
    ; V2 a" p- r0 N: e$ T
11. 
      c  [" v) b$ x
12.     // Constructor function,
    
13.     // necessary for this example contract to compile
    
14.     init() {
    
15.         self.cRef = emptyCell();
    
16.         self.bRef = beginCell();
    8 O6 z& a: L( V- W
17.         self.sRef = emptySlice();
    1 C" t- F+ m4 D! W- v
18.         self.cRem = emptyCell();
    
19.         self.bRem = beginCell();
    9 f, X1 R5 j. y/ a5 {
20.         self.sRem = emptySlice();
    2 i  `+ n: T5 ~& ]
21.     }
    
22. }

复制代码

其中，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
   . m" Y' k7 d; h" p2 c  u
3.     amount: Int as coins;               // amount of jettons transferred
   
4.     sender: Address;                    // address of the sender of the jettons
   6 H6 Z) p$ p) ?. H
5.     forwardPayload: Slice as remaining; // optional custom payload
   
6. }

复制代码

# F, M8 S+ v' W

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

* s+ _% J) S1 h( G" C: ]+ N

1. receive(msg: JettonTransferNotification) {
   1 |7 e5 G% r& K% d7 o
2.     // ... you do you ...
   
3. }

复制代码

& z% q2 L9 o2 v+ d/ d# K

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

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

1 i$ R8 V, }$ c$ q* ^6 u

Using Structs

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

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

  G% H" h1 D1 P% S- y# o( U4 Y. u  X

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

1. // First Struct
   
2. struct Showcase {
   ( M/ v: M+ l" j5 j
3.     id: Int as uint8;
   
4.     someImportantNumber: Int as int8;
   * ?* w7 t( n$ a8 R
5.     isThatCool: Bool;
   
6.     payload: Slice;
     l9 n* ^( B6 z3 i% k" H
7.     nanoToncoins: Int as coins;
   
8.     wackyTacky: Address;
   6 L/ Z, J. e/ n
9.     jojoRef: Adventure; // another Struct
   1 r/ `* a3 a% r4 W, p
10. }
    / w3 Z; `3 [9 |, D4 B
11. 
    
12. // Here it is
    
13. struct Adventure {
    % X2 a8 }5 z  h. b' A
14.     bizarre: Bool = true;
    ( V* h% n% }( ?1 ~* A
15.     time: Bool = false;
    
16. }
    % k* C4 F( ?  E- r) P5 V& \2 p  R
17. 
    6 b; M' M0 H0 K- v4 Y0 \( l6 H, G9 M
18. fun example() {
    . M& H% {) a: o# R- P4 n- R
19.     // Basics
    % H4 @2 r3 x4 Z8 l
20.     let s = Showcase.fromCell(
    # _$ a, X9 _: R
21.         Showcase{
    
22.             id: 7,
    
23.             someImportantNumber: 42,
    
24.             isThatCool: true,
    
25.             payload: emptySlice(),
    
26.             nanoToncoins: 1330 + 7,
    ) P' ~0 [$ e* O: T1 n, Y
27.             wackyTacky: myAddress(),
    : e1 w" H0 y) O5 V' ^4 p) e
28.             jojoRef: Adventure{ bizarre: true, time: false },
    + i2 C1 I- h2 u) g
29.         }.toCell());
    9 Z6 f+ ]. ~4 z8 Q: d5 h# k
30.     s.isThatCool; // true
    
31. }

复制代码

  D+ Y/ t, X* @0 O9 h