Agent skill
ts-sdk-types
Move to TypeScript type mapping in @aptos-labs/ts-sdk: u64/u128/u256 as bigint, address as string, TypeTag, functionArguments and typeArguments. Triggers on: 'typeArguments', 'functionArguments', 'Move to TypeScript', 'type mapping', 'TypeTag', 'bigint u128'.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/ts-sdk-types
Metadata
Additional technical details for this skill
- tags
-
typescript sdk types typetag bigint move
- author
- aptos-labs
- version
- 1.0
- category
- sdk
- priority
- high
SKILL.md
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
bigintfor u128 and u256 – in both view results andfunctionArguments; JavaScriptnumberloses precision above 2^53. - Use
stringfor address in payloads – e.g."0x1"oraccountAddress.toString(); SDK acceptsAccountAddressInput(string or AccountAddress). - Use
typeArgumentsfor generic Move functions – e.g. coin type["0x1::aptos_coin::AptosCoin"]forcoin::balanceorcoin::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
numberfor u128/u256 – precision loss; usebigint. - Do not pass raw number for large u64 in entry/view – use
bigintif 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> | T[] | [1, 2, 3] |
| String | string | "hello" |
| Object<T> | string (object address) | objectAddress.toString() |
| Option<T> | 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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?