tolk

Tolk

型付けされ、監査可能で、TON のメッセージおよびストレージの規約に準拠した、本番品質の Tolk コントラクトを構築するには、このスキルを使用してください。

運用ルール

• 現在のリポジトリで採用されているフレームワークとコマンドを優先してください。新しいツールを導入する前に、プロジェクトの構成を確認してください。
• バイナリレイアウトを明示してください。フィールドの順序、整数の固定ビット幅、参照、オプションフィールド、メッセージのオペコード、getter の戻り値の形式、送信モード、バウンス時の動作を明確にします。
• 手動での slice／builder 操作より、Tolk の型システムを優先してください。struct、型付きセル、カスタムシリアライザー、union のディスパッチ、遅延読み込み、型付きマップ、createMessage を活用します。
• 低レベルのセル／dict 操作は、境界が明確な箇所に限定してください。すぐに型付きエイリアス、struct、マップ、またはヘルパーメソッドでラップします。
• 公式 TON Docs を信頼できる情報源として扱ってください。https://docs.ton.org/llms.txt から始め、https://docs.ton.org/tolk/、TON の基礎、コントラクト開発、標準に関する関連ページのみを読み込みます。
• 作業を終える前に、実装した内容、作業の指針としたドキュメントまたは標準、正確なビルド／テスト結果、あるいは阻害要因を報告してください。

ワークフロー

1. コントラクトの対象範囲を特定します。

   • 標準、受信メッセージ、送信メッセージ、getter、ストレージフィールド、管理者ロール、手数料の前提、デプロイ時の動作を列挙します。
   • TON 標準を実装する場合は、オペコードや getter 名を決める前に、該当する標準のドキュメントを確認します。

2. 振る舞いより先にスキーマを設計します。

   • 永続データは storage.tolk に配置します。
   • メッセージ本文、オペコード付き struct、union 型、共有ペイロード型は messages.tolk に配置します。
   • エラー定数または enum は errors.tolk に配置します。
   • エントリーポイントのファイルには、検証、状態遷移、送信、getter に関する処理のみを記述します。

3. 型付きエントリーポイントを実装します。

   • バウンスされていない内部メッセージには、fun onInternalMessage(in: InMessage) を使用します。
   • 既知のメッセージを lazy AllowedMessage.fromSlice(in.body) として解析し、match でディスパッチします。
   • 不明なメッセージに対するポリシーを明示的に選択します。一般的な選択肢は「空のトップアップは無視し、それ以外は 0xFFFF をスローする」です。
   • 送信メッセージがバウンスする可能性があり、状態の復元が必要な場合は、fun onBouncedMessage(in: InMessageBounced) を使用します。
   • 外部フローに限り fun onExternalMessage(inMsg: slice) を使用し、検証後にのみガスを受け入れます。

4. ストレージと送信アクションを実装します。

   • contract.getData() と contract.setData(...) を囲むヘルパーとして、Storage.load() と Storage.save() を使用します。
   • getter と読み取りパスでは、lazy Storage.load() を使用します。
   • createMessage({ ... }) で送信メッセージを組み立て、.send(SEND_MODE_...) で送信します。
   • コントラクトが別のコントラクトをデプロイする場合は、StateInit または AutoDeployAddress の構築をヘルパーメソッドに切り出します。

5. 対象を絞ったテストで検証します。

   • デプロイ、受理されるメッセージ、拒否されるメッセージ、getter の値、送信メッセージ、バウンス、手数料の影響を受ける経路、リプレイ防止、マップの反復、大きなペイロードを網羅します。
   • リポジトリで既に使用されているテストフレームワークを使用します。複数のフレームワークがある場合は、近接するコントラクトで使われているものを優先します。

必須パターン

• オペコードを含むメッセージ本文には、struct (0x...) MessageName { ... } を使用します。
• 既知の受信メッセージ群には type AllowedMessage = A | B | C と match を使用します。
• 型付き参照には Cell<T> を使用し、セルの内容を意図的に不透明にする場合に限り cell を使用します。
• 真の残余ペイロードには RemainingBitsAndRefs を使用します。
• シリアライズする struct 内では、固定幅のシリアライズ可能な数値型（uint32、uint64、int32、coins など）を使用します。
• map<K, V> と MapLookupResult.isFound を使用します。マップの検索結果を nullable な値として扱わないでください。
• 複数値を返す応答には 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 構文でモデル化されています。
• 低レベルのシリアライズ、raw cell、手動参照、手動辞書の使用箇所が限定され、その理由が説明されています。
• 未知のメッセージ、バウンス、手数料、デプロイの動作が明示されています。
• 標準オペコード／ゲッター／戻り値の形式が、該当する場合に関連する TON 標準ドキュメントと照合されています。
• プロジェクトのツールを使用してビルド／テストが実行されているか、実行を妨げている正確な要因が報告されています。