ptbs

Sui プログラマブルトランザクションブロック（PTB）

MCP ツール： 環境で利用できる場合は、最新の回答を得るために Sui ドキュメント MCP サーバー（https://sui.mcp.kapa.ai）にも問い合わせてください。回答の検証や、これらのリファレンスファイルに記載されていない詳細の確認に使用してください。

PTB は、最大 1,024 個のコマンド（Move 呼び出し、コインの分割・統合、オブジェクトの転送、ベクターの構築、パッケージの公開・アップグレード）をまとめて順番に実行する、1 つの Sui トランザクションです。コマンドはアトミックに実行され（1 つのコマンドが失敗すると、ブロック全体が失敗します）、入力を共有し、結果を連鎖させます。Sui でトランザクションを実行する方法は PTB のみであり、「単一呼び出し」モードはありません。

このスキルは、目的別のリファレンスファイルを案内します。現在のタスクに関連するファイルだけを読み込んでください。

このスキルのすべてのパターンは、以下に基づいています。

• https://docs.sui.io/concepts/transactions/prog-txn-blocks
• https://docs.sui.io/develop/transactions/ptbs/building-ptb
• https://docs.sui.io/references/ptb-commands
• https://sdk.mystenlabs.com/sui/transactions/basics
• https://docs.sui.io/references/cli/client（CLI sui client ptb）

API、メソッドシグネチャ、エラーメッセージに確信が持てない場合は、回答する前に該当するページを取得してください。Ethereum、Solana、その他のチェーンを参考に推測したり、類推したりしないでください。PTB に直接対応するものはありません。

---

リファレンスファイル

fundamentals — PTB データモデル

パス： fundamentals.md 読み込む場面： PTB の概要を説明するとき、Input、Argument、NestedResult、GasCoin、所有・共有・不変・受信オブジェクトの参照、純粋入力の BCS ルール、コマンドの連鎖のセマンティクス、実行順序やアトミック性について説明するとき。 内容： PTB の構造、Input（CallArg）と ObjectArg のバリアント、純粋入力の型、Argument 列挙型、結果の連鎖、実行のセマンティクス（借用ルール、移動・コピー、ホットポテトのクリーク、トランザクション終了時の制約）、プロトコルの上限。

commands — コマンドリファレンス

パス： commands.md 読み込む場面： 特定のコマンド（MoveCall、SplitCoins、MergeCoins、TransferObjects、MakeMoveVec、Publish、Upgrade）を記述またはレビューするとき、あるいは引数の型の不一致や戻り値の形をデバッグするとき。 内容： 7 つの各コマンドのシグネチャ、引数のルール、戻り値の形、よくある落とし穴。

building — TypeScript SDK Transaction クラス

パス： building.md 読み込む場面： @mysten/sui/transactions を使って PTB を構築する TS/JS コードを記述するとき、ガスを設定するとき、ウォレット向けにビルドするとき、サービス間でシリアライズするとき、またはアプリ ↔ ウォレット ↔ スポンサー間で PTB を送るとき。 内容： Transaction API（tx.moveCall、tx.splitCoins、tx.mergeCoins、tx.transferObjects、tx.makeMoveVec、tx.publish、tx.upgrade、tx.balance、tx.coin、tx.add、tx.object、tx.pure、tx.gas、tx.setSender/setGasPrice/setGasBudget/setGasPayment/setGasOwner）、Inputs.*Ref ヘルパー、結果の分割代入、build({ onlyTransactionKind: true })、Transaction.from / fromKind、スポンサー付きトランザクションのフロー、署名と実行。

cli — CLI からの PTB の構築

パス： cli.md 読み込む場面： sui client ptb を使ってコマンドラインから PTB を構築するとき、TypeScript を使わずにトランザクションをスクリプト化するとき、CLI からコインを統合するとき、または CLI ベースのワークフローを説明するとき。 内容： sui client ptb の構文、コマンドの連鎖、一般的な CLI PTB のパターン（転送、コインの統合、Move 呼び出し）、ガス予算、実行前のプレビュー。

troubleshooting — よくあるエラー

パス： troubleshooting.md 読み込む場面： 失敗する PTB を診断するとき（ServerError、UnusedValueWithoutDrop、VMVerificationOrDeserializationError、No valid gas coins、InsufficientGas、共有オブジェクトの混雑、原因が分かりにくい「transaction failed」という出力など）。 内容： 各エラーカテゴリの Move/PTB レベルでの原因と、具体的な修正方法。

ルーティングガイド

タスク	読み込む内容
「PTB とは何ですか？」／概念の説明	fundamentals
TypeScript で新しい PTB を作成する	building + commands
CLI から新しい PTB を作成する	cli + commands
PTB の正確性を確認する	fundamentals + commands + building
特定のコマンドで型チェックに失敗する	commands
スポンサー付き／ガスレスのトランザクション	building
失敗する PTB のデバッグ	troubleshooting +（実行セマンティクスに関係する場合は fundamentals）
PTB 内のパッケージを公開またはアップグレードする	commands
サービス間（アプリ／ウォレット／スポンサー）で PTB のバイト列を構築する	building
CLI からコインを結合する、または単純な操作を行う	cli
コード全体のレビュー	すべてのリファレンスファイル

スキルの内容

重要な概念

• PTB がトランザクションです。 すべての Sui トランザクションは PTB です。単一の moveCall であっても、1 コマンドの PTB です。PTB を使わない実行経路はありません。
• 入力とコマンド。 inputs は外部から渡される値（オブジェクトおよび BCS エンコードされた「pure」バイト列）です。commands はそれらの入力と、ほかのコマンドの結果に対して処理を行います。コマンドは Argument enum を使って値を参照します：Input(i)、GasCoin、Result(i)、NestedResult(cmd, result)。
• 連結。 各コマンドは結果の配列を生成します。次のコマンドは、NestedResult(cmd, idx)、またはコマンドの戻り値がちょうど 1 つの場合は Result(cmd) を使って、任意の結果を受け取れます。TS SDK では、これを分割代入可能な値として扱えます：const [coin] = tx.splitCoins(tx.gas, [tx.pure.u64(100)]);。
• アトミック性。 コマンドは順番に実行されます。いずれかが失敗すると、ブロック全体がロールバックされ、部分的な効果は残りません。
• トランザクション終了時の制約。 実行中に生成された drop でない値は、すべて消費する必要があります（転送、破棄、または別のコマンドへの入力）。共有オブジェクトの有効な終了方法は、再共有または削除の 2 つだけです。転送も凍結もできません。ガスコインは所有者に返され、未使用のガスは返金されます。

ルール

1. transferObjects の場合を除き、tx.gas は参照で使用する必要があります。 ガスコインから所有済みの Coin<SUI> を取得するには、まず SplitCoins(tx.gas, [amount]) を使います。
2. 可能な場合は、ガス設定をウォレットに任せてください。 ユーザーのウォレットで署名するアプリコードでは、setGasBudget／setGasPrice／setGasPayment をハードコードしないでください。ウォレットがドライランを実行し、コインを適切に選択します。これらを設定するのは、バックエンドが署名するフローに限ります。
3. PTB をウォレットに渡すアプリコードでは、tx.build() ではなく await tx.toJSON() を使用してください。 ガス処理とコイン選択はウォレット自身が行う必要があります。アプリコードでバイト列を構築すると、その処理が先取りされてしまいます。
4. スポンサー付きフローでは Transaction.fromKind(kindBytes) を使用してください。 アプリで tx.build({ client, onlyTransactionKind: true }) を使って構築し、kind のみのバイト列をスポンサーサービスに送信します。そこで fromKind を使って再構築し、その後 setSender、setGasOwner、setGasPayment を設定します。検閲を避けるため、ユーザー（またはいずれかの当事者）が、完全に署名されたトランザクションをスポンサーサービスに戻すのではなく、フルノードに直接送信してください。
5. drop でない値はすべて消費する必要があります。 moveCall が不要な値を返す場合は、transferObjects（key + store を持つ場合）、public_transfer、またはデストラクターに渡してください。UnusedValueWithoutDrop は PTB レベルのエラーです。
6. 共有オブジェクトは転送、凍結、または値渡しで消費できません（読み取り専用として渡された場合、mutable: false）。 可変アクセスが必要な場合は、入力を構築する際に可変として指定してください。
7. Move 呼び出しから返される型は参照にはできません。 MoveCall の結果は値です。Move 関数が &T を返す場合、PTB から呼び出すことはできません。
8. 複数の戻り値がある Move 呼び出しでは、分割代入または配列インデックスを使用してください。 const [a, b] = tx.moveCall(...) または const r = tx.moveCall(...); r[0]; r[1]; とします。戻り値が 1 つの場合の形式だと決めつけないでください。
9. 不明な点がある場合は、ドキュメントを参照してください。 正式な情報源は上記のとおりです。レガシーの /develop/transactions/ptbs/* URL も引き続き表示できますが、/concepts/transactions/prog-txn-blocks と /guides/developer/sui-101/building-ptb を優先してください。

よくある間違い

• 型を指定せずに tx.pure(value) を呼び出す。 型指定のない純粋値は、入力の解決時に失敗します。型付きヘルパーの tx.pure.u64(n)、tx.pure.address(addr)、tx.pure.string(s)、または汎用形式の tx.pure('u64', n) を使用してください。
• tx.object(...) を使わずに、文字列のオブジェクト ID を moveCall の引数に渡す。 型が混在する引数では、明示的に tx.object(id) でラップする必要があります。そうしないと、SDK は純粋値とオブジェクトを区別できません。
• 共有オブジェクトを転送またはフリーズする。 共有オブジェクトは転送もフリーズもできませんが、削除はできます。PTB における共有オブジェクトの有効な終了方法は、再共有または削除の 2 つです。共有オブジェクトを transferObjects に含めないでください。共有オブジェクトを値として消費すると、そのホットポテトクリークは恒久的に「ホット」とマークされ、同じクリーク内の絡み合った値に対する、後続の非公開 entry 呼び出しがブロックされる点に注意してください。
• オフラインでビルドする際に setSender を忘れる。 送信者を設定する署名者を使わずに tx.build() を呼び出すと、送信者フィールドが空のままになり、ビルドに失敗します。
• 複数の値を返す moveCall の結果を単一の値として扱う。 戻り値はベクターです。インデックスでアクセスするか、分割代入してください。
• PTB から汎用型に対して transfer::transfer ／ transfer::share_object を使う。 これらのエントリには、モジュール内でのみ使用可能な型パラメーターが必要です。PTB からは、型に store が必要な transfer::public_transfer ／ transfer::public_share_object を使用してください。
• ガス予算を厳しく設定しすぎる。 予算を超過したトランザクションは中止されますが、ガスコインには引き続き課金されます。SDK のドライランに基づく自動予算設定を優先してください。
• 実行ステータスを確認しない。 トランザクションはバリデーターに受け入れられても、Move レベルで失敗することがあります（アサーション、ガス不足など）。操作が成功したと判断する前に、必ず result.$kind !== 'FailedTransaction' を確認してください。トランザクションダイジェストだけでは、エフェクトが適用されたことを意味しません。
• アプリのコードでループして N 件の個別トランザクションを送信する。 1 つの PTB にまとめてください（最大 1,024 個の操作）。1 つの PTB にまとめると、コストが低く、アトミックに実行されます。