use-ts-sdk

使用 TypeScript SDK（协调器）

用途

协调 @aptos-labs/ts-sdk 在 Aptos dApp 中的集成。对于特定任务，转交给相应的细分技能。对于组合任务（例如“为我构建一个完整的全栈 dApp”），请遵循以下工作流。

核心规则

1. 始终使用 @aptos-labs/ts-sdk（当前官方 SDK，而非已弃用的 aptos 包）
2. 绝不要在源代码或前端代码包中硬编码私钥
3. 绝不要在客户端代码或日志中暴露私钥
4. 绝不要将私钥存储在浏览器可访问的环境变量中（仅将 VITE_ 前缀用于公开配置）
5. 始终仅在服务端脚本中使用 process.env 从环境变量加载私钥

重要：样板模板

如果项目是通过 npx create-aptos-dapp（样板模板）搭建的，钱包适配器和 SDK 已经配置完成。 编写新代码前，请检查已有内容：

• frontend/components/WalletProvider.tsx — 钱包适配器配置，带有自动连接功能
• frontend/constants.ts — 从环境变量获取的 NETWORK、MODULE_ADDRESS、APTOS_API_KEY
• frontend/entry-functions/ — 现有的入口函数模式（新增入口函数时遵循这些模式）
• frontend/view-functions/ — 现有的视图函数模式（新增视图函数时遵循这些模式）

如果钱包提供程序、客户端配置或常量已存在，请勿重新创建。而应遵循现有模式，为你的 Move 合约添加新的入口函数或视图函数。

技能路由

根据任务转交给相应的细分技能：

任务	技能
设置 Aptos 客户端 / 配置网络	ts-sdk-client
创建账户/签名者（服务端）	ts-sdk-account
解析、格式化或派生地址	ts-sdk-address
构建、签名、提交、模拟交易	ts-sdk-transactions
读取链上数据（视图、余额、资源）	ts-sdk-view-and-query
将 Move 类型映射为 TypeScript 类型	ts-sdk-types
在 React 前端连接钱包	ts-sdk-wallet-adapter

全栈 dApp 工作流

构建完整的前端集成时：

1. 设置客户端 → 阅读 ts-sdk-client
2. 创建视图函数封装 → 阅读 ts-sdk-view-and-query
3. 创建入口函数载荷 → 阅读 ts-sdk-transactions
4. 接入钱包连接 → 阅读 ts-sdk-wallet-adapter
5. 正确处理类型 → 阅读 ts-sdk-types（按需）

文件组织模式

src/
  lib/
    aptos.ts                    # Singleton Aptos client + MODULE_ADDRESS
  view-functions/
    getCount.ts                 # One file per view function
    getListing.ts
  entry-functions/
    increment.ts                # One file per entry function
    createListing.ts
  hooks/
    useCounter.ts               # React hooks wrapping view functions
    useListing.ts
  components/
    WalletProvider.tsx           # AptosWalletAdapterProvider wrapper
    IncrementButton.tsx          # Components calling entry functions

错误处理模式

async function submitTransaction(
  aptos: Aptos,
  signer: Account,
  payload: InputGenerateTransactionPayloadData
): Promise<string> {
  try {
    const transaction = await aptos.transaction.build.simple({
      sender: signer.accountAddress,
      data: payload
    });

    const pendingTx = await aptos.signAndSubmitTransaction({
      signer,
      transaction
    });

    const committed = await aptos.waitForTransaction({
      transactionHash: pendingTx.hash
    });

    if (!committed.success) {
      throw new Error(`Transaction failed: ${committed.vm_status}`);
    }

    return pendingTx.hash;
  } catch (error) {
    if (error instanceof Error) {
      if (error.message.includes("RESOURCE_NOT_FOUND")) {
        throw new Error("Resource does not exist at the specified address");
      }
      if (error.message.includes("MODULE_NOT_FOUND")) {
        throw new Error("Contract is not deployed at the specified address");
      }
      if (error.message.includes("ABORTED")) {
        const match = error.message.match(/code: (\d+)/);
        const code = match ? match[1] : "unknown";
        throw new Error(`Contract error (code ${code})`);
      }
    }
    throw error;
  }
}

边缘情况

场景	检查	操作
未找到资源	error.message.includes("RESOURCE_NOT_FOUND")	返回默认值或 null
模块未部署	error.message.includes("MODULE_NOT_FOUND")	显示“合约未部署”消息
未找到函数	error.message.includes("FUNCTION_NOT_FOUND")	检查函数名称和模块地址
Move 中止	error.message.includes("ABORTED")	解析中止代码，转换为用户友好的错误
Gas 不足	error.message.includes("OUT_OF_GAS")	增加 maxGasAmount 并重试
序列号错误	error.message.includes("SEQUENCE_NUMBER")	获取最新序列号后重试
网络超时	error.message.includes("timeout")	使用指数退避策略重试
账户不存在	error.message.includes("ACCOUNT_NOT_FOUND")	为账户注资或提示用户创建账户
余额不足	error.message.includes("INSUFFICIENT_BALANCE")	显示余额和所需金额
用户在钱包中拒绝	钱包特定的拒绝错误	显示“交易已取消”消息

反模式

1. 切勿使用已弃用的 aptos npm 包——请使用 @aptos-labs/ts-sdk
2. 提交后切勿跳过 waitForTransaction——交易可能尚未提交
3. 切勿硬编码模块地址——请使用环境变量（VITE_MODULE_ADDRESS）
4. 切勿创建多个 Aptos 客户端实例——创建一个单例并共享使用
5. 面向真实用户时，切勿在前端代码中使用 Account.generate()——请使用钱包适配器
6. 切勿使用 scriptComposer——它已在 v6.0 中移除；请改用单独的交易
7. 切勿使用 getAccountCoinAmount 或 getAccountAPTAmount——它们已弃用；请使用 getBalance()

SDK 版本说明

AIP-80 私钥格式（v2.0+）

Ed25519 和 Secp256k1 私钥使用 toString() 序列化时，现在采用带 AIP-80 前缀的格式：

const key = new Ed25519PrivateKey("0x...");
key.toString(); // Returns AIP-80 prefixed format, NOT raw hex

可替代资产转账（v1.39+）

await aptos.transferFungibleAssetBetweenStores({
  sender: account,
  fungibleAssetMetadataAddress: metadataAddr,
  senderStoreAddress: fromStore,
  recipientStoreAddress: toStore,
  amount: 1000n
});

账户抽象（v1.34+，AIP-104）

// Check if AA is enabled for an account
const isEnabled = await aptos.abstraction.isAccountAbstractionEnabled({
  accountAddress: "0x...",
  authenticationFunction: `${MODULE_ADDRESS}::auth::authenticate`
});

// Enable AA on an account
const enableTxn = await aptos.abstraction.enableAccountAbstractionTransaction({
  accountAddress: account.accountAddress,
  authenticationFunction: `${MODULE_ADDRESS}::auth::authenticate`
});

// Use AbstractedAccount for signing with custom auth logic
import { AbstractedAccount } from "@aptos-labs/ts-sdk";

参考资料

模式文档：

• TYPESCRIPT_SDK.md — 完整的 SDK API 参考

官方文档：

• TypeScript SDK：https://aptos.dev/build/sdks/ts-sdk
• API 参考：https://aptos-labs.github.io/aptos-ts-sdk/
• 钱包适配器：https://aptos.dev/build/sdks/wallet-adapter/dapp
• GitHub：https://github.com/aptos-labs/aptos-ts-sdk

细分技能：

• ts-sdk-client — 客户端设置和配置
• ts-sdk-account — 账户/签名者创建
• ts-sdk-address — 地址解析和派生
• ts-sdk-transactions — 构建、签名和提交交易
• ts-sdk-view-and-query — 视图函数和查询
• ts-sdk-types — Move 到 TypeScript 的类型映射
• ts-sdk-wallet-adapter — React 钱包集成

相关技能：

• write-contracts — 编写此 SDK 交互所需的 Move 合约
• deploy-contracts — 在从 TypeScript 调用合约之前部署它们