ts-sdk-address

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript SDK: AccountAddress

TypeScript SDK：AccountAddress

Purpose

用途

Guide correct creation, parsing, and formatting of account addresses in

@aptos-labs/ts-sdk

. Addresses are 32-byte values; string format follows AIP-40.

指导在

@aptos-labs/ts-sdk

中正确创建、解析和格式化账户地址。地址为32字节值；字符串格式遵循AIP-40标准。

ALWAYS

必须遵循的规范

Use
AccountAddress.from()
for flexible input – accepts string (with or without
```
0x
```
),
```
Uint8Array
```
, or existing
```
AccountAddress
```
.
Use addresses as
AccountAddress
or string in API – SDK accepts
```
AccountAddressInput
```
(string or
```
AccountAddress
```
) in most APIs.
Use
AccountAddress.fromStringStrict()
/
AccountAddress.fromStrict()
when you need AIP-40 strict: LONG (0x + 64 hex chars) or SHORT only for special (0x0–0xf).
Use derived address helpers from the SDK for object/resource/token addresses – do not hand-roll hashing.

使用
AccountAddress.from()
处理灵活输入——接受带或不带
```
0x
```
的字符串、
```
Uint8Array
```
或已有的
```
AccountAddress
```
对象。
在API中使用
AccountAddress
对象或字符串作为地址——SDK的大多数API接受
```
AccountAddressInput
```
类型（字符串或
```
AccountAddress
```
对象）。
当需要严格遵循AIP-40标准时，使用
AccountAddress.fromStringStrict()
/
AccountAddress.fromStrict()
——长格式（0x + 64个十六进制字符）或仅特殊地址（0x0–0xf）允许使用短格式。
使用SDK提供的派生地址工具函数生成对象/资源/代币地址——不要手动实现哈希逻辑。

NEVER

禁止操作

Do not use raw strings for comparison – use
```
addr.equals(other)
```
or normalize with
```
AccountAddress.from()
```
.
Do not assume SHORT form for non-special addresses – non-special addresses must be LONG (64 hex chars) in strict mode.
Do not use the
Hex
class for account addresses – use
```
AccountAddress
```
only (per SDK docs).

不要使用原始字符串进行比较——使用
```
addr.equals(other)
```
或通过
```
AccountAddress.from()
```
标准化后再比较。
不要假设非特殊地址可以使用短格式——在严格模式下，非特殊地址必须使用长格式（64个十六进制字符）。
不要使用
Hex
类处理账户地址——仅使用
```
AccountAddress
```
（符合SDK文档要求）。

Address format (AIP-40)

地址格式（AIP-40）

Length: 32 bytes (64 hex chars in LONG form).
String: Must start with
```
0x
```
. LONG =
```
0x
```
+ 64 hex chars; SHORT = shortest form (e.g.
```
0x1
```
,
```
0xf
```
).
Special addresses:
```
0x0
```
–
```
0xf
```
(last byte < 16, rest zero). These may be written in SHORT form (
```
0x1
```
,
```
0xa
```
).
Reference: AIP-40.

长度：32字节（长格式为64个十六进制字符）。
字符串格式：必须以
```
0x
```
开头。长格式为
```
0x
```
+ 64个十六进制字符；短格式为最简形式（例如
```
0x1
```
、
```
0xf
```
）。
特殊地址：
```
0x0
```
–
```
0xf
```
（最后一个字节<16，其余字节为0）。这些地址可以用短格式书写（
```
0x1
```
、
```
0xa
```
）。
参考文档：AIP-40。

Creating AccountAddress

创建AccountAddress

From string (recommended: relaxed)

从字符串创建（推荐：宽松模式）

typescript

import { AccountAddress } from "@aptos-labs/ts-sdk";

// Relaxed: accepts with or without 0x, SHORT or LONG
const addr1 = AccountAddress.from("0x1");
const addr2 = AccountAddress.from("0xaa86fe99004361f747f91342ca13c426ca0cccb0c1217677180c9493bad6ef0c");
const addr3 = AccountAddress.from("1"); // no 0x ok

typescript

import { AccountAddress } from "@aptos-labs/ts-sdk";

// 宽松模式：接受带或不带0x的字符串、短格式或长格式
const addr1 = AccountAddress.from("0x1");
const addr2 = AccountAddress.from("0xaa86fe99004361f747f91342ca13c426ca0cccb0c1217677180c9493bad6ef0c");
const addr3 = AccountAddress.from("1"); // 不带0x也可

From string (strict AIP-40)

从字符串创建（严格遵循AIP-40）

typescript

// Strict: LONG (0x + 64 chars) or SHORT only for special (0x0–0xf)
const addrStrict = AccountAddress.fromStringStrict(
  "0x0000000000000000000000000000000000000000000000000000000000000001"
);
// Or use fromStrict for any AccountAddressInput
const a = AccountAddress.fromStrict("0x1"); // ok: special address in SHORT form

typescript

// 严格模式：长格式（0x + 64个字符）或仅特殊地址（0x0–0xf）允许使用短格式
const addrStrict = AccountAddress.fromStringStrict(
  "0x0000000000000000000000000000000000000000000000000000000000000001"
);
// 或使用fromStrict处理任意AccountAddressInput类型
const a = AccountAddress.fromStrict("0x1"); // 合法：特殊地址的短格式

From bytes

从字节创建

typescript

const bytes = new Uint8Array(32);
bytes[31] = 1;
const addr = new AccountAddress(bytes);
// or
const addrFrom = AccountAddress.from(bytes);

typescript

const bytes = new Uint8Array(32);
bytes[31] = 1;
const addr = new AccountAddress(bytes);
// 或者
const addrFrom = AccountAddress.from(bytes);

Built-in constants

内置常量

typescript

AccountAddress.ZERO;  // 0x0
AccountAddress.ONE;   // 0x1
AccountAddress.TWO;   // 0x2
AccountAddress.THREE; // 0x3
AccountAddress.FOUR;  // 0x4
AccountAddress.A;     // 0xa

typescript

AccountAddress.ZERO;  // 0x0
AccountAddress.ONE;   // 0x1
AccountAddress.TWO;   // 0x2
AccountAddress.THREE; // 0x3
AccountAddress.FOUR;  // 0x4
AccountAddress.A;     // 0xa

String output

字符串输出

Method	Use case
`addr.toString()`	AIP-40 default: SHORT for special, LONG for others
`addr.toStringLong()`	Always 0x + 64 hex chars
`addr.toStringShort()`	Shortest form (no leading zeros)
`addr.toStringLongWithoutPrefix()`	64 hex chars, no `0x`

typescript

const addr = AccountAddress.from("0x1");
addr.toString();   // "0x1"
addr.toStringLong(); // "0x0000...0001" (64 chars after 0x)

方法	使用场景
`addr.toString()`	AIP-40默认格式：特殊地址用短格式，其他地址用长格式
`addr.toStringLong()`	始终输出0x + 64个十六进制字符
`addr.toStringShort()`	输出最简形式（无前导零）
`addr.toStringLongWithoutPrefix()`	输出64个十六进制字符，不带 `0x` 前缀

typescript

const addr = AccountAddress.from("0x1");
addr.toString();   // "0x1"
addr.toStringLong(); // "0x0000...0001"（0x后接64个字符）

Validation

验证地址

typescript

const result = AccountAddress.isValid({
  input: "0x1",
  strict: false
});
if (result.valid) {
  // use address
} else {
  console.log(result.invalidReason, result.invalidReasonMessage);
}

typescript

const result = AccountAddress.isValid({
  input: "0x1",
  strict: false
});
if (result.valid) {
  // 使用该地址
} else {
  console.log(result.invalidReason, result.invalidReasonMessage);
}

Derived addresses (object / resource / token / user-derived)

派生地址（对象/资源/代币/用户派生）

Import from

@aptos-labs/ts-sdk

(via core):

typescript

import {
  AccountAddress,
  createObjectAddress,
  createResourceAddress,
  createTokenAddress,
  createUserDerivedObjectAddress,
} from "@aptos-labs/ts-sdk";

从

@aptos-labs/ts-sdk

（core模块）导入：

typescript

import {
  AccountAddress,
  createObjectAddress,
  createResourceAddress,
  createTokenAddress,
  createUserDerivedObjectAddress,
} from "@aptos-labs/ts-sdk";

Object address (e.g. named object)

对象地址（例如命名对象）

typescript

const creator = AccountAddress.from("0x120e79e45d21ef439963580c77a023e2729db799e96e61f878fac98fde5b9cc9");
const seed = "migration::migration_contract"; // or Uint8Array
const objectAddr = createObjectAddress(creator, seed);
// objectAddr.toString() => deterministic 0x... address

typescript

const creator = AccountAddress.from("0x120e79e45d21ef439963580c77a023e2729db799e96e61f878fac98fde5b9cc9");
const seed = "migration::migration_contract"; // 或Uint8Array类型
const objectAddr = createObjectAddress(creator, seed);
// objectAddr.toString() => 确定性的0x...地址

Resource account address

资源账户地址

typescript

const creator = AccountAddress.from("0x41e724e1d4fce6472ffcb5c9886770893eb49489e3f531d0aa97bf951e66d70c");
const seed = "create_resource::create_resource";
const resourceAddr = createResourceAddress(creator, seed);

typescript

const creator = AccountAddress.from("0x41e724e1d4fce6472ffcb5c9886770893eb49489e3f531d0aa97bf951e66d70c");
const seed = "create_resource::create_resource";
const resourceAddr = createResourceAddress(creator, seed);

Token (NFT) object address

代币（NFT）对象地址

typescript

const creator = AccountAddress.from("0x9d518b9b84f327eafc5f6632200ea224a818a935ffd6be5d78ada250bbc44a6");
const collectionName = "SuperV Villains";
const tokenName = "Nami #5962";
const tokenAddr = createTokenAddress(creator, collectionName, tokenName);
// Internally: seed = `${collectionName}::${tokenName}` -> createObjectAddress(creator, seed)

typescript

const creator = AccountAddress.from("0x9d518b9b84f327eafc5f6632200ea224a818a935ffd6be5d78ada250bbc44a6");
const collectionName = "SuperV Villains";
const tokenName = "Nami #5962";
const tokenAddr = createTokenAddress(creator, collectionName, tokenName);
// 内部逻辑：seed = `${collectionName}::${tokenName}` -> 调用createObjectAddress(creator, seed)

User-derived object address

用户派生对象地址

typescript

const sourceAddress = AccountAddress.from("0x653a60dab27fe8f3859414973d218e1b7551c778a8650a7055a85c0f8041b2a4");
const deriveFromAddress = AccountAddress.from("0xa");
const userDerivedAddr = createUserDerivedObjectAddress(sourceAddress, deriveFromAddress);

typescript

const sourceAddress = AccountAddress.from("0x653a60dab27fe8f3859414973d218e1b7551c778a8650a7055a85c0f8041b2a4");
const deriveFromAddress = AccountAddress.from("0xa");
const userDerivedAddr = createUserDerivedObjectAddress(sourceAddress, deriveFromAddress);

Equality and serialization

相等性判断与序列化

typescript

const a = AccountAddress.from("0x1");
const b = AccountAddress.from("0x0000000000000000000000000000000000000000000000000000000000000001");
a.equals(b); // true

// BCS: use serializer or SDK entry/script helpers in transaction building

typescript

const a = AccountAddress.from("0x1");
const b = AccountAddress.from("0x0000000000000000000000000000000000000000000000000000000000000001");
a.equals(b); // 返回true

// BCS序列化：在构建交易时使用序列化器或SDK的入口/脚本工具函数

Common mistakes

常见错误

Mistake	Correct approach
Using `Hex` for account address	Use `AccountAddress` only
Comparing with `===` on strings	Use `addr1.equals(addr2)` or compare after `AccountAddress.from()`
Using SHORT for non-special in strict	Use LONG (0x + 64 hex chars) or `AccountAddress.from()` (relaxed)
Hand-rolling object address hash	Use `createObjectAddress` / `createTokenAddress` / `createResourceAddress` / `createUserDerivedObjectAddress`

错误做法	正确方式
使用 `Hex` 类处理账户地址	仅使用 `AccountAddress`
使用 `===` 比较地址字符串	使用 `addr1.equals(addr2)` 或通过 `AccountAddress.from()` 标准化后再比较
在严格模式下为非特殊地址使用短格式	使用长格式（0x + 64个十六进制字符）或 `AccountAddress.from()` （宽松模式）
手动实现对象地址的哈希逻辑	使用 `createObjectAddress` / `createTokenAddress` / `createResourceAddress` / `createUserDerivedObjectAddress` 工具函数

References

参考资料

SDK:

src/core/accountAddress.ts

src/core/account/utils/address.ts

AIP-40: https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-40.md
Pattern: TYPESCRIPT_SDK.md

SDK源码：

src/core/accountAddress.ts

、

src/core/account/utils/address.ts

AIP-40：https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-40.md
模式文档：TYPESCRIPT_SDK.md