sui-ts-sdk-backend

Sui TypeScript SDK — バックエンドとエージェントのパターン

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

ソースの制約： このスキルの情報は、すべて sdk.mystenlabs.com のみを情報源としています。このスキルを拡張または更新する場合は、この情報源のみを参照してください。サードパーティのブログ、チュートリアル、非公式ドキュメントは使用しないでください。

このスキルでは、Sui CLI を使用できないバックエンドサービスや自律型エージェントで、Sui TypeScript SDK（@mysten/sui v2）を使用する方法を説明します。キーペアの作成、アドレスへの資金の追加、ネットワークへの接続、トランザクションの構築と署名、パッケージの公開、ユーザーに代わるトランザクションのスポンサー、スケールに応じた実行、クラウド KMS またはマルチシグでの署名まで、エンドツーエンドのプログラムによるワークフローを提供します。

このスキルのすべてのパターンは、次の情報源から導き出されています。 https://sdk.mystenlabs.com

API が不明な場合は、回答する前に該当するページを取得してください。推測したり、情報を拡張解釈したりしないでください。

---

リファレンスファイル

bootstrap — キーペア、Faucet、クライアントのセットアップ

パス： bootstrap.md 次の場合に読み込んでください： プログラムでキーペアを作成する場合、CLI を使わずに Faucet からアドレスに資金を追加する場合、SuiGrpcClient または SuiGraphQLClient を設定する場合、あるいはエージェントの Sui への初回接続をセットアップする場合。 内容： キーペアの作成（ランダム、ニーモニック、インポート／エクスポート、Bech32 suiprivkey 形式）、3 種類のキータイプ（Ed25519、Secp256k1、Secp256r1）、プログラムによる Faucet リクエスト、クライアントのインスタンス化とネットワークの選択、クライアント拡張機能、完全なブートストラップ手順。

transactions — トランザクション、コイン、実行の構築

パス： transactions.md 次の場合に読み込んでください： tx.coin() または tx.balance() でトランザクションを構築する場合、アドレス残高とコインオブジェクトを扱う場合、バックエンドのキーペアで署名して実行する場合、結果を確認する場合、インデックス作成を待つ場合、またはガス代不要のトランザクションを扱う場合。 内容： tx.coin() と tx.balance()（推奨されるコインアクセスパターン）、アドレス残高とコインオブジェクト、コインの分割と結合、キーペアによる直接署名、結果の処理（FailedTransaction の確認）、waitForTransaction、ガス代不要のステーブルコイン送金。

publishing — プログラムによるパッケージの公開とアップグレード

パス： publishing.md 次の場合に読み込んでください： CLI を使わずに TypeScript から Move パッケージを公開する場合、公開済みのパッケージをプログラムでアップグレードする場合、または Publish／Upgrade PTB コマンドを構築する場合。 内容： Move バイトコードのビルド、PTB での Publish コマンドの構築、公開トランザクションの実行、結果からのパッケージ ID と UpgradeCap の抽出、UpgradeCap を使用したプログラムによるアップグレード、アップグレードポリシー。

sponsorship — スポンサー付きトランザクション

パス： sponsorship.md 次の場合に読み込んでください： ユーザーのトランザクションをスポンサーする場合、ガスステーションのバックエンドを構築する場合、@mysten-incubation/sponsor SDK を使用する場合、またはアドレス残高ベースやコインベースのスポンサーシップフローを実装する場合。 内容： @mysten-incubation/sponsor パッケージ、クライアントで構築するフロー（推奨）、バックエンドでの検証と共同署名、設定エンドポイントのパターン、コインベースとアドレス残高ベースのスポンサーシップ、トークン送金での useGasCoin: false、結果の処理（Rejected、FailedTransaction、成功）。

executors — トランザクションをスケールに応じて実行

パス： executors.md 次の場合に読み込んでください： 1 つのアドレスから多数のトランザクションを実行する場合、高スループットのパイプラインを構築する場合、ガスプールを管理する場合、または手動でガスを管理せずにトランザクションを並列または直列に実行する必要がある場合。 内容： SerialTransactionExecutor（キューイング、ガスの結合、オブジェクトのキャッシュ）、ParallelTransactionExecutor（並行実行、ガスプール、競合検出）、設定オプション、未解決のオブジェクト ID に関するベストプラクティス。

signing — Cloud KMS と Multisig

パス： signing.md 読み込むタイミング： AWS KMS または GCP KMS で署名するとき、マルチシグウォレットを設定するとき、部分署名を組み合わせるとき、鍵ペアの種類（Ed25519 + zkLogin + passkey）を混在させるとき、またはカストディ／署名サービスを構築するとき。 内容： Signer インターフェース（すべての署名方式で共通）、AWS KMS 署名方式（@mysten/aws-kms-signer）、GCP KMS 署名方式（@mysten/gcp-kms-signer）、MultiSigPublicKey の設定（しきい値、重み）、MultiSigSigner、部分署名の組み合わせ、ハイブリッドマルチシグ（鍵ペア + zkLogin + passkey）。

---

ルーティングガイド

タスク	読み込むもの
エージェントをゼロからセットアップする	bootstrap
CLI を使わずに鍵ペアを作成する	bootstrap
CLI を使わずにテストネットの SUI を入手する	bootstrap
Mainnet／Testnet／Devnet に接続する	bootstrap
コインにアクセスするトランザクションを構築する	transactions
バックエンドから署名して実行する	transactions
アドレス残高とコインオブジェクトを扱う	transactions
TypeScript から Move パッケージを公開する	publishing
プログラムからパッケージをアップグレードする	publishing
ユーザーのトランザクションをスポンサーする	sponsorship
ガスステーションのバックエンドを構築する	sponsorship
多数のトランザクションを効率的に実行する	executors
高スループットのパイプラインを構築する	executors
AWS または GCP KMS で署名する	signing
マルチシグを設定する	signing
カストディサービスを構築する	signing
バックエンドサービスをゼロから構築する	すべてのリファレンスファイル
エージェントのオンボーディングを最初から最後まで行う	bootstrap + transactions

---

ルール

• 常に @mysten/sui v2（@mysten/sui/grpc、@mysten/sui/keypairs/ed25519 など）を使用してください。非推奨の @mysten/sui.js v1 は使用しないでください。
• デフォルトのクライアントとして常に SuiGrpcClient を使用してください。柔軟なリレーショナルクエリが必要な場合に限り、SuiGraphQLClient を使用してください。
• トランザクションの実行後は、必ず result.$kind を確認してください。Rejected 以外の結果でも、FailedTransaction（オンチェーンで実行されたものの、中断された状態。ガスは消費されます）である可能性があります。
• トランザクションの効果に依存する状態を読み取る前に、必ず await client.waitForTransaction({ result }) を呼び出してください。
• 資金へのアクセスには、主な手段として tx.coin() と tx.balance() を使用してください。これらはアドレス残高とコインオブジェクトの両方から自動的に解決します。SUI 以外のトークンには type を指定してください。
• 送金には transferObjects よりも balance::send_funds を優先してください。受取側にバージョン付きコインオブジェクトが残らないよう、受取人のアドレス残高に直接入金します。
• 送信者自身のトークンを送金する必要があるスポンサードトランザクションでは、tx.coin()／tx.balance() の呼び出しで useGasCoin: false を設定し、スポンサーのガスコインではなく送信者の残高から資金を取得してください。
• 大規模な処理には、手動のガス管理ループではなく SerialTransactionExecutor または ParallelTransactionExecutor を使用してください。
• 本番環境のバックエンドでは、生の秘密鍵を保存する代わりに AWS KMS または GCP KMS の署名方式を使用してください。

よくある間違い

• 本番環境で秘密鍵をそのまま環境変数に保存する。 AWS KMS または GCP KMS の署名機能を使用してください。生の鍵を使用できるのは、開発やテストの場合のみです。
• トランザクション後のインデックス作成を待たない。 読み取り API には、トランザクションの効果がすぐに反映されない場合があります。依存する読み取りを行う前に、必ず waitForTransaction を呼び出してください。
• result が成功を意味すると決めつける。 result.$kind !== 'FailedTransaction' を確認してください。FailedTransaction はオンチェーンで実行済み（ガスを消費済み）ですが、Move の呼び出しが中断されたことを示します。
• 送信者がガスの所有者ではない場合に、splitCoins(tx.gas, ...) を使用する。 スポンサー付きトランザクションでは、tx.gas はスポンサーに属します。送信者自身のトークンを送信する必要がある場合は、useGasCoin: false を指定して tx.coin() を使用し、送信者の残高から取得してください。
• 同じアドレスで複数の ParallelTransactionExecutor インスタンスを実行する。 これにより、ガスコインの競合が発生します。アドレスごとに単一のエグゼキューターを使用してください。
• エグゼキューターを使用する際に、オブジェクト参照を完全に指定してトランザクションを構築する。 解決前のオブジェクト ID（tx.object('0x...')）を使用すると、エグゼキューターがオブジェクトキャッシュを活用できます。