ts-sdk-types

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript SDK: Types (Move ↔ TypeScript)

TypeScript SDK：类型映射（Move ↔ TypeScript）

Purpose

目的

Guide type mapping between Move and TypeScript when using

@aptos-labs/ts-sdk

: numeric types (especially u128/u256), address, TypeTag, and

functionArguments

typeArguments

本文档指导使用

@aptos-labs/ts-sdk

时，Move与TypeScript之间的类型映射，包括数值类型（尤其是u128/u256）、地址、TypeTag以及

functionArguments

typeArguments

的使用。

ALWAYS

务必遵循

Use
bigint
for u128 and u256 – in both view results and
```
functionArguments
```
; JavaScript
```
number
```
loses precision above 2^53.
Use
string
for address in payloads – e.g.
```
"0x1"
```
or
```
accountAddress.toString()
```
; SDK accepts
```
AccountAddressInput
```
(string or AccountAddress).

Use
typeArguments
for generic Move functions – e.g. coin type

["0x1::aptos_coin::AptosCoin"]

for

coin::balance

coin::transfer

Cast view results explicitly when you know the Move return type – e.g.
```
BigInt(result[0] as string)
```
for u128.

u128和u256类型使用
bigint
——无论是视图返回结果还是
```
functionArguments
```
中；JavaScript的
```
number
```
类型在数值超过2^53时会丢失精度。
在负载中使用
string
类型表示地址——例如
```
"0x1"
```
或
```
accountAddress.toString()
```
；SDK支持
```
AccountAddressInput
```
类型（字符串或AccountAddress对象）。
泛型Move函数需指定
typeArguments
——例如调用
```
coin::balance
```
或
```
coin::transfer
```
时，需传入币种类型
```
["0x1::aptos_coin::AptosCoin"]
```
。
当已知Move返回类型时，显式转换视图结果——例如对于u128类型，使用
```
BigInt(result[0] as string)
```
进行转换。

NEVER

切勿操作

Do not use
number
for u128/u256 – precision loss; use
```
bigint
```
.
Do not pass raw number for large u64 in entry/view – use
```
bigint
```
if value can exceed Number.MAX_SAFE_INTEGER.
Do not omit typeArguments when the Move function has type parameters (e.g.
```
balance<CoinType>
```
).

不要用
number
类型表示u128/u256——会丢失精度；请使用
```
bigint
```
。
在入口函数/视图中不要直接传入大数值的u64原始数字——如果数值可能超过Number.MAX_SAFE_INTEGER，请使用
```
bigint
```
。
当Move函数包含类型参数时（如
balance<CoinType>
），不要省略
typeArguments
。

Move → TypeScript (summary)

Move → TypeScript（汇总）

Move type	TypeScript type	Example
u8, u16, u32	number	`255` , `65535`
u64	number \| bigint	Prefer bigint for large values
u128, u256	bigint	`BigInt("340282366920938463463374607431768211455")`
i8..i64 (Move 2.3+)	number \| bigint	Use bigint for i64 when large
i128, i256	bigint	`BigInt("-...")`
bool	boolean	`true`
address	string	`"0x1"`
signer	—	Not passed from TS; signer is the transaction sender
vector<u8>	Uint8Array \| string (hex)	`new Uint8Array([1,2,3])` or hex
vector<T>	T[]	`[1, 2, 3]`
String	string	`"hello"`
Object<T>	string (object address)	`objectAddress.toString()`
Option<T>	T \| null	Value or `null`

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
i128, i256	bigint	`BigInt("-...")`
bool	boolean	`true`
address	string	`"0x1"`
signer	—	无需从TS传入；signer为交易发送方
vector<u8>	Uint8Array \| string（十六进制）	`new Uint8Array([1,2,3])` 或十六进制字符串
vector<T>	T[]	`[1, 2, 3]`
String	string	`"hello"`
Object<T>	string（对象地址）	`objectAddress.toString()`
Option<T>	T \| null	具体值或 `null`

functionArguments

Order and types must match the Move entry/view function parameters:

typescript

// 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)
    ],
  },
});

参数的顺序和类型必须与Move入口/视图函数的参数完全匹配：

typescript

// 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...",  // 地址以字符串形式传入
      1000n,             // u64以bigint形式传入（小数值可使用number）
    ],
  },
});

typeArguments

For generic Move functions, pass full type strings (

address::module::StructName

typescript

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

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

对于泛型Move函数，传入完整的类型字符串（

address::module::StructName

）：

typescript

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

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

View return types

视图返回类型

typescript

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);

typescript

const result = await aptos.view({
  payload: {
    function: "0x1::coin::balance",
    typeArguments: ["0x1::aptos_coin::AptosCoin"],
    functionArguments: [accountAddress],
  },
});
// 结果是数组；u128在JSON中常以字符串形式返回
const balance = BigInt(result[0] as string);

TypeTag (advanced)

TypeTag（进阶）

When building payloads programmatically or parsing type strings:

typescript

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");

Use

typeArguments

as string array in simple cases; use TypeTag when the SDK API expects it.

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

typescript

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

// 类型标签字符串解析器
import { parseTypeTag } from "@aptos-labs/ts-sdk";
const tag = parseTypeTag("0x1::aptos_coin::AptosCoin");

简单场景下使用字符串数组形式的

typeArguments

；当SDK API明确要求时，使用TypeTag。

Object / resource address in arguments

参数中的对象/资源地址

Pass object address as string (LONG or SHORT per AIP-40):

typescript

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

以字符串形式传入对象地址（遵循AIP-40的长格式或短格式）：

typescript

functionArguments: [
  nftObjectAddress.toString(),  // 或直接传入"0x..."
  price,
]

Common mistakes

常见错误

Mistake	Correct approach
Passing number for u128 amount	Use `1000000n` or `BigInt("...")`
Omitting typeArguments for coin::balance	Add `typeArguments: ["0x1::aptos_coin::AptosCoin"]`
Using result[0] as number for u128	Use `BigInt(result[0] as string)`
Wrong order of functionArguments	Match Move parameter order exactly

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

References

参考资料

SDK:

src/transactions/typeTag/

src/transactions/instances/transactionArgument.ts

, view and build APIs

Pattern: TYPESCRIPT_SDK.md
Related: ts-sdk-view-and-query, ts-sdk-transactions, use-ts-sdk

SDK源码：

src/transactions/typeTag/

、

src/transactions/instances/transactionArgument.ts

，以及视图和构建API

模式文档：TYPESCRIPT_SDK.md
相关文档：ts-sdk-view-and-query、ts-sdk-transactions、use-ts-sdk