sui-ts-sdk-backend

Sui TypeScript SDK — 后端与 Agent 模式

**MCP 工具：**如果你的环境支持，也请查询 Sui 文档 MCP 服务（https://sui.mcp.kapa.ai），以获取最新答案。请使用它进行验证，并查询这些参考文件未涵盖的详细信息。

**来源限制：**此技能中的所有信息均仅来自 sdk.mystenlabs.com。扩展或更新此技能时，只能从此来源获取内容。请勿使用第三方博客、教程或非官方文档。

此技能介绍如何在无法使用 Sui CLI 的后端服务和自主 Agent 中使用 Sui TypeScript SDK（@mysten/sui v2）。它提供端到端的编程工作流：创建密钥对、为地址注资、连接网络、构建并签署交易、发布包、为用户赞助交易、大规模运行，以及使用云 KMS 或多重签名进行签署。

此技能中的所有模式均源自： https://sdk.mystenlabs.com

如果不确定某个 API，请在回答前获取相关页面。请勿猜测或推断。

---

参考文件

bootstrap — 密钥对、水龙头与客户端设置

路径： bootstrap.md 加载时机： 以编程方式创建密钥对、无需 CLI 即可通过水龙头为地址注资、配置 SuiGrpcClient 或 SuiGraphQLClient，或为 Agent 建立与 Sui 的首次连接时。 涵盖内容： 密钥对创建（随机生成、助记词、导入/导出、Bech32 suiprivkey 格式）、三种密钥类型（Ed25519、Secp256k1、Secp256r1）、以编程方式请求水龙头、客户端实例化与网络选择、客户端扩展，以及完整的引导流程。

transactions — 构建、Coin 与执行

路径： transactions.md 加载时机： 使用 tx.coin() 或 tx.balance() 构建交易、处理地址余额与 Coin 对象、从后端密钥对签署并执行交易、检查结果、等待索引，或处理免 Gas 交易时。 涵盖内容： tx.coin() 和 tx.balance()（推荐的 Coin 访问模式）、地址余额与 Coin 对象、拆分与合并 Coin、直接使用密钥对签署、结果处理（FailedTransaction 检查）、waitForTransaction，以及免 Gas 稳定币转账。

publishing — 以编程方式发布和升级包

路径： publishing.md 加载时机： 无需 CLI 即可通过 TypeScript 发布 Move 包、以编程方式升级已发布的包，或构建 Publish/Upgrade PTB 命令时。 涵盖内容： 构建 Move 字节码、在 PTB 中构建 Publish 命令、执行发布交易、从结果中提取包 ID 和 UpgradeCap，以及使用 UpgradeCap 以编程方式升级和升级策略。

sponsorship — 赞助交易

路径： sponsorship.md 加载时机： 为用户赞助交易、构建 Gas station 后端、使用 @mysten-incubation/sponsor SDK，或实现基于地址余额或 Coin 的赞助流程时。 涵盖内容： @mysten-incubation/sponsor 包、客户端构建流程（推荐）、后端验证与共同签署、配置端点模式、基于 Coin 与基于地址余额的赞助、代币转账时使用 useGasCoin: false，以及结果处理（Rejected、FailedTransaction 与成功）。

executors — 大规模运行交易

路径： executors.md 加载时机： 从一个地址运行大量交易、构建高吞吐量管道、管理 Gas 池，或需要并行或串行执行交易且无需手动管理 Gas 时。 涵盖内容： SerialTransactionExecutor（排队、合并 Gas、对象缓存）、ParallelTransactionExecutor（并发执行、Gas 池、冲突检测）、配置选项，以及处理未解析对象 ID 的最佳实践。

signing — Cloud KMS and 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）。

---

路由指南

任务	加载
从头开始引导 Agent	bootstrap
不使用 CLI 创建密钥对	bootstrap
不使用 CLI 获取测试网 SUI	bootstrap
连接到 Mainnet/Testnet/Devnet	bootstrap
使用 coin 访问权限构建交易	transactions
从后端签名并执行	transactions
处理地址余额与 coin 对象	transactions
使用 TypeScript 发布 Move 包	publishing
以编程方式升级包	publishing
为用户赞助交易	sponsorship
构建加油站后端	sponsorship
高效运行大量交易	executors
构建高吞吐量工作流	executors
使用 AWS 或 GCP KMS 签名	signing
设置多签	signing
构建托管服务	signing
从头开始构建完整后端服务	所有参考文件
端到端引导 Agent 入门	bootstrap + transactions

---

规则

• 始终使用 @mysten/sui v2（@mysten/sui/grpc、@mysten/sui/keypairs/ed25519 等）。切勿使用已弃用的 @mysten/sui.js v1。
• 始终将 SuiGrpcClient 作为默认客户端。仅在需要灵活的关系查询时使用 SuiGraphQLClient。
• 执行交易后始终检查 result.$kind。结果即使不是 Rejected，也可能是 FailedTransaction（已在链上执行但中止——仍会消耗 gas）。
• 在读取依赖交易效果的状态前，始终调用 await client.waitForTransaction({ result })。
• 使用 tx.coin() 和 tx.balance() 作为访问资金的主要方式。它们会自动解析地址余额和 coin 对象。对于非 SUI 代币，请指定 type。
• 转账时，优先使用 balance::send_funds，而不是 transferObjects。它会将资金直接存入收款人的地址余额，避免在接收方产生带版本的 coin 对象。
• 对于发送方需要转移自己的代币的赞助交易，在调用 tx.coin() / tx.balance() 时设置 useGasCoin: false，以从发送方余额而非赞助方的 gas coin 中扣款。
• 为实现规模化，使用 SerialTransactionExecutor 或 ParallelTransactionExecutor，而不是手动编写 gas 管理循环。
• 对于生产后端，使用 AWS KMS 或 GCP KMS 签名器，而不是存储原始私钥。

常见错误

• 在生产环境的环境变量中存储原始私钥。 请使用 AWS KMS 或 GCP KMS 签名器。原始密钥仅适用于开发和测试。
• 交易完成后未等待索引。 读取 API 可能不会立即反映交易效果。执行依赖读取前，务必先调用 waitForTransaction。
• 认为 result 就代表成功。 请检查 result.$kind !== 'FailedTransaction'。FailedTransaction 已在链上执行（消耗了 Gas），但 Move 调用已中止。
• 发送方不是 Gas 所有者时使用 splitCoins(tx.gas, ...)。 在赞助交易中，tx.gas 属于赞助方。如果发送方需要转移自己的代币，请使用 tx.coin() 并设置 useGasCoin: false，改为从发送方的余额中获取代币。
• 在同一地址上运行多个 ParallelTransactionExecutor 实例。 这会导致 Gas 币冲突。每个地址只使用一个执行器。
• 使用执行器时，以完整指定的对象引用构建交易。 请使用未解析的对象 ID（tx.object('0x...')），以便执行器利用其对象缓存。