tolk

Tolk

使用此技能构建可用于生产环境的 Tolk 合约，确保其具备类型约束、便于审计，并兼容 TON 消息和存储约定。

操作规则

• 优先采用当前仓库的框架和命令。在引入新工具前，先检查项目布局。
• 明确二进制布局：字段顺序、固定整数位宽、引用、可选字段、消息操作码、getter 返回形状、发送模式和反弹行为。
• 优先使用 Tolk 的类型系统，而不是手动操作 slice/builder：struct、类型化 cell、自定义序列化器、联合类型分派、延迟加载、类型化 map 和 createMessage。
• 将低级 cell/dict 代码限定在清晰的边界内，并立即用类型化别名、struct、map 或辅助方法封装。
• 以官方 TON 文档为准。先从 https://docs.ton.org/llms.txt 开始，然后仅加载 https://docs.ton.org/tolk/ 下与任务相关的页面，以及 TON 基础知识、合约开发和标准相关页面。
• 完成前，说明构建了什么、参考了哪些文档或标准，以及确切的构建/测试结果或阻碍。

工作流

1. 确定合约接口。

   • 列出标准、入站消息、出站消息、getter、存储字段、管理员角色、费用假设和部署行为。
   • 如果要实现 TON 标准，请先查阅相关标准文档，再选择操作码或 getter 名称。

2. 先设计 schema，再实现行为。

   • 将持久化数据放在 storage.tolk 中。
   • 将消息体、带操作码前缀的 struct、联合类型和共享载荷类型放在 messages.tolk 中。
   • 将错误常量或枚举放在 errors.tolk 中。
   • 入口文件应专注于验证、状态转换、发送和 getter。

3. 实现类型化入口。

   • 对内部且未反弹的消息，使用 fun onInternalMessage(in: InMessage)。
   • 将已知消息解析为 lazy AllowedMessage.fromSlice(in.body)，并使用 match 分派。
   • 明确选择未知消息的处理策略，常见做法是“忽略空充值，否则抛出 0xFFFF”。
   • 如果出站消息可能反弹且需要恢复状态，请使用 fun onBouncedMessage(in: InMessageBounced)。
   • 仅在外部流程中使用 fun onExternalMessage(inMsg: slice)，并且只在验证通过后接受 gas。

4. 实现存储和出站操作。

   • 使用 Storage.load() 和 Storage.save() 辅助方法封装 contract.getData() 和 contract.setData(...)。
   • 在 getter 和读取路径中使用 lazy Storage.load()。
   • 使用 createMessage({ ... }) 组合出站消息，并通过 .send(SEND_MODE_...) 发送。
   • 如果合约会部署其他合约，请将 StateInit 或 AutoDeployAddress 的构造提取到辅助方法中。

5. 通过有针对性的测试进行验证。

   • 覆盖部署、已接受的消息、被拒绝的消息、getter 值、发出的出站消息、反弹、对费用敏感的路径、重放保护、map 遍历和大型载荷。
   • 使用仓库现有的测试框架。如果存在多个框架，优先使用相邻合约已采用的框架。

必需模式

• 对带操作码的消息体使用 struct (0x...) MessageName { ... }。
• 对已知的入站消息类别使用 type AllowedMessage = A | B | C 和 match。
• 对类型化引用使用 Cell<T>；仅当 cell 内容有意保持不透明时才使用 cell。
• 对真正的剩余载荷使用 RemainingBitsAndRefs。
• 在序列化 struct 中使用固定宽度、可序列化的数值类型（uint32、uint64、int32、coins 等）。
• 使用 map<K, V> 和 MapLookupResult.isFound；不要将 map 查询结果当作可空值查询。
• 多值响应使用 getter 回复 struct；标准定义了 getter 名称时，应保留标准名称。
• 使用方法（fun Type.method(self)）避免全局名称冲突，并将行为放在靠近数据结构的位置。
• 除非实测发现有约束需要，否则避免使用汇编函数和微优化。

参考资料

• 实现或审查合约代码时，请打开 references/idiomatic-patterns.md。
• 完成合约变更或选择构建／测试命令前，请打开 references/development-checklist.md。

主要参考文档：

• https://docs.ton.org/tolk/overview
• https://docs.ton.org/tolk/idioms-conventions
• https://docs.ton.org/tolk/features/message-handling
• https://docs.ton.org/tolk/features/auto-serialization
• https://docs.ton.org/tolk/features/message-sending
• https://docs.ton.org/tolk/features/contract-storage
• https://docs.ton.org/tolk/features/contract-getters
• https://docs.ton.org/tolk/types/maps
• https://docs.ton.org/tolk/examples

完成门槛

除非以下条件均已满足或明确受阻，否则不要将任务标记为完成：

• 在可行的情况下，使用有类型的 Tolk 构造来建模存储、消息、getter 和出站操作。
• 对任何底层序列化、原始 cell、手动 refs 或手动字典进行局部封装并说明其合理性。
• 明确说明未知消息、bounce、费用和部署行为。
• 适用时，根据相关 TON 标准文档核对标准操作码、getter 和返回结构。
• 使用项目工具运行构建／测试，或报告确切的阻碍。