ts-sdk-types

TypeScript SDK：类型（Move ↔ TypeScript）

目的

使用 @aptos-labs/ts-sdk 时，指导如何在 Move 和 TypeScript 之间映射类型：数值类型（尤其是 u128/u256）、地址、TypeTag，以及 functionArguments / typeArguments。

务必遵守

1. u128 和 u256 使用 bigint ——在视图结果和 functionArguments 中都如此；JavaScript number 在超过 2^53 时会丢失精度。
2. payload 中的地址使用 string ——例如 "0x1" 或 accountAddress.toString()；SDK 接受 AccountAddressInput（string 或 AccountAddress）。
3. 泛型 Move 函数使用 typeArguments ——例如，coin::balance 或 coin::transfer 的币种类型为 ["0x1::aptos_coin::AptosCoin"]。
4. 明确转换视图结果的类型，前提是你知道 Move 返回类型 ——例如，对 u128 使用 BigInt(result[0] as string)。

切勿

1. 不要对 u128/u256 使用 number ——会丢失精度；应使用 bigint。
2. 不要在 entry/view 中为较大的 u64 传入原始 number ——如果值可能超过 Number.MAX_SAFE_INTEGER，请使用 bigint。
3. Move 函数有类型参数时，不要省略 typeArguments（例如 balance<CoinType>）。

---

Move → TypeScript（摘要）

Move 类型	TypeScript 类型	示例
u8、u16、u32	number	255、65535
u64	number | bigint	较大的值优先使用 bigint
u128、u256	bigint	BigInt("340282366920938463463374607431768211455")
i8..i64（Move 2.3+）	number | bigint	i64 的值较大时使用 bigint
bool	boolean	true
address	string	"0x1"
signer	—	不从 TS 传入；signer 是交易发送方
vector	Uint8Array | string (hex)	new Uint8Array([1,2,3]) 或十六进制
vector	T[]	[1, 2, 3]
String	string	"hello"
Object	string（对象地址）	objectAddress.toString()
Option	T | null	值或 null

---

functionArguments

顺序和类型必须与 Move entry/view 函数参数一致：

// Move: public fun transfer<CoinType>(to: address, amount: u64)
await aptos.transaction.build.simple({
  sender: account.accountAddress,
  data: {
    function: "0x1::coin::transfer",
    typeArguments: ["0x1::aptos_coin::AptosCoin"],
    functionArguments: [
      "0xrecipient...", // address as string
      1000n // u64 as bigint (or number if small)
    ]
  }
});

---

typeArguments

对于泛型 Move 函数，传入完整类型字符串（address::module::StructName）：

// Move: balance<CoinType>(addr): u64
typeArguments: ["0x1::aptos_coin::AptosCoin"];

// Move: transfer<CoinType>(to, amount)
typeArguments: ["0x1::aptos_coin::AptosCoin"];

---

视图返回类型

const result = await aptos.view({
  payload: {
    function: "0x1::coin::balance",
    typeArguments: ["0x1::aptos_coin::AptosCoin"],
    functionArguments: [accountAddress]
  }
});
// result is an array; u128 often returned as string in JSON
const balance = BigInt(result[0] as string);

---

TypeTag（高级）

以编程方式构建 payload 或解析类型字符串时：

import { TypeTag } from "@aptos-labs/ts-sdk";

// Parser for type tag strings
import { parseTypeTag } from "@aptos-labs/ts-sdk";
const tag = parseTypeTag("0x1::aptos_coin::AptosCoin");

简单场景中使用字符串数组作为 typeArguments；SDK API 要求 TypeTag 时则使用 TypeTag。

---

参数中的对象 / 资源地址

将对象地址作为字符串传入（按 AIP-40 使用 LONG 或 SHORT）：

functionArguments: [
  nftObjectAddress.toString(), // or "0x..."
  price
];

---

常见错误

错误	正确做法
为 u128 数量传入 number	使用 1000000n 或 BigInt("...")
为 coin::balance 省略 typeArguments	添加 typeArguments: ["0x1::aptos_coin::AptosCoin"]
将 u128 的 result[0] 当作 number 使用	使用 BigInt(result[0] as string)
functionArguments 顺序错误	严格匹配 Move 参数顺序

---

参考资料

• SDK：src/transactions/typeTag/、src/transactions/instances/transactionArgument.ts、视图和构建 API
• 模式：TYPESCRIPT_SDK.md
• 相关内容：ts-sdk-view-and-query、 ts-sdk-transactions、use-ts-sdk