TypeScript SDK: Types (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 .

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 or coin::transfer .

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

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

Move → TypeScript (summary)

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 Uint8Array | string (hex) new Uint8Array([1,2,3]) or hex

vector T[] [1, 2, 3]

String string "hello"

Object string (object address) objectAddress.toString()

Option T | null Value or null

functionArguments

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

// 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

For generic Move functions, pass full type strings (address::module::StructName ):

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

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

View return types

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 (advanced)

When building payloads programmatically or parsing type strings:

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.

Object / resource address in arguments

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

functionArguments: [ nftObjectAddress.toString(), // or "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

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