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

1. Use bigint for u128 and u256 – in both view results and functionArguments; JavaScript number loses precision above 2^53.
2. Use string for address in payloads – e.g. "0x1" or accountAddress.toString(); SDK accepts AccountAddressInput (string or AccountAddress).
3. Use typeArguments for generic Move functions – e.g. coin type ["0x1::aptos_coin::AptosCoin"] for coin::balance or coin::transfer.
4. Cast view results explicitly when you know the Move return type – e.g. BigInt(result[0] as string) for u128.

NEVER

1. Do not use number for u128/u256 – precision loss; use bigint.
2. Do not pass raw number for large u64 in entry/view – use bigint if value can exceed Number.MAX_SAFE_INTEGER.
3. 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