ts-sdk-types

Name: ts-sdk-types
Author: aptos-labs

19stars8forks

How to install ts-sdk-types?

aptos-labs/aptos-agent-skills/ts-sdk-types

$npx -y skills add aptos-labs/aptos-agent-skills --skill ts-sdk-types

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# TypeScript SDK: Types (Move ↔ TypeScript)
2
3	## Purpose
4
5	Guide type mapping between Move and TypeScript when using `@aptos-labs/ts-sdk`: numeric types (especially
6	u128/u256), address, TypeTag, and `functionArguments` / `typeArguments`.
7
8	## ALWAYS
9
10	1. Use `bigint` for u128 and u256 – in both view results and `functionArguments`; JavaScript `number` loses
11	precision above 2^53.
12	2. Use `string` for address in payloads – e.g. `"0x1"` or `accountAddress.toString()`; SDK accepts
13	`AccountAddressInput` (string or AccountAddress).
14	3. Use `typeArguments` for generic Move functions – e.g. coin type `["0x1::aptos_coin::AptosCoin"]` for
15	`coin::balance` or `coin::transfer`.
16	4. Cast view results explicitly when you know the Move return type – e.g. `BigInt(result[0] as string)` for u128.
17
18	## NEVER
19
20	1. Do not use `number` for u128/u256 – precision loss; use `bigint`.
21	2. Do not pass raw number for large u64 in entry/view – use `bigint` if value can exceed Number.MAX_SAFE_INTEGER.
22	3. Do not omit typeArguments when the Move function has type parameters (e.g. `balance<CoinType>`).
23
24	---
25
26	## Move → TypeScript (summary)
27
28	\| Move type \| TypeScript type \| Example \|
29	\| ------------------- \| -------------------------- \| ---------------------------------------------------- \|
30	\| u8, u16, u32 \| number \| `255`, `65535` \|
31	\| u64 \| number \\| bigint \| Prefer bigint for large values \|
32	\| u128, u256 \| bigint \| `BigInt("340282366920938463463374607431768211455")` \|
33	\| i8..i64 (Move 2.3+) \| number \\| bigint \| Use bigint for i64 when large \|
34	\| i128, i256 \| bigint \| `BigInt("-...")` \|
35	\| bool \| boolean \| `true` \|
36	\| address \| string \| `"0x1"` \|
37	\| signer \| — \| Not passed from TS; signer is the transaction sender \|
38	\| vector<u8> \| Uint8Array \\| string (hex) \| `new Uint8Array([1,2,3])` or hex \|
39	\| vector<T> \| T[] \| `[1, 2, 3]` \|
40	\| String \| string \| `"hello"` \|
41	\| Object<T> \| string (object address) \| `objectAddress.toString()` \|
42	\| Option<T> \| T \\| null \| Value or `null` \|
43
44	---
45
46	## functionArguments
47
48	Order and types must match the Move entry/view function parameters:
49
50	```typescript
51	// Move: public fun transfer<CoinType>(to: address, amount: u64)
52	await aptos.transaction.build.simple({
53	sender: account.accountAddress,
54	data: {
55	function: "0x1::coin::transfer",
56	typeArguments: ["0x1::aptos_coin::AptosCoin"],
57	functionArguments: [
58	"0xrecipient...", // address as string
59	1000n // u64 as bigint (or number if small)
60	]
61	}
62	});
63	```
64
65	---
66
67	## typeArguments
68
69	For generic Move functions, pass full type strings (`address::module::StructName`):
70
71	```typescript
72	// Move: balance<CoinType>(addr): u64
73	typeArguments: ["0x1::aptos_coin::AptosCoin"];
74
75	// Move: transfer<CoinType>(to, amount)
76	typeArguments: ["0x1::aptos_coin::AptosCoin"];
77	```
78
79	---
80
81	## View return types
82
83	```typescript
84	const result = await aptos.view({
85	payload: {
86	function: "0x1::coin::balance",
87	typeArguments: ["0x1::aptos_coin::AptosCoin"],
88	functionArguments: [accountAddress]
89	}
90	});
91	// result is an array; u128 often returned as string in JSON
92	const balance = BigInt(result[0] as string);
93	```
94
95	---
96
97	## TypeTag (advanced)
98
99	When building payloads programmatically or parsing type strings:
100
101	```typescript
102	import { TypeTag } from "@aptos-labs/ts-sdk";
103
104	// Parser for type tag strings
105	import { parseTypeTag } from "@aptos-labs/ts-sdk";
106	const tag = parseTypeTag("0x1::aptos_coin::AptosCoin");
107	```
108
109	Use `typeArguments` as string array in simple cases; use TypeTag when the SDK API expects it.
110
111	---
112
113	## Object / resource address in arguments
114
115	Pass object address as string (LONG or SHORT per AIP-40):
116
117	```typescript
118	functionArguments: [
119	nftObjectAddress.toString(), // or "0x..."
120	price
121	];
122	```
123
124	---
125
126	## Common mistakes
127
128	\| Mistake

People who liked this also viewed

6 picks

Type

ts-sdk-types

19stars8forks

View on GitHub

How to install ts-sdk-types?

aptos-labs/aptos-agent-skills/ts-sdk-types

$npx -y skills add aptos-labs/aptos-agent-skills --skill ts-sdk-types

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# TypeScript SDK: Types (Move ↔ TypeScript)
2
3	## Purpose
4
5	Guide type mapping between Move and TypeScript when using `@aptos-labs/ts-sdk`: numeric types (especially
6	u128/u256), address, TypeTag, and `functionArguments` / `typeArguments`.
7
8	## ALWAYS
9
10	1. Use `bigint` for u128 and u256 – in both view results and `functionArguments`; JavaScript `number` loses
11	precision above 2^53.
12	2. Use `string` for address in payloads – e.g. `"0x1"` or `accountAddress.toString()`; SDK accepts
13	`AccountAddressInput` (string or AccountAddress).
14	3. Use `typeArguments` for generic Move functions – e.g. coin type `["0x1::aptos_coin::AptosCoin"]` for
15	`coin::balance` or `coin::transfer`.
16	4. Cast view results explicitly when you know the Move return type – e.g. `BigInt(result[0] as string)` for u128.
17
18	## NEVER
19
20	1. Do not use `number` for u128/u256 – precision loss; use `bigint`.
21	2. Do not pass raw number for large u64 in entry/view – use `bigint` if value can exceed Number.MAX_SAFE_INTEGER.
22	3. Do not omit typeArguments when the Move function has type parameters (e.g. `balance<CoinType>`).
23
24	---
25
26	## Move → TypeScript (summary)
27
28	\| Move type \| TypeScript type \| Example \|
29	\| ------------------- \| -------------------------- \| ---------------------------------------------------- \|
30	\| u8, u16, u32 \| number \| `255`, `65535` \|
31	\| u64 \| number \\| bigint \| Prefer bigint for large values \|
32	\| u128, u256 \| bigint \| `BigInt("340282366920938463463374607431768211455")` \|
33	\| i8..i64 (Move 2.3+) \| number \\| bigint \| Use bigint for i64 when large \|
34	\| i128, i256 \| bigint \| `BigInt("-...")` \|
35	\| bool \| boolean \| `true` \|
36	\| address \| string \| `"0x1"` \|
37	\| signer \| — \| Not passed from TS; signer is the transaction sender \|
38	\| vector<u8> \| Uint8Array \\| string (hex) \| `new Uint8Array([1,2,3])` or hex \|
39	\| vector<T> \| T[] \| `[1, 2, 3]` \|
40	\| String \| string \| `"hello"` \|
41	\| Object<T> \| string (object address) \| `objectAddress.toString()` \|
42	\| Option<T> \| T \\| null \| Value or `null` \|
43
44	---
45
46	## functionArguments
47
48	Order and types must match the Move entry/view function parameters:
49
50	```typescript
51	// Move: public fun transfer<CoinType>(to: address, amount: u64)
52	await aptos.transaction.build.simple({
53	sender: account.accountAddress,
54	data: {
55	function: "0x1::coin::transfer",
56	typeArguments: ["0x1::aptos_coin::AptosCoin"],
57	functionArguments: [
58	"0xrecipient...", // address as string
59	1000n // u64 as bigint (or number if small)
60	]
61	}
62	});
63	```
64
65	---
66
67	## typeArguments
68
69	For generic Move functions, pass full type strings (`address::module::StructName`):
70
71	```typescript
72	// Move: balance<CoinType>(addr): u64
73	typeArguments: ["0x1::aptos_coin::AptosCoin"];
74
75	// Move: transfer<CoinType>(to, amount)
76	typeArguments: ["0x1::aptos_coin::AptosCoin"];
77	```
78
79	---
80
81	## View return types
82
83	```typescript
84	const result = await aptos.view({
85	payload: {
86	function: "0x1::coin::balance",
87	typeArguments: ["0x1::aptos_coin::AptosCoin"],
88	functionArguments: [accountAddress]
89	}
90	});
91	// result is an array; u128 often returned as string in JSON
92	const balance = BigInt(result[0] as string);
93	```
94
95	---
96
97	## TypeTag (advanced)
98
99	When building payloads programmatically or parsing type strings:
100
101	```typescript
102	import { TypeTag } from "@aptos-labs/ts-sdk";
103
104	// Parser for type tag strings
105	import { parseTypeTag } from "@aptos-labs/ts-sdk";
106	const tag = parseTypeTag("0x1::aptos_coin::AptosCoin");
107	```
108
109	Use `typeArguments` as string array in simple cases; use TypeTag when the SDK API expects it.
110
111	---
112
113	## Object / resource address in arguments
114
115	Pass object address as string (LONG or SHORT per AIP-40):
116
117	```typescript
118	functionArguments: [
119	nftObjectAddress.toString(), // or "0x..."
120	price
121	];
122	```
123
124	---
125
126	## Common mistakes
127
128	\| Mistake

People who liked this also viewed

6 picks

Type