ts-sdk-types

TypeScript SDK：型（Move ↔ TypeScript）

目的

@aptos-labs/ts-sdk を使用する際の、Move と TypeScript 間の 型マッピングについて説明します。数値型（特に u128/u256）、アドレス、TypeTag、functionArguments / typeArguments を扱います。

必ず守ること

1. u128 と u256 には bigint を使用します。ビューの結果と functionArguments の両方で使用してください。JavaScript の number は 2^53 を超えると精度が失われます。
2. ペイロード内のアドレスには string を使用します。例："0x1" または accountAddress.toString()。SDK は AccountAddressInput（string または AccountAddress）を受け入れます。
3. ジェネリックな Move 関数には typeArguments を使用します。例：coin::balance または coin::transfer のコイン型 ["0x1::aptos_coin::AptosCoin"]。
4. Move の戻り値の型がわかっている場合は、ビューの結果を明示的にキャストします。例：u128 の場合は BigInt(result[0] as string)。

決してしてはいけないこと

1. u128/u256 に number を使用しないでください。精度が失われるため、bigint を使用します。
2. entry/view で大きな u64 に生の number を渡さないでください。値が Number.MAX_SAFE_INTEGER を超える可能性がある場合は、bigint を使用します。
3. Move 関数に型パラメーターがある場合（例：balance<CoinType>）、typeArguments を省略しないでください。

---

Move → TypeScript（概要）

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	Uint8Array | string (hex)	new Uint8Array([1,2,3]) または hex
vector	T[]	[1, 2, 3]
String	string	"hello"
Object	string (object address)	objectAddress.toString()
Option	T | null	値または null

---

functionArguments

順序と型は、Move の entry/view 関数のパラメーターと一致させる必要があります。

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

ジェネリックな Move 関数には、完全な型文字列（address::module::StructName）を渡します。

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

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

---

ビューの戻り値の型

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（上級者向け）

ペイロードをプログラムで構築する場合や、型文字列を解析する場合：

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

単純なケースでは typeArguments に文字列配列を使用し、SDK API が要求する場合は TypeTag を使用します。

---

引数内のオブジェクト／リソースアドレス

オブジェクトアドレスは文字列として渡します（AIP-40 に従い LONG または SHORT を使用）。

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

---

よくある間違い

間違い	正しい方法
u128 の値に number を渡す	1000000n または BigInt("...") を使用
coin::balance の typeArguments を省略する	typeArguments: ["0x1::aptos_coin::AptosCoin"] を追加
u128 に result[0] を number として使用する	BigInt(result[0] as string) を使用
functionArguments の順序が間違っている	Move のパラメーター順と正確に一致させる

参考資料

• SDK：src/transactions/typeTag/、src/transactions/instances/transactionArgument.ts、view および build API
• パターン：TYPESCRIPT_SDK.md
• 関連：ts-sdk-view-and-query、 ts-sdk-transactions、use-ts-sdk